Skip to content

Commit

Permalink
feat: Update Maven plugin readme with latest consumer version selectors
Browse files Browse the repository at this point in the history
  • Loading branch information
@uglyog
uglyog committed Aug 2, 2022
1 parent 34d19e3 commit 05dce3c
Show file tree
Hide file tree
Showing 2 changed files with 309 additions and 21 deletions.
145 changes: 125 additions & 20 deletions provider/gradle/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@ not `-D` as with the other Pact-JVM modules!*__

```groovy
plugins {
id "au.com.dius.pact" version "4.1.0"
id "au.com.dius.pact" version "4.1.39"
}
```


### For Gradle versions prior to 2.1
### For Gradle versions prior to 2.1 or if you can't access the Gradle plugin portal

#### 1.1. Add the gradle jar file to your build script class path:

Expand All @@ -28,7 +28,7 @@ buildscript {
mavenCentral()
}
dependencies {
classpath 'au.com.dius.pact.provider:gradle:4.1.0'
classpath 'au.com.dius.pact.provider:gradle:4.1.39'
}
}
```
Expand Down Expand Up @@ -98,17 +98,17 @@ The following project properties can be specified with `-Pproperty=value` on the

The following project properties must be specified as system properties:

| Property | Description |
|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| `pact.verifier.disableUrlPathDecoding` | Disables decoding of request paths |
| `pact.pactbroker.httpclient.usePreemptiveAuthentication` | Enables preemptive authentication with the pact broker when set to `true` |
| `pact.provider.tag` | Sets the provider tag to push before publishing verification results (can use a comma separated list) |
| `pact.provider.branch` | Sets the provider branch to push before publishing verification results |
| `pact.content_type.override.<TYPE>.<SUBTYPE>=<VAL>` where `<VAL>` may be `text`, `json` or `binary` | Overrides the handling of a particular content type [4.1.3+] |
| `pact.verifier.enableRedirectHandling` | Enables automatically handling redirects [4.1.8+] |
| `pact.verifier.ignoreNoConsumers` | If set to `true`, don't fail the build if there are no consumers to verify [4.1.19+] |
| `pact.verifier.buildUrl` | Specifies buildUrl to report to the broker when publishing verification results [4.3.2+] |
| `pactbroker.consumerversionselectors.rawjson` | Overrides the consumer version selectors with raw JSON [4.1.29+/4.3.0+] || `pactbroker.consumerversionselectors.rawjson` | Overrides the consumer version selectors with raw JSON [4.1.29+/4.3.0+] |
| Property | Description |
|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `pact.verifier.disableUrlPathDecoding` | Disables decoding of request paths |
| `pact.pactbroker.httpclient.usePreemptiveAuthentication` | Enables preemptive authentication with the pact broker when set to `true` |
| `pact.provider.tag` | Sets the provider tag to push before publishing verification results (can use a comma separated list) |
| `pact.provider.branch` | Sets the provider branch to push before publishing verification results |
| `pact.content_type.override.<TYPE>.<SUBTYPE>=<VAL>` where `<VAL>` may be `text`, `json` or `binary` | Overrides the handling of a particular content type [4.1.3+] |
| `pact.verifier.enableRedirectHandling` | Enables automatically handling redirects [4.1.8+] |
| `pact.verifier.generateDiff` | Controls the generation of diffs. Can be set to `true`, `false` or a size threshold (for instance `1mb` or `100kb`) which only enables diffs for payloads of size less than that [4.2.7+] |
| `pact.verifier.buildUrl` | Specifies buildUrl to report to the broker when publishing verification results [4.2.16/4.3.2+] |
| `pactbroker.consumerversionselectors.rawjson` | Overrides the consumer version selectors with raw JSON [4.1.29+/4.3.0+] |

## Specifying the provider hostname at runtime

Expand Down Expand Up @@ -364,7 +364,7 @@ an override property: `pact.content_type.override.<TYPE>.<SUBTYPE>=text|binary`.

## Provider States

For a description of what provider states are, see the pact documentations: http://docs.pact.io/documentation/provider_states.html
For a description of what provider states are, see the pact documentations: https://docs.pact.io/getting_started/provider_states

### Using a state change URL

Expand Down Expand Up @@ -540,6 +540,12 @@ pact {
myProvider { // Define the name of your provider here
fromPactBroker {
// For 4.1.39+
withSelectors {
branch('test') // the latest version from a particular branch of each consumer.
}
// For versions before 4.1.39
selectors = latestTags('test') // specify your tags here. You can leave this out to just use the latest pacts
}
Expand All @@ -549,6 +555,106 @@ pact {
}
```

#### Using consumer version selectors (4.1.39+)

You can use a number of different selectors to fetch Pact files that match some criteria. See [Consumer Version Selectors](https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors)
for more information. The following selectors are available:

##### Main branch

The latest version from the main branch of each consumer, as specified by the consumer's mainBranch property.

```groovy
fromPactBroker {
withSelectors {
mainBranch()
}
}
```

##### Matching branch

The latest version from any branch of the consumer that has the same name as the current branch of the provider.
Used for coordinated development between consumer and provider teams using matching feature branch names.

```groovy
fromPactBroker {
withSelectors {
matchingBranch()
}
}
```

##### Branch

The latest version from a particular branch of each consumer, or for a particular consumer if the second
parameter is provided. If fallback is provided, falling back to the fallback branch if none is found from the
specified branch.

```groovy
fromPactBroker {
withSelectors {
branch('FEAT-1234') // Latest version from the particular branch of each consumer
branch('FEAT-1234', 'consumer-a') // Latest version from the particular branch of the provided consumer
branch('FEAT-1234', null, 'master') // Fall back to master branch if none is found from the specified feature branch
branch('FEAT-1234', 'consumer-a', 'master') // As above, but for a single consumer
}
}
```

##### Deployed or released

All the currently deployed and currently released and supported versions of each consumer. You can also specify if
deployed or released to a particular environment.

```groovy
fromPactBroker {
withSelectors {
deployedOrReleased() // All the currently deployed and currently released and supported versions of each consumer.
deployedTo('test') // Any versions currently deployed to the specified environment
releasedTo('test') // Any versions currently released and supported in the specified environment
environment('test') // any versions currently deployed or released and supported in the specified environment
}
}
```

##### Tags

Supports all the forms of selecting Pacts with tags.

```groovy
fromPactBroker {
withSelectors {
tag('test') // All versions with the specified tag.
latestTag('test') // The latest version for each consumer with the specified tag
}
}
```

Using the generic selector:

**NOTE: Generic Tag selectors are deprecated in favor of the more specific selectors (branches/tags/environments etc.)**

* With just the tag name, returns all versions with the specified tag.
* With latest, returns the latest version for each consumer with the specified tag.
* With a fallback tag, returns the latest version for each consumer with the specified tag, falling back to the fallbackTag if none is found with the specified tag.
* With a consumer name, returns the latest version for a specified consumer with the specified tag.
* With only latest, returns the latest version for each consumer. **NOT RECOMMENDED** as it suffers from race conditions when pacts are published from multiple branches.

```groovy
fromPactBroker {
withSelectors {
selector('test') // All versions with the specified tag.
selector('test', true) // The latest version for each consumer with the specified tag
selector('test', true, 'fallback') // the latest version for each consumer with the specified tag, falling back to the fallbackTag if none is found with the specified tag
selector('test', true, null, 'consumer-a') // the latest version for a specified consumer with the specified tag
}
}
```

### For Pact-JVM versions before 4.1.0

You configure your service provider and then use the `hasPactsFrom..` methods.
Expand Down Expand Up @@ -649,16 +755,15 @@ Preemptive Authentication can be enabled by setting the `pact.pactbroker.httpcli
### Allowing just the changed pact specified in a webhook to be verified [4.0.6+]

When a consumer publishes a new version of a pact file, the Pact broker can fire off a webhook with the URL of the changed
pact file. To allow only the changed pact file to be verified, you can override the URL by using the `pact.filter.consumers`
and `pact.filter.pacturl` project properties.
pact file. To allow only the changed pact file to be verified, you can override the URL by using the `pact.filter.pacturl` project properties.

For example, running:

```console
gradle pactVerify -Ppact.filter.consumers='Foo Web Client' -Ppact.filter.pacturl=https://test.pact.dius.com.au/pacts/provider/Activity%20Service/consumer/Foo%20Web%20Client/version/1.0.1
```
gradle pactVerify -Ppact.filter.pacturl=https://test.pact.dius.com.au/pacts/provider/Activity%20Service/consumer/Foo%20Web%20Client/version/1.0.1
```

will only run the verification for Foo Web Client with the given pact file URL.
will only run the verification with the given pact file URL.

## Verifying pact files from a S3 bucket

Expand Down
185 changes: 184 additions & 1 deletion provider/maven/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -478,7 +478,190 @@ configuration in your POM.
</plugin>
```

### Verifying pacts from a pact broker that match particular tags
### Verifying pacts from a pact broker using consumer version selectors [4.3.12+]

You can use a number of different selectors to fetch Pact files that match some criteria. See [Consumer Version Selectors](https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors)
for more information. The following selectors are available:

##### Main branch

The latest version from the main branch of each consumer, as specified by the consumer's mainBranch property.

```xml
<plugin>
<groupId>au.com.dius.pact.provider</groupId>
<artifactId>maven</artifactId>
<version>4.3.12</version>
<configuration>
<serviceProviders>
<serviceProvider>
<name>provider1</name>
<PactBroker>
<selectors>
<mainBranch/>
</selectors>
</PactBroker>
</serviceProvider>
</serviceProviders>
</configuration>
</plugin>
```

##### Matching branch

The latest version from any branch of the consumer that has the same name as the current branch of the provider.
Used for coordinated development between consumer and provider teams using matching feature branch names.

```xml
<plugin>
<groupId>au.com.dius.pact.provider</groupId>
<artifactId>maven</artifactId>
<version>4.3.12</version>
<configuration>
<serviceProviders>
<serviceProvider>
<name>provider1</name>
<PactBroker>
<selectors>
<matchingBranch/>
</selectors>
</PactBroker>
</serviceProvider>
</serviceProviders>
</configuration>
</plugin>
```

##### Branch

The latest version from a particular branch of each consumer, or for a particular consumer if the second
parameter is provided. If fallback is provided, falling back to the fallback branch if none is found from the
specified branch.

```xml
<plugin>
<groupId>au.com.dius.pact.provider</groupId>
<artifactId>maven</artifactId>
<version>4.3.12</version>
<configuration>
<serviceProviders>
<serviceProvider>
<name>provider1</name>
<PactBroker>
<selectors>
<!--Latest version from the particular branch of each consumer -->
<branch>
<name>FEAT-1234</name>
</branch>

<!-- Latest version from the particular branch of the provided consumer -->
<branch>
<name>FEAT-1234</name>
<consumer>consumer-a</consumer>
</branch>

<!-- Fall back to master branch if none is found from the specified feature branch -->
<branch>
<name>FEAT-1234</name>
<fallback>master</fallback>
</branch>

<!-- As above, but for a single consumer -->
<branch>
<name>FEAT-1234</name>
<fallback>master</fallback>
<consumer>consumer-a</consumer>
</branch>
</selectors>
</PactBroker>
</serviceProvider>
</serviceProviders>
</configuration>
</plugin>
```

##### Deployed or released

All the currently deployed and currently released and supported versions of each consumer. You can also specify if
deployed or released to a particular environment.

```xml
<plugin>
<groupId>au.com.dius.pact.provider</groupId>
<artifactId>maven</artifactId>
<version>4.3.12</version>
<configuration>
<serviceProviders>
<serviceProvider>
<name>provider1</name>
<PactBroker>
<selectors>
<!-- All the currently deployed and currently released and supported versions of each consumer. -->
<deployedOrReleased/>

<!-- Any versions currently deployed to the specified environment -->
<deployedTo>
<environment>test</environment>
</deployedTo>

<!-- Any versions currently released and supported in the specified environment -->
<releasedTo>
<environment>test</environment>
</releasedTo>

<!-- Any versions currently deployed or released and supported in the specified environment -->
<environment>
<name>test</name>
</environment>
</selectors>
</PactBroker>
</serviceProvider>
</serviceProviders>
</configuration>
</plugin>
```

##### Tags

Supports all the forms of selecting Pacts with tags.

```xml
<plugin>
<groupId>au.com.dius.pact.provider</groupId>
<artifactId>maven</artifactId>
<version>4.3.12</version>
<configuration>
<serviceProviders>
<serviceProvider>
<name>provider1</name>
<PactBroker>
<selectors>
<!-- All versions with the specified tag. -->
<tagName>
<name>test</name>
</tagName>

<!-- The latest version for each consumer with the specified tag -->
<latestTag>
<name>FEAT-1234</name>
</latestTag>

<!-- The latest version for each consumer with the specified tag with a fallback -->
<latestTag>
<name>FEAT-1234</name>
<fallback>master</fallback>
</latestTag>
</selectors>
</PactBroker>
</serviceProvider>
</serviceProviders>
</configuration>
</plugin>
```

### Verifying pacts from a pact broker that match particular tags [DEPRECATED]

**NOTE: Using tags has been deprecated in favour of using consumer version selectors (above).**

If your pacts in your pact broker have been tagged, you can set the tags to fetch by configuring the `tags`
element of the `pactBroker` element of your provider.
Expand Down

0 comments on commit 05dce3c

Please sign in to comment.