Module io.github.ascopes.jct

Package io.github.ascopes.jct.junit

Annotation Type JavacCompilerTest

@API(since="0.0.1",
     status=STABLE)
@ArgumentsSource(JavacCompilersProvider.class)
@DisabledInNativeImage
@Documented
@ParameterizedTest(name="for compiler \"{0}\"")
@Retention(RUNTIME)
@Tag("java-compiler-testing-test") @Tag("javac-test")
@Target({ANNOTATION_TYPE,METHOD})
@TestTemplate
public @interface JavacCompilerTest

Annotation that can be applied to a JUnit parameterized test to invoke that test case across multiple compilers, each configured to a specific version in a range of Java language versions.

This will also add the "java-compiler-testing-test" tag and "javac-test" tags to your test method, meaning you can instruct your IDE or build system to optionally only run tests annotated with this method for development purposes. As an example, Maven Surefire could be instructed to only run these tests by passing -Dgroup="javac-test" to Maven.

If your build is running in a GraalVM Native Image, then this test will not execute, as the Java Compiler Testing API is not yet tested within Native Images.

For example, to run a simple test on Java 11 through 17 (inclusive):

   class SomeTest {
     @JavacCompilerTest(minVersion = 11, maxVersion = 17)
     void canCompileHelloWorld(JctCompiler> compiler) {
       // Given
       try (var workspace = Workspaces.newWorkspace()) {
         workspace
            .createFile("org", "example", "HelloWorld.java")
            .withContents("""
              package org.example;

              public class HelloWorld {
                public static void main(String[] args) {
                  System.out.println("Hello, World!");
                }
              }
            """);

         var compilation = compiler.compile(workspace);

         assertThat(compilation)
             .isSuccessfulWithoutWarnings();
       }
     }
   }
 

Since:

0.0.1

Author:

Ashley Scopes

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Class<? extends JctCompilerConfigurer<?>>[]	configurers	Get an array of compiler configurer classes to apply in-order before starting the test.
int	maxVersion	Maximum version to use (inclusive).
int	minVersion	Minimum version to use (inclusive).
VersionStrategy	versionStrategy	The version strategy to use.

Element Details

minVersion

int minVersion

Minimum version to use (inclusive).

By default, it will use the lowest possible version supported by the compiler. This varies between versions of the JDK that are in use.

If the version is lower than the minimum supported version, then the minimum supported version of the compiler will be used instead. This enables writing tests that will work on a range of JDKs during builds without needing to duplicate the test to satisfy different JDK supported version ranges.

Returns:

the minimum version.

Default:

-2147483648

maxVersion

int maxVersion

Maximum version to use (inclusive).

By default, it will use the highest possible version supported by the compiler. This varies between versions of the JDK that are in use.

If the version is higher than the maximum supported version, then the maximum supported version of the compiler will be used instead. This enables writing tests that will work on a range of JDKs during builds without needing to duplicate the test to satisfy different JDK supported version ranges.

Returns:

the maximum version.

Default:

2147483647

configurers

Class<? extends JctCompilerConfigurer<?>>[] configurers

Get an array of compiler configurer classes to apply in-order before starting the test.

Each configurer must have a public no-args constructor, and their package must be open to this module if JPMS modules are in-use, for example:

 module mytests {
   requires io.github.ascopes.jct;
   requires org.junit.jupiter.api;

   opens org.example.mytests to io.github.ascopes.jct;
 }
 

An example of usage:

   public class WerrorConfigurer implements JctCompilerConfigurer<RuntimeException> {
     @Override
     public void configure(JctCompiler compiler) {
       compiler.failOnWarnings(true);
     }
   }

   // ...

   class SomeTest {
     @JavacCompilerTest(configurers = WerrorConfigurer.class)
     void someTest(JctCompiler compiler) {
       // ...
     }
   }
 

Returns:

an array of classes to run to configure the compiler. These run in the given order.

Default:

{}

versionStrategy

VersionStrategy versionStrategy

The version strategy to use.

This determines whether the version number being iterated across specifies the release, source, target, or source and target versions.

The default is to specify the release.

Returns:

the version strategy to use.

Default:

RELEASE