Introduction |
Previous | Next | Contents |
This chapter provides an overview of the principles that apply generally to all Technology Compatibility Kits (TCKs) and describes the Jakarta RESTful Web Services TCK (Jakarta REST 3.1 TCK). It also includes a high level listing of what is needed to get up and running with the Jakarta REST TCK.
This chapter includes the following topics:
Compatibility testing differs from traditional product testing in a number of ways. The focus of compatibility testing is to test those features and areas of an implementation that are likely to differ across other implementations, such as those features that:
Rely on hardware or operating system-specific behavior
Are difficult to port
Mask or abstract hardware or operating system behavior
Compatibility test development for a given feature relies on a complete specification and compatible implementation (CI) for that feature. Compatibility testing is not primarily concerned with robustness, performance, nor ease of use.
Jakarta platform compatibility is important to different groups involved with Jakarta technologies for different reasons:
Compatibility testing ensures that the Jakarta platform does not become fragmented as it is ported to different operating systems and hardware environments.
Compatibility testing benefits developers working in the Jakarta programming language, allowing them to write applications once and then to deploy them across heterogeneous computing environments without porting.
Compatibility testing allows application users to obtain applications from disparate sources and deploy them with confidence.
Conformance testing benefits Jakarta platform implementors by ensuring a level playing field for all Jakarta platform ports.
Compatibility criteria for all technology implementations are embodied in the TCK Compatibility Rules that apply to a specified technology. Each TCK tests for adherence to these Rules as described in Chapter 2, "Procedure for Certification."
A TCK is a set of tools and tests used to verify that a vendor’s compatible implementation of a Jakarta EE technology conforms to the applicable specification. All tests in the TCK are based on the written specifications for the Jakarta EE platform. A TCK tests compatibility of a vendor’s compatible implementation of the technology to the applicable specification of the technology. Compatibility testing is a means of ensuring correctness, completeness, and consistency across all implementations developed by technology licensees.
The set of tests included with each TCK is called the test suite. Most tests in a TCK’s test suite are self-checking, but some tests may require tester interaction. Most tests return either a Pass or Fail status. For a given platform to be certified, all of the required tests must pass. The definition of required tests may change from platform to platform.
The definition of required tests will change over time. Before your final certification test pass, be sure to download the latest version of this TCK.
The Jakarta EE Specification Process (JESP) program is the formalization of the open process that has been used since 2019 to develop and revise Jakarta EE technology specifications in cooperation with the international Jakarta EE community. The JESP program specifies that the following three major components must be included as deliverables in a final Jakarta EE technology release under the direction of the responsible Expert Group:
Technology Specification
Compatible Implementation (CI)
Technology Compatibility Kit (TCK)
For further information about the JESP program, go to Jakarta EE Specification Process community page https://jakarta.ee/specifications.
The Jakarta REST TCK 3.1 is designed as a portable, configurable, automated test suite for verifying the compatibility of a vendor’s implementation of the Jakarta REST 3.1 Specification.
This section lists the applicable requirements and specifications.
Specification Requirements: Software requirements for a Jakarta REST implementation are described in detail in the Jakarta REST 3.1 Specification. Links to the Jakarta REST specification and other product information can be found at https://jakarta.ee/specifications/restful-ws/3.1/.
Jakarta REST Version: The Jakarta REST 3.1 TCK is based on the Jakarta REST Specification, Version 3.1.
Compatible Implementation: One Jakarta REST 3.1 Compatible Implementation, Eclipse Jersey 3.1 is available from the Eclipse EE4J project (https://projects.eclipse.org/projects/ee4j). See the CI documentation page at https://projects.eclipse.org/projects/ee4j.jersey for more information.
See the Jakarta REST TCK Release Notes for more specific information about Java SE version requirements, supported platforms, restrictions, and so on.
The Jakarta REST TCK 3.1 includes the following components:
Jakarta REST TCK signature tests; check that all public APIs are supported and/or defined as specified in the Jakarta REST Version 3.1 implementation under test.
If applicable, an exclude list, which provides a list of tests that your implementation is not required to pass.
API tests for all of the Jakarta REST API in all related packages:
jakarta.ws.rs
jakarta.ws.rs.client
jakarta.ws.rs.container
jakarta.ws.rs.core
jakarta.ws.rs.ext
jakarta.ws.rs.sse
The Jakarta REST TCK tests run on the following platforms:
Debian GNU/Linux 10
The test suite is the collection of tests to test a particular technology implementation. In this case, it is the collection of JUnit tests used by the Jakarta REST TCK 3.1 to test a Jakarta REST 3.1 implementation. The tests are designed to verify that a vendor’s runtime implementation of the technology complies with the appropriate specification. The individual tests correspond to assertions of the specification.
The tests that make up the TCK compatibility test suite are precompiled and indexed within the TCK jar directory structure.
Each version of a TCK includes an Exclude List contained in a TCK-Exclude-List.txt
file.
This is a list of test file URLs that identify tests which do not
have to be run for the specific version of the TCK being used.
Whenever tests are run, the Junit framework automatically excludes
these tests from being executed as those are disabled using @Disabled tag in JUnit.
A vendor’s compatible implementation is not required to pass or run any test on the Exclude List.
The Exclude List file, jaxrs-tck-docs/TCK-Exclude-List.txt
, is documented in the
Jakarta REST TCK. Please note this file is not parsed to exclude any test and is only
for documentation purpose.
Note
|
From time to time, updates to the Exclude List are made available. The exclude list is included in the TCK ZIP archive. Each time an update is approved and released, the version number will be incremented. You should always make sure you are using an up-to-date copy of the Exclude List before running the Jakarta REST TCK to verify your implementation. |
A test might be in the Exclude List for reasons such as:
An error in an underlying implementation API has been discovered which does not allow the test to execute properly.
An error in the specification that was used as the basis of the test has been discovered.
An error in the test itself has been discovered.
The test fails due to a bug in the tools used to run the test.
In addition, all tests are run against the compatible implementations. Any tests that fail when run on a compatible Jakarta platform are put on the Exclude List. Any test that is not specification-based, or for which the specification is vague, may be excluded. Any test that is found to be implementation dependent (based on a particular thread scheduling model, based on a particular file system behavior, and so on) may be excluded.
Note
|
Vendors are not permitted to alter or modify Exclude Lists. Changes to an Exclude List can only be made by using the procedure described in Section 2.3.1, "TCK Test Appeals Steps." |
You need to set several variables in your test environment, and run the Jakarta REST tests, as described in Chapter 4, "Setup and Configuration."
Note
|
The Jakarta EE Specification Process support multiple compatible implementations. These instructions explain how to get started with the Eclipse Jersey 3.1 CI. If you are using another compatible implementation, refer to material provided by that implementation for specific instructions and procedures. |
This section provides an general overview of what needs to be done to install, set up, test, and use the Jakarta REST TCK. These steps are explained in more detail in subsequent chapters of this guide.
Make sure that the following software has been correctly installed on the system :
Jakarta EE 10 CI such as Eclipse GlassFish 6.1 or, at a minimum, a Web server with a Servlet container
Java SE 11
A CI for Jakarta REST 3.1. One example is Eclipse Jersey 3.1.
Jakarta REST TCK version 3.1
The Jakarta REST 3.1 Vendor Implementation (VI)
See the documentation for each of these software applications for
installation instructions. See Chapter 3,
"Installation," for instructions on installing the Jakarta REST TCK.
Set up the Jakarta REST TCK software.
See Chapter 4, "Setup and Configuration," for
details about the following steps.
Set up your shell environment.
Set the required System properties.
Test the Jakarta REST 3.1 implementation.
Test the Jakarta REST implementation installation by running
the test suite. See Chapter 5, "Executing Tests."
Previous | Next | Contents |