summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Silverstone <dsilvers+gitlab@digital-scurf.org>2022-04-10 08:51:18 +0000
committerDaniel Silverstone <dsilvers+gitlab@digital-scurf.org>2022-04-10 08:51:18 +0000
commit94d337a1592431b64e41e9938fdf020163bb9b67 (patch)
tree948e590012b539aba191424244d0571bbca8d99a
parent962f63413168862fab50da1fe3b6430028277c16 (diff)
parent307a37c2269058658a581838c31ab48d762d762c (diff)
downloadsubplot-94d337a1592431b64e41e9938fdf020163bb9b67.tar.gz
Merge branch 'effective' into 'main'
Some suggested copy-edits See merge request subplot/subplot!268
-rw-r--r--subplot.md15
1 files changed, 7 insertions, 8 deletions
diff --git a/subplot.md b/subplot.md
index f5dcbea..5098d74 100644
--- a/subplot.md
+++ b/subplot.md
@@ -463,24 +463,23 @@ action, or examination, but it's easier for humans reading the
scenario, or writing the corresponding code, if each step only does
the kind of work that is implied by the kind of step it's bound to.
-### Using Subplot's language effectively.
+### Using Subplot's language effectively
Your subplot scenarios will be best understood when they use the subplot
-language in a fashion consistent with all subplot scenarios in your project(s).
+language in a consistent fashion, within and even across *different* projects.
As with programming languages, it's possible to place your own style on your
-subplots, indeed there is no inherent internal implementation difference between
+subplots. Indeed, there is no inherent internal implementation difference between
how `given`, `when` and `then` steps are processed (other than that `given`
steps often also have cleanup functions associated with them).
-There is, however, value in having consistency between
-the subplot scenarios in *different* projects. Here is how we recommend you use
-the Subplot language, and indeed how we use it in Subplot and related projects…
+Nonetheless we have some recommendations about using the Subplot language,
+which reflect how we use it in Subplot and related projects.
When you are formulating your scenarios, it is common to try and use phraseology
along the lines of _if this happens then that is the case_ but this is not
language which works well with subplot. Scenarios describe what will happen in
the success case. As such we don't construct scenarios which say _if foo happens
-then the case fails_ instead we say _when I do the thing then foo does not happen_.
+then the case fails_, instead we say _when I do the thing then foo does not happen_.
This is a subtle but critical shift in the construction of your test cases which
will mean that they map more effectively to scenarios.
@@ -498,7 +497,7 @@ to inform the reader that some precondition is met. These statements are often
best along the lines of `given a setup which works` or `given a development enviroment`
or somesuch.
-The `when` statements should be best used to denote **active** steps. These are
+The `when` statements are best used to denote **active** steps. These are
the steps which your putative actors or personae use to achieve their goals.
These often work best in the form `when I do the thing` or
`when the user does the thing`.