<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <groupId>au.com.dius</groupId>
  <artifactId>pact-jvm-consumer-junit5</artifactId>
  <version>4.0.0-beta.2</version>
  <name>pact-jvm-consumer-junit5</name>
  <description>pact-jvm-consumer-junit5
========================

JUnit 5 support for Pact consumer tests

## Dependency

The library is available on maven central using:

* group-id = `au.com.dius`
* artifact-id = `pact-jvm-consumer-junit5`
* version-id = `4.0.x`

## Usage

### 1. Add the Pact consumer test extension to the test class.

To write Pact consumer tests with JUnit 5, you need to add `@ExtendWith(PactConsumerTestExt)` to your test class. This
replaces the `PactRunner` used for JUnit 4 tests. The rest of the test follows a similar pattern as for JUnit 4 tests.

```java
@ExtendWith(PactConsumerTestExt.class)
class ExampleJavaConsumerPactTest {
```

### 2. create a method annotated with `@Pact` that returns the interactions for the test

For each test (as with JUnit 4), you need to define a method annotated with the `@Pact` annotation that returns the
interactions for the test.

```java
    @Pact(provider=&amp;quot;ArticlesProvider&amp;quot;, consumer=&amp;quot;test_consumer&amp;quot;)
    public RequestResponsePact createPact(PactDslWithProvider builder) {
        return builder
            .given(&amp;quot;test state&amp;quot;)
            .uponReceiving(&amp;quot;ExampleJavaConsumerPactTest test interaction&amp;quot;)
                .path(&amp;quot;/articles.json&amp;quot;)
                .method(&amp;quot;GET&amp;quot;)
            .willRespondWith()
                .status(200)
                .body(&amp;quot;{\&amp;quot;responsetest\&amp;quot;: true}&amp;quot;)
            .toPact();
    }
```

### 3. Link the mock server with the interactions for the test with `@PactTestFor`

Then the final step is to use the `@PactTestFor` annotation to tell the Pact extension how to setup the Pact test. You
can either put this annotation on the test class, or on the test method. For examples see
[ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) and
[MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy).

The `@PactTestFor` annotation allows you to control the mock server in the same way as the JUnit 4 `PactProviderRule`. It
allows you to set the hostname to bind to (default is `localhost`) and the port (default is to use a random port). You
can also set the Pact specification version to use (default is V3).

```java
@ExtendWith(PactConsumerTestExt.class)
@PactTestFor(providerName = &amp;quot;ArticlesProvider&amp;quot;)
public class ExampleJavaConsumerPactTest {
```

**NOTE on the hostname**: The mock server runs in the same JVM as the test, so the only valid values for hostname are:

| hostname | result |
| -------- | ------ |
| `localhost` | binds to the address that localhost points to (normally the loopback adapter) |
| `127.0.0.1` or `::1` | binds to the loopback adapter |
| host name | binds to the default interface that the host machines DNS name resolves to |
| `0.0.0.0` or `::` | binds to the all interfaces on the host machine |

#### Matching the interactions by provider name

If you set the `providerName` on the `@PactTestFor` annotation, then the first method with a `@Pact` annotation with the
same provider name will be used. See [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) for
an example.

#### Matching the interactions by method name

If you set the `pactMethod` on the `@PactTestFor` annotation, then the method with the provided name will be used (it still
needs a `@Pact` annotation). See [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy) for an example.

### Injecting the mock server into the test

You can get the mock server injected into the test method by adding a `MockServer` parameter to the test method.

```java
  @Test
  void test(MockServer mockServer) throws IOException {
    HttpResponse httpResponse = Request.Get(mockServer.getUrl() + &amp;quot;/articles.json&amp;quot;).execute().returnResponse();
    assertThat(httpResponse.getStatusLine().getStatusCode(), is(equalTo(200)));
  }
```

This helps with getting the base URL of the mock server, especially when a random port is used.

## Changing the directory pact files are written to

By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property.
This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests.

For Gradle, add this to your build.gradle:

```groovy
test {
    systemProperties[&amp;apos;pact.rootDir&amp;apos;] = &amp;quot;$buildDir/custom-pacts-directory&amp;quot;
}
```

For maven, use the systemPropertyVariables configuration:

```xml
&amp;lt;project&amp;gt;
  [...]
  &amp;lt;build&amp;gt;
    &amp;lt;plugins&amp;gt;
      &amp;lt;plugin&amp;gt;
        &amp;lt;groupId&amp;gt;org.apache.maven.plugins&amp;lt;/groupId&amp;gt;
        &amp;lt;artifactId&amp;gt;maven-surefire-plugin&amp;lt;/artifactId&amp;gt;
        &amp;lt;version&amp;gt;2.18&amp;lt;/version&amp;gt;
        &amp;lt;configuration&amp;gt;
          &amp;lt;systemPropertyVariables&amp;gt;
            &amp;lt;pact.rootDir&amp;gt;some/other/directory&amp;lt;/pact.rootDir&amp;gt;
            &amp;lt;buildDirectory&amp;gt;${project.build.directory}&amp;lt;/buildDirectory&amp;gt;
            [...]
          &amp;lt;/systemPropertyVariables&amp;gt;
        &amp;lt;/configuration&amp;gt;
      &amp;lt;/plugin&amp;gt;
    &amp;lt;/plugins&amp;gt;
  &amp;lt;/build&amp;gt;
  [...]
&amp;lt;/project&amp;gt;
```

For SBT:

```scala
fork in Test := true,
javaOptions in Test := Seq(&amp;quot;-Dpact.rootDir=some/other/directory&amp;quot;)
```

### Using `@PactFolder` annotation

You can override the directory the pacts are written in a test by adding the `@PactFolder` annotation to the test
class.

## Forcing pact files to be overwritten (3.6.5+)

By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be 
overwritten, set the Java system property `pact.writer.overwrite` to `true`.

## Unsupported

The current implementation does not support tests with multiple providers. This will be added in a later release.
</description>
  <url>https://github.com/DiUS/pact-jvm</url>
  <licenses>
    <license>
      <name>Apache 2</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  <developers>
    <developer>
      <id>thetrav</id>
      <name>Travis Dixon</name>
      <email>the.trav@gmail.com</email>
    </developer>
    <developer>
      <id>rholshausen</id>
      <name>Ronald Holshausen</name>
      <email>rholshausen@dius.com.au</email>
    </developer>
  </developers>
  <scm>
    <connection>https://github.com/DiUS/pact-jvm.git</connection>
    <url>https://github.com/DiUS/pact-jvm</url>
  </scm>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <version>5.4.1</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>au.com.dius</groupId>
      <artifactId>pact-jvm-consumer</artifactId>
      <version>4.0.0-beta.2</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
      <version>1.7.26</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</project>
