
//   Copyright (c) 2018 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 LRA TCK

== 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

== Software Requirements

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

* Maven
* JDK8+

The TCK uses `JUnit 4` and `Arquillian`.

== SPI

In order to run TCK, the implementors must provide an implementation of
`org.eclipse.microprofile.lra.tck.service.spi.LraRecoveryService` and declare
it as a CDI bean so it can be used in the TCK environment.

== Configuration

The LRA TCK suite can be parametrized by following properties, handled in the suite with MicroProfile Config

`lra.tck.base.url`::
  The URL where the TCK suite deployment is exposed at. The TCK suite will construct path based on this URL.
  The default base URL is `http://localhost:8180`. This property needs to be provided for the container,
  and for the tests themselves (failsafe/surefire) too.
`lra.tck.timeout.factor`::
  Timeout factor adjust timeout values used in the TCK suite. The default value is `1.0`.
  When set bigger than `1.0` then timeout value will be bigger and waiting time is longer.
  When set-up lower then the timeouts will be shorter.
  Thus on slower machines it's expected longer timeouts will be needed. For example if test expects
  some waiting time to be 10 seconds and this factor is set to `1.5` then the result waiting time is 15 seconds.
  The timeout factor must be configured as system property because of the test limitations.
`lra.http.recovery.host`, `lra.http.recovery.port`, `lra.http.recovery.path`::
  Hostname, port and path for the recovery endpoint that will be contacted in tests checking recovery capabilities.

== Prerequisites for the MicroProfile LRA TCK implementation

* `pom.xml` dependencies are set-up
* the LRA TCK suite requires MicroProfile Config
* a default Arquillian container is configured in `arquillian.xml` (tests manually deploy with use of `@ArquillianResource Deployer`)
* JAX-RS `ClientBuilder` is used to run REST calls from tests to tested application. Provide the implementation of the
  JAX-RS `ClientBuilder` on the test class path.

=== Setting-up pom.xml dependencies and running the tests

To enable the tests in your implementation of this specification you need to add the following dependency to your build:

[source, xml]
----
<dependency>
    <groupId>org.eclipse.microprofile.lra</groupId>
    <artifactId>microprofile-lra-tck</artifactId>
    <version>${version.microprofile-lra-tck-to-test}</version>
    <scope>test</scope>
</dependency>
----

Next you need to specify what are tests to be run. You need to inject the TCK suite tests to be run automatically.
Here we use integration tests with `maven failsafe` where dependency to scan is set to include particular test classes.

[source, xml]
----
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-failsafe-plugin</artifactId>
            <configuration>
                <dependenciesToScan>
                    <dependency>org.eclipse.microprofile.lra:microprofile-lra-tck</dependency>
                </dependenciesToScan>
                <includes>
                    <include>**/*Test*.java</include>
                </includes>
            </configuration>
        </plugin>
    </plugins>
</build>
----

=== MicroProfile Config being available

The testsuite uses configuration while expecting MicroProfile Config is available. The maven coordinates
of config are `org.eclipse.microprofile.config:microprofile-config-api`.

=== Arquillian container

The `arquillian-*.xml` has to define a container that will be started and managed by Arquillian lifecycle
but that provide a way to deploy and undeploy deployments. That container to be expected with default type `suite`.


[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>

<arquillian>
    <container qualifier="lra-test-container" default="true" mode="suite">
        <configuration>
        ...
        </configuration>
    </container>
<arquillian>
----

== SPI

* The TCK provides an SPI `LRARecoveryService` which is retrived through the
`ServiceLoader` mechanism. The implmenter is required to provide an
implementation of this interface in order to run the TCK.

== Debugging tests

Debugging is dependent on the TCK implementor. The implementor configures Arquillian to use particular runtime
to deploy the test deployments and run the LRA client side implementation there. In general we can say that
the runtime needs to define java debug properties `-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y`.
Then debugger may be connected to port 8787 and to track the test execution.

