//
// Copyright (c) 2022-2023 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// 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.
//

= MicroProfile Telemetry Tracing TCK
Any MicroProfile Telemetry 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 this TCK on platforms running the Solaris, Linux, Windows, and Mac OS with the following software installed:

    * Maven
    * JDK11+

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

[source, xml]
----

<dependency>
    <groupId>org.eclipse.microprofile.telemetry</groupId>
    <artifactId>microprofile-telemetry-tracing-tck</artifactId>
    <version>1.0</version>
    <scope>test</scope>
</dependency>

----

== Declaring the Tests to run
There is a group of optional tests. This includes: 

* `optional-tests`: `B3` and `Jaeger` progagation formats. 
+
These tests test the B3 and Jaeger propagation formats which are not required. If your implementation does not include support for these propagation formats, you should exclude the `optional-tests` group.

Test groups can be excluded in the TestNG XML file. 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-telemetry-tracing-TCK" verbose="2" configfailurepolicy="continue" >
    <test name="telemetry-tracing-tests" verbose="10">
        <groups>
            <run>
                <!-- Exclude B3 and Jaeger propagation tests-->
                <exclude name="optional-tests"/>
            </run>
        </groups>
        <packages>
            <package name="org.eclipse.microprofile.telemetry.tracing.tck.*" />
        </packages>
    </test>
</suite>
----

If you want to run the optional tests, you can specify all tests in the `tck-suite.xml`. E.g. 

[source, xml]
----
<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd" >

<suite name="microprofile-telemetry-tracing-TCK" verbose="2" configfailurepolicy="continue" >
    <test name="telemetry-tracing-tests" verbose="10">
        <packages>
            <package name="org.eclipse.microprofile.telemetry.tracing.tck.*" />
        </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>
            </configuration>
        </plugin>
    </plugins>
</build>
----

== Providing an Executor [[Executor]]

When the tests are running, ensure that the classpath contains the following:

- A class that implements the interface `java.util.concurrent.Executor` in whatever way is most appropriate for your server.
- A file under META-INF/microprofile-telemetry-tck.properties. This file must contain a line `telemetry.tck.executor=<packagename>.<classname>` referring to the previous class.

== Running as a Scanned Dependency
You can also run the TCK as a scanned dependency.

=== Surefire Configuration in your pom.xml
Once you've added the dependency, you don't need a `tck-suite.xml` you can just scan the dependency for tests.

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