[[installation]]
== 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 Bean Validation TCK project via the
official http://beanvalidation.org/tck/[Jakarta Bean Validation
home page]. The Jakarta Bean Validation TCK is distributed as a ZIP file,
which contains the TCK artifacts (the test suite binary and source, the
test suite descriptor, the audit source and report), the TCK library
dependencies in `/lib` and documentation in `/doc`.
The contents should look like:

[source]
----
artifacts/
changelog.txt
docs/
lib/
license.txt
setup-examples/
src/
readme.md
----

You can also download the source code from GitHub - https://github.com/eclipse-ee4j/beanvalidation-tck[https://github.com/eclipse-ee4j/beanvalidation-tck].

The Jakarta Bean Validation reference implementation (RI) project is named
Hibernate Validator. You can obtain the Hibernate Validator release used
as reference implementation from the Hibernate Validator https://hibernate.org/validator/releases/[download
page].

[NOTE]
====
Hibernate Validator is not required for running the Bean
Validation TCK, but it can be used as a reference for familiarizing
yourself with the TCK before testing your own Jakarta Bean Validation
implementation.
====

[[tck-environment]]
=== The TCK Environment

The TCK requires the following two Java runtime environments:

* Java 8 (including a JavaFX implementation)
* Jakarta EE 8 or better (e.g. Eclipse GlassFish 5.1+)

You should refer to vendor instructions for how to install the
runtime.

The rest of the TCK software can simply be extracted. It's
recommended that you create a dedicated folder to hold all of the
Jakarta Bean Validation-related artifacts. This guide assumes the folder is called
`jakarta-bean-validation`. Extract the `src` folder
of the TCK distribution into a sub-folder named `tck`
or use the following git commands:

[source,subs="attributes"]
----
git clone git://github.com/eclipse-ee4j/beanvalidation-tck tck
git checkout {tckVersion}
----

You can also check out the full
Hibernate Validator source into a subfolder `ri`. This will allow you to run
the TCK against Hibernate Validator.

[source,subs="attributes"]
----
git clone git://github.com/hibernate/hibernate-validator.git ri
git checkout {hibernateValidatorVersion}
----

The resulting folder structure is shown here:

[source]
----
jakarta-bean-validation/
   ri/
   tck/
----

Now lets have a look at one concrete test of the TCK, namely
`ConstraintInheritanceTest` (found in
`tck/tests/src/main/java/org/hibernate/beanvalidation/tck/tests/constraints/inheritance/ConstraintInheritanceTest.java`):

[source, JAVA, indent=0]
----
include::{testsSourceDir}/org/hibernate/beanvalidation/tck/tests/constraints/inheritance/ConstraintInheritanceTest.java[lines=7..-1]
----

Each test class is treated as an individual artifact (hence
the `@Deployment` annotation on the class). In most tests
the created artifact is a standard http://en.wikipedia.org/wiki/WAR_file_format_%28Sun%29[Web
application Archive] build via `WebArchiveBuilder` which
in turn is a helper class of the TCK itself alleviating the creation of of
the artifact. All methods annotated with `@Test` are
actual tests which are getting run. Last but not least we see the use of
the `@SpecAssertion` annotation which creates the link between
the tck-audit.xml document and the actual test (see <<primer>>).

.Running the TCK against the Jakarta Bean Validation RI (Hibernate Validator) and WildFly 10.1
====
* Install Maven. You can find documentation on how to install
Maven 3 on the https://maven.apache.org/install.html[Maven official website].
* Change to the `ri/tck-runner` directory.
* Next, instruct Maven to run the TCK:
+
[source]
----
mvn test -Dincontainer
----
* TestNG will report, via Maven, the outcome of the run, and
report any failures on the console. Details can be found in
`target/surefire-reports/TestSuite.txt`.
====
