//
// 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 Config 2.0 implementation must pass this test suite. The TCK uses `TestNG` and `Arquillian`.

== Hardware Requirements

All systems should meet the following recommended hardware requirements:

    * CPU running at 2.0 GHz or higher
    * 4 GB of RAM or more
    * Network access to the Internet

== Software Requirements

You can run MicroProfile Config TCK on platforms running the Solaris, Linux, Windows, and Mac OS with the following software installed:

    * Maven
    * JDK8+

== Dependencies

To enable the TCK in your implementation you require at least the following dependencies:

[source, xml]
----
<properties>
   <version.weld.api>3.1.Final</version.weld.api>
</properties>

<dependencies>
    <dependency>
        <groupId>org.eclipse.microprofile.config</groupId>
        <artifactId>microprofile-config-api</artifactId>
        <version>3.1</version>
    </dependency>

    <dependency>
        <groupId>jakarta.enterprise</groupId>
        <artifactId>jakarta.enterprise.cdi-api</artifactId>
        <version>${dependency.jakarta.cdi.version}</version>
        <scope>provided</scope>
    </dependency>

    <dependency>
        <groupId>org.eclipse.microprofile.config</groupId>
        <artifactId>microprofile-config-tck</artifactId>
        <version>3.1</version>
        <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.jboss.weld</groupId>
      <artifactId>weld-api</artifactId>
      <version>${version.weld.api}</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.jboss.weld</groupId>
      <artifactId>weld-spi</artifactId>
      <version>${version.weld.api}</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.jboss.weld</groupId>
      <artifactId>weld-core-impl</artifactId>
      <version>${version.weld.api}</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.jboss.arquillian.container</groupId>
      <artifactId>arquillian-weld-embedded</artifactId>
      <version>${version.weld.api}</version>
      <scope>test</scope>
    </dependency>
</dependencies>
----

The dependencis list specify `Weld` as the CDI container implementation. This may be replaced by any other CDI
compatible implementation.

Additional dependencies may be required to specify the artifacts containing the MicroProfile Config implementation that
is going to betested.

== 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`
* `MP_TCK_ENV_DUMMY` with the value `dummy`
* `config_ordinal` with `45`
* `customer_name` with `Bob`

The following system properties and their values must be present in the test runner environment:

* `mp.tck.prop.dummy` with the value `dummy`
* `config_ordinal` with the value `120`
* `customer.hobby` with the value `Tennis`

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 3.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.22.2</version>
            <configuration>
                <suiteXmlFiles>
                    <suiteXmlFile>tck-suite.xml</suiteXmlFile>
                </suiteXmlFiles>
                <!-- These env variables are required for org.eclipse.configjsr.CDIPropertyNameMatchingTest -->
                <environmentVariables>
                    <MP_TCK_ENV_DUMMY>dummy</MP_TCK_ENV_DUMMY>
                    <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>
                    <config_ordinal>45</config_ordinal>
                    <customer_name>Bob</customer_name>
                </environmentVariables>
                <systemProperties>
                    <mp.tck.prop.dummy>dummy</mp.tck.prop.dummy>
                    <customer.hobby>Tennis</customer.hobby>
                    <config_ordinal>120</config_ordinal>
                </systemProperties>
            </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://github.com/apache/geronimo-config[Apache Geronimo Project].
