@suffolklitlab/alkiln 5.13.2 → 5.13.3-feat-random

package/docs/4_environments.md

@@ -0,0 +1,243 @@
+# Designing for the complexity of the 4 environments in which ALKiln can run
+
+## Context and scope
+
+Authors have different testing needs. For example, sometimes authors need to run individual tests more quickly as they are developing code and sometimes authors need to run a whole test suite on a weekly schedule to make sure their online forms keep working over time. To run individual tests more quickly, an author can run the tests directly on their development server. To run scheduled tests, an author can run tests on GitHub. Those are very different environments.
+
+Internal ALKiln developers need to run tests in more environments as well.
+
+To help with all these, ALKiln can work in 4 different environments. We have to design ALKiln's architecture with that in mind.
+
+## Goals
+
+- Help authors to test in the environments that best help them develop.
+- Help internal ALKiln developers develop the framework comfortably enough.
+- Keep openings where authors can interact directly with the systems we're using so they can customize behavior that we can't account for.
+
+## Non/anti-goals
+
+- Be an intermediary between the author and all the possible customization they need for their tests.
+
+## The actual design
+
+This design involves:
+
+- The 4 environments, the ALKiln flow for each, and the advantages each environment has.
+- The 4 separate command line commands.
+- Passing information between different runtime processes.
+- The 2 composite action scripts.
+
+<!-- Maybe the flows below should each be shown in the relevant individual sections for each environment. -->
+
+The flow for each environment is different.
+
+The temporary GitHub docasseble server action:
+
+1. Author workflow file > `./action_for_github/action.yml` > author workflow file > `./action.yml` > `alkiln-server-install` > `alkiln-run` > author workflow file
+
+<!-- Not sure how to represent this relationship. Trying to show what processes have access to what parts of the process. I'm not sure showing how `./action.yml` threads in and out is actually useful. I'm trying to show that the author's workflow has access in between `./action_for_github/action.yml` and `./action.yml` where they can do things so when someone reads about it later, they can understand.
+
+Author workflow
+  `./action_for_github/action.yml`
+Author workflow
+  `./action.yml`
+    `alkiln-server-install`
+  `./action.yml`
+    `alkiln-run`
+  `./action.yml`
+Author workflow
+
+Author workflow
+  `./action_for_github/action.yml`
+Author workflow
+  `./action.yml`
+    `alkiln-server-install`
+    `alkiln-run`
+Author workflow
+-->
+
+A GitHub action that installs tests in an author's account on their own docasseble server:
+
+1. Author workflow file > `./action.yml` > `alkiln-setup` > `alkiln-run` > `alkiln-takedown` > author workflow file
+
+<!-- Not sure how to represent this relationship
+Author workflow
+  `./action.yml`
+    `alkiln-setup`
+    `alkiln-run`
+    `alkiln-takedown`
+Author workflow
+-->
+
+ALKilnInThePlayground:
+
+1. `alkiln-run`
+
+A local developer might customize these steps in various ways in their console. If they are using the default workflow, this is what it looks like functionally when they develop a feature:
+
+1. Command line > `alkiln-setup` once
+2. Command line > `alkiln-run` many times
+3. Command line > `alkiln-takedown` once
+
+### 4 environments we need to account for
+
+#### 2 GitHub options
+
+Authors or admins use GitHub workflows to run our GitHub composite actions if they:
+
+- Want to run tests every time an author commits code.
+- Want to run tests based on other triggers, like a schedule or manually triggering the workflow.
+- They want to require that all tests pass before they merge a branch.
+- Use other CI pipelines.
+
+**Run on a temporary GitHub server**
+
+1. Author: commits code to GitHub.
+2. ALKiln: Creates a docassemble server, installs the docassemble package globally on the server, run the test suite once, and destroys the server.
+
+Authors use this if they:
+
+- Want less flake.
+- Want to test with latest version of da.
+- Don't mind extra setup time each test suite takes.
+- Know how to use bash to work with a Docker container (if needed).
+
+**Run from GitHub, but on their own server**
+
+1. Author: commits code to GitHub.
+2. ALKiln: Installs the docassemble package in the author's account on their own docassemble server, runs the test suite once, and deletes the docassemble package.
+
+Authors use this if they:
+
+- Want to Use data from SS3 and other remote databases.
+- Want to test with their own version of docassemble.
+- Don't want to have to be so careful with all their dependencies (like having to put all dependencies on pypi) because they have installed them on their server themselves.
+
+#### Running directly on docassemble server
+
+A docassemble server doesn't just serve forms to end users. It also lets authors develop the code of their forms[^1]. That is why it is useful to install and use ALKiln on an author's docassemble server. They do this by using the AlKilnInThePlayground package.
+
+An author installs AlKilnInThePlayground package on their server. They run the online form that package has. That lets them install ALKiln on their server. The package can tell who the user is and offers the user a choice of which of their Playground development Projects to test, and they run the tests right their on their server.
+
+1. Author: Installs the package they want to test into their account on the docassemble 1. server, edits their package, triggers the test run.
+2. ALKiln: Runs tests.
+3. Author: Edits, tests, and repeats. Finally, the author deletes the package in their account on the docassemble server.
+
+Authors use this if they:
+
+- Want to run tests faster than the GitHub test flow allows (a faster iteration cycle).
+- Want to avoid server reloads (in the case of a package with python modules).
+- Feel uncomfortable with failures on GitHub - they can get tests passing before pushing to GitHub.
+- Have the right version of nodejs on their docassemble server, which is based on what Docker image they have installed.
+
+#### Command line
+
+<!-- Do we mention that internal devs don't always use the bins? They use the package.json scripts? Seems like an unnecessary complication. -->
+
+1. Internal developer with ALKiln's help or with their own command line arguments: Installs the package on a specified docassemble server (local or remote).
+2. Internal developer with ALKiln's help: runs the tests as many times as they need while they develop the framework code.
+3. Internal developer with ALKiln's help or with their own command line arguments: deletes the package from the docassemble server.
+
+Internal developers do this if they:
+
+- Have to edit ALKiln's own code.
+- Want to run tests faster than the GitHub test flow allows (a faster iteration cycle).
+- Want to run tests on a local server.
+- See ALKiln's behavior live and with more detail.
+
+### 4 node command line commands
+
+`package.json` has 4 command-line commands. They are broken up by the different needs of the 4 different environments - installing packages on a server, saving temporary server information, running the core framework code[^2], deleting packages on a server. As this document describes. Some environments need only one of the commands.
+
+Read the API section for more details.
+
+Looking only at the command line commands does miss a crucial 1st part of the temporary GitHub docassemble server workflow - creating the docassemble server. That is done completely through `./action_for_github/action.yml`. See the section on GitHub composite actions for details.
+
+### Passing information between different processes.
+
+ALKiln needs to pass information between its different processes to do things like go to the right interview urls and store artifacts (like reports, debug logs, and screenshots) in the right folder.
+
+**`runtime_config.json`**
+
+Since different runtime processes can't pass information between them any other way, we create and modify `runtime_config.json` as each process runs to store information that other processes need. Different environments need to save different information or to save information differently.
+
+For example, `alkiln-setup` needs to create a Project on an author's Playground[^1] to store the code of the online forms and show the forms online. Later, `alkiln-run` needs to know how to find the URL for that specific Project on the server so it can interact with the forms.
+
+The name of the artifacts folder is an example of using `runtime_config.json` and how the complexity of these 4 environments invades ALKiln's core code. See the doc about the artifacts folder name.
+
+<!-- Do we need to list the specific possible values here? These aren't recorded anywhere else, so it's worth considering, but it doesn't feel like the right place. This is incomplete. Holding off until we decide where it goes.
+Everything uses these:
+
+- `artifacts_path`
+
+Temp GitHub docassemble server install uses these:
+
+`da_install_method` - `server` or `playground`
+`da_repo_folder_name` - For example, EvictionDefense in the docassemble-EvictionDefense repo. (see session_vars.js)
+
+Installation in an author's account on their own docassemble server and command line uses these:
+
+Does ALKilnInThePlayground also use the below?
+
+- `da_project_name` - The name of the docassemble project. Helps get the url of the interview. In local internal development, this lets developers keep using the same Project over and over so they don't need to make a new Project, and upload the package code, every time they run a test.
+-->
+
+**Env vars**
+
+ALKiln and test authors use environment variables to pass information to different processes. GitHub workflows and actions store them in their `.yml` files. ALKilnInThePlayground uses the server's configuration file. Local developers use their `.env` file. This is also the way authors and internal developers pass sensitive information to ALKiln. On GitHub, authors store sensitive information in GitHub secrets and then use them as environment variables.
+
+### 2 GitHub composite actions
+
+Authors use our GitHub composite actions in their GitHub workflow files.
+
+- `./action_for_github/action.yml` - Creates the temporary GitHub docassemble server. This action is a crucial part of the flow for temporary GitHub docassemble servers. The fact that it is a separate action gives authors the information and environment they need to change and customize the temporary server themselves in more ways than we can account for. For example, authors might need to make user accounts so they can test what a logged-in user sees. Right now, it cannot help them access remote databases like S3.
+- `./action.yml` - Installs packages on servers in the ways we've described, runs the tests, deletes packages on servers, and gives authors information from the test run, like reports and screenshots.
+
+The rest of the details and API are in the files themselves and in the author-facing documentation about GitHub workflow files at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#workflows.
+
+## APIs
+
+### Command-line API
+
+ALKiln's `package.json` offers 4 command-line commands:
+
+1. `alkiln-server-install` - Stores `runtime_config.json` variables of a temporary GitHub docassemble server for the core framework code[^2].
+2. `alkiln-setup` - Installs the docassemble package on the author's account and stores `runtime_config.json` variables for core framework code.
+3. `alkiln-run` - Wraps and then runs the framework's core code to run the tests.
+4. `alkiln-takedown` - Deletes the package there.
+
+### GitHub composite actions API
+
+The general description of the composite actions is in the composite action section. The details of composite action API is in the author-facing documentation about GitHub workflow files at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#workflows.
+
+## Degree of constraint
+
+This design is working within systems that limit how we can do what we need to do.
+
+- GitHub's action and workflow API and environment. For example, interacting with the temporary GitHub docassemble server vs. interacting with an author's server. Also, the ways in which we need to store and use environment variables.
+- docassemble's API and environment. It wasn't designed to be automated and used this way. For example, it stores package files very differently than the way GitHub arranges them and very differently depending on where we install the package, it has different memory constraints for installing the packages globally vs. in an individual developer's account, etc.
+- cucumberjs's inability to pass non-primitives to core framework code[^2].
+- 3rd party database storage systems, like S3, are hard to integrate into GitHub temporary server tests. We have excluded this feature at the moment. Authors would need to write their own workflow or composite action to access remote databases.
+
+## Alternatives considered
+
+Alternative: Get rid of our support for some of these environments. The temporary GitHub docassemble server environment hasn't been used by a lot of authors. Other than that, the other environments have gotten a lot of use. Even though authors have not yet used the temporary GitHub environment much, they say they want that functionality. The trouble there seems to be complexity with initial set up.
+
+Alternative: Instead of dealing with separate runtimes, have one command and script that wraps all these currently separate processes in one runtime and handles which ones to trigger under what circumstances. If we included `./action_for_github/action.yml` in that command, we would prevent authors from customizing the temporary GitHub docassemble server. That would not be acceptable. To avoid closing off access to server customization, we can only partially integrate these different processes. Also, GitHub actions in general will still have to deal with some core business sometimes. For example, they have to create the artifacts folder name so they can use it later to upload the artifacts. This combined runtime also feels more coupled/entangled and therefore harder to maintain. The need for more command line arguments could make local development more complicated. It is still worth considering.
+
+<!-- Discuss: How to articulate the entanglement with more specifics and examples. -->
+
+Alternative script names: `install_package`, `save_server`, `delete_package`.
+
+## Cross-cutting concerns
+
+_Security, privacy, observability, etc._
+
+- Some tests need to use sensitive information. For example, some tests need a logged-in user and thus ALKiln needs the login info for a user. Different environments store this information differently and there is documentation about how to use sensitive information securely and privately.
+- Core ALKiln code[^2] ends up needing to handle some of the complexity of the 4 environments. Example - the `Log` class `path` takes an optional initial argument to set the artifacts path at the beginning of that runtime process. Other parts of the process have to assume that this path already exists. We have tried to abstract environment complexity out to `run_cucumber.js`, the script that wraps the core code, but there is still logic that the core code handles.
+
+---
+
+[^1]: A docassemble server can have multiple purposes. One is to contain the packages for online forms which end users then use. Those packages are stored in a special place on the server and admins configure the server to give end users a list of those forms. Another purpose of the docassemble server is to be a development environment in which to create the forms. An author/developer of the forms has a developer account on the server. That account can store multiple packages and versions of packages. It also has an IDE that authors can use to work on those packages. They can push those files to GitHub from that IDE. They can also pull those packages from GitHub using that IDE.
+
+[^2]: **Core framework code/core code:** the code that implements the Steps in the `.feature` test files.

package/docs/artifacts_folder_name.md

@@ -0,0 +1,135 @@
+# Creating and using the name of the artifacts folder
+
+## Context and scope
+
+The artifacts folder is where an author can see the results of their tests, like the reports, screenshots, and downloaded documents.
+
+The name of this folder has a specific format to make it as short as possible while it still stays recognizable to users and that it is unique. To help keep it unique it includes a timestamp. (The human readable date/time is not as precise and also longer than the timestamp).
+
+Because of the 4 environments ALKiln can run in (see the docs about the 4 environments), we have different ways to make sure we use one unique artifacts folder name for each test run.
+
+## Goals
+
+- Minimize code duplication
+- In each of the 4 ALKiln environments, be able to track one unique folder name for each test suite run
+
+## The actual design
+
+Our 4 environments can be condensed into 3 environments for the purpose of managing the artifacts folder name:
+
+- GitHub action (`./action.yml`)
+- ALKilnInThePlayground
+- The command line for internal development
+
+The GitHub action creates an artifact folder name and sends it to various scripts that use an instance of the `Log` class to create the folder and save the name. In other environments, an instance of the `Log` class both creates the name, creates the folder, and saves the name. The instance of the `Log` saves the name in `runtime_config.json`. That instance of `Log` and other ALKiln code uses that name to create and store files in that artifacts folder.
+
+The artifact folder name generation code is in 2 places - the GitHub action and ALKiln's core code[^1]. In future, we may reduce that to just one location - the core code.
+
+<!-- More complex description that I don't think we need now, but want to double check:
+The scripts that GitHub action uses need to store its output in the same artifacts folder. The GitHub action therefore builds the name of the artifact folder and passes that around to the different scripts. The scripts pass the folder name to the `Log` class every time, which saves the folder name in `runtime_config.json`. After that, the core code uses that `json` value to put other artifacts in the same folder. We also have folder-naming code in the core code which we use for other purposes. The GitHub action duplicates that folder-naming code, which is unfortunate.
+
+At the same time, tests that run in ALKilnInThePlayground don't have GitHub to manage the artifact folder name. It only uses the `run_cucumber` script, not any of the others...
+
+Adding to that confusion, when people (like internal ALKiln developers) run tests from their command line, they do use the `setup` script once at first, but then run test suites repeatedly...
+
+Neither of the last 2 can depend on the `runtime_config.json` folder name that `setup` creates. If they did, all their multiple test runs would save to that first folder. Since both those environments use `run_cucumber.js` alone repeatedly, and since we don't want to duplicate folder-naming behavior between even more scripts, we decided that those non-GitHub environments should be able to let `Log` create a folder name from scratch every time. The `Log` constructor has to be able to accept a `path` argument with a folder name and also to accept an undefined `path` argument.
+-->
+
+A future goal is to remove the need to store the name in the runtime configuration file to reduce that complexity a bit. These flows are up for discussion.
+
+Below are more detailed descriptions of the different paths the folder name takes in the different environments. Where the folder name is created, gets passed, gets saved, and gets used. Note that there's a little glossing over the details. For example, everything saves to `runtime_config.json`, but only the core code[^1] ever uses the value there.
+
+The diagrams highlight `Log` to help visualize a common point in all the flows.
+
+### GitHub action
+
+1. GitHub action creates a new folder name, passes that name to `setup`, which passes that name to `Log`, which creates the artifacts folder and saves the name in `runtime_config.json`. The setup `Log` uses the name to store logs in the folder. The setup uses its `Log`.
+2. GitHub action uses the same folder name, passes that same name to `run_cucumber`, which passes that same name to `Log`. The `runtime_cucumber` process uses that `Log`. The `run_cucumber` process also triggers the core code, which uses the folder name in `runtime_config.json` to create its own `Log`. The core code also uses that name to store other artifact files in the folder.
+3. GitHub action creates the folder name, passes that same name to `takedown`, which passes that same name when instantiating its `Log`. The takedown `Log` uses the name to store logs in the folder.
+
+```mermaid
+%% "pass name too" has 2 o's at the end because mermaid makes one of them disappear
+
+flowchart LR
+    action[action part 1] --create/pass name too--> setup
+    setup["setup"] --pass name too--> log1["#96;Log#96;"]:::log
+    log1 --store name in/ignore--> runtime1["runtime config file"]
+    log1 --create with name--> folder1[folder]
+
+    action2[action part 2] --pass name too--> run["run"]
+    run --pass name too--> log2["#96;Log#96;"]:::log
+    log2 --store name in/ignore--> runtime2["runtime config file"]
+    log2 --use with name--> folder2[folder]
+    run --> core["core code"]
+    core --pass name too--> log3["#96;Log#96;"]:::log
+    core --use with name--> folder2
+    core --get name from--> runtime2
+    log3 --use with name--> folder2
+    log3 --store name in/ignore--> runtime2
+
+    action3[action part 3] --pass name too--> takedown["takedown"]
+    takedown --pass name too--> log4["#96;Log#96;"]:::log
+    log4 --store name in/ignore--> runtime3["runtime config file"]
+    log4 --create with name--> folder5[folder]
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+### ALKilnInThePlayground
+
+1. ALKilnInThePlayground triggers `run_cucumber` without a folder name which triggers `Log` without a folder name. `Log` creates a new folder name and saves it in `runtime_config.json`. It also creates the artifacts folder. The `run_cucumber` process also triggers the core code, which uses the folder name in `runtime_config.json` to create its own `Log`. The core code also uses that name to store other artifact files in the folder.
+
+```mermaid
+flowchart LR
+    ALKilnInThePlayground --> run["run"]
+    run --> log2["#96;Log#96;"]:::log
+    log2 --store name in/ignore--> runtime2["runtime config file"]
+    log2 --create with name--> folder2[folder]
+    run --> core["core code"]
+    core --> log3["#96;Log#96;"]:::log
+    core --use with name--> folder2
+    core --get name from--> runtime2
+    log3 --use with name--> folder2
+    log3 --store name in/ignore--> runtime2
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+### Command line
+
+1. The developer uses the command line to trigger setup without a folder name which triggers `Log` without a folder name. `Log` creates a name and creates the artifacts folder, then stores files in that folder.
+2. The developer uses the command line to trigger `run_cucumber` without a folder name which triggers `Log` without a folder name. `Log` creates and saves a new folder name in `runtime_config.json`, and creates the artifacts folder.  The `run_cucumber` process also triggers the core code, which uses the folder name in `runtime_config.json` to create its own `Log`. The core code also uses that name to store other artifact files in the folder.
+3. The developer uses the command line to trigger `takedown` without a folder name which triggers `Log` without a folder name. `Log` creates a name and the artifacts folder, then stores files in that folder.
+
+```mermaid
+flowchart LR
+    cmd1[command line] --> setup
+    setup["setup"] --> log1["#96;Log#96;"]:::log
+    log1 --store name in/ignore--> runtime1["runtime config file"]
+    log1 --create with/use with name--> folder1[folder]
+
+    cmd2[command line] --> run["run"]
+    run --> log2["#96;Log#96;"]:::log
+    log2 --store name in/ignore--> runtime2["runtime config file"]
+    log2 --create with name--> folder2[folder]
+    run --> core["core code"]
+    core --> log3["#96;Log#96;"]:::log
+    core --use with name--> folder2
+    core --get name from--> runtime2
+    log3 --use with name--> folder2
+    log3 --store name in/ignore--> runtime2
+
+    cmd3[command line] --> takedown["takedown"]
+    takedown --> log4["#96;Log#96;"]:::log
+    log4 --store name in/ignore--> runtime3["runtime config file"]
+    log4 --create with name--> folder5[folder]
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+## Alternatives considered
+
+- One script for creating the artifacts folder name: Make a script that saves the folder name to the ALKiln `runtime_config.json`. Then all the other code, including instances of `Log`, would always use `runtime_config.json`. We would want `package.json` scripts for the command line environment that would include getting the name of the folder. That potentially complicates the code and process for internal development. We will see how our current design behaves first.
+- Use `Log`'s path name instead of the one in `runtime_config.json`. We thought we would want to save in previous artifacts folders, but it now seems potentially unnecessary. This seems the most viable option for the future, but it is unclear how we can integrate `Log` with all the other files. I wouldn't consider PDFs and screenshots to be logs.
+
+[^1]: **Core framework code/core code:** the code that implements the Steps in the `.feature` test files.

package/docs/constrained_random_tests.md

@@ -0,0 +1,254 @@
+# Constrained random answers tests architecture and decisions
+
+(stub)
+
+Authors are eager to try random answers tests. Development time for testing is hard to find and almost no test suite is exhaustive. They hope to trigger errors they may not have thought to look for.
+
+## Pros and cons of random tests in general
+
+Pros:
+
+- Less work for the test author.
+- Can catch errors authors didn't think to test.
+
+Cons:
+
+- The tests are less deliberate and thought-through.
+- The tests may give authors a false sense of security.
+
+## Why set a maximum number of tests per Scenario?
+
+Because someone might intend to write 10 and add an extra 0 accidentally. These tests can take a long time to run.
+
+## Concerns with the current flow
+
+- The usual process for troubleshooting failing GitHub tests is to re-run the tests. Authors may not realize that they get all new randomized tests with each run _and_ rerun. If the random tests fail during the first run, but pass during the second run, they may mistakenly believe the first failure was a fluke.
+- How easy/hard will it be for ALKilnInThePlayground users to come back to previous runs to get their old generated tests? We will have to see how users find it.
+
+## Fast failure
+
+Based on author feedback, constrained random answers test generation should fail early and fast and avoid being too permissive, though some mistakes can get away with warnings.
+
+## The generating process
+
+The main test generation logic copies the existing generator Scenario strings and transforms them. This doc gives an example of the transformation. This doesn't show the order of what happens in the code. It just shows how ALKiln thinks about the transformation.
+
+A generator file can only have generator Scenarios in it, though it can have any number of generator Scenarios. For each generator file ALKiln gets, ALKiln makes one file with the right generated tests.
+
+### Part 1 - ALKiln gets this generator file
+
+```gherkin
+@go_places_maybe
+Feature: I go places
+
+I go to places like the store, the park, the zoo, etc.
+
+Scenario: I might go to the store
+  Given I start the interview at "store.yml"
+  And I make 2 constrained random tests that get to any of ["kickout", "success"] with:
+    | var | possible_values |
+    | user_goes | True;; False |
+  Then I wait .2 seconds
+
+# Check with Jaime - is the wording correct?
+Scenario: I visit the zoo
+  Given I start the interview at "zoo.yml"
+  And I generate 5 constrained random tests that get to any of ["end", "restart"] with:
+    | var | possible_values |
+    #...etc
+```
+
+By the end of the process there should be 1 file with 7 unique Scenarios.
+
+### Part 2 - ALKiln breaks the file up into sections
+
+Section 1 - the top of the file till the first generator Scenario:
+
+```gherkin
+@go_places_maybe
+Feature: I go places
+
+I go to places like the store, the park, the zoo, etc.
+
+```
+
+Section 2 - the text of generator Scenario 1 until its constraints Step:
+
+```gherkin
+@store   @obvious
+Scenario: I might go to the store
+  Given I start the interview at "store.yml"
+```
+
+Section 3 - the constrained random answers Step of generator Scenario 1:
+
+```gherkin
+  And I generate 2 random tests that get to any of ["kickout", "success"] when I pick from these constraints:
+    | var | possible_values |
+    | user_goes | True;; False |
+```
+
+Section 4 - the text of generator Scenario 1 after the constraints Step until the next generator Scenario:
+```gherkin
+  Then I wait .2 seconds
+
+# Check with Jaime - is the wording correct?
+```
+
+Section 5 - top of generator Scenario 2 until its constraints Step:
+
+```gherkin
+Scenario: I visit the zoo
+  Given I sign in at ""
+  And I start the interview at "zoo.yml"
+```
+
+TODO:
+
+```
+  And I generate 5 constrained random tests that get to any of ["end", "restart"] with:
+    | var | possible_values |
+    #...etc
+```
+
+And so on down the file.
+
+### Part 3 - ALKiln creates multiple Scenarios with Story Table Steps
+
+1st Story Table Step for generator Scenario 1:
+
+```gherkin
+  And I get to any of ["kickout", "success"] with this data:
+    | var | value |
+    | user_goes | False |
+```
+
+2nd Story Table Step for generator Scenario 1:
+
+```gherkin
+  And I get to any of ["kickout", "success"] with this data:
+    | var | value |
+    | user_goes | True |
+```
+
+1st Story Table Step for generator Scenario 2:
+
+```gherkin
+  And I get to any of ["end", "restart"] with this data:
+    | var | value |
+    #...etc
+```
+
+And so on for the other 4 Story Table Steps for generator Scenario 2.
+
+### Part 4 - Build whole Scenarios
+
+Combine the Story Table Steps with the start and end of their corresponding Scenarios.
+
+1st generated Scenario based on generator Scenario 1:
+
+```gherkin
+@store   @obvious
+Scenario: I might go to the store
+  Given I start the interview at "store.yml"
+  And I get to any of ["kickout", "success"] with this data:
+    | var | value |
+    | user_goes | False |
+  Then I wait .2 seconds
+
+# Check with Jaime - is the wording correct?
+```
+
+2nd generated Scenario based on generator Scenario 1:
+
+```gherkin
+@store   @obvious
+Scenario: I might go to the store
+  Given I start the interview at "store.yml"
+  And I get to any of ["kickout", "success"] with this data:
+    | var | value |
+    | user_goes | True |
+  Then I wait .2 seconds
+
+# Check with Jaime - is the wording correct?
+```
+
+1st generated Scenario based on generator Scenario 2:
+
+```gherkin
+Scenario: I visit the zoo
+  Given I start the interview at "zoo.yml"
+  And I get to any of ["end", "restart"] with this data:
+    | var | value |
+    #...etc
+```
+
+### Part 5 - Combine everything and add generation information
+
+We want to make sure authors know these tests were generated by ALKiln and we want to make each Scenario unique. We need unique text that is visible during test output and we need unique tags authors can use to test individual tests.
+
+```gherkin
+@go_places_maybe @alkiln @generated @randomized @constraints
+Feature: I go places with ALKiln randomization
+
+I go to places like the store, the park, the zoo, etc.
+
+@store   @obvious @generator1_scenario1_of_2
+Scenario: I might go to the store (1 of 2)
+  Given I start the interview at "store.yml"
+  And I get to any of ["kickout", "success"] with this data:
+    | var | value |
+    | user_goes | False |
+  Then I wait .2 seconds
+
+# Check with Jaime - is the wording correct?
+@store   @obvious @generator1_scenario2_of_2
+Scenario: I might go to the store (2 of 2)
+  Given I start the interview at "store.yml"
+  And I get to any of ["kickout", "success"] with this data:
+    | var | value |
+    | user_goes | True |
+  Then I wait .2 seconds
+
+# Check with Jaime - is the wording correct?
+@generator2_scenario1_of_5
+Scenario: I visit the zoo (1 of 5)
+  Given I start the interview at "zoo.yml"
+  And I get to any of ["end", "restart"] with this data:
+    | var | value |
+    #...etc
+```
+
+See unit tests for more examples.
+
+
+```
+@go_places_maybe
+Feature: I go places
+
+I go to places like the store, the park, the zoo, etc.
+
+Scenario: I might go to the store
+  Given I will make 10 random constrained tests
+  Given I start the interview at "store.yml"
+  And constrained random tests get to any of ["kickout", "success"] with:
+    | var | possible_values |
+    | user_goes | True;; False |
+  Then I wait .2 seconds
+  And constrained random tests get to any of ["download"] with:
+    | var | possible_values |
+    | user_goes | True;; False |
+  And I see the phrase "Goodbye"
+
+# Check with Jaime - is the wording correct?
+Scenario: I visit the zoo
+  Given I start the interview at "zoo.yml"
+  And I generate 5 constrained random tests that get to any of ["end", "restart"] with:
+    | var | possible_values |
+    #...etc
+```
+
+## Why not just create a new AST?
+
+The AST doesn't have a list of lines. For examples, Scenarios and comments are in separate lists. The AST also stores line numbers, so we'd have to keep updating line numbers for every object, which adds complexity. We've currently decided that the more structured model isn't worth that complexity.
+