Skip to content

docs: clarify plugin JAR selection and IDE module setup #150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PimvanderLoos merged 1 commit into from
Nov 6, 2026
Merged

docs: clarify plugin JAR selection and IDE module setup #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 24 additions & 2 deletions getting-started.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,8 @@ <h2>1. Add framework dependency</h2>

<section class="panel">
<h2>2. Configure prepare + cleanup goals</h2>
<p>The Maven plugin provisions its embedded runtime agent automatically.</p>
<p>The Maven plugin provisions its embedded runtime agent automatically. Your plugin under test must be
listed explicitly in <code>plugins</code>; it is not selected automatically from the current project.</p>
<pre><code data-maven-plugin="lightkeeper">&lt;plugin&gt;
&lt;groupId&gt;com.github.PimvanderLoos.LightKeeper&lt;/groupId&gt;
&lt;artifactId&gt;lightkeeper-maven-plugin&lt;/artifactId&gt;
Expand All @@ -74,6 +75,12 @@ <h2>2. Configure prepare + cleanup goals</h2>
&lt;serverType&gt;paper&lt;/serverType&gt;
&lt;userAgent&gt;LightKeeper/${project.version} (https://example.com/my-plugin)&lt;/userAgent&gt;
&lt;runtimeManifestPath&gt;${project.build.directory}/lightkeeper/runtime-manifest.json&lt;/runtimeManifestPath&gt;
&lt;plugins&gt;
&lt;plugin&gt;
&lt;sourceType&gt;path&lt;/sourceType&gt;
&lt;path&gt;${project.build.directory}/${project.build.finalName}.jar&lt;/path&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;execution&gt;
Expand All @@ -88,11 +95,26 @@ <h2>2. Configure prepare + cleanup goals</h2>
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;</code></pre>
<p><code>userAgent</code> may be set in the plugin-level <code>configuration</code>, as a shared value,
or in an execution's <code>configuration</code>, 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.</p>
<p>The <code>path</code> above refers to the JAR built by this Maven module, normally
<code>target/&lt;artifactId&gt;-&lt;version&gt;.jar</code>. During <code>mvn verify</code>, Maven runs
<code>package</code> before LightKeeper's <code>pre-integration-test</code> preparation, which copies the JAR
into the test server's <code>plugins/</code> directory. The file must exist when preparation runs.
If shading or another packaging step produces a separate deployable JAR, point <code>path</code> to that
output, including its classifier if applicable. Use the same JAR you would install on a normal server.</p>
<p>For a separate integration-test module, reference the plugin module's built JAR or use
<code>sourceType=maven</code> with its <code>groupId</code>, <code>artifactId</code>, and <code>version</code>.
The path above always refers to the module containing this configuration.</p>
</section>

<section class="panel">
<h2>3. Pass runtime manifest to tests</h2>
<p>Put this configuration in Maven Failsafe. Run integration tests with <code>mvn verify</code>. For IDE gutter launches, use the <a href="ide-testing.html">IDE setup guide</a>.</p>
<p>Put this configuration in Maven Failsafe in the module containing the integration tests. Run integration
tests with <code>mvn verify</code>. For IDE gutter launches, use the <a href="ide-testing.html">IDE setup guide</a>,
including its module-selection commands when running from a multi-module project root.</p>
<pre><code>&lt;systemPropertyVariables&gt;
&lt;lightkeeper.runtimeManifestPath&gt;
${project.build.directory}/lightkeeper/runtime-manifest.json
Expand Down
36 changes: 32 additions & 4 deletions ide-testing.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,31 @@ <h2>Consumer setup</h2>
<p>Use Java 21+, Maven 3.9+, and Linux or macOS for Unix-domain sockets. Your LightKeeper version must
contain IDE test setup. Keep the <a href="getting-started.html">prepare-server execution and framework dependency</a>.</p>
<ol>
<li>Package or install all locally developed plugins referenced by your LightKeeper configuration.</li>
<li>Run the configured preparation execution from the module or reactor owning the tests.</li>
<li>For <code>sourceType=path</code>, package the plugin so the configured JAR exists
(<code>mvn package</code> for the single-module setup in <a href="getting-started.html">Getting Started</a>).
For <code>sourceType=maven</code>, install locally developed plugin artifacts with <code>mvn install</code>.
Calling <code>prepare-server</code> directly does not run these lifecycle phases.</li>
<li>Run the configured preparation execution in the test module. From a multi-module project root,
select that module explicitly using <code>-pl</code>, as shown below.</li>
<li>Check that output says <code>Created IDE test setup</code> or <code>Reused IDE test setup</code>, with the expected module and platform.</li>
<li>Click the JUnit gutter button beside your test class or method.</li>
</ol>
<p>From the directory containing the test module's <code>pom.xml</code> (or your project root for a
single-module project), use the execution from <a href="getting-started.html">Getting Started</a>:</p>
<pre><code>mvn lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true</code></pre>
<p>The execution ID after <code>@</code> must match your POM. In a multi-module project each child owns its
<code>.lightkeeper/ide/</code> discovery record. Preparation never selects a parent or sibling runtime.</p>
<p>From a multi-module project root, select the test module by its <code>artifactId</code>. Replace
<code>my-plugin-e2e</code> with your module's artifact ID; the leading <code>:</code> avoids typing its
directory path:</p>
<pre><code>mvn -pl :my-plugin-e2e lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true</code></pre>
<p>Alternatively, point Maven directly at the test module's POM. Replace the example path with your own:</p>
<pre><code>mvn -f testing/my-plugin-e2e/pom.xml lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true</code></pre>
<p>The text after <code>@</code> must match the preparation execution's <code>&lt;id&gt;</code> in that module's
effective POM. For example, an execution named <code>prepare-server-paper</code> requires
<code>lightkeeper:prepare-server@prepare-server-paper</code>. The goal name and execution ID are independent.</p>
<p>Select only the test module for this preparation command. Use <code>-am</code> when building its dependencies
in the earlier packaging/install step; adding it here also selects upstream modules for the preparation goal.</p>
<p>Each test module owns its <code>.lightkeeper/ide/</code> discovery record. Preparation never selects a parent
or sibling runtime automatically.</p>
</section>
<section class="panel">
<h2>LightKeeper contributor setup</h2>
Expand All @@ -67,6 +84,8 @@ <h2>Daily use, persistence, and refresh</h2>
agent after changes requiring new agent/protocol behavior. Matching packaged inputs reuse the runtime;
changed hashes or launch settings create a new preparation.</p>
<p>Worlds, plugin data, and other server state persist across runs. To start fresh:</p>
<p>Run this from the test module's directory, or retain the same <code>-pl</code>/<code>-f</code> selection
and execution ID used during initial setup:</p>
<pre><code>mvn lightkeeper:prepare-server@prepare-server -Dlightkeeper.ide=true -Dlightkeeper.ide.refresh=true</code></pre>
<p>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
Expand All @@ -83,6 +102,15 @@ <h2>Overrides and validation</h2>
</section>
<section class="panel">
<h2>Troubleshooting</h2>
<p><code>No plugin found for prefix 'lightkeeper'</code>: Maven could not resolve the plugin before LightKeeper
could run. In a multi-module project, first check that you selected the test module with <code>-pl</code>,
<code>-f</code>, 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 <code>pluginRepositories</code>.
See <a href="getting-started.html">Getting Started</a> for repository setup.</p>
<p>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.</p>
<p>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 <code>-Dlightkeeper.ide.refresh=true</code>. Missing server cache:
Expand Down
Loading