Skip to content

Java projects

langadapter.java.adapter.JavaAdapter supports Maven and Gradle projects with the context's JDK. JUnit runs the tests, JaCoCo measures coverage and PIT measures mutation outcomes. Java tests run as Java runs them: the measurement helper that makes Python tests deterministic is not used. The context names the JDK by its java executable, such as Interpreter(path="/opt/jdk-21/bin/java"), in a container by its path inside the container.

Build and tools

The build can use a different JDK from the measured runtime, which LANGADAPTER_BUILD_JAVA_HOME in ProjectContext.environment selects. Project resolution never rereads it from the process environment. The context's runtime still compiles and runs the measured tests. Settings gives this variable and the build launcher's variables with their defaults.

The setup check looks up the build launcher as a run does and reports a missing launcher before any run. Outside Windows the project's wrapper (mvnw, gradlew) runs with the interpreter its first line names, sh when it names none, without being executed itself, so a project copy in a directory mounted without execution (a cluster's /dev/shm, many /tmp directories) still builds, and a bash wrapper runs under bash where sh is another shell. Windows runs mvnw.cmd and gradlew.bat directly.

The measurement tools (the JUnit console launcher, JaCoCo and PIT) are jars in a tool cache, which a run fills from Maven Central once. Settings names the cache's directory, the switch that forbids downloads and where a container reads both. JaCoCo's and PIT's jars and the other jars of fixed versions must match the SHA-256 that LangAdapter pins for them, downloaded or found in the cache. The other jars, chosen by the project's JUnit version, are checked against their published SHA-1 when they are downloaded. The quick check never downloads, and the tool check downloads only when the request sets allow_acquisition, as Setup checks explains with the build steps it tries. Only then does the tool check fetch the jars it needs within its time limit: the JUnit launcher's for its test discovery, and JaCoCo's and PIT's before it starts them. Otherwise a jar not yet downloaded is left to the first run. When LANGADAPTER_JAVA_TOOLS_OFFLINE forbids downloads, either check reports such a jar as missing setup. probe_capabilities() is not a setup check: it resolves the project with its build and prepares the tool jars as a run does, so it downloads a missing jar unless downloads are off. The jars keep their own licenses. THIRD_PARTY_NOTICES.md, which ships with LangAdapter beside its LICENSE, lists each one, what it is used for and its license.

Suites

A file whose name ends in Test.java, Tests.java, TestCase.java or IT.java is a test file. The test file named for a source file Calc.java is CalcTest.java.

Suite runs compile every declared Java helper source and put declared resources on the test classpath. A class from the project's test source directories that a listed file uses is compiled with it, and the build's own test output directory stays on the classpath. Other unlisted files are not added. The context's JVM flags and the project's test JVM settings apply to execution and measurement. Every run executes one test at a time, as PIT does: Jupiter's parallel execution is off whatever the project configures. PIT measures the top-level test classes a suite run selects, on its classpath in its order, so a JUnit 4 nested class runs under PIT only where the suite run runs it. collect_suite runs native JUnit discovery without executing test bodies, so parameterized invocations and dynamic children appear only at execution. run_as_delivered checks each declared test file on its own in a private copy, with its declared helpers, under the request's timeout_s as Python projects describes. Optional source replacements do not change the input files.

Suite, collection and as-delivered results keep the launcher's whole output, with the bound Python projects describes. A structure check returns the offending source text whole under the same bound.

Per-test coverage needs tests that do not overlap: JaCoCo's probes are process-wide and cannot separate concurrent tests. When a run still observes overlapping tests, per-test coverage is unsupported. A requested warm-up pass of the per-test evidence operation is discarded, and each pass starts a fresh JVM, so it does not warm the measured JVM. timeout_journal=True on a suite run records the tests active when the process was stopped. Several active tests stay a diagnostic, never an invented single killer.

Mutation runs

PIT takes a session's workers as Mutation sessions describes, as the number of its minion threads (--threads) a run uses. PIT runs one unit of mutants per thread and by default puts all mutants of a class in one unit, which keeps one or two threads busy. With more than one worker, a unit holds at most ten mutants of a class (PIT's mutationUnitSize), so the target's mutants spread over the threads. PIT counts the mutants only within the run, so the size is fixed rather than taken from their number. Each unit starts its own minion JVM. With one worker, PIT's default of one unit per class applies. A run records the size it used as its mutation_unit_size setting. PIT's timeout rule and each minion's JVM settings do not change with it.

PIT times out each test of a mutant's run, not the suite: a test's time under the mutant is limited to a factor times its time in the unmutated run, plus a constant. A TimeoutRule gives PIT its factor and, as the constant, its minimum_s, which the run records as its per_mutant_timeout. PIT has no cap, so a rule with cap_s is refused. A whole number of seconds is a fixed limit per test, and without either PIT's own factor and constant apply.

What Java does not provide

Automatic restoration of static state, arbitrary random seeding, leak recording and reverse-order execution are not implemented for Java. A suite run also refuses module_under_test and isolation_config: Java runs the project's own test configuration. Requests for them are refused explicitly, never silently ignored. sources.code_smells and tests.profile_suite are not implemented and answer unsupported. Scores and partial results says what a failed or incomplete measurement supplies.

Files that a Java test writes into the project directory stay for later test runs unless a run asks to remove them with remove_created_files=True, as Prepared copies describes. The project's build output stays.

Java in a Linux container you run yourself is described in Containers, and warmed JVM timing in Timing.