[[introduction]]

== Introduction (CDI TCK)

This chapter explains the purpose of a TCK and identifies the foundation elements of the CDI TCK. 



=== TCK Primer

A TCK, or Technology Compatibility Kit, is one of the three required pieces for any JSR (the other two being the specification document and the reference implementation). The TCK is a set of tools and tests to verify that an implementation of the technology conforms to the specification. The tests are the primary component, but the tools serve an equally critical role of providing a framework and/or set of SPIs for executing the tests. 

The tests in the TCK are derived from assertions in the written specification document. The assertions are itemized in an XML document, where they each get assigned a unique identifier, and materialize as a suite of automated tests that collectively validate whether an implementation complies with the aforementioned assertions, and in turn the specification. For a particular implementation to be certified, all of the required tests must pass (i.e., the provided test suite must be run unmodified). 

A TCK is entirely implementation agnostic. Ideally, it should validate assertions by consulting the specification's public API.  However, when the information returned by the public API is not low-level enough to validate the assertion, the implementation must be consulted directly. In this case, the TCK provides an independent API as part of a porting package that enables this transparency. The porting package must be implemented for each CDI implementation. <<tck-components>> introduces the porting package and <<porting-package>> covers the requirements for implementing it. 


[NOTE]
====
Oracle Corporation will implement the porting package for the CDI RI and test the CDI RI on the Java EE Reference Implementation. 


====




=== Compatibility Testing

The goal of any specification is to eliminate portability problems so long as the program which uses the implementation also conforms to the rules laid out in the specification. 

Executing the TCK is a form of compatibility testing. It's important to understand that compatibility testing is distinctly different from product testing. The TCK is not concerned with robustness, performance or ease of use, and therefore cannot vouch for how well an implementation meets these criteria. What a TCK can do is to ensure the exactness of an implementation as it relates to the specification. 

Compatibility testing of any feature relies on both a complete specification and a complete reference implementation. The reference implementation demonstrates how each test can be passed and provides additional context to the implementor during development for the corresponding assertion. 



==== Why Compatibility Is Important

Java platform compatibility is important to different groups involved with Java technologies for different reasons: 


*  Compatibility testing is the means by which the JCP ensures that the Java platform does not become fragmented as it's ported to different operating systems and hardware. 


*  Compatibility testing benefits developers working in the Java programming language, enabling them to write applications once and deploy them across heterogeneous computing environments without porting. 


*  Compatibility testing enables application users to obtain applications from disparate sources and deploy them with confidence. 


* Conformance testing benefits Java platform implementors by ensuring the same extent of reliability for all Java platform ports. 

The CDI specification goes to great lengths to ensure that programs written for Java EE are compatible and the TCK is rigorous about enforcing the rules the specification lays down. 


=== Compatibility Requirements

The compatibility requirements for Contexts and Dependency Injection for Java Version 2.0 consist of meeting the
requirements set forth by the rules and associated definitions contained in this section.

==== Definitions

These definitions are for use only with these compatibility requirements and are not
intended for any other purpose.

.Definitions
[options="header"]
|===============
|Term|Definition
|API Definition Product   +|
                     A Product for which the only Java class files contained in the product
                     are those corresponding to the application programming interfaces
                     defined by the Specifications, and which is intended only as a means
                     for formally specifying the application programming interfaces
                     defined by the Specifications.
|Computational Resource   +|
                     A piece of hardware or software that may vary in quantity, existence,
                     or version, which may be required to exist in a minimum quantity
                     and/or at a specific or minimum revision level so as to satisfy the
                     requirements of the Test Suite.
                     Examples of computational resources that may vary in quantity are
                     RAM and file descriptors.
                     Examples of computational resources that may vary in existence (that
                     is, may or may not exist) are graphics cards and device drivers.
                     Examples of computational resources that may vary in version are
                     operating systems and device drivers.
|Conformance Tests   +|
                     All tests in the Test Suite for an indicated Technology Under Test, as
                     distributed by the Maintenance Lead, excluding those tests on the
                     Exclude List for the Technology Under Test.
|Documented   +|
                     Made technically accessible and made known to users, typically by
                     means such as marketing materials, product documentation, usage
                     messages, or developer support programs.
|Edition   +|
                     A Version of the Java Platform. Editions include Java Platform
                     Standard Edition and Java Platform Enterprise Edition.
|Exclude List   +|
                     The most current list of tests, distributed by the Maintenance Lead or TCK Lead,
                     that are not required to be passed to certify conformance. The
                     Maintenance Lead or TCK Lead may add to the Exclude List for that Test Suite as
                     needed at any time, in which case the updated Exclude List supplants
                     any previous Exclude Lists for that Test Suite.
|Libraries   +|
                     The class libraries, as specified through the Java Community Process
                     (JCP), for the Technology Under Test.
                     The Libraries for Contexts and Dependency Injection for Java Version 2.0 are listed in <<libraries>>.
|Location Resource   +|
                     A location of classes or native libraries that are components of the test
                     tools or tests, such that these classes or libraries may be required to
                     exist in a certain location in order to satisfy the requirements of the
                     test suite.
                     For example, classes may be required to exist in directories named in a
                     CLASSPATH variable, or native libraries may be required to exist in
                     directories named in a PATH variable.
|Maintenance Lead   +|
                     The Java Community Process member responsible for maintaining the
                     Specification, reference implementation, and TCK for the Technology.
                     Red Hat Inc. is the Maintenance Lead for Contexts and Dependency Injection for Java Version 2.0.
|Operating Mode   +|
                     Any Documented option of a Product that can be changed by a user in
                     order to modify the behavior of the Product.
                     For example, an Operating Mode can be binary (enable/disable
                     optimization), an enumeration (select from a list of protocols), or a
                     range (set the maximum number of active threads).
                     Note that an Operating Mode may be selected by a command line
                     switch, an environment variable, a GUI user interface element, a
                     configuration or control file, etc.
|Product   +|
                     A licensee product in which the Technology Under Test is
                     implemented or incorporated, and that is subject to compatibility
                     testing.
|Product Configuration   +|
                     A specific setting or instantiation of an Operating Mode.
                     For example, a Product supporting an Operating Mode that permits
                     user selection of an external encryption package may have a Product
                     Configuration that links the Product to that encryption package.
|Reference Implementation (RI)   +|
                     The prototype or "proof of concept" implementation of a Specification.
|Resource   +|
                     A Computational Resource, a Location Resource, or a Security
                     Resource.
|Rules   +|
                     These definitions and rules in this Compatibility Requirements section
                     of this User’s Guide.
|Security Resource   +|
                     A security privilege or policy necessary for the proper execution of the
                     Test Suite.
                     For example, the user executing the Test Suite will need the privilege
                     to access the files and network resources necessary for use of the
                     Product.
|Specifications   +|
                     The documents produced through the Java Community Process that
                     define a particular Version of a Technology.
                     The Specifications for the Technology Under Test are referenced later
                     in this chapter.
|TCK Lead   +|
                     Person responsible for maintaining TCK for the Technology. TCK Lead is representative of Red Hat Inc.
|Technology   +|
                     Specifications and a reference implementation produced through the
                     Java Community Process.
|Technology Under Test  +|
                     Specifications and the reference implementation for Contexts and Dependency Injection for Java Version 2.0.
|Test Suite   +|
                     The requirements, tests, and testing tools distributed by the
                     Maintenance Lead or TCK Lead as applicable to a given Version of the Technology.
|Version  +|
                     A release of the Technology, as produced through the Java
                     Community Process.
|===============

==== Rules for Contexts and Dependency Injection for Java Version 2.0 Products

The following rules apply for each version of an operating system, software
component, and hardware platform Documented as supporting the Product:

*CDI-1* The Product must be able to satisfy all applicable compatibility requirements,
including passing all Conformance Tests, in every Product Configuration and in every
combination of Product Configurations, except only as specifically exempted by these
Rules.

For example, if a Product provides distinct Operating Modes to optimize performance,
then that Product must satisfy all applicable compatibility requirements for a Product
in each Product Configuration, and combination of Product Configurations, of those
Operating Modes.

*CDI-1.1* If an Operating Mode controls a Resource necessary for the basic execution of
the Test Suite, testing may always use a Product Configuration of that Operating Mode
providing that Resource, even if other Product Configurations do not provide that
Resource. Notwithstanding such exceptions, each Product must have at least one set of
Product Configurations of such Operating Modes that is able to pass all the Conformance Tests.

For example, a Product with an Operating Mode that controls a security policy which has one or more Product Configurations that cause
Conformance Tests to fail may be tested using a Product Configuration that allows all Conformance Tests to pass.

*CDI-1.2* A Product Configuration of an Operating Mode that causes the Product to
report only version, usage, or diagnostic information is exempted from these
compatibility rules.

*CDI-1.3* A Product may contain an Operating Mode that selects the Edition with
which it is compatible. The Product must meet the compatibility requirements for the
corresponding Edition for all Product Configurations of this Operating Mode. This
Operating Mode must affect no smaller unit of execution than an entire Application.

*CDI-1.4* An API Definition Product is exempt from all functional testing requirements
defined here, except the signature tests.

*CDI-2* Some Conformance Tests may have properties that may be changed. Properties
that can be changed are identified in the configuration interview. Properties that can be
changed are specified in <<tck-properties>>. Apart from changing such properties and other allowed
modifications described in this User’s Guide (if any), no source or binary code for a
Conformance Test may be altered in any way without prior written permission.

*CDI-3* The testing tools supplied as part of the Test Suite or as updated by the
Maintenance Lead or TCK Lead must be used to certify compliance.

*CDI-4* The Exclude List associated with the Test Suite cannot be modified.

*CDI-5* The Maintenance Lead or TCK Lead can define exceptions to these Rules. Such exceptions
would be made available to and apply to all licensees.

*CDI-6* All hardware and software component additions, deletions, and modifications to
a Documented supporting hardware/software platform, that are not part of the
Product but required for the Product to satisfy the compatibility requirements, must be
Documented and available to users of the Product.
For example, if a patch to a particular version of a supporting operating system is
required for the Product to pass the Conformance Tests, that patch must be
Documented and available to users of the Product.

*CDI-7* The Product must contain the full set of public and protected classes and
interfaces for all the Libraries. Those classes and interfaces must contain exactly the set
of public and protected methods, constructors, and fields defined by the Specifications
for those Libraries. No subsetting, supersetting, or modifications of the public and
protected API of the Libraries are allowed except only as specifically exempted by
these Rules.

*CDI-8* Except for tests specifically required by this TCK to be recompiled (if any), the
binary Conformance Tests supplied as part of the Test Suite or as updated by the
Maintenance Lead or TCK Lead must be used to certify compliance.

*CDI-9* The functional programmatic behavior of any binary class or interface must be
that defined by the Specifications.


=== About the CDI TCK

The CDI TCK is designed as a portable, configurable and automated test suite for verifying the compatibility of an implementation of the JSR 365: Contexts and Dependency Injection for Java 2.0 specification. The test suite is built atop TestNG framework and Arquillian platform.

Each test class in the suite acts as a deployable unit. The deployable units, or artifacts, can be either a WAR or an EAR. 


[NOTE]
====
The test archives are built with ShrinkWrap, a Java API for creating archives. 
ShrinkWrap is a part of the Arqullian platform ecosystem. 

====




==== CDI TCK Specifications and Requirements

This section lists the applicable requirements and specifications for the CDI TCK. 


*  *Specification requirements* - Software requirements for a CDI implementation are itemized in section 1.2, "Relationship to other specifications" in the CDI specification, with details provided throughout the specification. Generally, the CDI specification targets the Java EE 8 platform and will be aligned with its specifications.


*  *Contexts and Dependency Injection for
                     Java 2.0 API* - The Java API defined in the CDI specification and provided by the reference implementation.


*  *Testing platform* - The CDI TCK requires version 1.1.11.Final of the Arquillian (http://arquillian.org). The TCK test suite is based on TestNG 6.x (http://testng.org). .


*  *Porting Package* - An implementation of SPIs that are required for the test suite to run the in-container tests and at times extend the CDI 2.0 API to provide extra information to the TCK.


*  *TCK Audit Tool* - An itemization of the assertions in the specification documents which are cross referenced by the individual tests. Describes how well the TCK covers the specification. 


*  *Reference runtime* - The designated reference runtime for compatibility testing of the CDI specification is the Oracle Java Platform, Enterprise Edition (Java EE) 8 reference implementation (RI).


*  *JSR 330* - CDI builds on JSR 330, and as such JSR 365 implementations must additionally pass the JSR 330 TCK.


[TIP]
====
The TCK distribution includes +weld/porting-package-lib/weld-inject-tck-runner-X.Y.Z-Q-tests.jar+ which contains two classes showing how the CDI RI passes the JSR 330 TCK. The source for these classes is available from link:$$https://github.com/weld/core/tree/2.0/inject-tck-runner/src/test/java/org/jboss/weld/atinject/tck$$[] 


====


[[tck-components]]


==== CDI TCK Components

The CDI TCK includes the following components:


*  *Arquillian 1.1.11.Final*


*  *TestNG 6.8.8*


*  *Porting Package SPIs* - Extensions to the CDI SPIs to allow testing of a container. 


*  *The test suite*, which is a collection of TestNG tests, the TestNG test suite descriptor and supplemental resources that configure CDI and other software components. 


*  *The TCK audit* is used to list out the assertions identified in the CDI specification. It matches the assertions to testcases in the test suite by unique identifier and produces a coverage report. 

The audit document is provided along with the TCK; at least 95% of assertions are tested. Each assertion is defined with a reference to a chapter, section and paragraph from the specification document, making it easy for the implementor to locate the language in the specification document that supports the feature being tested. 


*  *TCK documentation* accompanied by release notes identifying updates between versions. 


[NOTE]
====
Oracle Corporation will implement the porting package for the CDI RI and test the CDI RI on the Java EE Reference Implementation. 


====


The CDI TCK has been tested on following platforms:


*  WildFly 10.x using Oracle Java SE 8 on Red Hat Enterprise Linux 7.2

CDI supports Java EE 6, Java EE 6 Web Profile, Java EE 7, Java EE 7 Web Profile, Embeddable EJB 3.1, and the Embeddable EJB 3.2. The TCK will execute on any of these runtimes, but is only part of the CTS for Java EE 8 and Java EE 8 Web Profile.

[[libraries]]

=== Libraries for Contexts and Dependency Injection for Java Version 2.0

The following is the list of packages that constitute the required class libraries for
Contexts and Dependency Injection for Java Version 2.0:

* javax.decorator
* javax.enterprise.context
* javax.enterprise.context.control
* javax.enterprise.context.spi
* javax.enterprise.event
* javax.enterprise.inject
* javax.enterprise.inject.literal
* javax.enterprise.inject.se
* javax.enterprise.inject.spi
* javax.enterprise.inject.spi.configurator
* javax.enterprise.util