@suffolklitlab/alkiln 5.13.3-feat-random-3 → 5.13.3-feat-random-5

package/.github/workflows/playground.yml

@@ -76,7 +76,7 @@ jobs:
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ env.DOCASSEMBLE_DEVELOPER_API_KEY }}"
           #### Developer note: See https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#optional-inputs
           #### You can probably leave this out
-          MAX_RANDOM_TESTS_PER_SCENARIO: 10
+          ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO: 10
           # Internal: docassemble changes sometimes break @a11y tests. That is
           # a da problem, not ours. We will trigger these tests manually when we
           # want to check up on this.

package/CHANGELOG.md

@@ -47,9 +47,9 @@ Format:
 
 ### Added
 
-- Add the `constrained random answers` Step. You must put the Step in a "constrained random test generator" Scenario which goes in a "constrained random test generator" file - a `.feature` file that starts with "alkiln_random". The file **MUST have ONLY 1 Scenario per generator file** at the moment. The Step is pretty strict. If there are irregularities, it will probably fail, but it will fail quickly. It is flexible about number of tests, though, and will default to 1. Closes [#962](https://github.com/SuffolkLITLab/ALKiln/issues/962).
-- Add `MAX_RANDOM_TESTS_PER_SCENARIO` optional environment variable for the above `constrained random answers` Step. Default value is `40` until we hear otherwise.
-- Regular tests that have incorrect syntax will fail more quickly now - very near the start. So will invalid "constrained random test generator" files. This will be a little slower for GitHub Sandbox tests right now, but still faster than it has been in the past. Closes [#972](https://github.com/SuffolkLITLab/ALKiln/issues/972).
+- Add the `constrained random answers` Step. You must put the Step in a "constrained random test template" Scenario which goes in a "constrained random test template" file - a `.feature` file that starts with "alkiln_random". The file **MUST have ONLY 1 Scenario per template file** at the moment. The Step is pretty strict. If there are irregularities, it will probably fail, but it will fail quickly. It is flexible about number of tests, though, and will default to 1. Closes [#962](https://github.com/SuffolkLITLab/ALKiln/issues/962).
+- Add `ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO` optional environment variable for the above `constrained random answers` Step. Default value is `40` until we hear otherwise.
+- Regular tests that have incorrect syntax will fail more quickly now - very near the start. So will invalid "constrained random test template" files. This will be a little slower for GitHub Sandbox tests right now, but still faster than it has been in the past. Closes [#972](https://github.com/SuffolkLITLab/ALKiln/issues/972).
 
 ### Changed
 
@@ -72,6 +72,17 @@ Format:
 - Fixed: log codes checker obob.
 - Fixed: updated `actions/upload-artifact@v3` to `actions/upload-artifact@v4`
 
+## [5.14.0] - 2025-05-15
+
+### Added
+
+- Adds a linear Step to properly set multi-line values for `textarea`s with a doc string (closes [#1003](https://github.com/SuffolkLITLab/ALKiln/issues/1003)). We are unable to fix the current "set variable" linear Step for this. See [this comment on #655](https://github.com/SuffolkLITLab/ALKiln/issues/655#issuecomment-2876491571).
+
+### Internal
+
+- Changes how Log joins logs.
+- Allows reports to accept log messages as an argument without duplicating metadata text. Debug logs will still save duplicate messages.
+
 ## [5.13.4] - 2025-01-11
 
 ### Changed

package/action.yml

@@ -33,7 +33,7 @@ inputs:
     description: "The version of docassemblecli to install."
     required: false
     default: "0.0.17"
-  MAX_RANDOM_TESTS_PER_SCENARIO:
+  ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO:
     description: "The maximum number of tests ALKiln will generate for every Scenario that can generate tests."
     required: false
     # Default will be internal to avoid duplication of data
@@ -72,7 +72,7 @@ runs:
         MAX_SECONDS_FOR_SETUP: ${{ inputs.MAX_SECONDS_FOR_SETUP }}
         SERVER_RELOAD_TIMEOUT_SECONDS: ${{ inputs.SERVER_RELOAD_TIMEOUT_SECONDS }}
         DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
-        MAX_RANDOM_TESTS_PER_SCENARIO: ${{ inputs.MAX_RANDOM_TESTS_PER_SCENARIO }}
+        ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO: ${{ inputs.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO }}
       shell: bash
       run: |
         log="💡 ALK0023 INFO: Set environment variables and create artifacts folder"
@@ -96,7 +96,7 @@ runs:
         echo "DOCASSEMBLE_DEVELOPER_API_KEY=$DOCASSEMBLE_DEVELOPER_API_KEY" >> $GITHUB_ENV
         echo "ALKILN_VERSION=$ALKILN_VERSION" >> $GITHUB_ENV
         echo "MAX_SECONDS_FOR_SETUP=$MAX_SECONDS_FOR_SETUP" >> $GITHUB_ENV
-        echo "MAX_RANDOM_TESTS_PER_SCENARIO=$MAX_RANDOM_TESTS_PER_SCENARIO" >> $GITHUB_ENV
+        echo "ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO=$ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO" >> $GITHUB_ENV
         echo "SERVER_RELOAD_TIMEOUT_SECONDS=$SERVER_RELOAD_TIMEOUT_SECONDS" >> $GITHUB_ENV
         echo "DOCASSEMBLECLI_VERSION=$DOCASSEMBLECLI_VERSION" >> $GITHUB_ENV
         # Hard-coded internal ALKiln vars
@@ -106,7 +106,7 @@ runs:
       run: |
         log="💡 ALK0024 INFO: Confirm environment variables"
         echo -e "\n$log" >> "${{ env.DEBUG_PATH }}"
-        vars_log='\nALKiln version is ${{ env.ALKILN_VERSION }}\nRepo is "${{ env.REPO_URL }}"\nBranch ref is "${{ env.BRANCH_PATH }}"\nCustom MAX_SECONDS_FOR_SETUP is "${{ env.MAX_SECONDS_FOR_SETUP }}"\nCustom SERVER_RELOAD_TIMEOUT_SECONDS is "${{ env.SERVER_RELOAD_TIMEOUT_SECONDS }}"\nCustom MAX_RANDOM_TESTS_PER_SCENARIO is "${{ env.MAX_RANDOM_TESTS_PER_SCENARIO }}"\n'
+        vars_log='\nALKiln version is ${{ env.ALKILN_VERSION }}\nRepo is "${{ env.REPO_URL }}"\nBranch ref is "${{ env.BRANCH_PATH }}"\nCustom MAX_SECONDS_FOR_SETUP is "${{ env.MAX_SECONDS_FOR_SETUP }}"\nCustom SERVER_RELOAD_TIMEOUT_SECONDS is "${{ env.SERVER_RELOAD_TIMEOUT_SECONDS }}"\nCustom ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO is "${{ env.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO }}"\n'
         echo -e "$vars_log" >> "${{ env.DEBUG_PATH }}" && echo -e "$vars_log"
 
     # Install ALKiln during GitHub workflow

package/docs/4_environments.md

@@ -223,7 +223,7 @@ This design is working within systems that limit how we can do what we need to d
 
 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.
+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 sometimes have to deal with some core business. 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. -->
 
@@ -234,7 +234,7 @@ Alternative script names: `install_package`, `save_server`, `delete_package`.
 _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.
+- 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 before the core code runs. The process in the core code (and elsewhere) have to assume that this path already exists and use config values. 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.
 
 ---
 

package/docs/artifacts_folder_name.md

@@ -21,115 +21,165 @@ Our 4 environments can be condensed into 3 environments for the purpose of manag
 - 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.
+Every environment runs npm commands. Those commands are sometimes run separately and thus trigger separate processes. We must find a way to persist information, like the name of the artifacts folder, across these processes.
 
-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.
+The GitHub action creates an artifact folder name and sends it to a script 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 is what creates the name.
 
-<!-- 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.
+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.
 
-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...
+The artifact folder name generation code is in 2 places - the GitHub action and ALKiln's core code[^1]. In future, we may be able to reduce that to just one location - the core code.
 
-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...
+Below are more detailed descriptions of how each environment interacts with the folder name. Where the folder name is created, gets passed, gets saved, and gets used. These descriptions still gloss over many details.
 
-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.
--->
+The diagrams highlight `Log` to help visualize a common point in all the flows.
 
-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.
+### Shared behavior
+
+For each environment, the start and end of how they manage the artifacts folder name is different. In the middle, though - once the artifacts folder name is already stored in the `runtime_config` file - the flow is the same.
+
+Npm commands that come in the middle have this flow to save logs:
+
+```mermaid
+flowchart LR
+
+    environment --triggers--> commands["middle</br>commands"]
+    commands --trigger--> scripts["package</br>code"]
+    scripts --make--> log2["#96;Log#96;"]:::log
+    log2 --"gets name</br>from"--> runtime2["runtime config</br>file"]
+    log2 --"adds to"--> folder2[folder</br>& files]
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+The core code also needs to use the artifacts folder name in order to save both logs and other artifacts:
+
+```mermaid
+flowchart LR
+
+    core["core</br>code"] --"makes"--> log4["#96;Log#96;"]:::log
+    core --"adds to"--> folder3[folder</br>& files]
+    core --"gets name</br>from"--> runtime3["runtime config</br>file"]
+    log4 --"gets name</br>from"--> runtime3
+    log4 --"adds to"--> folder3
+
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+Those are the shared flows. Each environment, though, has its own way to store the name at the start and each environment has its own way to give the author the final artifacts.
 
-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.
+The GitHub action starts off with an empty `runtime_config` file. The action creates a new folder name and passes that name to the `artifacts` script, which passes that name to a `Log`. The `Log` creates the artifacts folder and saves the name in `runtime_config.json`.
 
 ```mermaid
-%% "pass name too" has 2 o's at the end because mermaid makes one of them disappear
+flowchart LR
+
+    action["GitHub action"] --creates--> name["artifacts</br>folder name"]
+    action --"passes</br>name "--> command["'artifacts'</br>command"]
+    command --"passes</br>name"--> artifacts["artifacts.js"]
+    artifacts --"passes</br>name"--> log1["#96;Log#96;"]:::log
+    log1 --"stores name in</br>& uses"--> runtime1["runtime config</br>file"]
+    log1 --"creates</br>with name"--> folder1["folder</br>& files"]
+    log1 --"adds to"--> folder1
 
+classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
+```
+
+Then other processes use the name from the config to store logs and other files in the artifacts folder (as we've already shown).
+
+Finally, the action uses the name in the action context to download the artifacts folder so the user can have access to it after the action is done.
+
+```mermaid
 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]
+
+    action["GitHub action"] --previously created--> name["artifacts folder name"]
+    action --uses name to get--> folder["folder & files"]
 
 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.
+_Note: This should be implemented by the time anyone actually reads this. Here's hoping._
+
+ALKilnInThePlayground starts off with an empty `runtime_config` file. ALKilnInThePlayground triggers the `artifacts` command, but without a folder name. The code still creates a `Log` (also without a folder name). The `Log` itself creates the name.
 
 ```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
+
+    ALKilnInThePlayground --> command["'artifacts'</br>command"]
+    command --> artifacts["artifacts.js"]
+    artifacts --> log1["#96;Log#96;"]:::log
+    log1 --creates--> name["artifacts</br>folder name"]
+    log1 --stores name--> runtime1["runtime config file"]
+    log1 --"gets name</br>from"--> runtime1["runtime config</br>file"]
+    log1 --creates</br>with name--> folder1["folder</br>& files"]
 
 classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
 ```
 
+Then other processes use the name from the config to store logs and other files in the artifacts folder (as we've already shown).
+
+Finally, ALKilnInThePlayground itself uses the runtime config file to get the name so it can give the artifacts to the user.
+
+```mermaid
+flowchart LR
+
+    ALKilnInThePlayground --"gets name from"--> runtime1["runtime config file"]
+    ALKilnInThePlayground --"uses name to get"--> folder["folder & files"]
+
+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.
+The command line flow is similar to ALKilnInThePlayground, but has to deal with a pre-existing runtime config file[^2]. The command line flow overwrites the artifacts folder name on each run.
+
+An internal developer uses the command line to trigger the `artifacts` command, but without a folder name. The code still creates a `Log` (also without a folder name). The `Log` itself creates a name and overwrites the current name in the runtime config file.
 
 ```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]
+
+    dev --> command["'artifacts'</br>command"]
+    command --> artifacts["artifacts.js"]
+    artifacts --> log1["#96;Log#96;"]:::log
+    log1 --creates--> name["artifacts</br>folder name"]
+    log1 --"overwrites</br>previous name"--> runtime1["runtime config file"]
+    log1 --"gets name</br>from"--> runtime1["runtime config</br>file"]
+    log1 --creates</br>with name--> folder1["folder</br>& files"]
 
 classDef log fill:#d6fd88,stroke:#000,stroke-width:2px,color:#000
 ```
 
+Then other processes use the name from the config to store logs and other files in the artifacts folder (as we've already shown).
+
+ALKiln stores the artifacts folder in the root of the local repository folder. The developer has direct access to the file system and can see every new artifacts folder. In fact, they can also see any previous artifacts folders. We avoid adding those artifacts folders to the repo by including the folder name pattern in the `.gitignore` and `.npmignore` files.
+
+```mermaid
+flowchart LR
+
+    git --🙈--> folder["folders & files"]
+    dev --👁️--> folder
+    npm --🙉--> 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.
+- Each originator (GitHub, ALKilnInThePlayground, the dev) could always create the name from the outside. This would duplicate work, but would give more fine-grained control.
+- Have `Log` make a different folder name each time and, at the very end, combine the contents of those folders into one folder. Hey, all ideas are welcome here.
+
+For name creation:
+
+- Avoid GitHub actions creating names. That is, create names only in `artifacts.js` and pass that out again. Needs research.
+
 
 [^1]: **Core framework code/core code:** the code that implements the Steps in the `.feature` test files.
+
+[^2] Keeping the `runtime_config` file around helps greatly improves the local development experience. You can read more in the document that talks about the 4 environments ALKiln supports.

package/docs/constrained_random_tests.md

@@ -252,3 +252,27 @@ Scenario: I visit the zoo
 
 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.
 
+
+## Ranges may not be that useful
+
+Focused tests with actual thought out options are so useful. Take these examples:
+
+```gherkin
+# ❌ Too broad: May miss important scenarios
+Then ALKiln will stop at "end" with any combination of:
+  | var | possible values |
+  | income | 0..1000000 |
+  | assets | 0..1000000 |
+
+# ✅ Better: Focused ranges with critical points
+Then ALKiln will stop at "end" with any combination of:
+  | var | possible values |
+  | income | 0;; 30000;; 50000;; 75000;; 100000 |
+  | assets | 0;; 50000;; 100000;; 250000 |
+```
+
+The first one will make a lot of useless tests. Is there a way to have a cake and eat it too? I'm not sure. Example:
+
+```
+| income | 0..100;; 900..1000 |
+```

package/lib/docassemble/server_install.js

@@ -56,8 +56,6 @@ const server_install = async () => {
 session_vars.validateEnvironment();
 
 // 2. Prepare logs
-// Local devs: This will be separate from your test paths
-// unless you pass a `path` argument into the cucumber run command
 const argv = require(`minimist`)(process.argv.slice(2));
 const log = new Log({ path: argv.path, context, });
 

package/lib/docassemble/setup.js

@@ -54,7 +54,7 @@ const setup = async () => {
       + `dainstall this package on your server. See above for more details.`;
     log.throw({ code: `ALK0047`, context,
       before: `☝️ ☝️ ☝️  Error data ☝️ ☝️ ☝️\n`,
-      error: new Error(`Error while installing project on your docassemble server`) },
+      error: new Error(`Error while installing project on your docassemble server during GitHub+You™ tests`) },
       install_err_msg
     );
   }
@@ -68,8 +68,6 @@ const setup = async () => {
 session_vars.validateEnvironment();
 
 // 2. Prepare logs
-// Local devs: This will be separate from your test paths unless you pass a
-//    `path` argument into the cucumber run command
 const argv = require(`minimist`)(process.argv.slice(2));
 const log = new Log({ path: argv.path, context, });
 

package/lib/globals.js

@@ -6,5 +6,5 @@ let globals = {
 
 module.exports = globals;
 
-// Would this be clearer as a config file instead?
-// If not, change name to `constants`?
+// Discuss: Would this be clearer as a config file instead? If not, change name
+// to `constants`?

package/lib/scope.js

@@ -888,7 +888,7 @@ module.exports = {
   },  // Ends scope.normalizeTable()
 
   getAllFields:  async function ( scope, { html }) {
-    /* Given HTML string of a page, returns a list of all the fields in it
+    /** Given HTML string of a page, returns a list of all the fields in it
     *  as some kind of sophisticated data? With their selectors, for example.
     *  We will choose selectors that will continue to identify the node, eve
     *  after a hidden field is revealed, etc.
@@ -1019,12 +1019,15 @@ module.exports = {
       // button, radio, checkbox yesno, and maybe others need the value of the `value` attribute
       let values = [];
       if ( node.name === `select` ) {
+        // Get possible values
         values = await scope.getOptionValues( scope, { $select: $node });
       }
       if ( values.length === 0 && node.attribs.value ) {
         // TODO: Add links to docs about da YAML values that devs never fill in themselves and
         // so don't know what they are. E.g. yesnomabye -> True/False/None.
         // TODO: Text inputs and textareas must ignore the value, etc. How?
+
+        // Get the current value for not `select` fields
         values.push( node.attribs.value );
       }
 
@@ -1387,6 +1390,14 @@ module.exports = {
     * @param <field[n].guesses[n].trigger> {str} - var name that triggered this page
     * 
     * @returns [ var_data[n] ]
+    * @returns [{
+    *   table_row: var_data[n],
+    *   field: {
+    *     selector: str,
+    *     guesses: [{ values: [str] }]
+    *   }
+    * }]
+    * What does it return when there's no match?
     */
 
     let rows_that_match_field_names = [];

package/lib/setup/TestGenerator.js

@@ -7,19 +7,18 @@ const get_Gherkin_AST = require(`./get_Gherkin_AST`);
 const get_error_stacks = require(`../utils/get_error_stacks`);
 
 /**
- * TODO: We might give various levels of categories for warnings. For example,
- *     severe warnings (like "will skip the random test") vs. slight warnings
- *     (like "missing number in constraints random test")
+ * TODO: Update ALKilnInThePlayground to let author download the generated
+ *     tests. Also, store them in a unique location. 
  * TODO: Post-MVP, don't repeat tests that the author has already created
  * TODO: Post-MVP, write Steps that warn about fore-Steps and constraints Steps
  *     when they appear in a regular test. It probably means someone named the
  *     file incorrectly.
- * Discuss: Require author to use "Generator Scenario:" as they keyword (Also
- *     "Generator Scenario Outline:") (or "Scenario Generator", maybe harder to
- *     scan) for 2 reasons. 1. Gets the vocab of "generator" in early (though
+ * Discuss: Require author to use "Template Scenario:" as they keyword (Also
+ *     "Template Scenario Outline:") (or "Scenario Template", maybe harder to
+ *     scan) for 2 reasons. 1. Gets the vocab of "template" in early (though
  *     that doesn't match "constraints" Step, which is a whole other language
- *     problem we haven't solved yet.) 2. Saying "MAX_RANDOM_TESTS_PER_SCENARIO"
- *     is confusing when "Scenario" means different things - a generator
+ *     problem we haven't solved yet.) 2. Saying "ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO"
+ *     is confusing when "Scenario" means different things - a template
  *     Scenario and a regular Scenario.
  * Discuss: Now that Log is less fragile and duplicated, shall we create a new
  *     Log instance in here?
@@ -30,6 +29,9 @@ const get_error_stacks = require(`../utils/get_error_stacks`);
  *     do that now, but without the icon.
  * Discuss: If/when we allow multiple Scenarios, research how we find the end
  *     of a Scenario that ends in an `Example`.
+ * Discuss: We might give various levels of categories for warnings. For example,
+ *     severe warnings (like "will skip the random test") vs. slight warnings
+ *     (like "missing number in constraints random test")
  * */
 
 let log = null;
@@ -177,7 +179,7 @@ module.exports = class TestGenerator {
     let scenario_objs = doc_AST.feature.children;
     if ( !scenario_objs[0] ) {
       let syntax_error = log.error({ code: `ALK0235`, context: `generating files`, before: `\n\n`, },
-        `The author's generator .feature file at "${ generator_path }" may be missing its Scenarios.`
+        `It looks like the author's template .feature file at "${ generator_path }" has 0 Scenarios.`
       );
       return { new_contents: null, errors: [new Error( syntax_error )]};
     }
@@ -185,7 +187,7 @@ module.exports = class TestGenerator {
 
     if ( scenario_objs.length > 1 ) {
       let too_many_scenarios = log.error({ code: `ALK0236`, context: `generating files`, },
-        `A generator file can only have 1 generator Scenario. This one has ${ scenario_objs.length }.`
+        `A template file can only have 1 template Scenario. This one has ${ scenario_objs.length }.`
       );
       return { new_contents: ``, errors: [new Error( too_many_scenarios )] };
     }
@@ -250,7 +252,7 @@ module.exports = class TestGenerator {
     let errs_n_warns = new Misbehaviors();
 
     let strs_for_all_new_Scenarios = [];
-    // Soon we want to be able to handle multiple generator Scenarios per file
+    // Soon we want to be able to handle multiple template Scenarios per file
     for ( let scenario_obj_i = 0; scenario_obj_i < scenario_objs.length; scenario_obj_i++ ) {
 
       errs_n_warns.reset_warnings();
@@ -370,11 +372,11 @@ module.exports = class TestGenerator {
 
     let got_fewer_tests_than_desired = new_test_bodies.length < num_to_make;
     if ( got_fewer_tests_than_desired ) {
-      let warn_too_few = log.warn({ code: `ALK0260`, context: `generating files generator-scenario-level`, },
-        `ALKiln could only make ${ new_test_bodies.length } *unique* tests out of the ${ num_to_make } the author wanted for this Scenario. Note that ALKiln compares all generated Scenarios with each other to make sure all are unique. This Scenario may be a duplicate of a Scenario generated by a previous generator. The Scenario:\n      ${ scenario_description_for_logs({ scenario }) }`,
+      let warn_too_few = log.warn({ code: `ALK0260`, context: `generating files template-scenario-level`, },
+        `ALKiln could only make ${ new_test_bodies.length } *unique* tests out of the ${ num_to_make } the author wanted for this Scenario. Note that ALKiln compares all generated Scenarios with each other to make sure all are unique. This Scenario may be a duplicate of a Scenario generated from a previous template. The Scenario:\n      ${ scenario_description_for_logs({ scenario }) }`,
       )
       // Discuss: Should we add more structure to Misbehaviors to give them
-      //     context levels (Feature, generator Scenario, generated Scenario)
+      //     context levels (Feature, template Scenario, generated Scenario)
       misfits.add({ warnings: [ warn_too_few ] });
     }
 
@@ -493,7 +495,7 @@ function get_generator_AST({ file_text, generator_path }) {
 
   if ( generator_errors.length > 0 ) {
     let syntax_error = log.error({ code: `ALK0232`, context: `generating files`, before: `\n\n`, },
-      `The author's generator .feature file at "${ generator_path }" has Gherkin syntax error(s). You might see more warnings above or below this one.\n`,
+      `The author's template .feature file at "${ generator_path }" has Gherkin syntax error(s). You might see more warnings above or below this one.\n`,
       ...get_error_stacks({ errors: generator_errors })
     );
     return { doc_AST: null, errors: [new Error( syntax_error )] };
@@ -503,14 +505,14 @@ function get_generator_AST({ file_text, generator_path }) {
 
   if ( !doc_AST.feature ) {
     let feature_error = log.error({ code: `ALK0233`, context: `generating files`, before: `\n\n`, },
-      `The author's generator .feature file at "${ generator_path }" needs to include the \`Feature\` keyword.`
+      `The author's template .feature file at "${ generator_path }" needs to include the \`Feature\` keyword.`
     );
     return { doc_AST: null, errors: [new Error( feature_error )] };
   }
 
   // Should not get here
   let unknown_error = log.error({ code: `ALK0234`, context: `generating files`, before: `\n\n`, },
-    `The author's generator .feature file at "${ generator_path }" ran into an unanticipated error when ALKiln tried to parse it. If you have a moment, we would love for you to send us your debug.txt.`
+    `The author's template .feature file at "${ generator_path }" ran into an unanticipated error when ALKiln tried to parse it. If you have a moment, we would love for you to send us your debug.txt.`
   );
   return { doc_AST, errors: [new Error( unknown_error )] };
 }
@@ -657,7 +659,7 @@ function get_fore_Steps({ scenario }) {
   if ( there_were_no_fore_Steps ) {
     misfits.add({ errors: [
       new Error( log.error({ code: `ALK0242`, context: `generating files`, },
-        `A generator Scenario's first Step must say how many constrained random answers tests to make. The generator Scenario on line ${ scenario.location.line } is missing that Step. The Scenario's description is:\n${ description }`
+        `A template Scenario's first Step must say how many constrained random answers tests to make. The template Scenario on line ${ scenario.location.line } is missing that Step. The Scenario's description is:\n${ description }`
       ) )
     ] });
   } else {
@@ -724,7 +726,7 @@ function get_number_of_Scenarios_to_generate2({ step, prev_num_to_make }) {
     //     a way that is also maintainable?
     warnings.push( 
       log.warn({ code: `ALK0238`, context: `generating files`, },
-        `A generator Scenario has too many Steps that set the number of tests to make. ALKiln will use the final number Step it finds or calculates. The current Step:\n      ${ text }`
+        `A template Scenario has too many Steps that set the number of tests to make. ALKiln will use the final number Step it finds or calculates. The current Step:\n      ${ text }`
       )
     );
   }
@@ -735,7 +737,7 @@ function get_number_of_Scenarios_to_generate2({ step, prev_num_to_make }) {
   if ( number_matcher === null ) {
     warnings.push( 
       log.warn({ code: `ALK0239`, context: `generating files`, },
-        `A generator Scenario is missing the number of tests to make. ALKiln will now make 1 constrained random answers test. The current Step:\n      ${ text }`
+        `A template Scenario is missing the number of tests to make. ALKiln will now make 1 constrained random answers test. The current Step:\n      ${ text }`
       )
     );
     return { num_to_make: 1, warnings, errors };
@@ -744,7 +746,7 @@ function get_number_of_Scenarios_to_generate2({ step, prev_num_to_make }) {
   /** Too many numbers */
   if ( number_matcher && number_matcher.length > 1 ) {
     // Some feedback indicated using the last number makes more sense to people
-    //    than the first
+    //    than the first. Also, matches Story Table behavior.
     user_num = parseInt( number_matcher[ number_matcher.length - 1 ]);
     warnings.push(
       log.warn({ code: `ALK0240`, context: `generating files`, },
@@ -759,14 +761,14 @@ function get_number_of_Scenarios_to_generate2({ step, prev_num_to_make }) {
   }
 
   let num_to_make = Math.min(
-    session_vars.get_max_tests_per_generator_scenario(),
+    session_vars.get_max_tests_per_template_scenario(),
     user_num
   );
 
   if ( num_to_make !== user_num ) {
     warnings.push(
       log.warn({ code: `ALK0241`, context: `generating files`, },
-        `The author asked to make ${ user_num } tests, but maximum allowed is ${ num_to_make }. ALKiln will now make ${ num_to_make } tests. If you want to increase the maximum, use the MAX_TESTS_PER_GENERATOR_SCENARIO environment variable. Read more about environment variables at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#env-vars.`
+        `The author asked to make ${ user_num } tests, but maximum allowed is ${ num_to_make }. ALKiln will now make ${ num_to_make } tests. If you want to increase the maximum, use the ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO input. Read more about inputs at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#workflow-inputs. The Step:\n      ${ text }`
       )
     );
   }
@@ -1099,7 +1101,7 @@ function get_final_ids({ step_text }) {
   let ids = step_text.match( CAPTURE_QUESTION_IDS_REGEX );
 
   if ( ids === null ) {
-    let missing_ids_msg = `The constrained random answers Step is missing its question ids. ALKiln is unable to create random tests for this generator Scenario. The Step:\n${ step_text }`;
+    let missing_ids_msg = `The constrained random answers Step is missing its question ids. ALKiln is unable to create random tests for this template Scenario. The Step:\n${ step_text }`;
     let error = log.error({ code: `ALK0250`, context: `generating files`, }, missing_ids_msg );
     errors.push(new Error( error ));
   }
@@ -1348,7 +1350,7 @@ function remove_warning_tag_placeholder({ new_text }) {
 
 
 function add_total_tests({ scenario_group_str, num_tests }) {
-  /** Paste in the total number of tests generated for this generator Scenario.
+  /** Paste in the total number of tests generated for this template Scenario.
    * 
    * @param {object} obj - Named arguments
    * @param {str} obj.scenario_group_str - The combined string of all the
@@ -1369,10 +1371,10 @@ function add_warnings_Scenario({ scenarios_str, warnings }) {
    *     Scenarios. Basically, a whole-generator-scope warning.
    * 
    * Discuss: Add a pre-group Scenario for every group of generated Scenarios
-   *     identifying the generator Scenario of the subsequent new Scenarios.
+   *     identifying the template Scenario of the subsequent new Scenarios.
    *     That is, even when there is no warning to give.
    * 
-   * TODO: If/when we allow multiple generator Scenarios, use the ID here too
+   * TODO: If/when we allow multiple template Scenarios, use the ID here too
    * 
    * @param {object} obj - Named arguments
    * @param {str} obj.scenarios_str - The str of the already existing Scenarios
@@ -1381,7 +1383,7 @@ function add_warnings_Scenario({ scenarios_str, warnings }) {
    * @returns {str} - The text of the combined Scenarios.
    * */
   let tags = `@alkiln_extra_intro ${ ALKILN_WARNING_TAG }`;
-  let keyword_line = `Scenario: ALKiln humbly begs the author's forgiveness. The next tests might be flawed.`;
+  let keyword_line = `Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.`;
   let step_text = get_goofy_warnings_Step_text();
 
   let warnings_lines = warnings_as_list_of_lines({ warnings });
@@ -1435,7 +1437,7 @@ function get_warnings_docstring({ warnings_lines, indent }) {
    * */
   let doc_str_lines = [
     `"""`,
-    `――――― Generator file warnings ―――――`,
+    `――――― Template file warnings ―――――`,
     ...warnings_lines,
     `―――――`,
     `"""`,
@@ -1506,7 +1508,7 @@ function save_files({ tests_path, artifacts_path, file_strings }) {
 
   let count = 1;
   for ( let file_str of file_strings ) {
-    let filename = `${ count }_${ Date.now() }.feature`;
+    let filename = `_alkiln_generated_${ count }_${ Date.now() }.feature`;
     count++;
     // Implementation note: If the files don't exist, this creates them
     fs.appendFileSync( `${ tests_path }/${ filename }`, file_str );

package/lib/steps.js

@@ -420,11 +420,11 @@ When(/I? ?gets? to ?.*?(".*").*?with.*?(?:this data:)?/i, {timeout: -1}, async (
           // Some errors happen in there to be closer to the relevant code. We'd have to try/catch anyway.
           let error = await scope.setFields(scope, { var_data: ensured_var_data, id, ensure_navigation: true });
 
-          // TODO: use Log class to throw this error?
+          // Discuss: use Log class to throw this error?
           if ( error.was_found ) { await scope.throwPageError( scope, { id: id }); }
           resolve();
         } catch ( err ) {
-          let err_msg = `ALKiln ran into an error it tried to answer fields on the page with the question id "${ id }". The text above might have more information.`
+          let err_msg = `ALKiln ran into an error when it tried to answer fields on the page with the question id "${ id }". The text above might have more information.`
           reports.addToReport( scope, { type: `error`, code: `ALK0062`, value: err_msg });
           // Throw error instead?
           reject( err );
@@ -721,39 +721,48 @@ Then(/the "([^"]+)" link opens in (a new window|the same window)/, async (linkTe
   await scope.afterStep(scope);
 });
 
-Then(/(?:the )?text(?: in)?(?: the)?(?: JSON)?(?: var)?(?:iable)?(?: )?"([^"]+)" should be/i, async (var_name, expected_value) => {
-  /* Check that the text string of the page's JSON var value matches
-  *    the given text string. Does not currently accept nested values
-  *    like "foo.bar". The word "text" is required.
-  *
-  * The format for this step is something like this:
-  * ```
-  * Then the text in the JSON variable "var_name" should be
-  * """
-  * A single or
-  * multiline string
-  * """
-  * ```
-  *
-  * Sentence combinations that will work:
-  * `the text in the JSON variable "variable_with_text_value" should be`
-  * `the text in the JSON var "variable_with_text_value" should be`
-  * `the text in "variable_with_text_value" should be`
-  * `text var "variable_with_text_value" should be`
-  */
+Then(/(?:the )?text(?: in)?(?: for)?(?: the)?(?: JSON)?(?: var)?(?:iable)?(?: )?"([^"]+)" should be/i, async (var_name, expected_value) => {
+  /** Check that the text string of the page's JSON var value matches
+   *    the given text string. Does not currently accept nested values
+   *    like "foo.bar". The word "text" is required.
+   *
+   * The format for this step is something like this:
+   * ```
+   * Then the text in the JSON variable "var_name" should be
+   * """
+   * A single or
+   * multiline string
+   * """
+   * ```
+   * 
+   * Note: ALKiln removes `\r` from both the expected and actual values.
+   *
+   * Sentence combinations that will work:
+   * the text in the JSON variable "variable_with_text_value" should be
+   * the text in the JSON var "variable_with_text_value" should be
+   * the text for "variable_with_text_value" should be
+   * text "variable_with_text_value" should be
+   * */
 
   // Get JSON variable value
   let { json_path, json } = await scope.savePageJSONData( scope );
+
+  // docassemble (at least sometimes) makes new lines with `\r\n`
   let actual_value = json.variables[ var_name ];
+  actual_value = actual_value.replace(/\r/, ``);
+  // Normalize `expected_value` as well for backwards compatibility in case any
+  //     authors are already compensating for docassemble
+  expected_value = expected_value.replace(/\r/, ``);
 
   // Add warning to report if value is not as expected
   if ( actual_value !== expected_value ) {
     reports.addToReport( scope, {
       type: `error`,
       code: `ALK0083`,
-      value: `The variable "${ var_name }" was not equal to the expected `
-        + `value on the "${ scope.page_id }" screen. Check `
-        + `${ json_path } to see the page's JSON variables.`
+      value: `The variable "${ var_name }" was different from the expected `
+        + `value on the "${ scope.page_id }" screen.`
+        + `The expected values was\n` + expected_value
+        + `\nwhile the actual value was\n` + actual_value
     });
   }
 
@@ -1058,6 +1067,22 @@ When(/I set the var(?:iable)? "([^"]+)" to "([^"]+)"/, { timeout: -1 }, async (
 
 });
 
+When(/I set the var(?:iable)? "([^"]+)" to\s*$/, { timeout: -1 }, async ( var_name, answer ) => {
+  /** Set a non-story table variable (with or without a choice associated with
+   *     it) to a value that can have new lines in it. Most useful for
+   *     `textarea`s.
+   *
+   * Example:
+   *   I set the var "benefits['SSI']" to
+   *     """
+   *     Some multline
+   *     value
+   *     """
+   * */
+  // `page` timeout will deal with custom timeout
+  await scope.steps.set_regular_var( scope, var_name, answer )
+});
+
 When(/I set the var(?:iable)? "([^"]+)" to ?(?:the)? ?(?:GitHub)? secret "([^"]+)"/i, { timeout: -1 }, async ( var_name, set_to_env_name ) => {
   /* Set a non-story table variable to a secrete value. Same as the above, but reads the value from `process.env` */
   // This could theoretically tap an element, so

package/lib/utils/Log.js

@@ -624,31 +624,28 @@ class Log {
   }  // Ends Log._stringify_logs()
 
   _stringify_inline({ prev_line_type, inline_log }) {
-    /** Formats the start of an inline log based on the previous log and returns
-     *  that combined string.
+    /** Formats the log to add a space or a new line separator. May end up with
+     *     a leading space for now.
      *
      * @param { "inline"|"block"|null } prev_line_type - Required. The type of
      *     the previous log.
      * @param { null|non-obj } inline_log - Required. The log.
      *
-     * @returns { string } The formatted log.
+     * @returns { string } The formatted line.
      *
      * @example
      * // Backticks are to make the surrounding white space more clear
      * log._stringify_inline({ prev_line_type: null, inline_log: "apple" });
-     * // `apple`
+     * // "apple "
      * log._stringify_inline({ prev_line_type: 'inline', inline_log: "apple" });
-     * // ` apple`
+     * // "apple "
      * log._stringify_inline({ prev_line_type: 'block', inline_log: "apple" });
-     * // `
-     * // apple`
+     * // "
+     * // apple"
      * */
-    // An inline log's string starts with nothing if it's the first string...
     let start = ``;
-    // ...starts after a space if its next to an inline string...
-    if ( prev_line_type === `inline` ) { start = ` `; }
-    // ...or starts on a new line if it's after a block of text, like an error
-    // or object.
+    if ( prev_line_type === `inline` && !inline_log.startsWith(`\n`) ) { start = ` `; }
+    // This is actually the end of the block-type log
     else if ( prev_line_type === `block` ) { start = `\n`; }
     return `${ start }${ inline_log }`;
   }
@@ -658,6 +655,8 @@ class Log {
      *  a "block"-type separator at the start. Can handle circular references.
      *  Catch ANY error.
      *
+     * @param { "inline"|"block"|null } prev_line_type - Required. The type of
+     *     the previous log.
      * @param { Object } obj_log - Required. The object to format.
      *
      * @returns { string } The obj as a string plus a separator
@@ -669,15 +668,15 @@ class Log {
      * // { fruit: 'bananas' }
      * */
     let start = ``;
-    if ( prev_line_type === `inline` || prev_line_type === `block` ) {
-      start = `\n`;
-    }
+    // Avoid adding a new line to the start of the first line
+    let is_first_line = prev_line_type === null;
+    if ( !is_first_line ) { start = `\n`; }
 
     try {
       // Try to stringify the object.
       return `${ start }${ this._inspect({ value: obj_log }) }`;
 
-    // Discuss: record these errors?
+    // Discuss: record the outer error?
     } catch ( outer_error ) {
       // If that fails, see if it has its own way of stringifying
       try {

package/lib/utils/reports.js

@@ -263,25 +263,28 @@ reports.getPrintableScenario = function( scenario ) {
   return report;
 };  // Ends reports.getPrintableScenario()
 
-let getLineText = function ({ type=`no type`, code=`ALK00rl`, value=``, indent=`` }) {
+let getLineText = function ({ from_log, type=`no type`, code=`ALK00rl`, value=``, indent=`` }) {
 
-  value = `${ value.replace( /\n/g, "\n" + indent ) }`;
+  value = `${ value.replace( /\n/g, `\n` + indent ) }`;
 
   if ( type === `as_is` ) { return `${ indent }${ value }`; }
 
   let start = indent;
-  if ( type.includes(`outcome`) ) { start = `\n`; }
+  if ( type.includes(`outcome`) ) { start = `\n`; }  // extra new line
 
   if ( type.includes(`page_id`) ) { start += `screen id: `; }
-  else if ( type.includes(`warning`) ) { start += `🔎 ${ code } WARNING: `; }
-  else if ( type.includes(`error`) ) { start += `\n🤕 ${ code } ERROR: `; }  // extra new line
-  let result = `${ start }${ value }`;
-  return result;
-};  // Ends getLine()
+  else if ( type.includes(`warning`) && !from_log ) { start += `🔎 ${ code } WARNING: `; }
+  else if ( type.includes(`error`) && !from_log ) { start += `🤕 ${ code } ERROR: `; } // extra new line
+
+  return `${ start }${ value }`;
+
+}; // Ends getLine()
 
-let getDebugLine = function ({ type=``, code=`ALK0278`, value=``, indent=`` }) {
+let getDebugLine = function ({ from_log, type=``, code=`ALK00rd`, value=``, indent=`` }) {
   /** In debug log lines, include all the information possible. */
 
+  // Discuss: How to prevent saving in the debug log twice
+  if ( from_log ) { return value; }
   // `plain` is usually used for visual clarity and shouldn't have
   // codes and such associated with it. Return right away.
   if ( type.includes(`plain`) ) { return `${ indent }${ value }`; }
@@ -310,7 +313,7 @@ let getDebugLine = function ({ type=``, code=`ALK0278`, value=``, indent=`` }) {
   if ( type.includes(`warning`) ) { description_parts.push( `WARNING` ); }
   if ( type.includes(`error`) ) { description_parts.push( `ERROR` ); }
   // Default
-  if ( description_parts.length <= 0 ) { description_parts.push( `UNKNOWN` ); }
+  if ( description_parts.length <= 0 ) { description_parts.push( `UNKNOWN LOG TYPE` ); }
 
   start = [ start, ...description_parts ].join(` `);
 

package/lib/utils/session_vars.js

@@ -73,7 +73,7 @@ session_vars.get_setup_timeout_ms = function () {
   return timeout;
 };
 
-session_vars.get_max_tests_per_generator_scenario = function() {
+session_vars.get_max_tests_per_template_scenario = function() {
   /** Returns the maximum number of tests to generate for any one generator
    *    Scenario.
    * 
@@ -82,7 +82,7 @@ session_vars.get_max_tests_per_generator_scenario = function() {
    * 
    * @returns {int} - Max number of tests for one generator Scenario
    * */
-  return process.env.MAX_RANDOM_TESTS_PER_SCENARIO || 40;
+  return process.env.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO || 40;
 }
 
 session_vars.get_da_server_url = function () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.13.3-feat-random-3",
+  "version": "5.13.3-feat-random-5",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {

package/tests/unit_tests/constrained_random_answers/invalid.fixtures.js

@@ -9,7 +9,8 @@ module.exports = fixts = {};
  * 
  * TODO
  * Research: Can we get back null or undefined without syntax errors? (unlikely)
- * Research: Can feature.children[0] exist without a `.scenario` prop? (unlikely)
+ * Research: Can a feature.children item exist without having a `.scenario`
+ *     prop? (unlikely)
  * */
 
 fixts.generator_missing_Feature = {};

package/tests/unit_tests/constrained_random_answers/valid.fixtures.js

@@ -51,22 +51,6 @@ simple.exact_log_codes = [
 simple.num_Scenarios = 1;
 
 
-/** TODO: 2 generator Steps in one Scenario */
-
-`Feature: I generate constrained random tests
-
-Scenario: I fail with 2 generator Steps in 1 Scenario
-  Given ALKiln makes 2 constrained answers tests
-  Given I start the interview at "form_entrypoint_file_name"
-  And I generate 2 constrained random tests that get to "end" when I pick from:
-    | var | possible_values |
-    | other_var | val1;; val2;; val3 |
-  And I generate 1 constrained random test that gets to "end" when I pick from:
-    | var | possible_values |
-    | user_choice | correct;; wrong |
-`;
-
-
 /**
  * ===========
  * Minimal required Step text:
@@ -677,10 +661,10 @@ fixts.warnings.no_number.expected =
 Feature: I generate constrained random tests (generated by ALKiln)
 
 @alkiln_extra_intro @alkiln_generator_warning
-Scenario: ALKiln humbly begs the author's forgiveness. The next tests might be flawed.
+Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.
   Then ALKiln warns the author about a generator ${ fixts.FLUB_PLACEHOLDER }:
     """
-    ――――― Generator file warnings ―――――
+    ――――― Template file warnings ―――――
     🔎 ALK0239 ${ fixts.WARNING_PLACEHOLDER }
     ―――――
     """
@@ -713,10 +697,10 @@ fixts.warnings.multiple_numbers.expected =
 Feature: I generate constrained random tests (generated by ALKiln)
 
 @alkiln_extra_intro @alkiln_generator_warning
-Scenario: ALKiln humbly begs the author's forgiveness. The next tests might be flawed.
+Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.
   Then ALKiln warns the author about a generator ${ fixts.FLUB_PLACEHOLDER }:
     """
-    ――――― Generator file warnings ―――――
+    ――――― Template file warnings ―――――
     🔎 ALK0240 ${ fixts.WARNING_PLACEHOLDER }
     ―――――
     """
@@ -750,10 +734,10 @@ fixts.warnings.multiple_number_Steps.expected =
 Feature: I generate constrained random tests (generated by ALKiln)
 
 @alkiln_extra_intro @alkiln_generator_warning
-Scenario: ALKiln humbly begs the author's forgiveness. The next tests might be flawed.
+Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.
   Then ALKiln warns the author about a generator ${ fixts.FLUB_PLACEHOLDER }:
     """
-    ――――― Generator file warnings ―――――
+    ――――― Template file warnings ―――――
     🔎 ALK0238 ${ fixts.WARNING_PLACEHOLDER }
     ―――――
     """
@@ -787,10 +771,10 @@ fixts.warnings.multiple_number_Steps_and_numbers.expected =
 Feature: I generate constrained random tests (generated by ALKiln)
 
 @alkiln_extra_intro @alkiln_generator_warning
-Scenario: ALKiln humbly begs the author's forgiveness. The next tests might be flawed.
+Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.
   Then ALKiln warns the author about a generator ${ fixts.FLUB_PLACEHOLDER }:
     """
-    ――――― Generator file warnings ―――――
+    ――――― Template file warnings ―――――
     🔎 ALK0240 ${ fixts.WARNING_PLACEHOLDER }
     🔎 ALK0238 ${ fixts.WARNING_PLACEHOLDER }
     🔎 ALK0240 ${ fixts.WARNING_PLACEHOLDER }
@@ -840,10 +824,10 @@ Feature: I generate valid constrained random answers tests 1 (generated by ALKil
 # The 1st of 2 related tests. This 1st one tests uniqueness within one Scenario.
 
 @alkiln_extra_intro @alkiln_generator_warning
-Scenario: ALKiln humbly begs the author's forgiveness. The next tests might be flawed.
+Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.
   Then ALKiln warns the author about a generator ${ fixts.FLUB_PLACEHOLDER }:
     """
-    ――――― Generator file warnings ―――――
+    ――――― Template file warnings ―――――
     🔎 ALK0260 ${ fixts.WARNING_PLACEHOLDER }
     ―――――
     """
@@ -868,10 +852,10 @@ Feature: I generate valid constrained random answers tests 2 (generated by ALKil
 # The 2nd of 2 related tests. Because ALKiln will try to only generate unique tests between all the generators, this 2nd one tests uniqueness of tests between generators. Only the body of the Scenario should matter for uniqueness.
 
 @alkiln_extra_intro @alkiln_generator_warning
-Scenario: ALKiln humbly begs the author's forgiveness. The next tests might be flawed.
+Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.
   Then ALKiln warns the author about a generator ${ fixts.FLUB_PLACEHOLDER }:
     """
-    ――――― Generator file warnings ―――――
+    ――――― Template file warnings ―――――
     🔎 ALK0260 ${ fixts.WARNING_PLACEHOLDER }
     ―――――
     """
@@ -888,6 +872,43 @@ fixts.warnings.fewer_unique_than_requested.included_log_codes = [
 ];
 
 
+fixts.warnings.over_max = {};
+fixts.warnings.over_max.max_num_allowed = 1;
+fixts.warnings.over_max.arg =
+`Feature: I generate constrained random tests
+
+Scenario: I'm warned of asking for more than the max num tests
+  Given ALKiln makes 2 constrained random tests
+  Given I start the interview at "test_kickout"
+  And ALKiln gets to "end" when I pick from:
+    | var | possible_values |
+    | user_choice | correct;; wrong |`;
+fixts.warnings.over_max.expected =
+`@alkiln @generated @randomized @constraints
+Feature: I generate constrained random tests (generated by ALKiln)
+
+@alkiln_extra_intro @alkiln_generator_warning
+Scenario: ALKiln begs the author's forgiveness. The next tests might be flawed.
+  Then ALKiln warns the author about a generator ${ fixts.FLUB_PLACEHOLDER }:
+    """
+    ――――― Template file warnings ―――――
+    🔎 ALK0241 ${ fixts.WARNING_PLACEHOLDER }
+    ―――――
+    """
+
+@scenario1_of_1
+Scenario: I'm warned of asking for more than the max num tests (1 of 1)
+  Given I start the interview at "test_kickout"
+  And I get to any of the question ids ["end"] with this data:
+    | var | value |
+${ fixts.RANDOM_TABLE_PLACEHOLDER }`;
+fixts.warnings.over_max.exact_log_codes = [
+  `ALK0237`, `ALK0241`, `ALK0243`, `ALK0244`,
+  `ALK0245`, `ALK0248`, `ALK0249`, `ALK0246`, `ALK0246`, `ALK0246`, `ALK0255`, `ALK0257`, `ALK0259`, `ALK0246`,
+  `ALK0261`, `ALK0262`, `ALK0264`,
+];
+
+
 /**
  * ===========
  * Silent warnings

package/tests/unit_tests/constrained_random_answers/valid.test.js

@@ -20,7 +20,7 @@ const TABLE_ROW_REGEX = /^(?!(?:.*\| var \| value \|))(.*\| .* \|)/gm;
 const TABLE_PLACEHOLDER_REGEX = new RegExp(`(${ RANDOM_TABLE_PLACEHOLDER }(\n)?)+`, `g`);
 
 const WARNING_PLACEHOLDER = fixtures.WARNING_PLACEHOLDER;
-const WARNING_MSG_REGEX = /(ALK\d{4} )(.*\d{4}-\d\d-\d\d \d\d:\d\d:\d\dUTC.*(?:\n.+))/g;
+const WARNING_MSG_REGEX = /(ALK\d{4} )(.*\d{4}-\d\d-\d\d \d\d:\d\d:\d\dUTC.*(?!\n    ―)(?:\n)?.+)/g;
 
 const FLUB_PLACEHOLDER = fixtures.FLUB_PLACEHOLDER;
 const FLUB_REGEX = fixtures.FLUB_OPTIONS_REGEX;
@@ -96,6 +96,11 @@ function mutate_globals_with({ testing_vals, do_compare=false }) {
   // Reset log codes
   logger.clear_internal_log_records();
 
+  process.env.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO = 40;
+  if ( testing_vals.max_num_allowed ) {
+    process.env.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO = testing_vals.max_num_allowed;
+  }
+
   // Fresh namespace
   let generator = new TestGenerator();
   // Mutates `fixture`
@@ -505,6 +510,23 @@ describe(`Constrained random answers parser, when given a valid generator Scenar
     });
   });
 
+  describe(`that asks for over max # of tests allowed - 1 -`, function () {
+
+    before(function () { mutate_globals_with({ testing_vals: fixtures.warnings.over_max }); });
+
+    let outer = fixtures.warnings.over_max;
+    it(`has these exact log codes with warnings: ${ JSON.stringify( outer.exact_log_codes )}`, function () {
+      expect( get_log_codes({ logger }) ).to.have.all.members( fixture.exact_log_codes );
+    });
+    
+    it(`returns no errors`, function () { expect( errors ).to.have.lengthOf( 0 ); });
+
+    it(`has max # of tests - 1`, function () {
+      expect( comparable_text( new_contents )).to.equal( fixture.expected );
+    });
+
+  });
+
   describe(`that has a blank var value in a generator column`, function () {
 
     before(function () { mutate_globals_with({ testing_vals: fixtures.empty_string_value }); });