add scenario

1 files changed, 60 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index 05450e8..97a8fa5 100644
--- a/subplot.md
+++ b/subplot.md
@@ -1221,6 +1221,66 @@ given I am Tomjon
 ~~~
 
 
+## Set environment variables in generated test programs
+
+The generated test programs run each scenario with a fixed, almost
+empty set of environment variables. This is so that tests are more
+repeatable and less dependent on any values accidentally set by the
+developers.
+
+However, sometimes it's helpful for the user to be able to set
+environment variables for the scenarios. For example, if the scenarios
+test locally built binaries that may be installed anywhere, the
+installation directory should be added to the PATH variable so that
+scenarios can invoke the scripts easily.
+
+The scenario in this section verifies that the Python test program
+generated by `sp-codegen` accepts the option `--env NAME=VALUE`.
+
+There is currently no equivalent functionality for the generated Bash
+test program. Patches for that are welcome.
+
+~~~scenario
+given file env.md
+and file env.yaml
+and file env.py
+and an installed subplot
+when I run sp-codegen env.md -o test.py
+when I try to run python3 test.py
+then command fails
+when I try to run python3 test.py --env FOO=foo
+then command fails
+when I try to run python3 test.py --env FOO=bar
+then command is successful
+~~~
+
+~~~~~~{#env.md .file .markdown .numberLines}
+---
+title: Environment variables
+bindings: env.yaml
+functions: env.py
+...
+
+# Test
+~~~scenario
+then environment variable FOO is set to "bar"
+~~~
+~~~~~~
+
+~~~{#env.yaml .file .yaml .numberLines}
+- then: environment variable {name} is set to "{value:text}"
+  function: is_set_to
+~~~
+
+~~~{#env.py .file .python .numberLines}
+import os, sys
+def is_set_to(ctx, name=None, value=None):
+  sys.stderr.write(f"{name}={os.environ.get(name)!r}\n")
+  assert os.environ.get(name) == value
+~~~
+
+
+
 ## Avoid changing typesetting output file needlessly
 
 ### Avoid typesetting if output is newer than source files