[[introduction]]
= Introduction

This document provides instructions for installing, configuring, and
running the Jakarta Platform, Enterprise Edition 11 Test Compatibility Kit
(Jakarta EE {tck_version} Platform TCK).

This chapter includes the following topics:

* <<compatibility-testing>>
* <<about-jakarta-ee-11-platform-tck>>
* <<hardware-requirements>>
* <<software-requirements>>
* <<additional-jakarta-ee-platform-tck-requirements>>
* <<getting-started-with-the-jakarta-ee-platform-tck-test-suite>>

[[compatibility-testing]]
== Compatibility Testing

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 compabitle implementation for that feature.
Compatibility testing is not primarily concerned with robustness,
performance, or ease of use.

[why-compatibility-testing-is-important]
=== Why Compatibility Testing is Important

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 Java
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-rules]
=== Compatibility Rules

Compatibility criteria for all technology implementations are embodied
in the Compatibility Rules that apply to a specified technology. The
Jakarta EE {tck_version} Platform TCK tests for adherence to these Rules as described in
<<procedure-for-jakarta-platform-enterprise-edition-certification>> for Jakarta EE {tck_version} and
<<procedure-for-jakarta-platform-enterprise-edition-web-profile-certification>> for Jakarta EE {tck_version} Web
Profile.

[tck-overview]
=== TCK Overview

A Jakarta EE {tck_version} Platform TCK is a set of tools and tests used to verify that a
Implementer's implementation of Jakarta EE {tck_version} technology conforms to the
applicable specification. All tests in the TCK are based on the written
specifications for the Jakarta Platform. The TCK tests compatibility of a
Implementer's implementation of a 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 Implementers.

The set of tests included with the Jakarta EE {tck_version} Platform TCK is called the test
suite. All tests in the TCK 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 Jakarta EE {tck_version} Platform TCK. The definition of required tests will change over time. See <<exclude-lists>> for more
information.

[[spec-proc-and-compatibility-testing]]
=== Jakarta Specification Community Process Program and Compatibility Testing

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 specification project committer group:

* Technology Specification
* A Compatible Implementation
* Technology Compatibility Kit (TCK)

For further information about the JESP program, go to Jakarta EE
Specification Process community page (https://jakarta.ee/specifications).

[[about-jakarta-ee-11-platform-tck]]
== About Jakarta EE {tck_version} Platform TCK

Jakarta EE {tck_version} Platform TCK is a portable, configurable, automated test suite for
verifying the compliance of an Implementer's implementation of the Jakarta EE {tck_version} technologies.

For documentation on the test harness used for running the Jakarta EE {tck_version} Platform TCK
test suite, see https://github.com/arquillian/arquillian-core[Arquillian]
and https://junit.org/junit5/[Junit5] for the underlying test framework documentation.

[[jakarta-ee-technologies-tested-with-jakarta-ee-platform-tck]]
=== Jakarta EE {tck_version} Technologies Required for Jakarta EE {tck_version} Platform Compatibility

The Jakarta EE {tck_version} Platform Specification defines the required and optional component specifications.
The full list with specification version requirements is defined in the Platform EE Specification document (https://jakarta.ee/specifications/platform/11/), see the heading 'Full Jakarta(TM) EE Product Requirements,'

Jakarta EE {tck_version} TCK tests verify partial compatibility for the Jakarta EE Platform.
The Platform TCK includes tests for the following components:

The complete list of Jakarta EE {tck_version} technologies for the Platform can be found in section 9.7 of the https://jakarta.ee/specifications/platform/11/[Platform Specification].

* Jakarta Activation
* Jakarta Authentication
* Jakarta Authorization
* Jakarta Batch
* Jakarta Bean Validation
* Jakarta Common Annotations
* Jakarta Concurrency
* Jakarta Connectors
* Jakarta Contexts and Dependency Injection
* Jakarta Debugging Support for Other Languages
* Jakarta Dependency Injection
* Jakarta Enterprise Beans (also, see optional below)
* Jakarta Enterprise Web Services
* Jakarta Expression Language
* Jakarta Server Faces
* Jakarta Interceptors
* Jakarta JSON Binding
* Jakarta JSON Processing
* Jakarta Mail
* Jakarta Messaging
* Jakarta Persistence
* Jakarta RESTful Web Services
* Jakarta Security
* Jakarta Server Pages
* Jakarta Servlet
* Jakarta Standard Tag Library
* Jakarta Transactions
* Jakarta WebSocket

Jakarta EE {tck_version} Platform TCK provides compatibility certification verification for implementations contained in the Platform for the following component specifications:

* Jakarta Annotations
* Jakarta Authorization
* Jakarta Connectors
* Jakarta Enterprise Beans (including optional elements)
* Jakarta Expression Language
* Jakarta Interceptors
* Jakarta Messaging
* Jakarta Persistence
* Jakarta Server Pages
* Jakarta Servlet
* Jakarta SOAP with Attachments
* Jakarta Standard Tag Library
* Jakarta Transactions
* Jakarta Web Socket
* Jakarta XML Web Services

[jakarta-ee-11-web-profile-technologies-tested-with-jakarta-ee-11-platform-tck]
=== Jakarta EE {tck_version} Web Profile Technologies Tested With Jakarta EE {tck_version} Platform TCK

The Jakarta EE {tck_version} Web Profile Specification defines the required component specifications.
The complete list with specification version requirements is defined in the Web Profile specification document (https://jakarta.ee/specifications/webprofile/11/), see heading 'Web Profile Definition', sub-heading 'Required Components'.

The Jakarta EE {tck_version} Platform TCK test suite provides partial compatibility verification for
the following component technologies:

* Jakarta Annotations
* Jakarta Authentication, Servlet Container Profile
* Jakarta Bean Validation
* Jakarta Common Annotations
* Jakarta Contexts and Dependency Injection
* Jakarta Concurrency
* Jakarta Debugging Support for Other Languages
* Jakarta Dependency Injection
* Jakarta Enterprise Beans, Lite
* Jakarta Expression Language
* Jakarta Faces
* Jakarta Interceptors
* Jakarta JSON Binding
* Jakarta JSON Processing
* Jakarta Persistence
* Jakarta RESTful Web Services
* Jakarta Security
* Jakarta Server Pages
* Jakarta Servlet
* Jakarta Standard Tag Library
* Jakarta Transactions
* Jakarta WebSocket

There are no optional specifications defined in the Web Profile specification.

Jakarta EE {tck_version} Platform TCK provides compatibility certification verification for implementations contained in the platform, Web Profile for the following component specifications:

* Jakarta Annotations
* Jakarta Enterprise Beans, Lite
* Jakarta Expression Language
* Jakarta Interceptors
* Jakarta Servlet
* Jakarta Standard Tag Library
* Jakarta Transactions
* Jakarta Web Socket

[tck-tests]
=== TCK Tests

The Jakarta EE {tck_version} Platform TCK contains API tests and enterprise edition tests, which
are tests that start in the Jakarta EE {tck_version} platform and use the underlying
enterprise service or services as specified. For example, a JDBC
enterprise edition test connects to a database, uses SQL commands and
the JDBC 4.2 API to populate the database tables with data, queries the
database, and compares the returned results against the expected
results.

[[figure-1-1]]
.*Typical Jakarta Platform, Enterprise Edition Workflow*
image:img/overviewa.png["Typical Jakarta Platform, Enterprise Edition Workflow"]

Note: References in diagram to Java EE refer to Jakarta EE.

<<figure-1-1>> shows how most Implementers will use the test
suite. They will set up and run the test suite with the Jakarta Platform,
Enterprise Edition 11 Compatible Implementation (Jakarta EE {tck_version} CI) first to
become familiar with the testing process. Then they will set up and run
the test suite with their own Jakarta EE {tck_version} implementation. This is called the
Vendor Implementation, or VI in this document. When they pass
all of the tests, they will apply for and be granted certification.

* Before you do anything with the test suite, read the rules in
<<procedure-for-jakarta-platform-enterprise-edition-certification>> or <<procedure-for-jakarta-platform-enterprise-edition-web-profile-certification>> These chapters explain the certification process and
provides a definitive list of certification rules for Jakarta EE {tck_version} and Jakarta EE {tck_version} Web Profile implementations.
* Third, install and configure the Jakarta EE {tck_version} Platform TCK software and the Jakarta
EE {tck_version} CI or Jakarta EE {tck_version} Web Profile CI and run the tests as described in
this guide. This will familiarize you with the testing process.
* Finally, set up and run the test suite with your own Jakarta EE {tck_version} or Jakarta
EE {tck_version} Web Profile implementation.


[NOTE]
======================================================================

In the instructions in this document, variables in angle brackets need
to be expanded for each platform. For example, `<TS_HOME>` becomes
`$TS_HOME` on Solaris/Linux and `%TS_HOME%` on Windows. In addition, the
forward slashes (`/`) used in all of the examples need to be replaced
with backslashes (`\`) for Windows.

======================================================================


[[testing-harness]]
=== Arquillian and Junit5

The Arquillian and Junit5 are set of tools designed to run and manage test suites on different Java platforms.


The tests that make up the TCK are precompiled and bundled in the TCK distribution/artifacts directory as test jars. You will need to create a runner that supports executing Junit5 unit tests. The {glassfish_version} compatibile implementation used maven with the failsafe plugin to run the tests.

[[exclude-lists]]
=== Exclude Tests

As of version {tck_version}, the Jakarta EE Platform TCK uses Junit5 `org.junit.jupiter.api.Disabled` annotations to exclude tests from the test suite. Test methods or classes that are successfully challenged are annotated with the `@Disabled("https://link-to-challenge-issue")` and released in a new service release.

A implementor is not required to pass or run any tests that are annotated with the `@Disabled("...")` tag. The `@Disabled("...")` annotation is used to indicate that the test is not required for certification. When a service release is made to exclude tests due to a challenge, the tests with any `@Disabled("...")` annotations are removed from the test suite by the Junit5 framework.

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 (such as the Arquillian/Junit5 harness, for example).

In addition, all tests are run against the compatible implementations.
Any tests that cannot be run on a compatible Jakarta Platform may be put on the
Exclude List if the Specification project team agrees the test is invalid. 
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]
======================================================================
Implementers are not permitted to alter or modify which tests are Excluded Tests. Changes the Excluded Tests can only be made by using the procedure described in
<<appeals-process-ee>> and <<appeals-process-wp>>
======================================================================


[[apache-ant]]
=== Apache Ant (Optional)

There are example setup scripts for the TCK test databases that use of Apache Ant 1.9.7 from the Apache Ant Project (`http://ant.apache.org/`). Apache Ant is a free, open-source,
Java-based build tool, similar in some ways to the make tool, but more
flexible, cross-platform compatible, and centered around XML-based
configuration files. You do not need to use these scripts, but the SQL statements in the scripts will have to be loaded into your testing database in order for the TCK tests to pass.


Apache Ant is protected under the Apache Software, License 2.0, which is is available on the Apache Ant Project license page at
`http://ant.apache.org/license.html`.

==== Installing Apache Ant

* Download the Apache Ant 1.9.7 binary bundle from the Apache Ant 
  Project.
* Change to the directory in which you want to install Apache Ant and
  extract the bundle
* Set the `ANT_HOME` environment variable to point to the 
  `apache-ant-<version>` directory
* Add `<ANT_HOME>/bin` directory to the environment variable `PATH`

[[hardware-requirements]]
== Hardware Requirements

The following section lists the hardware requirements for the Jakarta EE {tck_version}
TCK software, using the Jakarta EE {tck_version} CI or Jakarta EE {tck_version} Web Profile CI.
Hardware requirements for other compatible implementations will vary.

All systems should meet the following recommended hardware requirements:

* CPU running at 2.0 GHz or higher
* 4 GB of RAM or more
* 2 GB of swap space , if required
* 6 GB of free disk space for writing data to log files, the Jakarta EE {tck_version}
repository, and the database
* Network access to the Internet

[[software-requirements]]
== Software Requirements

You can run the Jakarta EE {tck_version} Platform TCK software on platforms running the
Linux software that meet the following software requirements:

* Operating Systems:
** Any operating system that supports the Java SE 17 or 21 platform
* Java SE 17 or 21
* Jakarta EE {tck_version} CI or Jakarta EE {tck_version} Web Profile CI
* Mail server that supports the IMAP and SMTP protocols (Full Platform Only)
* One of the following databases:
** MySQL
** Apache Derby

[[additional-jakarta-ee-platform-tck-requirements]]
== Additional Jakarta EE {tck_version} Platform TCK Requirements

In addition to the instructions and requirements described in this
document, all Jakarta EE {tck_version} Platform implementations must also pass the standalone TCKs for the following technologies. See the links for additional details.

* Jakarta Activation -- https://jakarta.ee/specifications/activation/2.1/
* Jakarta Authentication -- https://jakarta.ee/specifications/authentication/3.1/
* Jakarta Batch -- https://jakarta.ee/specifications/batch/2.1/
* Jakarta Bean Validation -- https://jakarta.ee/specifications/bean-validation/3.1/
* Jakarta Concurrency -- https://jakarta.ee/specifications/concurrency/3.1/
* Jakarta Contexts and Dependency Injection (including Language Model TCK) -- https://jakarta.ee/specifications/cdi/4.1/
* Jakarta Data -- https://jakarta.ee/specifications/data/1.0/
* Jakarta Debugging Support for Other Languages -- https://jakarta.ee/specifications/debugging/2.0/
* Jakarta Dependency Injection -- https://jakarta.ee/specifications/dependency-injection/2.0/
* Jakarta Faces -- https://jakarta.ee/specifications/faces/4.1/
* Jakarta JSON Binding -- https://jakarta.ee/specifications/jsonb/3.0/
* Jakarta JSON Processing -- https://jakarta.ee/specifications/jsonp/2.1/
* Jakarta Mail -- https://jakarta.ee/specifications/mail/2.1/
* Jakarta RESTFul Web Services -- https://jakarta.ee/specifications/restful-ws/4.0/
* Jakarta Security -- https://jakarta.ee/specifications/security/4.0/
* Jakarta Servlet -- https://jakarta.ee/specifications/servlet/6.1/
* Jakarta WebSocket -- https://jakarta.ee/specifications/websocket/2.2/

All Jakarta EE {tck_version} Web Profile implementations must also pass the standalone TCKs for the following technologies:

* Jakarta Authentication -- https://jakarta.ee/specifications/authentication/3.1/
* Jakarta Bean Validation -- https://jakarta.ee/specifications/bean-validation/3.1/
* Jakarta Concurrency -- https://jakarta.ee/specifications/concurrency/3.1/
* Jakarta Contexts and Dependency Injection (including Language Model TCK) -- https://jakarta.ee/specifications/cdi/4.1/
* Jakarta Data -- https://jakarta.ee/specifications/data/1.0/
* Jakarta Debugging Support for Other Languages -- https://jakarta.ee/specifications/debugging/
* Jakarta Dependency Injection -- https://jakarta.ee/specifications/dependency-injection/2.0/
* Jakarta Faces -- https://jakarta.ee/specifications/faces/4.0/
* Jakarta JSON Binding -- https://jakarta.ee/specifications/jsonb/3.0/
* Jakarta JSON Processing -- https://jakarta.ee/specifications/jsonp/2.1/
* Jakarta RESTFul Web Services -- https://jakarta.ee/specifications/restful-ws/4.0/
* Jakarta Security -- https://jakarta.ee/specifications/security/4.0/
* Jakarta Servlet -- https://jakarta.ee/specifications/servlet/6.1/
* Jakarta WebSocket -- https://jakarta.ee/specifications/websocket/2.2/

[NOTE]
====
Web Profile implementations may ignore sections in this labelled as (Full Platform Only).
====

[[getting-started-with-the-jakarta-ee-platform-tck-test-suite]]
== Getting Started With the Jakarta EE {tck_version} Platform TCK Test Suite

Installing, configuring, and using the Jakarta EE {tck_version} Platform TCK involves the
following general steps:

1.  Download, install, and configure a Jakarta EE {tck_version} CI or Jakarta EE {tck_version} Web
Profile CI. For example Eclipse {glassfish_version}.
2.  Download and install the Jakarta EE {tck_version} Platform TCK package.
3.  Configure your database to work with your CI.
4.  Configure the TCK to work with your database and CI.
5.  Run the TCK tests.

The remainder of this guide explains these steps in detail. If you just
want to get started quickly with the Jakarta EE {tck_version} Platform TCK using the most basic
test configuration, refer to <<installation>>.
