These components are part of the internal API and should not be used by external + * modules. As such, they are not covered by the semantic versioning policy and may change + * without notice. */ +@API(since = "0.0.1", status = Status.INTERNAL) package io.github.ascopes.jct.annotations; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/DiagnosticAssert.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/DiagnosticAssert.java index 7a9fb0347..7f483501c 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/DiagnosticAssert.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/DiagnosticAssert.java @@ -183,11 +183,7 @@ public AbstractStringAssert threadName() { * Get assertions for the stack trace of the location the diagnostic was reported to. * * @return the assertions for the stack trace. - * @deprecated I have put up a pull request for AssertJ to support this functionality in AssertJ - * Core. Once this is merged, this return type will be changed to use the AssertJ - * implementation. */ - @Deprecated(forRemoval = true) public StackTraceAssert stackTrace() { return new StackTraceAssert(actual.getStackTrace()); } diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/impl/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/impl/package-info.java index 5b998ac15..c30f26bff 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/impl/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/impl/package-info.java @@ -15,5 +15,13 @@ */ /** * Various internal helper types for assertions. + * + *
These components are part of the internal API and should not be used by external + * modules. As such, they are not covered by the semantic versioning policy and may change + * without notice. */ +@API(since = "0.0.1", status = Status.INTERNAL) package io.github.ascopes.jct.assertions.impl; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/package-info.java index e80e549e1..034ff13ee 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/assertions/package-info.java @@ -16,4 +16,8 @@ /** * Assertions to perform on the result of a compilation. */ +@API(since = "0.0.1", status = Status.EXPERIMENTAL) package io.github.ascopes.jct.assertions; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/impl/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/impl/package-info.java index 5d30aae54..32b5a7d15 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/impl/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/impl/package-info.java @@ -15,5 +15,13 @@ */ /** * Implementation details for compiler integrations. + * + *
These components are part of the internal API and should not be used by external + * modules. As such, they are not covered by the semantic versioning policy and may change + * without notice. */ +@API(since = "0.0.1", status = Status.INTERNAL) package io.github.ascopes.jct.compilers.impl; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/package-info.java index dd57af883..a79f06e54 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/compilers/package-info.java @@ -16,4 +16,8 @@ /** * Compiler frontends that allow invoking compilers easily from tests. */ +@API(since = "0.0.1", status = Status.EXPERIMENTAL) package io.github.ascopes.jct.compilers; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/impl/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/impl/package-info.java index db3e09e1a..749ff32d8 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/impl/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/impl/package-info.java @@ -15,5 +15,13 @@ */ /** * Internal implementations of containers and container groups. + * + *
These components are part of the internal API and should not be used by external + * modules. As such, they are not covered by the semantic versioning policy and may change + * without notice. */ +@API(since = "0.0.1", status = Status.INTERNAL) package io.github.ascopes.jct.containers.impl; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/package-info.java index e50015849..8c7212d9f 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/containers/package-info.java @@ -16,4 +16,8 @@ /** * Containers used to integrate with the JSR-199 API in a modular way. */ +@API(since = "0.0.1", status = Status.EXPERIMENTAL) package io.github.ascopes.jct.containers; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/diagnostics/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/diagnostics/package-info.java index 37a9bdd17..d32de3e74 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/diagnostics/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/diagnostics/package-info.java @@ -16,4 +16,8 @@ /** * Support for collecting and representing diagnostics from compiler implementations. */ +@API(since = "0.0.1", status = Status.EXPERIMENTAL) package io.github.ascopes.jct.diagnostics; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/ex/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/ex/package-info.java index eb5f50025..7777cae3a 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/ex/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/ex/package-info.java @@ -16,4 +16,8 @@ /** * Exceptions used within this API. */ +@API(since = "0.0.1", status = Status.EXPERIMENTAL) package io.github.ascopes.jct.ex; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/junit/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/junit/package-info.java index 657aac18e..19a2770d6 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/junit/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/junit/package-info.java @@ -16,4 +16,8 @@ /** * Additional functionality to simplify writing tests with Junit. */ +@API(since = "0.0.1", status = Status.EXPERIMENTAL) package io.github.ascopes.jct.junit; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/package-info.java index c608e6e62..20bb4c39f 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/package-info.java @@ -14,12 +14,14 @@ * limitations under the License. */ /** - * Tools for writing tests involving the Java compiler. + * Root package for the JCT library. */ - +@API(since = "0.0.1", status = Status.EXPERIMENTAL) @NonNullApi @NonNullImpl package io.github.ascopes.jct; import io.github.ascopes.jct.annotations.NonNullApi; import io.github.ascopes.jct.annotations.NonNullImpl; +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/impl/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/impl/package-info.java index 582ca56af..505b649e0 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/impl/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/impl/package-info.java @@ -15,5 +15,13 @@ */ /** * Internal objects for handling paths. + * + *
These components are part of the internal API and should not be used by external + * modules. As such, they are not covered by the semantic versioning policy and may change + * without notice. */ +@API(since = "0.0.1", status = Status.INTERNAL) package io.github.ascopes.jct.pathwrappers.impl; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/package-info.java index 3ffc25895..bc5176181 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/pathwrappers/package-info.java @@ -16,4 +16,8 @@ /** * Facilities for handling paths. */ +@API(since = "0.0.1", status = Status.EXPERIMENTAL) package io.github.ascopes.jct.pathwrappers; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/io/github/ascopes/jct/utils/package-info.java b/java-compiler-testing/src/main/java/io/github/ascopes/jct/utils/package-info.java index 487b1ceed..0156fc6c0 100644 --- a/java-compiler-testing/src/main/java/io/github/ascopes/jct/utils/package-info.java +++ b/java-compiler-testing/src/main/java/io/github/ascopes/jct/utils/package-info.java @@ -16,6 +16,12 @@ /** * Internal shared utilities. * - *
Nothing in here is exposed in the public API. + *
These components are part of the internal API and should not be used by external + * modules. As such, they are not covered by the semantic versioning policy and may change + * without notice. */ +@API(since = "0.0.1", status = Status.INTERNAL) package io.github.ascopes.jct.utils; + +import org.apiguardian.api.API; +import org.apiguardian.api.API.Status; diff --git a/java-compiler-testing/src/main/java/module-info.java b/java-compiler-testing/src/main/java/module-info.java index 0dcf449e3..4a227ab80 100644 --- a/java-compiler-testing/src/main/java/module-info.java +++ b/java-compiler-testing/src/main/java/module-info.java @@ -13,8 +13,83 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + /** - * Java compiler testing facilities. + * A framework for performing exhaustive integration testing against Java compilers in modern Java + * libraries, with a focus on full JPMS support. + * + *
The Java Compiler Testing API has a number of facilities for assisting in testing + * anything related to the Java compiler. This includes Javac plugins and JSR-199 annotation + * processors. + * + *
All test cases are designed to be as stateless as possible, with facilities to produce + * {@link io.github.ascopes.jct.pathwrappers.RamDirectory in-memory file systems} (using Google's + * JIMFS API), or using + * {@link io.github.ascopes.jct.pathwrappers.TempDirectory OS-provided temporary directories}. All + * file system mechanisms are complimented with a fluent API that enables writing expressive + * declarations without unnecessary boilerplate. + * + *
Integration test cases can be written to cross-compile against a range of Java compiler + * versions, with the ability to provide as much or as little configuration detail as you wish. + * Additionally, APIs can be easily + * {@link io.github.ascopes.jct.compilers.AbstractJctCompiler extended} to integrate with any other + * JSR-199-compliant compiler as required. + * + *
Compilation results are complimented with a suite of + * {@link io.github.ascopes.jct.assertions.JctAssertions assertion} facilities that extend the + * AssertJ API to assist in writing fluent and human-readable test cases for your code. Each of + * these assertions comes with specially-developed human-readable error messages and formatting. + * + *
Full {@link io.github.ascopes.jct.junit.JavacCompilerTest JUnit5 integration} + * is provided to streamline the development process, letting you focus on your + * code rather than flaky test environments and dependency management.
+ * + *
+ * import static io.github.ascopes.jct.assertions.JctAssertions.assertThatCompilation;
+ * import static io.github.ascopes.jct.pathwrappers.RamDirectory.newRamDirectory;
+ *
+ * import io.github.ascopes.jct.compilers.JctCompiler;
+ * import io.github.ascopes.jct.junit.JavacCompilerTest;
+ *
+ * import org.example.processor.JsonSchemaAnnotationProcessor;
+ * import org.skyscreamer.jsonassert.JSONAssert;
+ *
+ * class JsonSchemaAnnotationProcessorTest {
+ * {@literal @JavacCompilerTest(minVersion=11, maxVersion=19)}
+ * void theJsonSchemaIsCreatedFromTheInputCode(JctCompiler<?, ?> compiler) {
+ * // Given
+ * var sources = newRamDirectory("sources")
+ * .createDirectory("org", "example", "tests")
+ * .copyContentsFrom("src", "test", "resources", "code", "schematest");
+ *
+ * // When
+ * var compilation = compiler
+ * .addSources(sources)
+ * .addAnnotationProcessors(new JsonSchemaAnnotationProcessor())
+ * .addAnnotationProcessorOptions("jsonschema.verbose=true")
+ * .failOnWarnings(true)
+ * .showDeprecationWarnings(true)
+ * .compile();
+ *
+ * // Then
+ * assertThatCompilation(compilation)
+ * .isSuccessfulWithoutWarnings();
+ *
+ * assertThatCompilation(compilation)
+ * .diagnostics().notes().singleElement()
+ * .message().isEqualTo(
+ * "Creating JSON schema in Java %s for package org.example.tests",
+ * compiler.getRelease()
+ * );
+ *
+ * assertThatCompilation(compilation)
+ * .classOutputs().packages()
+ * .fileExists("json-schemas/UserSchema.json").contents()
+ * .isNotEmpty()
+ * .satisfies(contents -> JSONAssert.assertEquals(...));
+ * }
+ * }
+ *