mework.cloud.spring-cloud-contract-docs.4.0.4.source-code.sagan-boot.adoc Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of spring-cloud-contract-docs Show documentation
Spring Cloud Docs
There is a newer version: 4.1.5
Show newest version
== On the Producer Side

To start working with Spring Cloud Contract, you can add files with REST or messaging contracts expressed in either Groovy DSL or YAML to the contracts directory, which is set by the contractsDslDir property. By default, it is $rootDir/src/test/resources/contracts.

Then you can add the Spring Cloud Contract Verifier dependency and plugin to your build file, as the following example shows:

```xml

    org.springframework.cloud
    spring-cloud-starter-contract-verifier
    test

```

The following listing shows how to add the plugin, which should go in the build/plugins portion of the file:

```xml

    org.springframework.cloud
    spring-cloud-contract-maven-plugin
    ${spring-cloud-contract.version}
    true

```

Running `./mvnw clean install` automatically generates tests that verify the application compliance with the added contracts. By default, the tests get generated under `org.springframework.cloud.contract.verifier.tests`.

As the implementation of the functionalities described by the contracts is not yet present, the tests fail.

To make them pass, you must add the correct implementation of either handling HTTP requests or messages. Also, you must add a base test class for auto-generated tests to the project. This class is extended by all the auto-generated tests, and it should contain all the setup information necessary to run them (for example `RestAssuredMockMvc` controller setup or messaging test setup).

The following example, from pom.xml, shows how to specify the base test class:

```xml

    
        
            org.springframework.cloud
            spring-cloud-contract-maven-plugin
            ${spring-cloud-contract.version}
            true
            
                com.example.contractTest.BaseTestClass 
            
        
        
            org.springframework.boot
            spring-boot-maven-plugin
        
    

```

INFO: The baseClassForTests element lets you specify your base test class. It must be a child of a configuration element within spring-cloud-contract-maven-plugin.

Once the implementation and the test base class are in place, the tests pass, and both the application and the stub artifacts are built and installed in the local Maven repository. You can now merge the changes, and you can publish both the application and the stub artifacts in an online repository.

== On the Consumer Side

You can use Spring Cloud Contract Stub Runner in the integration tests to get a running WireMock instance or messaging route that simulates the actual service.

To do so, add the dependency to Spring Cloud Contract Stub Runner, as the following example shows:

```xml

    org.springframework.cloud
    spring-cloud-starter-contract-stub-runner
    test

```

You can get the Producer-side stubs installed in your Maven repository in either of two ways:

By checking out the Producer side repository and adding contracts and generating the stubs by running the following commands:

```bash
$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests
```

The tests are being skipped because the producer-side contract implementation is not in place yet, so the automatically-generated contract tests fail.

By getting already-existing producer service stubs from a remote repository. To do so, pass the stub artifact IDs and artifact repository URL as Spring Cloud Contract Stub Runner properties, as the following example shows:

```yml
    stubrunner:
      ids: 'com.example:http-server-dsl:+:stubs:8080'
      repositoryRoot: https://repo.spring.io/libs-snapshot
```  

Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation, provide the group-id and artifact-id values for Spring Cloud Contract Stub Runner to run the collaborators' stubs for you, as the following example shows:

```java
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
        stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {
```

Use the `REMOTE` stubsMode when downloading stubs from an online repository and `LOCAL` for offline work.

Now, in your integration test, you can receive stubbed versions of HTTP responses or messages that are expected to be emitted by the collaborator service.