diff --git a/README.md b/README.md index b15c804b..4d88faa0 100644 --- a/README.md +++ b/README.md @@ -52,11 +52,6 @@ String aliceJson = "{\"id\":5678,\"name\":\"Alice\",\"age\":42}"; User alice = jsonb.fromJson(aliceJson, User.class); ``` -## How to run the TCK tests - -The JSON-B TCK tests are produced as a Maven artifact where the tests use Arquillian + JUnit. To run the TCK tests using your implementation, -include the TCK module and apply the appropriate Arquillian container. See the [Eclipse Yasson](https://github.com/eclipse-ee4j/yasson) repository for an example of this. - ## Links - [Official web site](https://eclipse-ee4j.github.io/jsonb-api) diff --git a/tck/README.md b/tck/README.md new file mode 100644 index 00000000..67dba8d3 --- /dev/null +++ b/tck/README.md @@ -0,0 +1,117 @@ +# TCK Reference Guide for Jakarta JSON Binding + +## Preface + +This guide describes how to download, install, configure, and run the Technology Compatibility Kit (TCK) used to verify the compatibility of an implementation of Jakarta JSON Binding (JSON-B) 1.0. + +The Jakarta JSON Binding TCK is built atop Arquillian, a portable and configurable automated test suite for authoring unit and integration tests in a Jakarta EE environment. + +The Jakarta JSON Binding TCK is provided under the Eclipse Public License v2.0. + +## Who Should Use This Guide + +This guide is for implementors of the Jakarta JSON Binding specification to assist in running the test suite that verifies the compatibility of their implementation. + +## About the Jakarta JSON Binding TCK + +The Jakarta JSON Binding TCK is designed as a portable, configurable and automated test suite for verifying the compatibility of an implementation of Jakarta JSON-B. The test suite is built atop JUnit and provides a series of extensions that allow runtime packaging and deployment of Jakarta EE artifacts for in-container testing (Arquillian). + +Each test class in the suite acts as a deployable unit. The deployable units, or artifacts, are defined in a declarative way using annotations. + +The declarative approach allows many of the tests to be executed in a standalone implementation of Jakarta JSON-B, accounting for a boost in developer productivity. However, an implementation is only valid if all tests pass using the in-container execution mode. The standalone mode is merely a developer convenience. + +The reason the Jakarta Bean Validation TCK must pass running in a Jakarta EE container is that Jakarta Bean Validation is part of Jakarta EE 8 itself. + +### TCK Components + +The Jakarta JSON-B TCK includes the following components: + +- **The test suite**, which is a collection of JUnit tests + +- **TCK documentation** accompanied by release notes identifying updates between versions. + +### Passing the Jakarta JSON Binding TCK + +In order to pass the Jakarta JSON-B TCK (which is one requirement for becoming a certified Jakarta JSON-B provider), you need to: + +- Pass the Jakarta JSON-B signature tests (see Running the Signature Test) asserting the correctness of the JSON-B API used. + +- Run and pass the test suite (see Running the TCK test suite). The test must be run within a Jakarta EE 8 container and pass with an unmodified set of tests. + +## Appeals process + +Any test case (i.e. `@Test` method), test case configuration (e.g. `@Deployment`), test entities, annotations and other resources may be challenged by an appeal. + +To initiate a challenge, refer to the [Jakarta EE TCK Process 1.0](https://jakarta.ee/committees/specification/tckprocess/) + +## Installation + +This chapter explains how to obtain the TCK and supporting software and provides recommendations for how to install/extract it on your system. + +### Obtaining the Software + +You can obtain a release of the Jakarta JSON-B TCK from Maven Central at the following coordinates: + +```xml + + jakarta.json.bind + jakarta.json.bind-tck + ${jsonb.version} + test + +``` + +### The TCK Environment + +To successfully run the JSON-B TCK, the following components are required: + +- [Apache Maven](https://maven.apache.org/install.html) +- Java 8 or newer +- An implementation of JSON-B +- An implementation of CDI + +The rest of the TCK software can simply be obtained via Maven dependency described in the "Obtaining the Software" section. + +## Configuration + +To configure the JSON-B TCK, the following elements are required: + +1. A Maven `` that pulls in the `jakarta.json.bind-tck` as described in the "Obtaining the Software" section +2. A Maven `` that pulls in an implementation of JSON-B +3. A Maven `` that pulls in an implementation of CDI (may be from the same depenency as (2)) +4. A Maven `` that pulls in an appropriate Arquillian container adapter +5. Configuration of the `maven-surefire-plugin` to include running the JSON-B TCK tests: + + ``` + + maven-surefire-plugin + 3.0.0-M4 + + + jakarta.json.bind:jakarta.json.bind-tck + + + + ``` + +6. Any runtime-specific configuration needed in order to enable JSON-B functionality + +## Reports + +Since tests are run using the `maven-surefire-plugin`, test reports can also be produced and configured using the [`maven-surefire-report-plugin`](https://maven.apache.org/surefire/maven-surefire-report-plugin/) + +## Running the TCK tests + +Once the TCK has been configured for your runtime and all required software has been installed, the TCKs can be executed by running: + +``` +$ mvn test +``` + +All test execution follows standard Maven Surefire practices, such as: + - Run a single test class with `mvn test -Dtest=MyTestClass + - Run a singl etest method with `mvn test -Dtest-MyTestClass#myTestMethod + +## Example setup + +See the [Eclipse Yasson repository](https://github.com/eclipse-ee4j/yasson/tree/master/yasson-tck) for a working example of how a JSON-B implementation can consume and run these TCK tests.