From 21a8688be3861fc82e224949c1881fcf0ff25142 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Mon, 5 Aug 2019 21:28:46 +0300 Subject: Change: use definition list for keywords --- fable-arch.md | 108 ++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 60 insertions(+), 48 deletions(-) diff --git a/fable-arch.md b/fable-arch.md index 6c63b7f..338f8f4 100644 --- a/fable-arch.md +++ b/fable-arch.md @@ -286,54 +286,66 @@ The language understood by Fable has the following general structure: The keywords have the following meanings: -* ASSUMING—a condition for the scenario. If an ASSUMING step - fails, the scenario is skipped. - - This is used for skipping test scenarios that require specific - software to be installed in the test environment, or access to - external services, but which can't be required for all runs of the - acceptance tests. - -* USING—indicate that the scenario uses a resource such as a - database, that's constrained and can't be used by all scenarios if - they run concurrently. When scenarios declare the resource, Fable can - limit which scenarios run concurrently. - - For example, if several scenarios require uncontested use of the - GPU, of which there is typically only one per machine, they can all - declare "using the graphical processing unit", and Fable will run - them one at a time. - - (This is an intentionally simplistic way of controlling concurrency. - The goal is to be simple and correct rather then achievee maximal - concurrency.) - - The actual management of resources belongs to the generated test - program at runtime, not the Fable compiler. - -* GIVEN—set up the test environment for the action (WHEN). This - might create files, start a background process, or something like - that. This also sets up the reversal of the setup, so that any - background processes are stopped automatically after the scenario - has ended. The setup and cleanup must succeed, or the scenario will - fail. - - The cleanups are executed in the reverse order of the GIVENs, and - they're done always, whether the scenario succeeds or not. - -* WHEN—perform the action that is being tested. This must - succeed. This might, for example, execute a command line program, - and capture its output and exit code. - -* THEN—test the results of the action. This would examine the - output and exit code of the program run in a WHEN step, or examine - current content of the database, or whatever is needed. - -* AND—this keyword exists to make scenarios "read" better in - English. The keyword indicates that this step should use the same - keyword as the previous step, whatever that keyword is. For example, - a step "THEN output is empty" might be followed by "AND the exit - code is 0" rather than "THEN the exit code is 0". +**assuming** + +: A condition for the scenario. If an ASSUMING step fails, the + scenario is skipped. + + This is used for skipping test scenarios that require specific + software to be installed in the test environment, or access to + external services, but which can't be required for all runs of the + acceptance tests. + +**using** + +: Indicate that the scenario uses a resource such as a + database, that's constrained and can't be used by all scenarios if + they run concurrently. When scenarios declare the resource, Fable can + limit which scenarios run concurrently. + + For example, if several scenarios require uncontested use of the + GPU, of which there is typically only one per machine, they can all + declare "using the graphical processing unit", and Fable will run + them one at a time. + + (This is an intentionally simplistic way of controlling concurrency. + The goal is to be simple and correct rather then achievee maximal + concurrency.) + + The actual management of resources belongs to the generated test + program at runtime, not the Fable compiler. + +**given** + +: Set up the test environment for the action (WHEN). This + might create files, start a background process, or something like + that. This also sets up the reversal of the setup, so that any + background processes are stopped automatically after the scenario + has ended. The setup and cleanup must succeed, or the scenario will + fail. + + The cleanups are executed in the reverse order of the GIVENs, and + they're done always, whether the scenario succeeds or not. + +**when** + +: Perform the action that is being tested. This must succeed. This + might, for example, execute a command line program, and capture + its output and exit code. + +**then** + +: Test the results of the action. This would examine the output and + exit code of the program run in a WHEN step, or examine current + content of the database, or whatever is needed. + +**and** + +: This keyword exists to make scenarios "read" better in English. + The keyword indicates that this step should use the same keyword + as the previous step, whatever that keyword is. For example, a + step "THEN output is empty" might be followed by "AND the exit + code is 0" rather than "THEN the exit code is 0". The order of steps is somewhat constrainted: first any ASSUMING steps, then any USING steps, at least one WHEN must come before a THEN. -- cgit v1.2.1