From 2f2bf2bb089c81186e08a9dea41f26b744daa440 Mon Sep 17 00:00:00 2001 From: Pim van der Loos Date: Fri, 6 Nov 2026 16:06:24 +0100 Subject: [PATCH] docs: clarify plugin JAR selection and IDE module setup Complete the consumer setup guides by identifying the deployable plugin JAR and explaining shared userAgent configuration. Make IDE preparation commands explicit about the owning module and execution ID, with multi-module examples and prefix-resolution troubleshooting. These changes address both reported setup gaps without changing runtime behavior. --- getting-started.html | 26 ++++++++++++++++++++++++-- ide-testing.html | 36 ++++++++++++++++++++++++++++++++---- 2 files changed, 56 insertions(+), 6 deletions(-) diff --git a/getting-started.html b/getting-started.html index 0ebf9a1b..cd18b664 100644 --- a/getting-started.html +++ b/getting-started.html @@ -61,7 +61,8 @@

1. Add framework dependency

2. Configure prepare + cleanup goals

-

The Maven plugin provisions its embedded runtime agent automatically.

+

The Maven plugin provisions its embedded runtime agent automatically. Your plugin under test must be + listed explicitly in plugins; it is not selected automatically from the current project.

<plugin>
     <groupId>com.github.PimvanderLoos.LightKeeper</groupId>
     <artifactId>lightkeeper-maven-plugin</artifactId>
@@ -74,6 +75,12 @@ 
2. Configure prepare + cleanup goals

                 <serverType>paper</serverType>
                 <userAgent>LightKeeper/${project.version} (https://example.com/my-plugin)</userAgent>
                 <runtimeManifestPath>${project.build.directory}/lightkeeper/runtime-manifest.json</runtimeManifestPath>
+                <plugins>
+                    <plugin>
+                        <sourceType>path</sourceType>
+                        <path>${project.build.directory}/${project.build.finalName}.jar</path>
+                    </plugin>
+                </plugins>
             </configuration>
         </execution>
         <execution>
@@ -88,11 +95,26 @@ 
2. Configure prepare + cleanup goals

         </execution>
     </executions>
 </plugin>
+

userAgent may be set in the plugin-level configuration, as a shared value, + or in an execution's configuration, as shown here. Execution-level values override shared + values with the same name. Both locations are valid; moving it does not require a LightKeeper version change. + Replace the example project URL with your own contact URL or email address.

+

The path above refers to the JAR built by this Maven module, normally + target/<artifactId>-<version>.jar. During mvn verify, Maven runs + package before LightKeeper's pre-integration-test preparation, which copies the JAR + into the test server's plugins/ directory. The file must exist when preparation runs. + If shading or another packaging step produces a separate deployable JAR, point path to that + output, including its classifier if applicable. Use the same JAR you would install on a normal server.

+

For a separate integration-test module, reference the plugin module's built JAR or use + sourceType=maven with its groupId, artifactId, and version. + The path above always refers to the module containing this configuration.

3. Pass runtime manifest to tests

-

Put this configuration in Maven Failsafe. Run integration tests with mvn verify. For IDE gutter launches, use the IDE setup guide.

+

Put this configuration in Maven Failsafe in the module containing the integration tests. Run integration + tests with mvn verify. For IDE gutter launches, use the IDE setup guide, + including its module-selection commands when running from a multi-module project root.

<systemPropertyVariables>
     <lightkeeper.runtimeManifestPath>
         ${project.build.directory}/lightkeeper/runtime-manifest.json
diff --git a/ide-testing.html b/ide-testing.html
index 2056e212..94e546f0 100644
--- a/ide-testing.html
+++ b/ide-testing.html
@@ -39,14 +39,31 @@ 
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. Package or install all locally developed plugins referenced by your LightKeeper configuration.
    2. 
-            
  2. Run the configured preparation execution from the module or reactor owning the tests.
    3. 
+            
  3. 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.
    4. 
+            
  4. Run the configured preparation execution in the test module. From a multi-module project root,
+                select that module explicitly using -pl, as shown below.
    5. 
             
  5. Check that output says Created IDE test setup or Reused IDE test setup, with the expected module and platform.
    6. 
             
  6. Click the JUnit gutter button beside your test class or method.
    7. 
         

+        
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

-        
The execution ID after @ must match your POM. In a multi-module project each child owns its
-            .lightkeeper/ide/ discovery record. Preparation never selects a parent or sibling runtime.

+        
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

@@ -67,6 +84,8 @@

Daily use, persistence, and refresh

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 @@ -83,6 +102,15 @@

Overrides and validation

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: