@suffolklitlab/alkiln 5.11.2 → 5.12.0-delete2

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

@@ -43,7 +43,45 @@ Format:
 - 
 -->
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Changed
+
+- Update links in logs to new Suffolk docs pages
+
+### Fixed
+
+- Now delete interviews upon interview completion for signed in users
+
+### Internal
+
+- Test deleting interviews upon interview completion for signed in users
+- 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, { session = null, api_key = null }) {
+  /* Delete an interview with the given session id. */
+  let options = {
+    method: 'DELETE',
+    headers: { 'X-API-Key': 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/user/interviews`,
+    params: { session },
+    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, { session = null, api_key = null }) {
+  /* Get a specific interview. */
+  let options = {
+    method: 'GET',
+    headers: { 'X-API-Key': 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/user/interviews`,
+    params: { session },
+    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,129 @@ 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 = {}, api_keys = [], options = {} }) {
+  /** Try to delete the given interviews. Fail silently. Example failure: the test
+   *    did not log in any users and the testing account's role prevents
+   *    access to other user's interviews. Do we need to watch for a timeout? */
+
+  // Defaults
+  let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
+
+  let responses = [];
+  for ( let id in interviews ) {
+    let interview = interviews[ id ];
+    if ( interview && interview.uid ) {
+      let sub_responses = await da_i.quietly_delete_one_interview( timeout, {
+        interview,
+        api_keys
+      });
+      responses.push( sub_responses );
+    } else {
+      log.debug({ type: `da api info`, code: `ALK0191`, pre: `There is no interview to delete.` });
+    }
+  }
+  return responses;
+
+};  // Ends da_i.quietly_try_to_delete_interviews()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").quietly_delete_one_interview(...)'
+da_i.quietly_delete_one_interview = async function ( timeout, { interview = {}, api_keys = [] }) {
+  /** Try to delete an interview using all available API keys. Fail silently.
+   *    Example failure: the test did not log in any users and the testing
+   *    account's role prevents access to other user's interviews. */
+  api_keys = normalize_api_keys( api_keys );
+  let responses = [];
+  for ( let api_key of api_keys ) {
+    try {
+      log.debug({ type: `da api info`, code: `ALK0188`,
+        pre: `Trying to delete the interview with the id ${ interview.uid } and an API key.`
+      });
+
+      // Actual work:
+      let response = await _da_REST.delete_interview( timeout, {
+        session: interview.uid,
+        api_key
+      });
+      responses.push( response );
+
+      log.debug({ type: `da api info`, code: `ALK0189`,
+        pre: `No error when trying to delete interview ${ interview.uid } at ${ interview.i }.`
+      });
+    } catch ( error ) {
+      error.interview = interview;
+      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 });
+    }
+  }  // ends for api keys
+  return responses;
+};  // Ends da_i.quietly_delete_one_interview()
+
+// node -e 'require("./lib/docassemble/docassemble_api_interface.js").get_interviews(...)'
+da_i.get_interviews = async function ({ interviews = {}, api_keys = [], options = {} }) {
+  /** Return an object of interviews that exist on the server
+   *    that match the given interviews. Keys are the session ids. */
+
+  api_keys = normalize_api_keys( api_keys );
+
+  let fetched_interviews = {};
+  if ( interviews ) {
+    for ( let id in interviews ) {
+      let interview = interviews[ id ];
+      let fetched = await da_i.get_interview({ interview, api_keys, options });
+      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 = {}, api_keys = [], options = {} }) {
+  /** Try to get an interview from the server that matches the given interview data. */
+
+  // Defaults
+  let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
+  api_keys = normalize_api_keys( api_keys );
+
+  if ( interview && interview.uid ) {
+    for ( let api_key of api_keys ) {
+      try {
+        log.debug({ type: `da api info`, code: `ALK0192`, pre: `Trying to get the interview with the id ${ interview.uid } and an API key.` });
+
+        // Actual work:
+        let response = await _da_REST.get_interview( timeout, {
+          session: interview.uid,
+          api_key
+        });
+
+        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.uid }`});
+        }
+      } catch ( error ) {
+        error.interview = interview;
+        let msg = `${ error.status || `No error.status.` } ${ error.statusText || error.data || `No error.statusText.` } Ran into an error when getting the interview ${ interview.uid }. See https://docassemble.org/docs/api.html#interviews.`
+        log.debug({ type: `da api info`, code: `ALK0195`, pre: msg, data: error });
+      }
+    }  // ends for api_keys
+  } else {
+    log.debug({ type: `da api info`, code: `ALK0196`, pre: `There is no interview to get.` });
+  }
+
+  return null;
+
+};  // Ends da_i.get_interview()
+
+let normalize_api_keys = function ( api_keys = [] ) {
+  /** Ensure the dev API key is in the api_keys list. */
+  let dev_key = session_vars.get_dev_api_key();
+  if ( !api_keys ) { api_keys = [ dev_key ]; }
+  if ( !api_keys.includes( dev_key ) ) { api_keys.unshift( dev_key ); }
+  return api_keys;
+};

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 });
+    }
   });
 })();