Merge branch 'release/0.0.13' into main

Author: Jenkins

Jenkinsfile

@@ -49,7 +49,7 @@ pipeline {
   }
   post {
     always {
-        archiveArtifacts 'README.md'
+        archiveArtifacts(artifacts: '*.md')
         junit (testResults: 'target/surefire-reports/*.xml', allowEmptyResults: true)
     }
   }

README.md

@@ -6,19 +6,21 @@
 [![Twitter Follow](https://img.shields.io/twitter/follow/skuzzleOSS.svg?style=social)](https://twitter.com/skuzzleOSS)
 
 # spring-boot-wiremock
-(This is **not** an official extension from the Spring Team!)
+_This is **not** an official extension from the Spring Team!_ (Though one exists as part of the 
+[spring-cloud](https://cloud.spring.io/spring-cloud-contract/reference/html/project-features.html#features-wiremock) 
+project).
 
-The easiest way to setup a [WireMock](http://wiremock.org/)  server in your Spring-Boot tests with *JUnit5*
+The easiest way to setup a [WireMock](http://wiremock.org/)  server in your Spring-Boot tests.
 - [x] Run WireMock server on random port
 - [x] Inject WireMock hosts (http and https) as spring application property
 - [x] Easily setup server- and client side SSL
-- [x] Define simple stubs using annotations
+- [x] Declarative stubs using annotations
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.springboot.test</groupId>
     <artifactId>spring-boot-wiremock</artifactId>
-    <version>0.0.12</version>
+    <version>0.0.13</version>
     <scope>test</scope>
 </dependency>
 ```
@@ -66,6 +68,10 @@ Injecting the host into the application context happens _before_ any bean instan
 property values takes precedence over any other, for example statically configured value. This means, in most cases the 
 extension works out of the box with your current context configuration.
 
+You can see more annotation stubbing examples in 
+[this](https://github.com/skuzzle/spring-boot-wiremock/blob/main/src/test/java/de/skuzzle/springboot/test/wiremock/TestHttpStub.java) 
+test class.
+
 ## Rationale
 [WireMock](http://wiremock.org/) is an awesome library for mocking HTTP endpoints in unit tests. However, it can be 
 quite cumbersome to integrate with Spring-Boot: when you manually manage the `WireMockServer` from within the test,
@@ -84,17 +90,166 @@ can be injected into the Spring application properties, simply replacing an exis
 
 ## Compatibility
 - [x] Requires Java 11
-- [x] Tested against Spring-Boot `2.2.13.RELEASE, 2.3.12.RELEASE, 2.4.7, 2.5.2`
+- [x] Tested against Spring-Boot `2.2.13.RELEASE, 2.3.12.RELEASE, 2.4.8, 2.5.2`
 - [x] Tested against WireMock `2.27.1`
 
+## Usage
+
+### WireMock based stubbing
+If you set up WireMock using `@WithWireMock` the server instance is made available as bean in the Spring 
+`ApplicationContext`. It can thus be injected into the test class like this:
+
+```java
+@WithWiremock(...)
+@SpringBootTest
+public class WiremockTest {
+
+    @Autowired
+    private WireMockServer wiremock;
+}
+```
+
+You can then use the normal WireMock API in your test methods to define stubs and verifications.
+
+### Annotation based stubbing
+If you opt-in to use annotation based stubbing provided by this library you gain the advantages of full declarative 
+stubbing and easily reusable stubs.
+
+> **Warning**: Please note that using annotation based stubbing will make it harder to get rid of this library from your 
+> code base in the future. You should consider to only use WireMock based stubbing to reduce coupling to this library.
+
+Not all WireMock features (e.g. verifications) are available in annotation based stubbing. It is always possible though 
+to combine annotation based stubs with plain WireMock based stubs as describe above.
+
+#### Simple stubs
+You can define a simple stub by annotating your test/test class with `@HttpStub`. If you specify no further attributes,
+the mock will now respond with `200 OK` for every request it receives. Note that all additional attributes are optional.
+
+Here is a more sophisticated stub example:
+```java
+@HttpStub(
+    onRequest = @Request(
+            withMethod = "POST",
+            toUrlPath = "/endpoint",
+            withQueryParameters = "param=matching:[a-z]+",
+            containingHeaders = "Request-Header=eq:value",
+            containingCookies = "sessionId=containing:123456",
+            withBody = "containing:Just a body",
+            authenticatedBy = @Auth(
+                    basicAuthUsername = "username",
+                    basicAuthPassword = "password")),
+    respond = @Response(
+            withStatus = HttpStatus.CREATED,
+            withBody = "Hello World",
+            withContentType = "application/text",
+            withHeaders = "Response-Header=value"))
+```
+
+#### String matching
+All stub request attributes that expect a String value optionally take a matcher prefix like shown in the above example.
+The following prefixes are supported:
+| Prefix             | Operation |
+|--------------------|-----------|
+|`eq:`               | Comparison using `String.equals` |
+|`eqIgnoreCase:`     | Comparison using `String.equalsIgnoreCase` |
+|`eqToJson:`         | Interpretes the strings as json |
+|`eqToXml`           | Interpretes the strings as xml |
+|`matching:`         | Comparison using the provided regex pattern |
+|`notMatching:`      | Comparison using the provided regex pattern but negates the result |
+|`matchingJsonPath:` | Interpretes the string as json and matches it against the provided json path |
+|`matchingXPath:`    | Interpretes the string as xml and matches it against the provided xpath |
+|`containing:`       | Comparison using `String.contains` |
+
+No prefix always results in a comparison using `String.equals`.
+
+#### Multiple responses
+It is possible to define multiple responses that will be returned by the stub when a stub is matched by consecutive 
+requests. Internally this feature will create a WireMock scenario, thus you can not combine multiple responses and 
+explicit scenario creation using `Requst.scenario`.
+
+```java
+@HttpStub(
+    respond = {
+            @Response(withStatus = HttpStatus.CREATED),
+            @Response(withStatus = HttpStatus.OK),
+            @Response(withStatus = HttpStatus.ACCEPTED)
+    })
+```
+When stubbing multiple responses you can define what happens when the last response has been returned using 
+`HttpStub.onLastResponse` with the following options:
+
+| `onLastResponse`         | Behavior |
+|--------------------------|----------|
+|`WrapAround.RETURN_ERROR` | Default behavior. Mock will answer with a `403` code after the last response |
+|`WrapAround.START_OVER`   | After the last response the mock will start over and answer with the first response |
+|`WrapAround.REPEAT`       | The mock keeps returning the last response |
+
+```java
+@HttpStub(
+    // ...
+    respond = {
+        // ...
+    },
+    onLastResponse = WrapAround.REPEAT;
+)
+```
+
+#### Sharing stubs
+It is possible to share stubs among multiple tests. You can either define your stubs on a super class or an interface 
+implemented by your test class. However, the preferred way of sharing stubs is to create a new annotation which 
+is meta-annotated with all the stubs (and optionally also with `@WithWiremock`) like in the following example:
+
+```java
+@Retention(RUNTIME)
+@Target(TYPE)
+@WithWiremock(injectHttpHostInto = "sample-service.url")
+@HttpStub(onRequest = @Request(toUrl = "/info"),
+        respond = @Response(withStatus = HttpStatus.OK, withStatusMessage = "Everything is Ok"))
+@HttpStub(onRequest = @Request(toUrl = "/submit/entity", withMethod = "PUT"), respond = {
+        @Response(withStatus = HttpStatus.CREATED, withStatusMessage = "Entity created"),
+        @Response(withStatus = HttpStatus.OK, withStatusMessage = "Entity already exists")
+})
+public @interface WithSampleServiceMock {
+
+}
+```
+
+You can now easily reuse the complete mock definition in any `SpringBootTest`:
+```java
+@SpringBootTest
+@WithSampleServiceMock
+public class MetaAnnotatedTest {
+
+    @Value("${sample-service.url}")
+    private String sampleServiceUrl;
+    
+    // ...
+}
+```
+
 ## Changelog
 
+  
+### Version 0.0.13
+* Improve documentation
+* [Change] Move stubbing annotations into their own package: `de.skuzzle.wiremock.test.stubs` (**breaking**)
+* [Change] Deprecated `HttpStub.wrapAround` and introduced `HttpStub.onLastResponse` with new enum `WrapAround`
+* [Add] New properties that will always be injected: `wiremock.server.http(s)Host`, `wiremock.server.http(s)Port`
+* [Add] `WrapAround.REPEAT` which will repeat the last response on every subsequent request
+* [Add] Allow to globally define required authentication via `WithWiremock.withGlobalAuthentication`
+
+<details>
+  <summary><b>Previous releases</b></summary>
+  
+### Version 0.0.12
+* Just some improvements to the build/release process
+
 ### Version 0.0.11
 * Just some improvements to the build/release process
 
 ### Version 0.0.10
-* [FiX] Readme
-* [Change] Use latest WireMock version
+* [Fix] Readme
+* [Change] Use latest WireMock version (`2.27.1`)
 
 ### Version 0.0.9
 * [Add] Possibility to set a stub's priority
@@ -136,3 +291,5 @@ can be injected into the Spring application properties, simply replacing an exis
 
 ### Version 0.0.1
 * Initial prototype
+
+</details>

RELEASE_NOTES.md

@@ -1,10 +1,17 @@
-* Just some improvements to the build/release process
+* Improve documentation
+* [Change] Move stubbing annotations into their own package: `de.skuzzle.wiremock.test.stubs` (**breaking**)
+* [Change] Deprecated `HttpStub.wrapAround` and introduced `HttpStub.onLastResponse` with new enum `WrapAround`
+* [Add] New properties that will always be injected: `wiremock.server.http(s)Host`, `wiremock.server.http(s)Port`
+* [Add] `WrapAround.REPEAT` which will repeat the last response on every subsequent request
+* [Add] Allow to globally define required authentication via `WithWiremock.withGlobalAuthentication`
+
+Maven Central coordinates for this release:
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.springboot.test</groupId>
     <artifactId>spring-boot-wiremock</artifactId>
-    <version>0.0.12</version>
+    <version>0.0.13</version>
     <scope>test</scope>
 </dependency>
 ```

pom.xml

@@ -9,7 +9,7 @@
 
     <groupId>de.skuzzle.springboot.test</groupId>
     <artifactId>spring-boot-wiremock</artifactId>
-    <version>0.0.12</version>
+    <version>0.0.13</version>
     <url>https://github.com/skuzzle/spring-boot-wiremock</url>
 
     <name>SpringBoot WireMock</name>
@@ -18,13 +18,12 @@
     <properties>
         <coveralls.skip>false</coveralls.skip>
 
-
         <!-- Minimal compatible Spring-Boot version. Newer versions are tested during Jenkins build. -->
         <version.spring-boot>2.2.13.RELEASE</version.spring-boot>
         <version.wiremock>2.27.1</version.wiremock>
         <version.guava>30.1.1-jre</version.guava>
         <!-- All the remaining spring-boot versions we run the tests against (comma separated) -->
-        <compatible-spring-boot-versions>2.3.12.RELEASE, 2.4.7, 2.5.2</compatible-spring-boot-versions>
+        <compatible-spring-boot-versions>2.3.12.RELEASE, 2.4.8, 2.5.2</compatible-spring-boot-versions>
 
         <site.name>spring-boot-wiremock</site.name>
         <github.name>spring-boot-wiremock</github.name>