compile-testing: a harness for asserting on javac output

One narrow job: asserting on what javac does

The project describes itself in one line: a library for testing javac compilation with or without annotation processors. That sentence is the whole scope, and it is worth being precise about what it implies.

The subject under test is the compiler, not your application code. A team reaches for this library when it has written an annotation processor and wants to know what the processor does when javac runs over a source file. The questions it answers are the ones a compiler test needs answered. Did the processor run at all. Which diagnostics did javac report, and on which line and file. Was an error raised, and was it the expected one. What did the processor generate.

The word without in the description matters just as much. The library supports testing compilation with annotation processors and testing compilation without them, which is the pair of cases a processor author needs to prove that a diagnostic comes from the processor rather than from the compiler itself.

The practical effect is that a processor test stops being a subprocess invocation with a directory of golden files and becomes a set of assertions against a result object. The library does the work of setting up an in-process compilation, and the test reads the outcome.

What the project is not is broader than that. It is not a test runner, it does not define assertions for your business logic, and it does not replace JUnit in your project. It is a helper for one specific kind of test, and its value is in how narrowly it does that one thing.

The readme points to javadoc because there is no example here

The readme is unusually thin, and it says why. After the one line description, it tells you to see the javadoc for usage examples, and that is the entirety of the guidance.

That is a deliberate choice rather than an oversight, and it has consequences for anyone evaluating the project. There is no installation section, no dependency snippet, no code example and no configuration in the readme. The documentation link points at javadoc.io for the artifact, which is where the API and the examples live.

For a Java library this is defensible. The API surface is what matters, and javadoc with usage examples is a fine place for it. But it means the decision to adopt the library cannot be made from the readme alone, and it means anyone writing a tutorial, a blog post or an internal adoption note will have to go read the generated javadoc for the current version.

The javadoc badge in the readme is not a secondary nicety here. It is the project's documentation, and the readme's single actionable instruction is to go there. A team that evaluates libraries by whether the readme shows a working example in thirty seconds will pass this one over, which is a reason to evaluate it on the artifact and the API instead.

The top level of the repository reflects the same minimalism. Alongside the readme there is the source in src/, a pom.xml, a checkstyle.xml, a LICENSE.txt, a CONTRIBUTING.md and the .github directory. There is no examples directory, no sample module and no integration test project at the top level, so the test fixtures and their expected outputs live inside src rather than in a separate demo tree.

Maven coordinates, javadoc and the release pipeline

The publishing setup is conventional for a Google library and gives you the concrete facts you need to depend on it.

The artifact is com.google.testing.compile:compile-testing, published to Maven Central, with the badge pointing at the Sonatype Central listing and the javadoc published on javadoc.io under the same coordinates. The group id is not com.google, which is worth noting if your dependency management groups by organisation, because compile-testing is maintained under the Google testing group rather than the core Google group.

The build is a Maven project with a pom.xml at the root, and the CI badge points at a GitHub Actions workflow named ci.yml running on the main branch, with a separate Maven release workflow. The presence of a checkstyle.xml at the repository root means the build enforces a style configuration, and CONTRIBUTING.md covers the contribution process.

The release history shows a steady cadence. v0.24.0 was tagged on 2026-10-09, v0.23.0 on 2025-09-10, and v0.22.0 on 2025-09-03. Two of those three landed within a week of each other in September 2025, and the current version is a year later.

The 0.x version line is the thing to think about. A library at 0.24.0 signals that its API may still change between minor versions, so the practical advice for an annotation processor team is to pin the version and to read the release notes for the version you upgrade to, rather than assuming the semver promises you are used to from a 1.x artifact.

Why an in-process compiler test beats a subprocess

The mechanism behind the library is not described in the readme, so what follows is inference from what the library is for rather than a documented claim. The reason this kind of library exists at all is instructive.

Testing an annotation processor the obvious way means invoking javac as an external process on a temporary source file, capturing the diagnostics it printed, and matching them against expectations. That approach has a pile of incidental fragility. The path to the compiler differs between machines. The classpath has to be assembled by hand, including the processor itself. Diagnostics are formatted as text and parsed back, so a change in javac message formatting breaks your test for no good reason. And the whole thing runs out of process, so failures are reported as an exit code plus some stderr rather than as structured data.

An in-process approach, using the compiler API that javac itself exposes, removes all of that. The compiler runs in the same JVM as the test, the diagnostics arrive as objects with a message, a position and a source, and the test asserts on those objects rather than on text. The processor is registered directly rather than through a service loader file on a hand built classpath.

The cost of that approach is that the library must run inside a JVM whose javac matches the one under test, which is one reason version alignment between the library and your JDK matters more here than for an ordinary utility.

None of this is documented in the readme, which is the honest limitation of this article on the mechanism. The javadoc is the place to confirm the actual API shape.

Where compile-testing is the wrong tool

There are clear cases where this library does not apply.

If you are not writing a compiler plugin or an annotation processor, it does nothing for you. A team with ordinary application code and ordinary unit tests has no use for assertions on compiler diagnostics, and adding this dependency would be cargo cult.

If your processor already works by transforming a source tree and you are testing the transformation output, a different tool is a better fit. The library is about compilation, not about the code that your processor emits at runtime.

If you need to test a non Java annotation processor, for example one written in Kotlin, the library is still about javac as the compiler, so it depends on how the processor is registered rather than on the language it is written in. That is workable, but it means the integration question is worth checking in the javadoc.

If you need end to end coverage of a build that runs the processor across many modules, with incremental compilation and processor path configuration, this library sits at the wrong level. It is a unit test harness for a single compilation, and the documentation does not describe a multi module or incremental build story.

The last case is the most common one for a team evaluating it out of curiosity. The scope is narrow enough that if you cannot name a specific diagnostic assertion you want to make, you should not add the dependency.

Licence, maintenance state and the upgrade cost

The licence is Apache-2.0, held by Google, Inc. with the copyright dated 2013, and the readme reproduces the standard licence text: The full text is in LICENSE.txt at the repository root, and the readme carries the notice itself:

Copyright 2013 Google, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Apache-2.0 is the licence most Java infrastructure is published under, and it places no obligation on a test scoped dependency that would not already exist for the rest of your build. The one thing to remember is the attribution and notice condition, which means that if you redistribute a jar that bundles this library, the notices travel with it.

On maintenance, the repository is not archived and the last push was on 2026-10-09, the same day as the v0.24.0 tag. The recent release history is one version per year with a cluster in September 2025, which is consistent with a library that moves when the compiler API changes rather than on a schedule.

For an annotation processor team, the upgrade cost is low but not zero. It is a test scoped dependency, so a version bump does not reach production, and the main risk is API change in a 0.x line. The cost of an upgrade is reading the javadoc diff and the release notes for the new version, and the readme will not help you there because it contains no API description at all.

The practical summary is that this is a stable, narrowly scoped, permissively licensed test helper whose documentation lives in its javadoc, and that is both its strength and its most common source of friction.

Editorial conclusion

Adopt compile-testing if you maintain an annotation processor or a compiler plugin and you need assertions on what javac emits, since that is the single problem the library exists to solve and it is published on Maven Central with javadoc as the usage reference. Do not adopt it as a general testing framework or as a replacement for a builder style API in your own project, since it targets one narrow scenario. Before you start, open the javadoc on javadoc.io rather than expecting the readme to show you an example, and check that the version you depend on matches the javac release your build uses, given the release cadence visible in the tags.

Frequently asked questions

Official sources

1. google/compile-testing on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases