From zero to full server integration test.

Prerequisites

• Java 21
• Maven 3.9+
• Linux, macOS, or a recent version of Windows with UDS support (Windows is untested, though)

1. Add framework dependency

<dependency>
    <groupId>nl.pim16aap2.lightkeeper</groupId>
    <artifactId>lightkeeper-framework-junit</artifactId>
    <version>${lightkeeper.version}</version>
    <scope>test</scope>
</dependency>

2. Configure prepare + cleanup goals

<plugin>
    <groupId>nl.pim16aap2.lightkeeper</groupId>
    <artifactId>lightkeeper-maven-plugin</artifactId>
    <version>${lightkeeper.version}</version>
    <configuration>
        <userAgent>LightKeeper/${project.version} ([email protected])</userAgent>
        <agentJarPath>${project.build.directory}/lightkeeper-agent/lightkeeper-agent-paper.jar</agentJarPath>
    </configuration>
    <executions>
        <execution>
            <id>prepare-server</id>
            <goals><goal>prepare-server</goal></goals>
            <configuration>
                <serverType>paper</serverType>
                <runtimeManifestPath>${project.build.directory}/lightkeeper/runtime-manifest.json</runtimeManifestPath>
            </configuration>
        </execution>
        <execution>
            <id>cleanup-server</id>
            <phase>post-integration-test</phase>
            <goals><goal>cleanup-server</goal></goals>
            <configuration>
                <deleteTargetServerOnSuccess>true</deleteTargetServerOnSuccess>
                <failsafeSummaryPath>${project.build.directory}/failsafe-reports/failsafe-summary.xml</failsafeSummaryPath>
            </configuration>
        </execution>
    </executions>
</plugin>

3. Pass runtime manifest to tests

<systemPropertyVariables>
    <lightkeeper.runtimeManifestPath>
        ${project.build.directory}/lightkeeper/runtime-manifest.json
    </lightkeeper.runtimeManifestPath>
</systemPropertyVariables>

4. Write your first test

@ExtendWith(LightkeeperExtension.class)
class MyPluginIT {
    @Test
    void basicFlow(ILightkeeperFramework framework) {
        final var world = framework.mainWorld();
        final var player = framework.createPlayer("lk_tester", world);

        player.placeBlock("minecraft:stone", 1, 100, 0).andWaitTicks(1);
        assertThat(world).hasBlockAt(1, 100, 0).ofType("minecraft:stone");
    }
}