Merge branch 'main' into add-new-command-options-for-http-client

_config.yml

@@ -234,11 +234,11 @@ compress_html:
     ignore:
         envs: development
 
-wiremock_version: 3.6.0
+wiremock_version: 3.9.1
 wiremock_baseline: 3.x
 pageEditPrefix: https://github.com/wiremock/wiremock.org/edit/main/
 
-grpc_extension_version: 0.6.0
+grpc_extension_version: 0.8.0
 
 community_slack:
   join_url: https://slack.wiremock.org/

_docs/configuration.md

@@ -125,6 +125,9 @@ HTTP/2 can be disabled separately for plain text (HTTP) and TLS (HTTPS):
 
 // Send the Host header in the original request onwards to the system being proxied to
 .preserveHostHeader(false)
+
+// As of WireMock `3.7.0`, when in proxy mode, this option will transfer the original `User-Agent` header from the client to the proxied service.
+.preserveUserAgentProxyHeader(true) 
 
  // Override the Host header sent when reverse proxying to another system (this and the previous parameter are mutually exclusive)
 .proxyHostHeader("my.otherdomain.com")
@@ -177,6 +180,16 @@ The request journal records requests received by WireMock. It is required by the
 .maxRequestJournalEntries(Optional.of(100))
 ```
 
+## Template Cache
+
+When response templating is enabled, compiled template fragments are cached to improve performance.  This setting allows
+you to configure the maximum number of entries to allow in the cache.  As of WireMock `3.7.0`, this defaults to 1000 
+cache entries.  Before WireMock `3.7.0` the default was unlimited
+
+```java
+.withMaxTemplateCacheEntries(100)
+```
+
 ## Notification (logging)
 
 WireMock wraps all logging in its own `Notifier` interface. It ships with no-op, Slf4j and console (stdout) implementations.

_docs/grpc.md

@@ -45,9 +45,9 @@ Maven:
 </dependency>
 ```
 
-Create a root directory for WireMock e.g. `src/test/resources/wiremock` and create a subdirectory under this named `grpc`.
+Create a root directory for WireMock, typically `src/test/resources/wiremock`, and create a subdirectory in it named `grpc`.
 
-Put the descriptor files generated by `protoc` from your `.proto` files into the `grpc` directory.
+Copy the descriptor files generated by `protoc` from your `.proto` files into the `grpc` subdirectory.
 
 Initialise WireMock server with the extension enabled and the root directory set to the path created in the previous steps:
 
@@ -72,7 +72,7 @@ WireMockGrpcService mockGreetingService =
 
 ### Stubbing via JSON matching + responses
 
-To specify request criteria and response data via JSON:
+To specify request criteria and response data using JSON:
 
 ```java
 mockGreetingService.stubFor(
@@ -81,8 +81,9 @@ mockGreetingService.stubFor(
         .willReturn(json("{ "greeting": "Hi Tom from JSON" }")));
 ```
 
+Or, with a templated response:
 
-Or with a templated response:
+{% raw %}
 
 ```java
 mockGreetingService.stubFor(
@@ -93,6 +94,8 @@ mockGreetingService.stubFor(
                 "{ \"greeting\": \"Hello {{jsonPath request.body '$.name'}}\" }")));
 ```
 
+{% endraw %}
+
 ### Stubbing via Java message objects
 
 Matching and stubbing in the Java DSL can also be specified using the Java classes generated by `protoc`:
@@ -126,13 +129,13 @@ For a more complete set of examples, see the [Java demo project](https://github.
 
 ### Setup
 
-Download the <a id="wiremock-standalone-download" href="https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/{{ site.wiremock_version }}/wiremock-standalone-{{ site.wiremock_version }}.jar">standalone JAR</a> at version 3.2.0 or above 
+Download the <a id="wiremock-standalone-download" href="https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/{{ site.wiremock_version }}/wiremock-standalone-{{ site.wiremock_version }}.jar">standalone JAR</a> at version 3.2.0 or above
  and the <a id="wiremock-standalone-download" href="https://repo1.maven.org/maven2/org/wiremock/wiremock-grpc-extension-standalone/{{ site.grpc_extension_version }}/wiremock-grpc-extension-standalone-{{ site.grpc_extension_version }}.jar">gRPC extension JAR</a> into your working directory.
 
-Create a WireMock data directory with a subdirectory for stub mappings and one for descriptor files:
+Create a WireMock data directory with two subdirectories; one for stub mappings, and another for descriptor files:
 
 ```bash
-mkdir -p wiremock/mappings wiremock/grpc
+mkdir -p wiremock wiremock/mappings wiremock/grpc
 ```
 
 Compile your proto files into descriptors:
@@ -141,12 +144,12 @@ Compile your proto files into descriptors:
 protoc --descriptor_set_out wiremock/grpc/services.dsc ExampleServices.proto
 ```
 
-Run WireMock with both on the classpath:
+Run WireMock, with both directories you just created on the classpath:
 
 ```bash
-java -cp wiremock-standalone-{{ site.wiremock_version }}.jar:wiremock-grpc-extension-standalone-{{ site.grpc_extension_version }}.jar \
+java -cp wiremock-standalone-{{ versions.wiremock_version }}.jar:wiremock-grpc-extension-standalone-{{ versions.grpc_extension_version }}.jar \
   wiremock.Run \
-  --root-dir wiremock-data
+  --root-dir wiremock
 ```
 
 ### Stubbing
@@ -172,6 +175,10 @@ gRPC stubs are defined using WireMock's standard JSON format. Requests should al
 }
 ```
 
+## Reloading gRPC descriptor files
+
+If you plan to update your gRPC descriptor files at runtime, you can inform WireMock to reload all file descriptors via a POST to the admin API endpoint `/__admin/ext/grpc/reset`.
+
 ## More Demos
 
-For more see the [standalone demo project](https://github.com/wiremock/wiremock-grpc-demos/tree/main/standalone).
+For more see the [standalone demo project](https://github.com/wiremock/wiremock-grpc-demos/tree/main/standalone).

_docs/quickstart/java-junit.md

@@ -42,7 +42,7 @@ like [Apache HttpClient](https://hc.apache.org/httpcomponents-client-5.2.x/#).
 <dependency>
     <groupId>org.assertj</groupId>
     <artifactId>assertj-core</artifactId>
-    <version>3.24.2</version>
+    <version>3.26.3</version>
     <scope>test</scope>
 </dependency>
 ```

_docs/request-matching.md

@@ -987,6 +987,46 @@ The full list of comparison types used by default is as follows:
 `CHILD_LOOKUP`
 `ATTR_NAME_LOOKUP`
 
+#### Same child nodes with different content
+By default, WireMock takes into account an order of identical child nodes. Meaning if actual request has different order of same node on same level than stub it won't be matched.
+As of WireMock version `3.7.0`, this can be changed by passing additional argument to the `equalToXml` method
+
+Java:
+
+```java
+    .withRequestBody(equalToXml("<body>" +
+            "   <entry>1</entry>" +
+            "   <entry>2</entry>" +
+            "</body>",false,true))
+```
+```json
+{
+  "request": {
+    ...
+    "bodyPatterns" : [ {
+      "equalToXml" : "<body><entry>1</entry><entry>2</entry></body>",
+      "ignoreOrderOfSameNode": true
+    } ]
+    ...
+  },
+  ...
+}
+```
+This will make sure that stub above matches both of following requests:
+```xml
+<body>
+    <entry>2</entry>
+    <entry>1</entry>
+</body>
+```
+and 
+```xml
+<body>
+    <entry>1</entry>
+    <entry>2</entry>
+</body>
+```
+If third argument is passed as `false` then first xml will not match the stub
 ### XPath
 
 Deems a match if the attribute value is valid XML and matches the XPath expression supplied. An XML document will be considered to match if any elements are returned by the XPath evaluation. WireMock delegates to Java's in-built XPath engine (via XMLUnit), therefore up to (at least) Java 8 it supports XPath version 1.0.

_docs/response-templating.md

@@ -181,6 +181,8 @@ wm.stubFor(get(urlPathMatching("/static/.*"))
 
 The model of the request is supplied to the header and body templates. The following request attributes are available:
 
+`request.id` - The unique ID of each request (introduced in WireMock version `3.7.0`)
+
 `request.url` - URL path and query
 
 `request.path` - URL path. This can be referenced in full or it can be treated as an array of path segments (like below) e.g. `request.path.3`.
@@ -214,6 +216,18 @@ When the path template URL match type has been used you can additionally referen
 
 `request.body` - Request body text (avoid for non-text bodies)
 
+`request.bodyAsBase64` - As of WireMock `3.8.0`, the Base64 representation of the request body.
+
+`request.multipart` - As of WireMock `3.8.0`, if the request is a multipart request (boolean).
+
+`request.parts` - As of WireMock `3.8.0`, the individual parts of a multipart request are exposed via the template
+model. Each part can be referenced by its name and exposes a number of properties in the template model.  For example, 
+a multipart request with a name of `text` has the following properties available:
+* `request.parts.text.binary` - if the part is a binary type.
+* `request.parts.text.headers.<key>` - first value of a part header - `request.parts.text.headers.content-type`
+* `request.parts.text.body` - part body as text.
+* `request.parts.text.bodyAsBase64` - part body as base64.
+
 ### Values that can be one or many
 
 A number of HTTP elements (query parameters, form fields, headers) can be single or multiple valued. The template request model and built-in helpers attempt to make
@@ -343,9 +357,10 @@ Variable assignment and number helpers are available:
 
 ## Val helper
 
-The `val` helper can be used to access values or provide a default if the value is not present. It can also be used to
-assign a value to a variable much like the `assign` helper.  The main difference between `val` and `assign` is that `val`
-will maintain the type of the date being assigned whereas `assign` will always assign a string.
+Released in WireMock version `3.6.0`, the `val` helper can be used to access values or provide a default if the value 
+is not present. It can also be used to assign a value to a variable much like the `assign` helper.  The main difference 
+between `val` and `assign` is that `val` will maintain the type of the date being assigned whereas `assign` will always 
+assign a string.
 
 {% raw %}
 
@@ -670,9 +685,116 @@ Likewise decimals can be produced with or without bounds:
 {{randomDecimal upper=12.5}}
 {{randomDecimal lower=-24.01}}
 ```
+{% endraw %}
+
+## Formatting numbers
+
+The `numberFormat` helper allows you to specify how numbers are printed. It supports
+a number of predefined formats, custom format strings and various other options
+including rounding mode, decimal places and locale.
+
+### Predefined formats
+`numberFormat` supports the following predefined formats:
+
+* `integer`
+* `currency`
+* `percent`
+
+Predefined formats can be affected by locale, so it's usually a good idea to explicitly
+specify this.
+
+For example, to format a decimal number as currency, specifically British pounds:
+
+{% raw %}
+```handlebars
+{{{numberFormat 123.4567 'currency' 'en_GB'}}}
+```
+{% endraw %}
+
+Output: `£123.46`.
+
+Alternatively, if we wanted to output the number as a percentage:
+
+{% raw %}
+```handlebars
+{{{numberFormat 123.4567 'percent' 'en_GB'}}}
+```
+{% endraw %}
+
+Output: `12,346%`.
+
+### Custom format string
+For maximum control over the number format you can specify a format string:
+
+{% raw %}
+```handlebars
+{{{numberFormat 123.4567 '###.000000' 'en_GB'}}}
+```
+{% endraw %}
+
+Output: `123.456700`.
+
+See the [Java DecimalFormat documentation](https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html)
+for details on how to use format strings.
+
+
+### Configuring number of digits
+Separate from the format parameter, the number of digits before and after the
+decimal place can be bounded using one or more of four parameters:
+`maximumFractionDigits`, `minimumFractionDigits`, `maximumIntegerDigits`, `minimumIntegerDigits`.
+
+{% raw %}
+```handlebars
+{{{numberFormat 1234.567 maximumIntegerDigits=3 minimumFractionDigits=6}}}
+```
+{% endraw %}
+
+Output: `234.567000`.
+
+
+### Disabling grouping
+By default `numberFormat` will insert commas, periods etc. per the locale between
+groups of digits e.g. `1,234.5`.
+
+This behaviour can be disabled with `groupingUsed`.
+
+{% raw %}
+```handlebars
+{{{numberFormat 12345.678 groupingUsed=false}}}
+```
+{% endraw %}
+
+Output: `12345.678`.
 
+
+### Rounding mode
+The `roundingMode` parameter affects how numbers will be rounded up or down when
+it's necessary to do so.
+
+For instance, to always round down:
+
+{% raw %}
+```handlebars
+{{{numberFormat 1.239 roundingMode='down' maximumFractionDigits=2}}}
+```
 {% endraw %}
 
+Output: `1.23`.
+
+Available rounding modes are:
+
+* `up`
+* `down`
+* `half_up`
+* `half_down`
+* `half_even`
+* `ceiling`
+* `floor`.
+
+See the [Java RoundingMode documentation](https://docs.oracle.com/javase/8/docs/api/java/math/RoundingMode.html)
+for the exact meaning of each of these.
+
+
 ## Fake data helpers
 
 This helper produces random fake data of the desired types available in the [Data Faker library](https://github.com/datafaker-net/datafaker). Due to the size of this library, this helper has been provided via [`RandomExtension`](https://github.com/wiremock/wiremock-faker-extension).    
@@ -744,9 +866,9 @@ Providing no parameters will result in an empty array.
 {% endraw %}
 
 ## Array add & remove helpers
-The `arrayAdd` and `arrayRemove` helpers can be used to add or remove elements from an array based on a position value
-or the `start` or `end` keywords. If no position is specified, the element will be added or removed from the end of the 
-array.
+As of WireMock version `3.6.0`, the `arrayAdd` and `arrayRemove` helpers can be used to add or remove elements from an 
+array based on a position value or the `start` or `end` keywords. If no position is specified, the element will be 
+added or removed from the end of the array.
 
 {% raw %}
 
@@ -766,7 +888,8 @@ array.
 
 ## arrayJoin helper
 
-The `arrayJoin` helper will concatenate the values passed to it with the separator specified:
+Released in WireMock version `3.6.0`, the `arrayJoin` helper will concatenate the values passed to it with the 
+separator specified:
 
 {% raw %}