docs: describes how to trigger SOAP fault response.

docs/configuration.md

@@ -85,7 +85,7 @@ response:
     X-Custom-Header: foo
 ```
 
-A few things to call out:
+Some highlights:
 
 - This endpoint will only be accessible via the `POST` HTTP method
 - We've indicated that status code 201 should be returned

docs/openapi_plugin.md

@@ -94,7 +94,7 @@ definitions:
         type: "string"
 ```
 
-A few things to call out:
+Some highlights:
 
 * We’ve defined the endpoint `/pets` as expecting an HTTP GET request
 * We’ve said it will produce JSON responses

docs/rest_plugin.md

@@ -81,7 +81,7 @@ We can configure different responses at multiple paths as follows:
         response:
           file: dogs.json
 
-A few things to call out:
+Some highlights:
 
 * We’ve defined the endpoint `/cats` to return the contents of our sample JSON file; in other words an array of cats.
 * We’ve also said that, because the response file is a JSON array, we want to allow querying of individual items by their ID, under the `/cats/{id}` endpoint.

docs/soap_plugin.md

@@ -23,9 +23,9 @@ This plugin will match the operation using a combination of:
 * matching SOAPAction (if required)
 * matching XML schema type of the root element within the request SOAP envelope body 
 
-Imposter will return the first response found that matches the above criteria. You can, of course, override the behaviour by setting the response body (see below).
+Imposter will return the first response found that matches the above criteria. You can, of course, override the behaviour by setting the response body (see below) or status code.
 
-Typically, you will use the configuration file `<something>-config.yaml` to customise the response, however, you can use the in-built script engine to gain further control of the response data, headers etc. (see below). 
+Typically, you will use the configuration file `<something>-config.yaml` to customise the response, however, you can use the in-built script engine to gain further control of the response data, headers etc.
 
 ## Example
 
@@ -88,7 +88,7 @@ In this example, we are using a WSDL file (`petstore.wsdl`) containing the follo
 </description>
 ```
 
-A few things to call out:
+Some highlights:
 
 * We’ve defined the service `PetService` at the SOAP endpoint `/pets/`
 * We’ve said it has one operation: `getPetById`
@@ -223,6 +223,26 @@ $ curl -v -X POST http://localhost:8080/pets/ -H 'SOAPAction: invalid-pet-action
 HTTP/1.1 400 Bad Request
 ```
 
+## Returning fault messages
+
+If your WSDL document defines a `fault`, then Imposter can generate a sample response from its type. To return a fault, set the response status code to 500.
+
+### Example configuration to respond with a fault
+
+```yaml
+plugin: soap
+wsdlFile: service.wsdl
+
+resources:
+  - binding: SoapBinding
+    operation: getPetById
+    response:
+      statusCode: 500
+```
+
+> **Tip**
+> Use conditional matching with resources, to only return a fault in particular circumstances. 
+
 ## Scripted responses (advanced)
 
 For more advanced scenarios, you can also control Imposter's responses using JavaScript or Groovy scripts.
@@ -258,29 +278,37 @@ response:
 
 Now, `example.groovy` can control the responses, such as:
 
-1. the content of a file to return
-
-```groovy
-respond().withFile('some-file.xml')
-```
-
-2. a literal string to return
-
-```groovy
-respond().withContent('''<?xml version="1.0" encoding="UTF-8"?>
-<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
-    <env:Header/>
-    <env:Body>
-        <getPetByIdResponse xmlns="urn:com:example:petstore">
-            <id>3</id>
-            <name>Custom pet name</name>
-        </getPetByIdResponse>
-    </env:Body>
-</env:Envelope>
-''')
-```
-
-#### Examples
+1. **the content of a file to return**
+
+   ```groovy
+   respond().withFile('some-file.xml')
+   ```
+
+2. **a literal string to return**
+
+   ```groovy
+   respond().withContent('''<?xml version="1.0" encoding="UTF-8"?>
+   <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
+       <env:Header/>
+       <env:Body>
+           <getPetByIdResponse xmlns="urn:com:example:petstore">
+               <id>3</id>
+               <name>Custom pet name</name>
+           </getPetByIdResponse>
+       </env:Body>
+   </env:Envelope>
+   ''')
+   ```
+
+3. **a specific HTTP status code**
+
+   Setting the status code to 500 will trigger a fault message to be returned if one is defined within the WSDL document.
+
+   ```groovy
+   respond().withStatusCode(500)
+   ```
+
+#### Scripting examples
 
 - [conditional-example](https://github.com/outofcoffee/imposter/blob/main/examples/soap/conditional-example)
 - [scripted-example](https://github.com/outofcoffee/imposter/blob/main/examples/soap/scripted-example)