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

package/CHANGELOG.md

@@ -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/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/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

@@ -746,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`, },

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.13.3-feat-random-4",
+  "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: