Switch to "scenario testing"

1 files changed, 30 insertions, 30 deletions

diff --git a/README.yarn b/README.yarn
index a117866..ae857e0 100644
--- a/README.yarn
+++ b/README.yarn
@@ -1,19 +1,19 @@
-README for story testing
-========================
+README for scenario testing
+===========================
 
 Introduction
 ------------
 
-`yarn` is a story testing tool: you write a story describing how a
+`yarn` is a scenario testing tool: you write a scenario describing how a
 user uses your software and what should happen, and express, using
-very lightweight syntax, the story in such a way that it can be tested
-automatically. The story has a simple, but strict structure:
+very lightweight syntax, the scenario in such a way that it can be tested
+automatically. The scenario has a simple, but strict structure:
 
     GIVEN some setup for the test
     WHEN thing that is to be tested happens
     THEN the post-conditions must be true
 
-As an example, consider a very short test story for verifying that
+As an example, consider a very short test scenario for verifying that
 a backup program works, at least for one simple case.
 
     GIVEN some live data in a directory
@@ -24,10 +24,10 @@ a backup program works, at least for one simple case.
 (Note the addition of AND: you can have multiple GIVEN, WHEN, and
 THEN statements. The AND keyword makes the text be more readable.)
 
-Stories are meant to be written in somewhat human readable language.
+Scenarios are meant to be written in somewhat human readable language.
 However, they are not free form text. In addition to the GIVEN/WHEN/THEN
 structure, the text for each of the steps needs a computer-executable
-implementation. This is done by using IMPLEMENTS. The backup story
+implementation. This is done by using IMPLEMENTS. The backup scenario
 from above might be implemented as follows:
 
     IMPLEMENTS GIVEN some live data in a directory
@@ -74,40 +74,40 @@ A test document is written in [Markdown][markdown], with block
 quoted code blocks being interpreted specially. Each block
 must follow the syntax defined here.
 
-* Every step in a story is one line, and starts with a keyword.
+* Every step in a scenario is one line, and starts with a keyword.
 * Each implementation (IMPLEMENTS) starts as a new block, and
   continues until there is a block that starts with another
   keyword.
 
 The following keywords are defined.
 
-* **STORY** starts a new story. The rest of the line is the name of
-  the story. The name is used for documentation and reporting
-  purposes only and has no semantic meaning. STORY MUST be the
-  first keyword in a story, with the exception of IMPLEMENTS.
+* **SCENARIO** starts a new scenario. The rest of the line is the name of
+  the scenario. The name is used for documentation and reporting
+  purposes only and has no semantic meaning. SCENARIO MUST be the
+  first keyword in a scenario, with the exception of IMPLEMENTS.
   The set of documents passed in a test run may define any number of
-  stories between them, but there must be at least one or it is a
+  scenarios between them, but there must be at least one or it is a
   test failure. The IMPLEMENTS sections are shared between the
-  documents and stories.
+  documents and scenarios.
 
-* **ASSUMING** defines a condition for the story. The rest of the
+* **ASSUMING** defines a condition for the scenario. The rest of the
   line is "matched text", which gets implemented by an
   IMPLEMENTS section. If the code executed by the implementation
-  fails, the story is skipped.
+  fails, the scenario is skipped.
 
 * **GIVEN** prepares the world for the test to run. If
-  the implementation fails, the story fails.
+  the implementation fails, the scenario fails.
 
 * **WHEN** makes the change to the world that is to be tested.
-  If the code fails, the story fails.
+  If the code fails, the scenario fails.
 
 * **THEN** verifies that the changes made by the GIVEN steps
-  did the right thing. If the code fails, the story fails.
+  did the right thing. If the code fails, the scenario fails.
 
-* **FINALLY** specifies how to clean up after a story. If the
-  code fails, the story fails. All FINALLY blocks get run either when
-  encountered in the story flow, or at the end of the story, regardless
-  of whether the story is failing or not.
+* **FINALLY** specifies how to clean up after a scenario. If the
+  code fails, the scenario fails. All FINALLY blocks get run either when
+  encountered in the scenario flow, or at the end of the scenario, regardless
+  of whether the scenario is failing or not.
 
 * **AND** acts as ASSUMING, GIVEN, WHEN, THEN, or FINALLY: whichever
   was used last. It must not be used unless the previous step was
@@ -119,7 +119,7 @@ The following keywords are defined.
   an empty line (no characters, not even whitespace) between two
   block quoted code blocks starts a new one or not, so we resolve the
   ambiguity by specifiying that a code block directly following a code
-  block is a continuation unless it starts with one of the story
+  block is a continuation unless it starts with one of the scenario
   testing keywords.
 
   The shell commands get parenthesised parts of the match of the
@@ -144,7 +144,7 @@ The following keywords are defined.
 
 Semantics:
 
-* The name of each story (given with STORY) must be unique.
+* The name of each scenario (given with SCENARIO) must be unique.
 * All names will be normalised before use (whitespace collapse, leading
   and trailing whitespace
 * Every ASSUMING, GIVEN, WHEN, THEN, FINALLY must be matched by
@@ -152,7 +152,7 @@ Semantics:
   any code.
 * Every IMPLEMENTS may match any number of ASSUMING, GIVEN, WHEN,
   THEN, or FINALLY. The test runner can warn if an IMPLEMENTS is unused.
-* If ASSUMING fails, that story is skipped, and any FINALLY steps
+* If ASSUMING fails, that scenario is skipped, and any FINALLY steps
   are not run.
 
 See also
@@ -169,14 +169,14 @@ TODO
 ----
 
 * Add DEFINING, PRODUCING, if they turn out to be useful.
-* Need something like ASSUMING, except fail the story if the
+* Need something like ASSUMING, except fail the scenario if the
   pre-condition is not true. Useful for testing that you can ssh
   to localhost when flinging, for example.
   **DJAS**: We think this might be 'REQUIRING' and it still does
   not run the FINALLY group.
 * Consider the ordering some more.  IMPLEMENTS can come anywhere
-  but otherwise stories are defined as:
-    * STORY
+  but otherwise scenarios are defined as:
+    * SCENARIO
     * 0+: ASSUMING
     * 1+:
         * 1+: GIVEN