//
// Copyright (c) 2016-2017 Contributors to the Eclipse Foundation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

= Running the Microprofile Config TCK

Any Microprofile 1.2 and higher release must pass this test suite.
The TCK uses `testng`

== Dependencies

To enable the tests in your project you need to add the following dependency to your build:

[source, xml]
----
<properties>
   <microprofile.config.version>1.1</microprofile.config.version>
</properties>

<dependency>
    <groupId>org.eclipse.microprofile.config</groupId>
    <artifactId>microprofile-config-api</artifactId>
    <version>${microprofile.config.version}</version>
</dependency>

<dependency>
    <groupId>org.eclipse.microprofile.config</groupId>
    <artifactId>microprofile-config-tck</artifactId>
    <version>${microprofile.config.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testng</groupId>
    <artifactId>testng</artifactId>
    <version>6.9.9</version>
    <scope>test</scope>
</dependency>
----

== Environment Requirements

Some tests are asserting statements related to environment variables.
The following environment variable and their values must be present in the test runner environment:

* `my_int_property` with the value `45`
* `MY_BOOLEAN_PROPERTY` with the value `true`
* `my_string_property` with the value `haha`
* `MY_STRING_PROPERTY` with the value `woohoo`

See below for an example configuration to provide these environment variables in a Maven pom.xml.

== Declaring the Tests to run

You also need to specify which tests you want to run, e.g. create a file `tck-suite.xml` in your project which contains the following content:
[source, xml]
----
<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >

<suite name="microprofile-config-TCK" verbose="2" configfailurepolicy="continue" >

    <test name="microprofile-config 1.1 TCK">
        <packages>
            <package name="org.eclipse.microprofile.config.tck.*">
            </package>
        </packages>
    </test>

</suite>
----

== Configuration in Apache Maven pom.xml

If you use Apache Maven then the tests are run via the `maven-surefire-plugin`
[source, xml]
----
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.19.1</version>
            <configuration>
                <suiteXmlFiles>
                    <suiteXmlFile>tck-suite.xml</suiteXmlFile>
                </suiteXmlFiles>
                <!-- These env variables are required for org.eclipse.configjsr.CDIPropertyNameMatchingTest -->
                <environmentVariables>
                    <my_int_property>45</my_int_property>
                    <MY_BOOLEAN_PROPERTY>true</MY_BOOLEAN_PROPERTY>
                    <my_string_property>haha</my_string_property>
                    <MY_STRING_PROPERTY>woohoo</MY_STRING_PROPERTY>
                </environmentVariables>
            </configuration>
        </plugin>
    </plugins>
</build>
----

== Using Surefire

If you don't want to use a tck-suite.xml file, you can also just use in line surefire configuration

[source, xml]
----
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <dependenciesToScan>
            <dependency>org.eclipse.microprofile.config:microprofile-config-tck</dependency>
        </dependenciesToScan>
    </configuration>
</plugin>
----

== Deploying additional Implementation Artifacts

If your implementation needs additional Artifacts in the test Deployments then you have to add them via an Arquillian Extension as shown here:

- https://github.com/apache/geronimo-config/blob/trunk/impl/src/test/java/org/apache/geronimo/config/test/GeronimoConfigExtension.java[Arquillian Extension to register archive appending]
- https://github.com/apache/geronimo-config/blob/trunk/impl/src/test/java/org/apache/geronimo/config/test/GeronimoConfigArchiveProcessor.java[Arquillian Extension that appends to the archive]
- https://github.com/apache/geronimo-config/blob/trunk/impl/src/test/resources/META-INF/services/org.jboss.arquillian.core.spi.LoadableExtension[Arquillian Loadable Extension service provider]

== Example Implementation Using the TCK
An example of how an implementation might go about integrating the Microprofile-Config TCK into a build
can be found in the
https://svn.apache.org/repos/asf/geronimo/components/config/trunk/[Apache Geronimo Project].

