type=page status=published title=Introduction next=rules.html prev=TCKpreface.html ~~ Introduction
1 Introduction
This document provides instructions for installing, configuring, and running the Jakarta Platform, Enterprise Edition 10 Test Compatibility Kit (Jakarta EE 10 Platform TCK). This chapter includes the following topics: * link:#GBFTK[Compatibility Testing] * link:#GEUYK[About Jakarta EE 10 Platform TCK] * link:#GEVAD[Hardware Requirements] * link:#GEVBB[Software Requirements] * link:#GEVCL[Additional Jakarta EE 10 Platform TCK Requirements] * link:#GBFQW[Getting Started With the Jakarta EE 10 Platform TCK Test Suite] [[GBFTK]][[compatibility-testing]] 1.1 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. [[GBFQN]][[why-compatibility-testing-is-important]] 1.1.1 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. [[GBFPR]][[compatibility-rules]] 1.1.2 Compatibility Rules ^^^^^^^^^^^^^^^^^^^^^^^^^ Compatibility criteria for all technology implementations are embodied in the Compatibility Rules that apply to a specified technology. The Jakarta EE 10 Platform TCK tests for adherence to these Rules as described in link:rules.html#GBFSN[Chapter 2, "Procedure for Jakarta Platform, Enterprise Edition 10 Certification,"] for Jakarta EE 10 and link:rules-wp.html#GJJPZ[Chapter 3, "Procedure for Jakarta Platform, Enterprise Edition 10 Web Profile Certification,"] for Jakarta EE 10 Web Profile. [[GBFPW]][[tck-overview]] 1.1.3 TCK Overview ^^^^^^^^^^^^^^^^^^ A Jakarta EE 10 Platform TCK is a set of tools and tests used to verify that a Implementer's implementation of Jakarta EE 10 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 10 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 Exclude List for the Jakarta EE 10 Platform TCK. The definition of required tests will change over time. See link:#GEUYQ[Section 1.2.5, "Exclude Lists,"] for more information. [[GBFPB]][[jakarta-community-community-process-program-and-compatibility-testing]] 1.1.4 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). [[GEUYK]][[about-jakarta-ee-10-platform-tck]] 1.2 About Jakarta EE 10 Platform TCK ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Jakarta EE 10 Platform TCK is a portable, configurable, automated test suite for verifying the compliance of a Implementer's implementation of the Jakarta EE 10 technologies. Jakarta EE 10 Platform TCK includes version 5.0 of the JavaTest harness. For documentation on the test harness used for running the Jakarta EE 10 Platform TCK test suite, see `https://wiki.openjdk.java.net/display/CodeTools/Documentation`. [[sthref4]][[jakarta-ee-10-technologies-tested-with-jakarta-ee-10-platform-tck]] 1.2.1 Jakarta EE 10 Technologies Tested with Jakarta EE 10 Platform TCK ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Jakarta EE 10 Platform TCK test suite includes compatibility tests for the following required and optional Jakarta EE 10 technologies: * Jakarta Enterprise Beans 4.0 + * Jakarta Server Pages 3.1 * Jakarta Servlet 6.0 * Jakarta Expression Language 5.0 * Jakarta Messaging 3.0 * Jakarta Transactions 2.0 * Jakarta Mail 2.0 * Jakarta Connectors 2.0 * Jakarta Enterprise Web Services 2.0 (optional) * Jakarta RESTful Web Services 3.0 * Jakarta WebSocket 2.1 * Jakarta JSON Processing 2.0 * Jakarta JSON Binding 2.0 * Jakarta Concurrency 2.0 * Jakarta Authorization 2.0 * Jakarta Authentication 2.0 * Jakarta Standard Tag Library 2.0 * Jakarta Faces 3.0 * Jakarta Security 2.0 * Jakarta Annotations 2.0 * Jakarta Persistence 3.0 * Jakarta Bean Validation 3.0 * Jakarta Managed Beans 2.0 * Jakarta Interceptors 2.0 * Jakarta Contexts and Dependency Injection 3.0 * Jakarta Dependency Injection 2.0 * Jakarta Debugging Support for Other Languages 2.0 * Jakarta Enterprise Beans 3.2 and earlier entity beans and associated Jakarta Enterprise Beans QL (optional) * Jakarta Enterprise Beans 2.x API group (optional) * Jakarta Enterprise Web Services 2.0 (optional) * Jakarta SOAP with Attachments 2.0 (optional) * Jakarta Web Services Metadata 3.0 (optional) * Jakarta XML Web Services 3.0 (optional) [[BHCGFHDI]][[jakarta-ee-10-web-profile-technologies-tested-with-jakarta-ee-10-platform-tck]] 1.2.2 Jakarta EE 10 Web Profile Technologies Tested With Jakarta EE 10 Platform TCK ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Jakarta EE 10 Platform TCK test suite can also be used to test compatibility for the following required Jakarta EE 10 Web Profile technologies: * Jakarta Server Pages 3.1 * Jakarta Servlet 6.0 * Jakarta Expression Language 5.0 * Jakarta Standard Tag Library 2.0 * Jakarta Faces 3.0 * Jakarta RESTful Web Services 3.0 * Jakarta WebSocket 2.1 * Jakarta JSON Processing 2.0 * Jakarta JSON Binding 2.0 * Jakarta Common Annotations 2.0 * Jakarta Enterprise Beans 4.0, Lite * Jakarta Transactions 2.0 * Jakarta Persistence 3.0 * Jakarta Bean Validation 3.0 * Jakarta Managed Beans 2.0 * Jakarta Interceptors 2.0 * Jakarta Contexts and Dependency Injection 3.0 * Jakarta Dependency Injection 2.0 * Jakarta Security 2.0 * Jakarta Authentication 2.0, Servlet Container Profile * Jakarta Debugging Support for Other Languages 2.0 [[GEUZS]][[tck-tests]] 1.2.3 TCK Tests ^^^^^^^^^^^^^^^ The Jakarta EE 10 Platform TCK contains API tests and enterprise edition tests, which are tests that start in the Jakarta EE 10 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. [[GEUZU]] .*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. link:#GEUZU[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 10 Compatible Implementation (Jakarta EE 10 CI) first to become familiar with the testing process. Then they will set up and run the test suite with their own Jakarta EE 10 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 link:rules.html#GBFSN[Chapter 2, "Procedure for Jakarta Platform, Enterprise Edition 8 Certification,"] or link:rules-wp.html#GJJPZ[Chapter 3, "Procedure for Jakarta Platform, Enterprise Edition 10 Web Profile Certification."] These chapters explain the certification process and provides a definitive list of certification rules for Jakarta EE 10 and Jakarta EE 10 Web Profile implementations. * Next, take a look at the test assertions in the Assertion List, which you can find in the Jakarta EE 10 Platform TCK documentation bundle. The assertions explain what each test is testing. When you run the tests with the JavaTest GUI, the assertion being tested as part of the test description of the currently selected test is displayed. * Third, install and configure the Jakarta EE 10 Platform TCK software and the Jakarta EE 10 CI or Jakarta EE 10 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 10 or Jakarta EE 10 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. ======================================================================= [[GEUYR]][[javatest-harness]] 1.2.4 JavaTest Harness ^^^^^^^^^^^^^^^^^^^^^^ The JavaTest harness version 5.0 is a set of tools designed to run and manage test suites on different Java platforms. The JavaTest harness can be described as both a Java application and a set of compatibility testing tools. It can run tests on different kinds of Java platforms and it allows the results to be browsed online within the JavaTest GUI, or offline in the HTML reports that the JavaTest harness generates. The JavaTest harness includes the applications and tools that are used for test execution and test suite management. It supports the following features: * Sequencing of tests, allowing them to be loaded and executed automatically * Graphic user interface (GUI) for ease of use * Automated reporting capability to minimize manual errors * Failure analysis * Test result auditing and auditable test specification framework * Distributed testing environment support To run tests using the JavaTest harness, you specify which tests in the test suite to run, how to run them, and where to put the results as described in link:using.html#GBFWO[Chapter 7, "Executing Tests."] The tests that make up the TCK are precompiled and indexed within the TCK test directory structure. When a test run is started, the JavaTest harness scans through the set of tests that are located under the directories that have been selected. While scanning, the JavaTest harness selects the appropriate tests according to any matches with the filters you are using and queues them up for execution. [[GEUYQ]][[exclude-lists]] 1.2.5 Exclude Lists ^^^^^^^^^^^^^^^^^^^ The Jakarta EE 10 Platform TCK includes an Exclude List contained in a `.jtx` 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 JavaTest harness automatically excludes any test on the Exclude List from being executed. A implementor is not required to pass or run any test on the Exclude List. The Exclude List file, `<TS_HOME>/bin/ts.jtx`, is included in the Jakarta EE 10 TCK. [NOTE] ======================================================================= Always make sure you are using an up-to-date copy of the Exclude List before running the Jakarta EE 10 Platform TCK test suite 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 (such as the JavaTest 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 Exclude Lists. Changes to an Exclude List can only be made by using the procedure described in link:rules.html#CJAICHHD[Section 2.3.1, "Jakarta Platform, Enterprise Edition TCK Test Appeals Steps,"] and link:rules-wp.html#CEGCHJGH[Section 3.3.1, "Jakarta Platform, Enterprise Edition TCK Test Appeals Steps."] ======================================================================= [[GEUZN]][[apache-ant]] 1.2.6 Apache Ant ^^^^^^^^^^^^^^^^ The Jakarta EE 10 CI, Jakarta EE 10 Web Profile CI, and Jakarta EE 10 Platform TCK require implementations 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. Ant is invoked in the Jakarta EE 10 CI, Jakarta EE 10 Web Profile CI, and Jakarta EE 10 TCK in conjunction with various XML files containing Ant targets. These Ant targets provide a convenient way to automate various configuration tasks for Jakarta EE 10 Platform TCK. For example, the initial configuration of the Jakarta EE 10 CI or Jakarta EE 10 Web Profile CI for TCK is done by means of the `config.vi` Ant target. The Ant configuration targets are there for your convenience. When configuring your Jakarta EE 10 or Jakarta EE 10 Web Profile implementation for the Jakarta EE 10 Platform TCK, you can either set up your environment to use the Ant tools, or you can perform some or all of your configuration procedures manually. Jakarta EE 10 Platform TCK includes the Ant Contrib package, and the tasks included with Ant Contrib are used within the TCK build files. See `http://ant-contrib.sourceforge.net/` for more information about Ant Contrib. This User's Guide does not provide in-depth instruction on Ant internals or how to configure Ant targets for your particular Jakarta EE 10 or Jakarta EE 8 Web Profile implementation. For complete information about Ant, refer to the extensive documentation on the Apache Ant Project site. The Apache Ant Manual is available at `http://ant.apache.org/manual/index.html`. 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` [[GEVAD]][[hardware-requirements]] 1.3 Hardware Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~ The following section lists the hardware requirements for the Jakarta EE 10 TCK software, using the Jakarta EE 10 CI or Jakarta EE 10 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 10 repository, and the database * Network access to the Internet [[GEVBB]][[software-requirements]] 1.4 Software Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~ You can run the Jakarta EE 10 Platform TCK software on platforms running the Linux software that meet the following software requirements: * Operating Systems: ** CentOS Linux 7 ** Alpine Linux v3.12 * Java SE 8 (1.8) or 11 * Jakarta EE 10 CI or Jakarta EE 10 Web Profile CI * Mail server that supports the IMAP and SMTP protocols * One of the following databases: ** MySQL ** Apache Derby [[GEVCL]][[additional-jakarta-ee-10-platform-tck-requirements]] 1.5 Additional Jakarta EE 10 Platform TCK Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to the instructions and requirements described in this document, all Jakarta EE 10 and Jakarta EE 10 Web Profile implementations must also pass the standalone TCKs for the following technologies: * Jakarta Batch 2.1 * Jakarta Contexts and Dependency Injection 4.0 * Jakarta Dependency Injection 2.0 * Jakarta Bean Validation 3.0 * Jakarta XML Binding 3.0 * Jakarta JSON Binding 3.0 * Jakarta JSON Processing 2.1 * Jakarta RESTful Web Services 3.1 For more information about the Jakarta Batch technology, see the specification at `https://jakarta.ee/specifications/batch/2.1/` For more information about the Jakarta Contexts and Dependency Injection technology, see the specification at `https://jakarta.ee/specifications/cdi/4.0/` For more information about the Jakarta Dependency Injection, see the specification at `https://jakarta.ee/specifications/dependency-injection/2.0/` For more information about the Jakarta Bean Validation technology, see the specification at `https://jakarta.ee/specifications/bean-validation/3.0/` For more information about the Jakarta XML Binding technology, see the specification at `https://jakarta.ee/specifications/xml-binding/3.0/` For more information about the Jakarta JSON Binding technology, see the specification at `https://jakarta.ee/specifications/jsonb/3.0/` For more information about the Jakarta JSON Processing technology, see the specification at `https://jakarta.ee/specifications/jsonp/2.1/` For more information about the Jakarta RESTful Web Services technology, see the specification at `https://jakarta.ee/specifications/restful-ws/3.1/` [[GBFQW]][[getting-started-with-the-jakarta-ee-10-platform-tck-test-suite]] 1.6 Getting Started With the Jakarta EE 10 Platform TCK Test Suite ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Installing, configuring, and using the Jakarta EE 10 Platform TCK involves the following general steps: 1. Download, install, and configure a Jakarta EE 10 CI or Jakarta EE 10 Web Profile CI. For example Eclipse GlassFish 6.1. 2. Download and install the Jakarta EE 10 Platform TCK package. 3. Configure your database to work with your CI. 4. Configure 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 10 Platform TCK using the most basic test configuration, refer to link:install.html#GBFTP[Chapter 4, "Installation."]