scenarios.md

+(This documentation is adapted from the original documentation of WireMock.)
+
+**Most web services tend to have some state, which changes as you and
+others interact with it. So it's pretty useful to be able to simulate
+this when you've swapped a real service for a test double.**
+
+## Scenarios
+
+Mimus Serve supports state via the notion of scenarios. A scenario is
+essentially a state machine whose states can be arbitrarily assigned. It
+starting state is always `Scenario.STARTED`. Stub mappings can be
+configured to match on scenario state, such that stub A can be returned
+initially, then stub B once the next scenario state has been triggered.
+
+For example, suppose we're writing a to-do list application consisting
+of a rich client of some kind talking to a REST service. We want to test
+that our UI can read the to-do list, add an item and refresh itself,
+showing the updated list.
+
+The setup could be set up like this:
+
+```json
+{
+    "mappings": [
+        {
+            "scenarioName": "To do list",
+            "requiredScenarioState": "Started",
+            "request": {
+                "method": "GET",
+                "url": "/todo/items"
+            },
+            "response": {
+                "status": 200,
+                "body": "<items><item>Buy milk</item></items>"
+            }
+        },
+        {
+            "scenarioName": "To do list",
+            "requiredScenarioState": "Started",
+            "newScenarioState": "Cancel newspaper item added",
+            "request": {
+                "method": "POST",
+                "url": "/todo/items",
+                "bodyPatterns": [
+                    { "contains": "Cancel newspaper subscription" }
+                ]
+            },
+            "response": {
+                "status": 201
+            }
+        },
+        {
+            "scenarioName": "To do list",
+            "requiredScenarioState": "Cancel newspaper item added",
+            "request": {
+                "method": "GET",
+                "url": "/todo/items"
+            },
+            "response": {
+                "status": 200,
+                "body": "<items><item>Buy milk</item><item>Cancel newspaper subscription</item></items>"
+            }
+        }
+    ]
+}
+```
+
+## Resetting scenarios
+
+The state of all configured scenarios can be reset back to
+`Scenario.START` either by calling the HTTP API, send an empty `POST` request to `/__admin/scenarios/reset`.
+
+
+## Resetting a single scenario (TODO)
+
+You can reset the state of an individual scenario.
+
+This done via the HTTP API, send an empty `PUT` to `/__admin/scenarios/my_scenario/state`.
+
+
+## Setting the state of an individual scenario (TODO)
+
+You can also set the state of an individual scenario to a specific value.
+
+Java:
+
+```java
+Mimus Serve.setScenarioState("my_scenario", "state_2");
+```
+
+HTTP:
+
+```json
+PUT /__admin/scenarios/my_scenario/state
+{
+    "state": "state_2"
+}
+```
\ No newline at end of file