Unit and runtime tests

Run a focused test in its owning module first. For example, after changing capability composition:

./gradlew :anvil-capability:capability-common:test
./gradlew verifyArchitecture
./gradlew :anvil-testkit:tests:runtime:test

A focused integration test can use temporary files, sockets, isolated protocol workers, or Gradle TestKit without starting Minecraft. Its location follows the owner of the behavior.

Use the relevant module suite

Use --tests '*ClassName' to select the regression class when appropriate. Tests should establish an observable contract or failure outcome, rather than repeat the implementation's steps.

Workspace tests mirror the directory, preparation, and snapshot implementation packages. Agent client tests exercise host lifetimes and connections; server tests exercise embedded handlers and endpoints. Cross-process assertions belong in the live suite, with the independently compiled fixture checking the public client and server API dependencies.

Run the Docker engine tests

Tests that start containers on a real Docker engine live in the module's dockerTest test suite, in src/dockerTest/java, apart from its test suite. test, and therefore build, never runs them, so neither needs Docker. Run them with a Docker engine available:

./gradlew dockerTest
./gradlew :anvil-environment:execution:execution-docker:dockerTest

They run in the image anvil.docker.testImage in gradle.properties names, the only place it is named. It is a copy of eclipse-temurin:21-jdk on the GitHub Container Registry, which the Docker test image workflow refreshes when dev changes the reference, weekly and on demand. A test pulls the image when the engine does not have it; the package is public, so that needs no login, and CI pulls it with its GITHUB_TOKEN. To test against another image for a run, pass -Panvil.docker.testImage=<image>; to change it for everyone, change the property, and the workflow copies the new image once the change reaches dev.

Check cross-module discovery

anvil-testkit/tests/runtime exercises protocol library selection, platform providers, and capability composition without Minecraft. It consumes actual runtime dependencies and the separately built external-extension JAR.

./gradlew :anvil-testkit:tests:runtime:test
./gradlew :anvil-testkit:tests:runtime:test --tests '*ExternalProviderDiscoveryIntegrationTest'

Use these tests for ranked and explicit protocol library selection, ties between libraries, missing dependencies, external service discovery, and offline authentication defaults. The runtime suite also holds JavaVersionTableDocumentationTest, which compares the Java guide's table with the platform providers' version data. They complement module-level tests by testing the installed composition rather than manually assembled implementation objects.

Check the IntelliJ package

Tests live with the module that owns the behaviour; intellij-api has no test sources. Each feature module's tests load its real descriptor fragment through a test-only META-INF/plugin.xml, which adds the shared services and a stand-in for any contract another module implements, so actions, settings pages, and extensions are registered exactly as in the plugin. Test fixtures shared by several modules, such as SwingTestSupport and the controlled tooling process, live in intellij-common/src/testFixtures and are never packaged in the plugin. The plugin's own tests check how the fragments compose: service bindings, the settings tree, cross-module action groups, editor extensions, and the tool window.

Run all module tests together:

./gradlew :anvil-integration:integration-intellij:test

./gradlew :anvil-integration:integration-intellij:buildPlugin :anvil-integration:integration-intellij:verifyPlugin

The verifier checks the declared IDE baselines. To verify against an installed IDE, pass -Panvil.intellijVerificationPath=/absolute/path/to/idea. IDE tests exercise native model import and session behavior without starting Minecraft. Project tooling describes the contract; installation describes the ZIP workflow.

Validate UI changes against the current IDE as well as the compilation baseline:

./gradlew :anvil-integration:integration-intellij:intellij-scenario:testCurrentIde --tests '*SectionTabsPlatformTest' -Panvil.intellijVerificationPath=/absolute/path/to/idea

This separate test task keeps baseline compilation intact while using the selected IDE's runtime, test framework, and sandbox. Omit the path to use the configured current verification version. The UI sandbox excludes optional Ultimate product hooks, whose obfuscated classes collide under the test framework's flat class loader; Anvil, Java, Gradle, and the IDE's native themes remain loaded. Section-switcher tests exercise both standard themes and the current IDE's Islands themes; editor tab styling can differ from the Services-style JBTabbedPane used for Anvil's sections.

Both declared baselines currently verify as compatible with no deprecated or scheduled-for-removal API usage. The remaining findings are experimental APIs the Gradle adapter and source discovery rely on (ExternalSystemBuildEvent and TrustedProjectsListener); recheck them when raising the baseline.

UI tests lay out and paint their screens offscreen on every run. To inspect the renders, add -Panvil.uiCaptures; the images are written to intellij-scenario/build/reports/ui-captures:

./gradlew :anvil-integration:integration-intellij:intellij-scenario:test -Panvil.uiCaptures

Finish with the build

./gradlew build

The normal build skips the whole real-server test task. For behavior involving Minecraft sessions, packet bindings, forwarding, or platform agents, also run the relevant live coverage. For dependency or publication changes, verify a separate consumer through local publication.