Prepare once. Run tests from the gutter.

Consumer setup

Use Java 21+, Maven 3.9+, and Linux or macOS for Unix-domain sockets. Your LightKeeper version must contain IDE test setup. Keep the prepare-server execution and framework dependency.

1. For sourceType=path, package the plugin so the configured JAR exists (mvn package for the single-module setup in Getting Started). For sourceType=maven, install locally developed plugin artifacts with mvn install. Calling prepare-server directly does not run these lifecycle phases.
2. Run the configured preparation execution in the test module. From a multi-module project root, select that module explicitly using -pl, as shown below.
3. Check that output says Created IDE test setup or Reused IDE test setup, with the expected module and platform.
4. Click the JUnit gutter button beside your test class or method.

From the directory containing the test module's pom.xml (or your project root for a single-module project), use the execution from Getting Started:

mvn lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true

From a multi-module project root, select the test module by its artifactId. Replace my-plugin-e2e with your module's artifact ID; the leading : avoids typing its directory path:

mvn -pl :my-plugin-e2e lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true

Alternatively, point Maven directly at the test module's POM. Replace the example path with your own:

mvn -f testing/my-plugin-e2e/pom.xml lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true

The text after @ must match the preparation execution's <id> in that module's effective POM. For example, an execution named prepare-server-paper requires lightkeeper:prepare-server@prepare-server-paper. The goal name and execution ID are independent.

Select only the test module for this preparation command. Use -am when building its dependencies in the earlier packaging/install step; adding it here also selects upstream modules for the preparation goal.

Each test module owns its .lightkeeper/ide/ discovery record. Preparation never selects a parent or sibling runtime automatically.

LightKeeper contributor setup

Install the current plugin, framework, agent, and fixture before invoking the goal directly:

mvn -pl lightkeeper-integration-tests -am install \
  -DskipTests -DskipITs -Dlightkeeper.skip=true -Dmaven.javadoc.skip=true
mvn -pl lightkeeper-integration-tests \
  lightkeeper:prepare-server@prepare-server-paper -Dlightkeeper.ide=true

Replace prepare-server-paper with prepare-server-spigot to select Spigot. The execution supplies platform identity; lightkeeper.expectedServerType is only a Failsafe assertion input.

Daily use, persistence, and refresh

Test-only edits need ordinary IDE compilation. mvn clean removes target while preserving the runtime under the owning module's .lightkeeper/ide/. Compile tests again to restore its discovery anchor. Ordinary unit tests do no LightKeeper work.

After plugin changes, package or install the plugin and repeat preparation. Rebuild the LightKeeper agent after changes requiring new agent/protocol behavior. Matching packaged inputs reuse the runtime; changed hashes or launch settings create a new preparation.

Worlds, plugin data, and other server state persist across runs. To start fresh:

Run this from the test module's directory, or retain the same -pl/-f selection and execution ID used during initial setup:

mvn lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true -Dlightkeeper.ide.refresh=true

Refresh creates a new preparation and switches later launches atomically. It never changes a runtime held by an active test. Old preparations are not pruned automatically. For a complete reset, close running tests, move the module's .lightkeeper/ directory to trash, and repeat setup.

Overrides and validation

-Dlightkeeper.runtimeManifestPath=/absolute/path/runtime-manifest.json overrides discovery. An invalid explicit path fails immediately; it does not fall back. Lightkeeper.start(Path) follows the same contract. For custom IDE class-output layouts, use the explicit property.

Preparation fingerprints resolved server metadata, JVM settings, the embedded agent, deployed plugins, world templates, and overlays. Launch checks ownership and durable files. It cannot detect unbuilt edits or new remote snapshots until Maven resolves those inputs during another preparation.

Troubleshooting

No plugin found for prefix 'lightkeeper': Maven could not resolve the plugin before LightKeeper could run. In a multi-module project, first check that you selected the test module with -pl, -f, or by running from its directory. A plugin declared only in a child POM is not visible in the root POM. Verify that the selected module declares the LightKeeper Maven plugin and version, and that its artifact is installed locally or available through the configured pluginRepositories. See Getting Started for repository setup.

Using fully qualified plugin coordinates can bypass prefix lookup, but it does not select a child module or load that child's execution configuration. Moving the plugin declaration into the root POM also does not make preparation automatically choose the test module.

Missing or corrupt discovery: repeat preparation in the owning module. Moved checkout: repeat setup at the new path. Stale runtime: rebuild packaged inputs, then prepare again. Busy runtime: close the other test/server. Dirty state: use -Dlightkeeper.ide.refresh=true. Missing server cache: repeat preparation to recreate required artifacts.

Debug framework/JUnit code with your IDE's test debugger. Bukkit/Paper code runs in a separate JVM; use the Maven plugin's server JVM debug arguments for it.

The underlying command-line class/method workflow was verified with Temurin 25.0.4 (release 21), Maven 3.9.9, and Linux. The IntelliJ gutter UI was not automated.