/
configuration.xml
175 lines (151 loc) · 8.77 KB
/
configuration.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "tck.ent">
%BOOK_ENTITIES;
]>
<chapter id="configuration">
<title>Running the TCK test suite</title>
<para>This chapter lays out how to run and configure the TCK harness against
a given Bean Validation provider in a given Java EE container. If you have
not by now made yourself familiar with the <ulink
url="https://docs.jboss.org/author/display/ARQ/Reference+Guide">Arquillian
documentation</ulink>, this is a good time to do it. It will give you a
deeper understanding of the different parts described in the following
sections.</para>
<section>
<title>Setup examples</title>
<para>The TCK distribution comes with a directory
<filename>setup-examples</filename> which contains two example projects
for running the TCK. If you followed the instructions in <xref
linkend="installation"/> you find the directory under
<filename>jsr349/tck/setup-examples</filename>. Both setups are using
Hibernate Validator as Bean Validation Provider and Glassfish 4 as EE
constainer. However, one is using <ulink
url="http://maven.apache.org/">Maven</ulink> as build tool to run the TCK,
the other <ulink url="http://ant.apache.org/">Ant</ulink>. Depending which
of the examples you want to use, you need to install the corresponding
build tool.</para>
<para>Each example comes with a <filename>readme.md</filename> containing
the prerequisites for using this setup, how to run the TCK against
Hibernate Validator and Glassfish. The readme in
<filename>setup-examples</filename> itself contains information about what
needs to be changed to use a different Bean Validation provider and EE
container.</para>
<para>The following chapters contain some more information about the
general structure of the TCK which will give you a deeper understanding
above the simple readme files.</para>
</section>
<section>
<title>Configuring TestNG to execute the TCK</title>
<para>The Bean Validation test harness is built atop TestNG, and it is
TestNG that is responsible for selecting the tests to execute, the order
of execution, and reporting the results. Detailed TestNG documentation can
be found at <ulink
url="http://testng.org/doc/documentation-main.html">testng.org</ulink>.</para>
<para>The <literal>tck-tests.xml</literal> artifact provided in the TCK
distribution must be run by TestNG (described by the TestNG documentation
as "with a <literal>testng.xml</literal> file") unmodified for an
implementation to pass the TCK. For testing purposes it is of course ok to
modify the file (see also the TestNG <ulink
url="http://testng.org/doc/documentation-main.html#testng-xml">documentation</ulink>)</para>
<programlisting><suite name="JSR-349-TCK" verbose="1">
<test name="JSR-349-TCK">
<method-selectors>
<method-selector>
<selector-class name="org.hibernate.beanvalidation.tck.util.IntegrationTestsMethodSelector"/>
</method-selector>
</method-selectors>
<packages>
<package name="org.hibernate.beanvalidation.tck.tests"/>
</packages>
</test>
</suite></programlisting>
<para>TestNG provides extensive reporting information. Depending on the
build tool or IDE you use, the reporting will take a different format.
Please consult the TestNG documentation and the tool documentation for
more information.</para>
</section>
<section>
<title>Selecting the <classname>ValidationProvider</classname></title>
<para>The most important configuration you have make in order to run the
Bean Validation TCK is to specify your
<classname>ValidationProvider</classname> you want to run your tests
against. To do so you need to set the Java system property
<property>validation.provider</property> to the fully specified class name
of your <classname>ValidationProvider</classname>. In Maven this is done
via the <emphasis>systemProperties</emphasis> configuration option of the
<emphasis>maven-surefire-plugin</emphasis>, whereas
<emphasis>sysproperty</emphasis> is used in an Ant testng task. This
system property will be picked up by
<classname>org.hibernate.beanvalidation.tck.util.TestUtil</classname>
which will instantiate the <classname>Validator</classname> under test.
This means the test harness does not rely on the service provider
mechanism to instantiate the Bean Validation provider under test, partly
because this selection mechanism is under test as well.</para>
</section>
<section id="configuration-deployable-container">
<title>Selecting the <classname>DeployableContainer</classname></title>
<para>After setting the <classname>ValidationProvider</classname> you have
to make a choice on the right <classname>DeployableContainer</classname>.
Arquillian picks which container it is going to use to deploy the test
archive and negotiate test execution using Java's service provider
mechanism. Concretely Arquillian is looking for an implementation of the
<classname>DeployableContainer</classname> SPI on the classpath. The setup
examples use a remote Glassfish container adapter, which means that
Arquillian tries to deploy the test artifacts onto a specified remote
Glassfish instance, run the tests remotely and report the results back to
the current JVM. The installation directory of the remote container is
specified via the <emphasis>container.home</emphasis> property in the
example build files. <tip>
<para>To make it easier to develop, debug or test the TCK, an in JVM
adapter is provided as part of the distribution
(<filename>beanvalidation-standalone-container-adapter-&tckVersion;.jar</filename>).
Using this adapter the tests are not executed in a remote Java EE
container, but in the current JVM. This allows for easy and fast
debugging. Some tests, however, are only runnable in a EE container
and will fail in this in JVM execution mode. By setting the property
<property>excludeIntegrationTests</property> to
<constant>true</constant> these tests can be excluded.</para>
<para>The adapter is also available as Maven artifact under the GAV
<emphasis>org.hibernate.beanvalidation.tck:beanvalidation-standalone-container-adapter:&tckVersion;.</emphasis>
You can refer to <filename>pom.xml</filename> in the tck-runner module
of Hibernate Validator (in the directory
<filename>jsr349/ri/tck-runner</filename>, if you followed the
instruction in <xref linkend="installation"/>) to see how it is
used.</para>
</tip></para>
</section>
<section id="configuration-arquillian-xml">
<title>arquillian.xml</title>
<para>The next piece in the configuration puzzle is
<filename>arquillian.xml</filename>. This xml file needs to be in the root
of the classpath and is used to pass additional options to the selected
container. Let's look at an example:<programlisting><arquillian xmlns="http://jboss.org/schema/arquillian" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.org/schema/arquillian
http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
<defaultProtocol type="Servlet 3.0"/>
<engine>
<property name="deploymentExportPath">target/artifacts</property>
</engine>
<container qualifier="incontainer" default="true">
<configuration>
<property name="glassFishHome">@CONTAINER.HOME@</property>
<property name="adminHost">localhost</property>
<property name="adminPort">4848</property>
<property name="debug">true</property>
</configuration>
</container>
</arquillian></programlisting></para>
<para>The most important container configuration option is the protocol
type which determines how Arquillian communicates with the selected
container. The most popular types are <emphasis>Servlet 3.0</emphasis> and
<emphasis>Local</emphasis>. The former is used when connecting to a remote
container whereas the latter is used for the in JVM mode.</para>
<para>Another interesting property is
<property>deploymentExportPath</property> which is optional and instructs
Arquillian to dump the test artifacts to the specified directory on disk.
Inspection of the deployed artifacts can be very useful when debugging
test failures.</para>
</section>
</chapter>