@suffolklitlab/alkiln 5.11.2-fix-root-dir-1 → 5.12.0-delete1

package/.github/workflows/github_server.yml

@@ -23,8 +23,8 @@ on:
 jobs:
 
   github-server-tests:
-    #### Developer note: If under `on` (above) you have both `push` and
-    #### `pull_request`, this avoids running double tests when someone
+    #### Developer note: If you have both `push` and `pull_request` in the
+    #### `on` section (above), this avoids running double tests when someone
     #### on the team makes a pull request
     # 1: Trigger job on push or dispatch from this repository
     # 2: Trigger job on pull request from a fork
@@ -71,10 +71,10 @@ jobs:
         shell: bash
 
       #### Developer note: You can probably leave this out
-      # Optional debugging to explore things like docker issues
-      - name: Docker debug tmate session
-        if: ${{ github.event.inputs.enable_tmate }}
-        uses: mxschmitt/action-tmate@v3
+      # # Optional debugging to explore things like docker issues
+      # - name: Docker debug tmate session
+      #   if: ${{ failure() && github.event.inputs.enable_tmate == 'true' }}
+      #   uses: mxschmitt/action-tmate@v3
 
       #### Developer note: You can probably leave this out
       - name: Run ALKiln - Env vars for our own tests from server output
@@ -93,25 +93,49 @@ jobs:
 
       - name: "Run ALKiln tests"
         if: ${{ success() }}
+        id: alkiln
         #### Developer note: you'll need to replace `uses: ./`
         #### with the path to ALKiln’s repository name and branch name. For example,
         #### for version 5, use the branch name `v5`: `uses: suffolkLITLab/ALKiln@v5`
         uses: ./
-        #### Developer note: You can probably leave this out
+        #### Developer note: You can probably leave out this `env` section
         env:
-          ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || 'not @a11y' }}"
+          # 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.
+          ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || '(not @error) and (not @temp_error)' }}"
         with:
           #### Developer note: Required inputs. See
           #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#sandbox-inputs
           SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}"
           INSTALL_METHOD: "server"
-          #### Developer note: See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#optional-inputs
-          #### You can probably leave this out
-          # 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.
-          ALKILN_TAG_EXPRESSION: $ALKILN_TAG_EXPRESSION
-          #### Developer note: You can probably leave this out
-          # ALKILN_VERSION: url
+          #### Developer note: You can probably leave the rest out
+          #### To learn more, see https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#optional-inputs
+          ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
+          ALKILN_VERSION: delete
+
+      #### Developer note: Example of making an issue when tests fail
+      #### that includes the text of the failure output file
+      #### See https://cli.github.com/manual/gh_issue_create for more details
+      - shell: bash
+        if: ${{ failure() }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PATH_TO_REPORT_FILE: "${{ steps.alkiln.outputs.PATH_TO_REPORT_FILE }}"
+          PATH_TO_UNEXPECTED_RESULTS_FILE: "${{ steps.alkiln.outputs.PATH_TO_UNEXPECTED_RESULTS_FILE }}"
+          PATH_TO_DEBUG_LOG_FILE: "${{ steps.alkiln.outputs.PATH_TO_DEBUG_LOG_FILE }}"
+        run: |
+          # Make an issue with file contents or 'no file' message as part of the body
+
+          if [ -f "${{ env.PATH_TO_UNEXPECTED_RESULTS_FILE }}" ]; then
+            UNEXPECTED_2=$(cat "${{ env.PATH_TO_UNEXPECTED_RESULTS_FILE }}")
+          else
+            UNEXPECTED_2="unexpected_results.txt does not exist. Something other than the interview tests may have failed."
+          fi
+
+          gh issue create --body "An ALKiln test run failed. See the action at ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}.
+
+          ### Results:
 
+          $UNEXPECTED_2" --repo "$GITHUB_REPOSITORY" --label "testing" --title "ALKiln tests failed"

package/.github/workflows/playground.yml

@@ -13,8 +13,8 @@ on:
 jobs:
 
   puppeteer-tests:
-    #### Developer note: If under `on` (above) you have both `push` and
-    #### `pull_request`, this avoids running double tests when someone
+    #### Developer note: If you have both `push` and `pull_request` in the
+    #### `on` section (above), this avoids running double tests when someone
     #### editing the repository makes a pull request
     # 1: Trigger job on push or dispatch from this repository
     # 2: Trigger job on pull request from a fork
@@ -55,18 +55,13 @@ jobs:
       # Place the root directory in this branch to access relative paths to action files
       - uses: actions/checkout@v4
 
-      - name: Pause between triggers
-        if: (github.event_name == 'pull_request' && ! github.event.pull_request.head.repo.fork)
-        shell: bash
-        run: sleep 60
-
       #### Developer note: you'll need to replace `uses: ./`
       #### with the path to ALKiln’s repository name and branch name. For example,
       #### for version 5, use the branch name `v5`: `uses: suffolkLITLab/ALKiln@v5`
       - uses: ./
         #### Developer note: You can probably leave this out
         env:
-          ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || 'not @a11y' }}"
+          ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || '(not @error) and (not @temp_error)' }}"
         with:
           #### Developer note: Required ALKiln inputs. You can read more at
           #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#githubNyou-inputs
@@ -77,6 +72,6 @@ jobs:
           # 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.
-          ALKILN_TAG_EXPRESSION: $ALKILN_TAG_EXPRESSION
+          ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
           #### Developer note: You can probably leave this out
-          # ALKILN_VERSION: url
+          ALKILN_VERSION: delete

package/CHANGELOG.md

@@ -47,7 +47,41 @@ Format:
 
 ### Changed
 
-- Use an absolute path for `runtime_config.json`
+- Update links in logs to new Suffolk docs pages
+
+### Fixed
+
+- Now delete interviews upon interview completion
+
+### Internal
+
+- Test deleting interviews upon interview completion
+- Added @temp_error to neutralize tests that are getting undesired errors right now, but which we anticipate being fixed soon. We want to ignore them for a short while. For example, an upstream change temporarily breaking some tests.
+
+## [5.12.0] - 2024-06-06
+
+### Added
+
+- New file with just failure results, including cucumber results when possible. It accumulates Scenario info as the tests run. Even if a test run stops early, there will still be some results.
+- New output from ALKiln action - `PATH_TO_ARTIFACTS`. The value is `""` or the path to the folder that contains the output of the test run, if the test run actually happened. Sometimes this folder doesn't get created. For example, if there was a typo in one or more `.feature` file. For example, `"alkiln-2024-06-03 at 02h29m44sUTC"`.
+- New outputs from the ALKiln action - `PATH_TO_REPORT_FILE`, `PATH_TO_UNEXPECTED_RESULTS_FILE`, and `PATH_TO_DEBUG_LOG_FILE`.  For example, `"alkiln-2024-06-03 at 02h29m44sUTC/report.txt"`. Authors can choose to use these as they wish. For example, they can put the contents of these files in issues they create from their workflow. Closes [#701](https://github.com/SuffolkLITLab/ALKiln/issues/701).
+- Added cucumber output to report.txt.
+- Added more explanation for the logs that appear when test runs error in a way that prevents debug_log.txt and such files from being created. We will watch for feedback about the error data itself. It may still be too confusing.
+
+### Changed
+
+- report.txt accumulates over time instead of being created all at once at the end. Even if a test run stops early, there will still be some results.
+
+### Fixed
+
+- Tag expression not being parsed correctly. Surrounded `ALKILN_TAG_EXPRESSION` with `"`.
+
+### Internal
+
+- Download ALKiln's artifacts back into the running job.
+- Removed our own workflow's pause between triggers.
+- Improved our use of ALKIN_TAG_EXPRESSION env var.
+- Exclude tests that we are aware fail. We will test those manually.
 
 ## [5.11.2] - 2024-05-17
 

package/README.md

@@ -12,7 +12,7 @@ https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-rea
 
 ## Use ALKiln
 
-Read about how to use this framework in [Assembly Line's documentation](https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/).
+Read about how to use [this framework in Assembly Line's documentation](https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/intro).
 
 If you have questions or need to report a bug, [start a new issue](https://github.com/SuffolkLITLab/ALKiln/issues/new).
 

package/action.yml

@@ -1,5 +1,5 @@
 name: "ALKiln: Automated docassemble tests"
-description: "Automatically test any docassemble interview in a any branch on your GitHub repository whenever you commit or push. See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing."
+description: "Automatically test any docassemble interview in a any branch on your GitHub repository whenever you commit or push. See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/setup/#types."
 
 inputs:
   SERVER_URL:
@@ -34,6 +34,20 @@ inputs:
     required: false
     default: "0.0.17"
 
+outputs:
+  PATH_TO_ARTIFACTS:
+    description: 'An empty string ("") or the path to the artifacts folder that contains the test run output. Remember to check for the existence of the folder before using it.'
+    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_ARTIFACTS }}
+  PATH_TO_REPORT_FILE:
+    description: 'An empty string ("") or the path to report.txt. Remember to check for the existence of the file before using it.'
+    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_REPORT_FILE }}
+  PATH_TO_UNEXPECTED_RESULTS_FILE:
+    description: 'An empty string ("") or the path to unexpected_results.txt. Remember to check for the existence of the file before using it.'
+    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_UNEXPECTED_RESULTS_FILE }}
+  PATH_TO_DEBUG_LOG_FILE:
+    description: 'An empty string ("") or the path to debug_log.txt. Remember to check for the existence of the file before using it.'
+    value: ${{ steps.alkiln_outputs.outputs.PATH_TO_DEBUG_LOG_FILE }}
+
 runs:
   using: "composite"
   steps:
@@ -102,6 +116,7 @@ runs:
       if: ${{ inputs.INSTALL_METHOD == 'playground' && failure() }}
       shell: bash
       run: |
+        # 😞 ALK0028 ERROR: Unable to create a Project
         echo -e "\n\n====\n😞 ALK0028 ERROR: Unable to create a Project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
 
     # Server installations - find folders and save session vars
@@ -121,7 +136,7 @@ runs:
       env:
         ALKILN_TAG_EXPRESSION: ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
       shell: bash
-      run: alkiln-run $ALKILN_TAG_EXPRESSION
+      run: alkiln-run "$ALKILN_TAG_EXPRESSION"
     
     # on playground, delete project
     - name: "💡 ALK0032 INFO: Delete the Project from the Playground"
@@ -137,6 +152,64 @@ runs:
         name: ${{ env.ARTIFACT_NAME }}
         path: ./alkiln-*
 
+    # Download artifacts folder internally to create action output
+    - name: "💡 ALK0183 INFO: Get uploaded artifacts folder"
+      if: ${{ always() }}
+      uses: actions/download-artifact@v4
+      with:
+        name: ${{ env.ARTIFACT_NAME }}
+
+    - name: "💡 ALK0184 INFO: Prepare ALKiln output file paths"
+      if: ${{ always() }}
+      id: alkiln_outputs
+      shell: bash
+      run: |
+        # 💡 ALK0184 INFO: Prepare ALKiln output file paths
+
+        FOLDER=$(ls -d */ | grep -E '^alkiln-*' || true)
+
+        echo "Test results artifacts folder is $FOLDER"
+
+        if [[ "$FOLDER" = "" ]]; then
+          echo "Artifacts folder is missing. The path is an empty string: '$FOLDER'"
+
+        else
+          REPORT_PATH="${FOLDER}report.txt"
+          UNEXPECTED_RESULTS_PATH="${FOLDER}unexpected_results.txt"
+          DEBUG_LOG_PATH="${FOLDER}debug_log.txt"
+
+          if [ -f "$REPORT_PATH" ]; then
+            echo "$REPORT_PATH exists"
+          else
+            echo "$REPORT_PATH is missing"
+            REPORT_PATH=""
+          fi
+
+          if [ -f "$UNEXPECTED_RESULTS_PATH" ]; then
+            echo "$UNEXPECTED_RESULTS_PATH exists"
+          else
+            echo "$UNEXPECTED_RESULTS_PATH is missing"
+            UNEXPECTED_RESULTS_PATH=""
+          fi
+
+          if [ -f "$DEBUG_LOG_PATH" ]; then
+            echo "$DEBUG_LOG_PATH exists"
+          else
+            echo "$DEBUG_LOG_PATH is missing"
+            DEBUG_LOG_PATH=""
+          fi
+
+        fi
+
+        echo "PATH_TO_ARTIFACTS=$FOLDER" >> "$GITHUB_OUTPUT"
+        echo "PATH_TO_REPORT_FILE=$REPORT_PATH" >> "$GITHUB_OUTPUT"
+        echo "PATH_TO_UNEXPECTED_RESULTS_FILE=$UNEXPECTED_RESULTS_PATH" >> "$GITHUB_OUTPUT"
+        echo "PATH_TO_DEBUG_LOG_FILE=$DEBUG_LOG_PATH" >> "$GITHUB_OUTPUT"
+
+    # Avoid creating output from text in files
+    # Cannot properly create outputs with multi-line text. Collapses onto one line.
+
     - shell: bash
+      if: ${{ always() }}
       run: |
         echo "💡 ALK0034 INFO: ALkiln finished running tests"

package/action_for_github_server/action.yml

@@ -109,12 +109,14 @@ runs:
         if: ${{ env.OUTPUT_DOCKER == 'false' }}
         shell: bash
         run: |
-          echo '===\n💡 ALK0007 INFO: ALKiln will now hide docker output to avoid possibly showing details about your config. If you want to get output to see more of what is going on, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "true". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
+          # 💡 ALK0007 INFO: ALKiln will now hide docker output
+          echo -e '===\n💡 ALK0007 INFO: ALKiln will now hide docker output to avoid possibly showing details about your config. If you want to get output to see more of what is going on, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "true". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
       - name: "💡 ALK0008 INFO: ALKiln will show docker output"
         if: ${{ env.OUTPUT_DOCKER == 'true' }}
         shell: bash
         run: |
-          echo '===\n💡 ALK0008 INFO: ALKiln will show docker output. ALKiln cannot control this output. If you want to prevent output, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "false". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
+          # 💡 ALK0008 INFO: ALKiln will show docker output
+          echo -e '===\n💡 ALK0008 INFO: ALKiln will show docker output. ALKiln cannot control this output. If you want to prevent output, use "with:" and set the input "SHOW_DOCKER_OUTPUT" to "false". This output will only be visible to those who can already see the action output, like people with admin or write permissions.\n==='
 
       # TODO: Reduce these to 1 block by putting ` > /dev/null 2>&1` into an env var
       # No docker output
@@ -156,6 +158,7 @@ runs:
         if: ${{ env.OUTPUT_DOCKER == 'false' }}
         shell: bash
         run: |
+          # 💡 ALK0011 INFO: The following messages are not docker output
           echo "💡 ALK0011 INFO: The following messages are not docker output, just ALKiln waiting for the server to start"
 
       - name: "💡 ALK0012 INFO: Waiting for server to start"
@@ -245,4 +248,3 @@ runs:
         if: ${{ failure() }}
         run: |
           echo "🤕 ALK0022 ERROR: Something went wrong. See above for more details."
-

package/docs/story_tables.md

@@ -4,7 +4,7 @@ The Story Table is a very flexible tool. It lets the author answer interview (fo
 
 When the robot arrives on each interview page, it finds all the fields on the page and loops through the whole Story Table trying to match rows with fields.
 
-Here's some [documentation on the use of Story Table rows](https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#story-tables).
+Here's some [documentation on the use of Story Table rows](https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing#story-table).
 
 ## Tracking use of rows
 

package/lib/docassemble/docassemble_api_REST.js

@@ -31,7 +31,7 @@ da.get_dev_id = async function ( timeout ) {
 };  // Ends da.get_dev_id()
 
 
-// node -e 'require("./lib/docassemble/docassemble_api_REST.js").delete_project( "create1" )'
+// node -e 'require("./lib/docassemble/docassemble_api_REST.js").delete_project()'
 da.delete_project = async function ( timeout ) {
   /* Delete a project on the user's da server. */
   let options = {
@@ -53,6 +53,51 @@ da.delete_project = async function ( timeout ) {
 };  // Ends da.delete_project()
 
 
+// node -e 'require("./lib/docassemble/docassemble_api_REST.js").delete_interview(...)'
+da.delete_interview = async function ( timeout, { uid = null }) {
+  /* Delete an interview with the given session id. */
+  let options = {
+    method: 'DELETE',
+    headers: { 'X-API-Key': session_vars.get_dev_api_key() },
+    // Can't use `api/session` that uses the API key to identify the user's
+    // interview sessions. The test may have signed in with an account
+    // that's different than the ALKiln dev account that sends this request.
+    url: `${ session_vars.get_da_server_url() }/api/interviews`,
+    params: { session: uid },
+    timeout: timeout,
+  };
+
+  try {
+    return await axios.request( options );
+  } catch (error) {
+    let response = error.response || {data: null}
+    throw {...error.toJSON(), data: response.data};
+  }
+};  // Ends da.delete_interview()
+
+// node -e 'require("./lib/docassemble/docassemble_api_REST.js").get_interview(...)'
+da.get_interview = async function ( timeout, { uid = null }) {
+  /* Get a specific interview. */
+  let options = {
+    method: 'GET',
+    headers: { 'X-API-Key': session_vars.get_dev_api_key() },
+    // Can't use `/api/user/interviews` that uses the API key to identify the user's
+    // interview sessions. The test may have signed in with an account
+    // that's different than the ALKiln dev account that sends this request.
+    url: `${ session_vars.get_da_server_url() }/api/interviews`,
+    params: { session: uid },
+    timeout: timeout,
+  };
+
+  try {
+    return await axios.request( options );
+  } catch ( error ) {
+    let response = error.response || { data: null }
+    throw { ...error.toJSON(), data: response.data };
+  }
+};  // Ends da.get_interview()
+
+
 // node -e 'require("./lib/docassemble/docassemble_api_REST.js").__delete_projects_starting_with( "testingdocassembleALAutomatedTestingTestsmain", 1, 1 )'
 da.__delete_projects_starting_with = async function ( base_name, starting_num=1, ending_num ) {
   /** FOR DEVELOPMENT ONLY. Deletes a set of Projects that start with a shared

package/lib/docassemble/docassemble_api_interface.js

@@ -15,6 +15,9 @@ const time = require('../utils/time');
 // to specific functions, which can run in a very small
 // window.
 
+// TODO: Move get_dev_id() and such into here instead of in
+// docassemble_REST - args should be the same vals as the request expects
+
 /** Notes:
 * - Checking for a busy server is vulnerable to race conditions, but
 *    there's nothing we can do about that.
@@ -180,7 +183,7 @@ da_i.delete_project = async function ( delete_options ) {
   *   for a timeout? */
 
   // Defaults
-  let { timeout } = delete_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
+  let { timeout } = delete_options || { timeout: DEFAULT_MAX_REQUEST_MS };
 
   let project_name = session_vars.get_project_name()
   log.info({ type: `da api`, code: `ALK0170`, pre: `Trying to delete Project ${ project_name }` });
@@ -196,3 +199,88 @@ da_i.delete_project = async function ( delete_options ) {
   }
 
 };  // Ends da_i.delete_project()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").quietly_try_to_delete_interviews(...)'
+da_i.quietly_try_to_delete_interviews = async function ({ interviews = {}, options = {} }) {
+  /** Delete a user's interview. Do we need to watch for a timeout? */
+
+  // Defaults
+  let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
+
+  for ( let id in interviews ) {
+    let interview_vars = interviews[ id ];
+    if ( interview_vars && interview_vars.uid ) {
+      try {
+        log.debug({ type: `da api info`, code: `ALK0188`, pre: `Trying to delete the interview with the id ${ interview_vars.uid }.` });
+
+        // Actual work:
+        let response = await _da_REST.delete_interview( timeout, interview_vars );
+        log.debug({ type: `da api info`, code: `ALK0189`,
+          pre: `No error when trying to delete interview ${ interview_vars.uid } at ${ interview_vars.i }.`
+        });
+
+      } catch ( error ) {
+        error.interview_vars = interview_vars;
+        let msg = `Error when deleting the interview. See https://docassemble.org/docs/api.html#session_delete.`
+        log.debug({ type: `da api info`, code: `ALK0190`, pre: msg, data: error });
+      }
+    } else {
+      log.debug({ type: `da api info`, code: `ALK0191`, pre: `There is no interview to delete.` });
+    }
+  }
+
+};  // Ends da_i.quietly_try_to_delete_interviews()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").get_interviews(...)'
+da_i.get_interviews = async function ({ interviews = {}, options = {} }) {
+  /** Return an object of interviews that exist on the server
+   *    that match the given interviews. Keys are the session ids. */
+  // Defaults
+  let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
+
+  let fetched_interviews = {};
+  if ( interviews ) {
+    for ( let id in interviews ) {
+      let interview_vars = interviews[ id ];
+      let fetched = await da_i.get_interview({ interview_vars });
+      if ( fetched && fetched.session ) {
+        fetched_interviews[ fetched.session ] = fetched;
+      }
+    }
+  }  // ends if interviews
+
+  return fetched_interviews;
+};  // Ends da_i.get_interviews()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").get_interview(...)'
+da_i.get_interview = async function ({ interview_vars, options = {} }) {
+  /** Try to get an interview from the server that matches the given interview data. */
+
+  // Defaults
+  let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
+
+  if ( interview_vars && interview_vars.uid ) {
+    try {
+      log.debug({ type: `da api info`, code: `ALK0192`, pre: `Trying to get the interview with the id ${ interview_vars.uid }.` });
+
+      // Actual work:
+      let response = await _da_REST.get_interview( timeout, interview_vars );
+      if ( response && response.data && response.data.items && response.data.items[0] && response.data.items[0].session ) {
+        log.debug({ type: `da api info`, code: `ALK0193`, pre: `Status ${ response.status }. Got ${ response.data.items[0].session }.`});
+        return response.data.items[0];
+      } else {
+        log.debug({ type: `da api info`, code: `ALK0194`, pre: `Status ${ response.status }. Cannot find ${ interview_vars.uid }`});
+      }
+
+    } catch ( error ) {
+      error.interview_vars = interview_vars;
+      let msg = `${ error.status } "${ error.statusText }" Ran into an error when getting the interview ${ interview_vars.uid }. See https://docassemble.org/docs/api.html#interviews.`
+      log.debug({ type: `da api info`, code: `ALK0195`, pre: msg, data: error });
+    }
+  } else {
+    log.debug({ type: `da api info`, code: `ALK0196`, pre: `There is no interview to get.` });
+  }
+
+  return null;
+
+};  // Ends da_i.get_interview()

package/lib/run_cucumber.js

@@ -3,9 +3,12 @@
 const fs = require('fs');
 const cucumber_api = require('@cucumber/cucumber/api');
 
-const log = require('./utils/log');
+const log = require('./utils/log');  // These always log in the console
 const session_vars = require('./utils/session_vars');
 
+const SUMMARY_FILENAME = `cucumber-report.txt`;
+
+
 function build_config( command_args ) {
   // Turn all the paths to the sources folders into paths to the feature files
   let sources_paths = session_vars.get_sources_paths();
@@ -17,14 +20,17 @@ function build_config( command_args ) {
   const config = {
     publishQuiet: true,
     require: `./lib/index.js`,
-    format: [`progress`, `summary:cucumber-report.txt`],
+    format: [`progress`, `summary:${ SUMMARY_FILENAME }`],
     paths: feature_paths,
     retry: 1,
   }
 
   // Normalize tag expressions, if there are any
-  let tags = command_args[`_`];
-  if (tags.length > 0) {
+  // Joining and splitting handles both tags surrounded with `""` or those without `""`
+  let tags = command_args[`_`].join(` `).split(` `);
+  // If there was no tag expression, `tags` is ['']. Remove that item.
+  tags = tags.filter(function(entry) { return entry !== ""; })
+  if ( tags.length > 0 ) {
     let joined_tags = '';
     // Cucumber expects tags in boolean expressions, like (@a0 or @a1) and @random.
     // If we get a list of only tags, then "or" them all together
@@ -105,19 +111,22 @@ function build_config( command_args ) {
 
   const { success } = await cucumber_api.runCucumber({...runConfiguration, support});
   if ( success ) {
-    log.info({ type: `run`, code: `ALK0054`, pre: `Cucumber executed correctly` });
+    log.success({ type: `run`, code: `ALK0054`, pre: `Tests succeeded!` });
   } else {
-    log.error({ type: `run`, code: `ALK0055`, pre: `Cucumber ran into an error` });
+    log.error({ type: `run`, code: `ALK0055`, pre: `The test run ran into something unexpected. Look above for more details.` });
   }
-  const exitCode = success ? 0 : 1;
+  // Custom exit code. May overlap with other systems.
+  // Best info I've found via stack overflow: https://tldp.org/LDP/abs/html/exitcodes.html
+  const exitCode = success ? 0 : 50;
   process.exitCode = exitCode;
 
   // This is hardcoded information from `provide_config` above.
   // This code isn't used for anything other than detecting and removing color codes.
-  let summary_file_name = 'cucumber-report.txt';
+  let summary_file_name = SUMMARY_FILENAME;
   fs.readFile(summary_file_name, 'utf8', (err, text) => {
     if (err) {
-      log.error({ type: `run`, code: `ALK0056`, pre: `cucumber report`, data: err });
+      // Something else will probably show an error that's more relevant
+      log.info({ type: `run`, code: `ALK0056`, pre: `Failed to read cucumber report`, data: err });
       return;
     }
 
@@ -127,6 +136,18 @@ function build_config( command_args ) {
 
     // Put it in the correct file in the correct folder
     let artifacts_path = session_vars.get_artifacts_path_name();
-    fs.appendFileSync( `${ artifacts_path }/${ log.debug_log_file }`, `\n\n${text}`);
+    try {
+      fs.appendFileSync( `${ artifacts_path }/${ log.debug_log_file }`, `\n\n${text}`);
+    } catch ( error ) {
+      log.info({ type: `run`, code: `ALK0182`, pre: `Something probably went wrong earlier. Look above for more details, but here is more information just in case: ALKiln was unable to write to ${ artifacts_path }/${ log.debug_log_file }.`, data: error });
+    }
+    try {
+      // Add to a unexpected results file when tests themselves fail
+      if ( exitCode === 50 ) {
+        fs.appendFileSync( `${ artifacts_path }/${ log.unexpected_filename }`, `\n\n${ text }` );
+      }
+    } catch ( error ) {
+      log.info({ type: `run`, code: `ALK0181`, pre: `Something probably went wrong earlier. Look above for more details, but here is more information just in case: ALKiln was unable to write to ${ artifacts_path }/${ log.unexpected_filename }.`, data: error });
+    }
   });
 })();

package/lib/scope.js

@@ -627,7 +627,7 @@ module.exports = {
       interview_url = `${ base_url }${ file_name }`;
     }
 
-    reports.addToReport(scope,{
+    reports.addToReport(scope, {
       code: `ALK0113`,
       type: `row info`,
       value: `Trying to load the interview at "${ interview_url }"`
@@ -638,7 +638,17 @@ module.exports = {
     // TODO: implement and use scope.handle_possible_timeout()
     try {
 
-      await scope.page.goto(interview_url, { waitUntil: 'domcontentloaded', timeout: scope.timeout })
+      await scope.page.goto(interview_url, { waitUntil: 'domcontentloaded', timeout: scope.timeout });
+      // Get interview session values, if possible, so we can delete the session later
+      let interview_vars = await scope.page.evaluate(async function() {
+        try {
+          // won't exist on non-da interview pages
+          return await get_interview_variables();
+        } catch (error) {
+          return null;
+        }
+      });
+      scope.set_interview_session_data( scope, { vars: interview_vars });
 
     } catch ( error ) {
 
@@ -682,6 +692,36 @@ module.exports = {
     return scope.page;
   },  // Ends scope.load()
 
+  set_interview_session_data: function ( scope, { vars = null }) {
+    /** Sets this interview's session data for this scenario if it doesn't
+     *    already exist.
+     *
+     * @returns final_vars { object | null }
+     * @returns final_vars.i { str } File path of interview
+     * @returns final_vars.uid { str } UID of interview
+     * */
+    if ( vars && vars.i ) {
+      let scenario = scope.scenarios.get( scope.scenario_id );
+      if ( !scenario.interviews ) { scenario.interviews = {}; }
+      if ( !scenario.interviews[ vars.uid ] ) {
+        scenario.interviews[ vars.uid ] = vars;
+        log.debug({
+          code: `ALK0185`, type: `info`,
+          pre: `Saved new interview data. File path: ${ vars.i }. Session id: ${ vars.uid }.`
+        });
+      } else {
+        log.debug({
+          code: `ALK0186`, type: `info`,
+          pre: `Interview data already existed. File path: ${ vars.i }. Session id: ${ vars.uid }.`
+        });
+      }
+      return vars;
+    } else {
+      log.debug({ code: `ALK0187`, type: `info`, pre: `Found no interview data.` });
+      return null;
+    }
+  },  // Ends scope.set_interview_session_data()
+
   getLoadData: async function ( scope ) {
     /* Return elements that could load on the page, like #daMainQuestion
     * and #da-retry. If there's a system error on the page, return its main text.
@@ -771,7 +811,7 @@ module.exports = {
             if ( row_raw.length > 3 ) { more_or_less = `less`; }
             let bad_table_msg = `Your Story Table should have ${ more_or_less } than`
               + ` ${ row_raw.length } columns. Take another look at Story Table documentation at`
-              + ` https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#story-tables.`
+              + ` https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing#story-table.`
             reports.addToReport( scope, { type: `error`, code: `ALK0120`, value: bad_table_msg})
             throw Error(bad_table_msg);
           }
@@ -798,7 +838,7 @@ module.exports = {
           let not_in_env_msg = `ALKiln could not find the GitHub secret "${ row.flags.secret_name }".`
             + ` Check for a typo and check your workflow file.`
             + ` Read more about using GitHub secrets in your workflow file at`
-            + ` https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#github-secrets.`
+            + ` https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing#secrets.`
           reports.addToReport( scope, { type: `error`, code: `ALK0121`, value: not_in_env_msg });
           throw ReferenceError(not_in_env_msg);
         }
@@ -1317,6 +1357,7 @@ module.exports = {
     * setting fields, and an object for a DOM field, returns list of the
     * rows that match the DOM field. That list of story table rows may be empty.
     *
+    * Using a `trigger` column is deprecated, but still used in many tests in the wild.
     * For notes on trigger var, see https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#trigger
     * 
     * @param var_data {arr} - fields and the values they can be set to
@@ -1411,9 +1452,13 @@ module.exports = {
 
       // field/page trigger name is needed but is missing.
       if ( !page_trigger_name ) {
-        let page_trigger_warning = `A field on this page uses an index `
-          + `variable or a generic object, but the page is missing `
-          + `the ALKiln "trigger" variable's name. See `
+        let page_trigger_warning = `You are using a 3-column Story Table. If possible, you should `
+          + `think about switching to the newer, easier, 2-column Story Table. That will probably `
+          + `get rid of this warning. Read more at `
+          + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/trouble#deprecated-story-tables. `
+          + `If you still want to use this 3-column format, here is more info about the warning: `
+          + `A field on this page uses an index variable or a generic object in a 3-column `
+          + `Story Table, but the page is missing the ALKiln "trigger" variable's name. See `
           + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#a-missing-trigger-variable.`;
         reports.addToReport(scope, { type: `warning`, code: `ALK0127`, value: page_trigger_warning });
       }
@@ -1430,7 +1475,7 @@ module.exports = {
 
           // First, make the row data more readable to humans.
           let row_as_story_table = reports.convertToOriginalStoryTableRow( scope, { row_data: row_that_matches_this_field });
-          let row_trigger_warning = `This Story Table row needs a value in the "trigger" `
+          let row_trigger_warning = `This 3-column Story Table row needs a value in the "trigger" `
             + `column, but it is empty. The test might get unexpected results. See `
             + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#trigger.`
             + `\nThe rows:\n${ row_as_story_table }`;
@@ -1467,7 +1512,7 @@ module.exports = {
 
         let all_trigger_names_conflict_msg = `${ rows_that_match_field_names.length } `
           + `Story Table row(s) matched a field name, but didn't match a trigger `
-          + `variable. The Story Table might be missng a row or a trigger variable. `
+          + `variable. This 3-column Story Table might be missing a row or a trigger variable. `
           + `The test will have to ignore this field. See `
           + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#trigger.`
           + `\nThe row(s) data:\n${ conflicts_as_story_table_rows.join( `\n` )}`
@@ -3228,8 +3273,7 @@ module.exports = {
     * 
     * @param expected {array} Arr of strs that should appear in the report.
     */
-    let current_report_obj = scope.report.get( scope.scenario_id );
-    let scenario = [ scope.scenario_id, current_report_obj ];  // Mimic how loop works with `Map`
+    let scenario = scope.report.get( scope.scenario_id );
     let report = reports.getPrintableScenario( scenario );
     let all_are_included = true;
     for ( let one_expectation of expected ) {
@@ -3248,8 +3292,7 @@ module.exports = {
     * 
     * @param not_expected {array} Arr of strs that should not appear in the report.
     */
-    let current_report_obj = scope.report.get( scope.scenario_id );
-    let scenario = [ scope.scenario_id, current_report_obj ];  // Mimic how loop works with `Map`
+    let scenario = scope.report.get( scope.scenario_id );
     let report = reports.getPrintableScenario( scenario );
     let none_included = true;
     for ( let one_expectation of not_expected ) {
@@ -3262,4 +3305,6 @@ module.exports = {
     return none_included;
   },
 
+  // Test that all interviews have been deleted
+
 };

package/lib/steps.js

@@ -22,6 +22,7 @@ const log = require('./utils/log');
 const session_vars = require('./utils/session_vars');
 const files = require('./utils/files' );
 const reports = require(`./utils/reports`);
+const da_api = require('./docassemble/docassemble_api_interface');
 
 /* Of Note:
 - We're using `*=` for selectors because sometimes da text has funny characters in it that are hard to anticipate
@@ -83,6 +84,9 @@ let click_with = {
 
 BeforeAll(async () => {
   scope.showif_timeout = 600;
+  // TODO: Do these really need to be maps? As sets, they may make the output
+  // more predictable to the user, but they add complexity.
+  scope.scenarios = new Map();
   scope.report = new Map();
 
   // Start tracking whether server is up and running
@@ -93,7 +97,7 @@ BeforeAll(async () => {
 
   // TODO: figure out how to test file and folder creation stuff,
   // especially when setup is excluded from the flow.
-  
+
   // Make the folder to store all the files for this run of the tests
   scope.paths.artifacts = files.make_artifacts_folder();
   // Save its name in a file. `session_vars` can get it back later.
@@ -101,8 +105,11 @@ BeforeAll(async () => {
   session_vars.save_artifacts_path_name( scope.paths.artifacts );
 
   scope.paths.report = `${ scope.paths.artifacts }/report.txt`;
+  scope.paths.failures = `${ scope.paths.artifacts }/${ log.unexpected_filename }`;
   scope.paths.debug_log = `${ scope.paths.artifacts }/${ log.debug_log_file }`;
   fs.writeFileSync( scope.paths.debug_log, "" );
+
+  reports.create( scope );
 });
 
 Before(async (scenario) => {
@@ -124,13 +131,15 @@ Before(async (scenario) => {
     }
   }
   // Clean up all previously existing pages
-  for (const page of await scope.browser.pages()) { 
+  for (const page of await scope.browser.pages()) {
     await page.close();
   }
   // Make a new page
   scope.page = await scope.browser.newPage()
 
   scope.scenario_id = uuidv4();
+  scope.scenarios.set( scope.scenario_id, {} );
+  scope.scenarios.get( scope.scenario_id ).interviews = {};
   scope.expected_status = null;
   scope.expected_in_report = null;
   scope.expected_not_in_report = null;
@@ -176,7 +185,7 @@ Given(/I start the interview at "([^"]+)"/, {timeout: -1}, async (file_name) =>
 
   // Load the right interview page
   await scope.load( scope, file_name );
-  
+
   // The page timeout is set in here too in case someone set a custom timeout
   // just before a page was loaded for the Scenario. Move this to just after page creation?
   // The function itself won't really timeout here, so we don't need to wrap it in
@@ -310,7 +319,7 @@ Given(/the max(?:imum)? sec(?:ond)?s for each step (?:in this scenario )?is (\d+
   /* At any time, set a custom timeout for the scenario. */
   // TODO: Add 1 second to this to allow other steps to not fail, like "I wait n seconds"
   scope.timeout = parseInt( seconds ) * 1000;
-  
+
   // Cucumber timeouts are made custom for each step that needs it
 
   // If there is no page yet, we've ensured custom timeout will still be set
@@ -650,7 +659,7 @@ Then('I should see the link to {string}', async ( url ) => {  // √
   let msg = `Cannot find a link to "${ url }".`;
   if ( !link ) { reports.addToReport(scope, { type: `error`, code: `ALK0080`, value: msg }); }
   expect(link, msg ).to.exist;
-  
+
   await scope.afterStep(scope);
 });
 
@@ -659,7 +668,7 @@ Then(/the "([^"]+)" link leads to "([^"]+)"/, async (linkText, expected_url) =>
   let [link] = await scope.page.$x(`//a[contains(text(), "${linkText}")]`);
   // TODO: Possibly add a check here for the link text, though note this
   // Step is not currently supported.
-  
+
   let prop_obj = await link.getProperty('href');
   let actual_url = await prop_obj.jsonValue();
 
@@ -753,7 +762,7 @@ Then(/I expect the baseline PDF "([^"]+)" and the new PDF "([^"]+)" to be the sa
   * Variations:
   * Then I expect the baseline PDF "simple-doc-Baseline.pdf" and the new PDF "simple-doc.pdf" to be the same
   */
-  
+
   return await wrapPromiseWithTimeout(
     scope.steps.compare_pdfs(scope, {existing_pdf_path, new_pdf_path}),
     scope.timeout
@@ -877,7 +886,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
 
       // Set up timeout to stop infinite loops
       let page_timeout_id = setTimeout(async function() {
-        
+
         // Make sure to only throw once
         if ( has_thrown ) { return; }
         else { has_thrown = true; }
@@ -1175,6 +1184,57 @@ Given(/the final Scenario status should be "([^"]+)"/i, async ( expected_status
   scope.expected_status = expected_status.toUpperCase();
 });
 
+Then(/of two interviews, I delete one __internal__/i, async () => {
+  /** Test that an interview does get successfully deleted. This tests whether
+   *    the API code is working correctly.
+   */
+  // Make sure we have two interviews in `scope.scenario.interviews` (two session ids)
+  let interviews = scope.scenarios.get( scope.scenario_id ).interviews;
+  let internal_keys = Object.keys( interviews );
+  expect(
+    internal_keys.length,
+    `Of 2 interview sessions, ALKiln only saved ${ internal_keys.length }`
+  ).to.equal( 2 );
+
+  // Check that both interviews exist on the server. 1 √ 2 √
+  let existing_interviews = await da_api.get_interviews({ interviews });
+  let existing_keys = Object.keys( existing_interviews );
+  expect(
+    existing_keys.length,
+    `2 interviews should be on the server. Instead: ${ existing_keys.join(', ') }`
+  ).to.equal( 2 );
+
+  // Delete one. 1 x 2 √
+  let to_delete = interviews[ internal_keys[ 0 ]];
+  await da_api.quietly_try_to_delete_interviews({
+    interviews: { [internal_keys[ 0 ]]: to_delete }
+  });
+
+  // Check that only one session exists on the server. This tests that
+  // 1. An interview has been deleted and
+  // 2. We are fetching interviews correctly because we are getting one
+  // back (e.g. not passing null into the api function)
+  // 1 x 2 √
+  let after_deletion = await da_api.get_interviews({ interviews });
+  let keys_after_deletion = Object.keys( after_deletion );
+  expect(
+    keys_after_deletion.length,
+    `1 interviews should be on the server: ${ keys_after_deletion.join(', ') }`
+  ).to.equal( 1 )
+  // In After(), the other session should get deleted
+});
+
+// Then(/there are no interview_vars saved __internal__/i, async () => {
+//   /** Test that no interviews were saved internally */
+//   // Check the number of interviews
+//   let interviews = scope.scenarios.get( scope.scenario_id ).interviews;
+//   let keys = Object.keys( interviews );
+//   expect(
+//     keys.length,
+//     `0 interviews should exist, but at least one does: ${ keys.join(', ') }`
+//   ).to.equal( 0 );
+// });
+
 
 //#####################################
 //#####################################
@@ -1202,17 +1262,17 @@ After(async function(scenario) {
   }
 
   if ( scope.failed_pdf_compares.length > 0) {
-    let msg = scope.failed_pdf_compares.reduce((str, new_msg) => `${ str }\n---\n${ new_msg }`)
+    let msg = scope.failed_pdf_compares.reduce((str, new_msg) => `${ str }\n―――\n${ new_msg }`)
     changeable_test_status = `FAILED`;
     reports.addToReport(scope, {
       type: `error`,
       code: `ALK0093`,
-      value: `PDF comparison failed ${ scope.failed_pdf_compares.length } time(s)\n---\n${ msg }\n---\n`
+      value: `PDF comparison failed ${ scope.failed_pdf_compares.length } time(s)\n―――\n${ msg }\n―――\n`
     });
   }
 
   // Record status before internal report tests can interfere with values
-  reports.setReportScenarioStatus( scope, { status: changeable_test_status });
+  reports.saveFinalScenarioData( scope, { status: changeable_test_status });
 
   if (changeable_test_status !== `PASSED`) {
     log.debug({
@@ -1256,11 +1316,11 @@ After(async function(scenario) {
   }  // ends if not passed
 
   // Add report text to Scenario folder after everything has been added to the report
-  let current_report_obj = scope.report.get( scope.scenario_id );
-  let scenario_report_obj = [ scope.scenario_id, current_report_obj ];  // Mimic how loop works with `Map`
+  let scenario_report_obj = scope.report.get( scope.scenario_id );
   let report = reports.getPrintableScenario( scenario_report_obj );
   // Save the report as in the Scenario folder
   fs.writeFileSync( scope.paths.scenario_report, report );
+  // TODO: Save any cucumber failure message for the Scenario here (instead of waiting till run_cucumber.js)
 
   // ---------------- Check internal test results ----------------
 
@@ -1273,7 +1333,7 @@ After(async function(scenario) {
     // Reset report values no matter what so they don't mess up future scenarios
     scope.expected_in_report = null;
   }
-  
+
   if (scope.expected_not_in_report && scope.expected_not_in_report.length > 0) {
     let all_prohibited_strings_were_absent = await scope.reportDoesNotInclude(
       scope,
@@ -1311,8 +1371,8 @@ After(async function(scenario) {
       // it as failed too.
       expected_status_was_met = false;
       // Keep it general. Users may see this message, e.g. for a11y tests.
-      let msg = `Test failed. Expected status: ${scope.expected_status}. `
-          + `ALKiln's assessed status: ${ changeable_test_status }. `
+      let msg = `Test ${ changeable_test_status }. `
+          + `Expected status: ${scope.expected_status}. `
           + `See the report for details.`;
       let code = `ALK0099`;
       log.debug({ type: `error`, code: code, pre: msg, })
@@ -1354,7 +1414,7 @@ After(async function(scenario) {
     // Catch a possible reload error.
     try {
       // puppeteer will ensure proper timeout.
-      await scope.page.goto(`${ session_vars.get_da_server_url() }/user/sign-out`, {waitUntil: `domcontentloaded`});  
+      await scope.page.goto(`${ session_vars.get_da_server_url() }/user/sign-out`, {waitUntil: `domcontentloaded`});
 
     } catch ( error ) {
       signout_succeeded = false;
@@ -1369,7 +1429,7 @@ After(async function(scenario) {
             code: code,
             message: non_reload_report_msg,
           }, error });
-        } catch {
+        } catch ( error ) {
           signout_error_msg = `🤕 ${ code } ERROR: ${ non_reload_report_msg }`;
         }
       } else {
@@ -1384,10 +1444,34 @@ After(async function(scenario) {
 
   }  // ends if scope.page
 
+  // Now that we're no longer on the interview page, one way or
+  // another, try to delete the interviews created during the test
+  try {
+    let interviews = scope.scenarios.get( scope.scenario_id ).interviews;
+    await da_api.quietly_try_to_delete_interviews({ interviews });
+    let existing_interviews = await da_api.get_interviews({ interviews });
+    let existing_keys = Object.keys( existing_interviews );
+    // Deleting interviews is nice, but not non-critical. Don't bother the
+    // user with it. Don't want to cover up a more meaningful failure (like
+    // going to the wrong file). If it becomes a problem we can track it down later.
+    if ( existing_keys.length > 0 ) {
+      log.debug({ type: `internal warning`, code: `ALK0197`,
+        pre: `${ existing_keys.length } interviews were not deleted: ${ existing_keys.join( ', ' ) }`
+      });
+    }
+  } catch ( error ) {
+    // Deleting interviews is nice, but not non-critical. Don't bother the
+    // user with it. Don't want to cover up a more meaningful failure (like
+    // going to the wrong file). If it becomes a problem we can track it down later.
+    // Consider add "internal" to docs: "If you see this, make an issue in ALKiln with your debug/verbose log"
+    log.debug({ type: `internal warning`, code: `ALK0198`, pre: `Error while cleaning up interviews.`, data: error });
+  }
+
+  // Handle all the accumulated errors
   let errors = []
   if ( !expected_status_was_met ) { errors.push( expected_status_err_msg ); }
   if ( !signout_succeeded ) { errors.push( signout_error_msg ); }
-  if ( !expected_status_was_met || !signout_succeeded ) {
+  if ( errors.length > 0 ) {
     throw new Error( `${errors.join( errors, '\n')}` );
   }
 
@@ -1405,17 +1489,14 @@ After(async function(scenario) {
 AfterAll(async function() {
   // Stop collecting server response statuses
   scope.stop_tracking_server_status = true;
-  
+
   let report = reports.getPrintableReport( scope );
   // Log the report. Can't get this.attach() or this.log() to work in `After()` or here.
   // May need newest version of cucumberjs
   console.log( `\n\n${ report }` );
 
-  // Save/download the report as an artifact
-  fs.writeFileSync( scope.paths.report, report );
-
   // If there is a browser open, then close it
   if (scope.browser) {
     await scope.browser.close();
   }
-});
+});

package/lib/utils/log.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const session_vars = require( './session_vars' );
 
 // ? 🌈 💡 🔎 🤕 🐞
+// Alternatives: 🩹 ❤️‍🩹 🚑
 // TODO: return full message so it can be passed to manually
 // thrown errors if needed.
 
@@ -91,4 +92,5 @@ log.add_to_debug_log = function(value) {
   fs.appendFileSync(log.debug_log_file, value);
 };
 
-log.debug_log_file = 'debug_log.txt'
+log.debug_log_file = `debug_log.txt`;
+log.unexpected_filename = `unexpected_results.txt`;

package/lib/utils/reports.js

@@ -7,6 +7,13 @@ const files = require(`./files` );
 
 module.exports = reports = {};
 
+reports.title = `Assembly Line Kiln Automated Testing Report - ${ (new Date()).toUTCString() }\n`;
+reports.failures = [ `\n\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n🤕 Failed scenarios\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n` ];
+reports.successes = [ `\n\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n🌈 Passed scenarios\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n` ];
+// reports.warnings = [ `\n\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n🔎 Scenarios to check\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n` ];
+// reports.undefineds = [ `\n\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n[langs icon] Scenarios with typos\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n` ];
+reports.others = [ `\n\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n🔎 Other scenarios that did not pass\n≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n` ];
+
 reports.addReportHeading = function (scope, { scenario }) {
   /** Return printable heading based on Scenario name and tags.
   *    Allow characters from other languages.
@@ -19,14 +26,14 @@ reports.addReportHeading = function (scope, { scenario }) {
     tag_names.push( tag.name );
   }
 
-  let heading = `\n---------------\n`
+  let heading = `\n―――――――――――――――\n`
     + `Scenario: ${ scenario.pickle.name }`;
 
   if ( tag_names.length > 0 ) {
     heading += `\nTags: ${ tag_names.join(' ') }`;
   }
 
-  heading += `\n---------------`;
+  heading += `\n―――――――――――――――`;
 
   reports.addToReport( scope, {
     code: `ALK0176`,
@@ -71,21 +78,30 @@ reports.addToReport = function( scope, { type, code, value }) {
   }
 
   // Report stuff
-  let scenario = makeSureReportPartsExist( scope );
+  let scenario = reports.makeSureScenarioExists( scope );
   scenario.lines.push({ type, code, value });
 
   return scenario;
 };  // Ends reports.addToReport()
 
-let makeSureReportPartsExist = function( scope ) {
+reports.create = function( scope ) {
+  reports.makeSureReportExists( scope );
+}
+
+reports.makeSureReportExists = function( scope ) {
   /** If a part of the report needs to exist right now, but doesn't exist,
   * create it. */
   if ( !scope.report ) { scope.report = new Map(); }
+  return this;
+};  // Ends reports.makeSureReportExists()
+
+reports.makeSureScenarioExists = function ( scope ) {
+  reports.makeSureReportExists( scope );
   if ( !scope.scenario_id ) {
     scope.scenario_id = `_report_${ Date.now() }`;
   }
   if ( !scope.report.get( scope.scenario_id )) {
-    scope.report.set( scope.scenario_id, {} )
+    scope.report.set( scope.scenario_id, {} );
     scope.report.get( scope.scenario_id ).status = `in progress`;
   }
 
@@ -93,11 +109,36 @@ let makeSureReportPartsExist = function( scope ) {
   if ( !scenario.lines ) { scenario.lines = []; }
 
   return scenario;
-};  // Ends makeSureReportPartsExist()
+};  // Ends reports.makeSureScenarioExists()
+
+reports.saveFinalScenarioData = function( scope, { status=`in progress` }) {
+  this.setReportScenarioStatus( scope, { status });
+  let scenario = scope.report.get( scope.scenario_id );
+  let report = this.getPrintableScenario( scenario );
+  if ( scenario.status === `FAILED` ) { this.failures.push( report ); }
+  else if ( scenario.status === `PASSED` ) { this.successes.push( report ); }
+  // else if ( scenario.status === `WARNING` ) { passed_reports += report; this.warnings.push( report ); }
+  // else if ( scenario.status === `UNDEFINED` ) { passed_reports += report; this.undefineds.push( report ); }
+  else { this.others.push( report ); }
+
+  // Save to failures.txt (worry about optimization later)
+  if ( this.failures.length > 1 || this.others.length > 1 ) {
+    fs.writeFileSync(
+      scope.paths.failures,
+      this.title + this.getPrintableUnexpected( scope )
+    );
+  }
+  // Save to reports.txt (worry about optimization later)
+  fs.writeFileSync( scope.paths.report, this.getPrintableReport( scope ) );
+
+  return scenario;
+};  // Ends reports.saveFinalScenarioData()
+
 
 reports.setReportScenarioStatus = function( scope, { status=`PASSED` }) {
   /** Add final status of scenario to scenario report object - passed, failed, etc. */
   scope.report.get( scope.scenario_id ).status = status;
+  return scope.report.get( scope.scenario_id );
 };  // Ends reports.setReportScenarioStatus()
 
 reports.convertToOriginalStoryTableRow = function( scope, { row_data }) {
@@ -124,34 +165,38 @@ let trimJSON = function( str=`` ) {
 };  // Ends trimJSON()
 
 reports.getPrintableReport = function( scope ) {
-  /** Return a string generated from test report data. */
-  let report = `Assembly Line Kiln Automated Testing Report - ${ (new Date()).toUTCString() }\n`;
-
-  // First list failed scenarios, then non-passed scenarios, then passed scenarios
-  let failed_reports = ``;
-  let passed_reports = ``;
-  let other_reports = ``;
-  for ( let scenario of scope.report ) {
-
-    let report = reports.getPrintableScenario( scenario );
-    let [ scenario_id, data ] = scenario;
-    if ( data.status === `FAILED` ) { failed_reports += report; }
-    else if ( data.status === `PASSED` ) { passed_reports += report; }
-    else { other_reports += report; }
-  };  // ends for every scenario
-
-  if ( failed_reports !== `` ) { report += `\n\n===============================\n===============================\n🤕 Failed scenarios:\n${ failed_reports }`; }
-  if ( other_reports !== `` ) { report += `\n\n===============================\n===============================\n🔎 Scenarios that did not pass:\n${ other_reports }`; }
-  if ( passed_reports !== `` ) { report += `\n\n===============================\n===============================\n🌈 Passed scenarios:\n${ passed_reports }`; }
+  /** Return a string generated from test report data.
+  *
+  * First list failed scenarios, then non-passed scenarios, then passed scenarios. */
+  let report = this.getTitle( scope );
+
+  if ( this.failures.length > 1 ) { report += this.failures.join( `` ); }
+  if ( this.successes.length > 1 ) { report += this.successes.join( `` ); }
+  // if ( this.warnings.length > 1 ) {}
+  // if ( this.undefineds.length > 1 ) {}
+  if ( this.others.length > 1 ) { report += this.others.join( `` ); }
 
   return report;
 };  // Ends reports.getPrintableReport()
 
+reports.getTitle = function( scope ) { return this.title; }
+
+reports.getPrintableUnexpected = function( scope ) {
+  // Note about `> 1`: The first line of the report section always exists
+  let output = ``;
+  if ( this.failures.length > 1 ) {
+    output += this.failures.join(``);
+  }
+  if ( this.others.length > 1 ) {
+    output += this.others.join(``);
+  }
+  return output;
+};  // Ends reports.getPrintableUnexpected()
+
 reports.getPrintableScenario = function( scenario ) {
   /** Return a string generated from scenario list of report items. */
-  let [ scenario_id, data ] = scenario;
   let report = ``;
-  for ( let line of data.lines ) {
+  for ( let line of scenario.lines ) {
     let { type, code, value } = line;
     report += `${ getLineText({ type, code, value }) }\n`;
   }

package/lib/utils/session_vars.js

@@ -107,7 +107,7 @@ session_vars.get_languages = function () {
 };  // Ends session_vars.get_languages()
 
 
-const runtime_config_path = path.join(process.cwd(), `runtime_config.json`);
+const runtime_config_path = `runtime_config.json`;
 const project_name_key = `da_project_name`;
 session_vars.save_project_name = function ( project_name ) {
   /* Saves the name of the project to a json obj so deletion can use it later.

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.11.2-fix-root-dir-1",
+  "version": "5.12.0-delete1",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {
     "test": "npm run unit && npm run codes && npm run cucumber",
     "cucumber": "./lib/run_cucumber.js",
     "local": "npm run setup && npm run cucumber; npm run takedown",
+    "pass": "npm run cucumber 'not @error and not @temp_error'",
+    "fail": "npm run cucumber '@error'",
     "setup": "./lib/docassemble/setup.js",
     "takedown": "./lib/docassemble/takedown.js",
     "server_install": "./lib/docassemble/server_install.js",
@@ -30,7 +32,7 @@
   "bugs": {
     "url": "https://github.com/SuffolkLITLab/ALKiln/issues"
   },
-  "homepage": "https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/",
+  "homepage": "https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/intro",
   "dependencies": {
     "@axe-core/puppeteer": "4.7.3",
     "@cucumber/cucumber": "9.3.0",

package/setup.py

@@ -50,7 +50,7 @@ setup(name='docassemble.ALKilnTests',
       author='plocket',
       author_email='example@example.com',
       license='The MIT License (MIT)',
-      url='https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln',
+      url='https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/intro',
       packages=find_packages(),
       namespace_packages=['docassemble'],
       install_requires=['docassemble.ALToolbox>=0.8.2', 'docassemble.AssemblyLine>=2.24.0'],

package/tests/log_codes/check_codes.sh

@@ -106,7 +106,8 @@ ALK0026
 ALK0027
 ALK0028
 ALK0030
-ALK0049"
+ALK0049
+ALK0184"
 
 # Use a sorted list. `uniq` only detects consecutive duplicates
 duplicates=$(echo "$sorted" | uniq -d)