From 2c288169fd38032575feb4414c039e9c1e9e8764 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Wed, 19 Jun 2013 20:42:58 +0100 Subject: Switch to "scenario testing" --- README.yarn | 60 ++++++++++++++++++++++++++++++------------------------------ 1 file changed, 30 insertions(+), 30 deletions(-) (limited to 'README.yarn') 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 -- cgit v1.2.1