@suffolklitlab/alkiln 5.4.2 → 5.5.0

package/.github/workflows/github_server.yml

@@ -0,0 +1,68 @@
+name: GitHub server tests
+
+on:
+  push:
+  workflow_dispatch:
+    inputs:
+      tags:
+        required: False
+        description: 'Optional. Use a "tag expression" specify which tagged tests to run (https://cucumber.io/docs/cucumber/api/#tag-expressions)'
+      enable_tmate:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+jobs:
+
+  github-server-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    env:
+      SECRET_VAR1: secret-var1-value
+      SECRET_VAR2: secret-var2-value
+      SECRET_FOR_MISSING_FIELD: secret for missing field
+      
+    steps:
+      # Place the root directory in this branch
+      - uses: actions/checkout@v3
+
+      - name: Run ALKiln - Start the temporary GitHub server
+        id: github_server
+        uses: ./action_for_github_server
+        with:
+          CONFIG_CONTENTS: "${{ secrets.CONFIG_CONTENTS }}"
+      - run: echo "ALKiln finished starting the isolated GitHub docassemble server"
+
+      # Debugging on failure to explore things like config issues
+      - name: Run ALKiln - Docker failure tmate session
+        if: ${{ failure() }}
+        uses: mxschmitt/action-tmate@v3
+
+      - name: Run ALKiln - Env vars from server output
+        run: |
+          echo "USER1_EMAIL=${{ steps.github_server.outputs.DA_ADMIN_EMAIL }}" >> $GITHUB_ENV
+          echo "USER1_PASSWORD=${{ steps.github_server.outputs.DA_ADMIN_PASSWORD }}" >> $GITHUB_ENV
+      ## Example of working with the docker container after it's been started
+      ## For example, you can make more users with different permissions and passwords
+      #- name: Work with docker
+      #  run: |
+      #    container_name=$(docker ps --format '{{.Names}}' | head -n 1)
+      #    echo "container_name is $container_name"
+
+      - name: "Run ALKiln tests"
+        if: ${{ success() }}
+        uses: ./
+        with:
+          SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
+          DOCASSEMBLE_DEVELOPER_API_KEY: "${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}"
+          INSTALL_METHOD: "server"
+          # Temporary while in pre-release
+          ALKILN_VERSION: "server"
+          # Has been useful for development. Can remove when more stable.
+          ALKILN_TAG_EXPRESSION: ""
+      - run: echo "ALkiln finished running ALKiln tests"
+

package/CHANGELOG.md

@@ -45,6 +45,14 @@ Format:
 
 <!-- ## [Unreleased] -->
 
+## [5.5.0] - 2023-10-27
+
+### Added
+- Added a github action that allows authors to run tests on an isolated server that ALKiln creates on GitHub. They will need to create a new GitHub workflow to run the action. This reduces flakiness that authors' servers can create during server reload caused by updating their config, pulling in a package with a module, and other such things. As with all tests, especially with end to end test, there will always be some flakiness.
+
+### Fixed
+- Continuing development of random input test: Deal with non-existent elements, add a default input `type` of 'text', only press 'Back' 10% of the time instead of potentially 50%, navigate back to the interview from an external link (that goes outside the server) if necessary. Also add more debug logs to help diagnose problems. https://github.com/SuffolkLITLab/ALKiln/pull/633
+
 ## [5.4.2] - 2023-10-22
 
 ### Changed
@@ -896,4 +904,4 @@ Format:
 - `example.feature` - an example test to get a project started
 - `github/workflows/run_form_tests.yml` - Automated github workflow to run tests when code is pushed and a manual trigger for testing without needing to push
 - `.gitignore` - ignores files that are generated by the tests and shouldn't be added to the repo
-- `package.json` - keep up-to-date version of this test repository and hold scripts that the automated tests run
+- `package.json` - keep up-to-date version of this test repository and hold scripts that the automated tests run

package/action.yml

@@ -22,6 +22,15 @@ inputs:
     description: "Max amount of time to give the server to reload if it needs to"
     required: false
     # no default to let the custom Scenario timeouts create the reload timeout
+  # INSTALL_LOCATION? Will that get confused with the location passed into the command line?
+  # Maybe `INSTALL_LOCATION` could be "playground", "server", or a custom path and we could handle all those.
+  INSTALL_METHOD:
+    description: "Default is 'playground'. Other option: 'server'. How to install the package onto the server."
+    required: false
+    default: "playground"
+  ALKILN_TAG_EXPRESSION:
+    description: "The tag expression to use to limit which tests to run. Default is no tag expression."
+    required: false
 
 runs:
   using: "composite"
@@ -46,29 +55,43 @@ runs:
         echo -e "\nALKiln version is $ALKILN_VERSION\nRepo is $REPO_URL\nBranch ref is $BRANCH_PATH\nMAX_SECONDS_FOR_SETUP is $MAX_SECONDS_FOR_SETUP\nSERVER_RELOAD_TIMEOUT_SECONDS is $SERVER_RELOAD_TIMEOUT_SECONDS\n"
       shell: bash
 
-    # Install node
+    # Install
     - name: "ALKiln: Install node packages"
       uses: actions/setup-node@v3
       with:
         node-version: "18"
     - name: Install ALKiln directly from npm
       run: |
-        npm install -g @suffolklitlab/alkiln
+        npm install -g @suffolklitlab/alkiln@$ALKILN_VERSION
       shell: bash
 
-    # Run tests
+    # Install on playground
     - name: "ALKiln: Create a Project and pull the package from GitHub"
+      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
       run: alkiln-setup
       shell: bash
+    - run: echo -e "\n\n====\nALKiln could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
+      if: ${{ inputs.INSTALL_METHOD == 'playground' && failure() }}
+      shell: bash
+
+    # Install on server
+    - name: "ALKiln: Install the GitHub package onto the server"
+      if: ${{ inputs.INSTALL_METHOD == 'server' }}
+      run: alkiln-server-install
+      shell: bash
+    - run: echo -e "\n\n====\nALKiln could not install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"
+      if: ${{ inputs.INSTALL_METHOD == 'server' && failure() }}
+      shell: bash
+
+    # run tests
     - name: "ALKiln: Run tests"
       if: ${{ success() }}
-      run: alkiln-run ${{ github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
-      shell: bash
-    - run: echo -e "\n\n====ALKiln could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
-      if: ${{ failure() }}
+      run: alkiln-run ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
       shell: bash
-    - name: "ALKiln: Delete project from docassemble test account"
-      if: ${{ always() }}
+    
+    # on playground, delete project
+    - name: "ALKiln: Try to delete the project from the playground of the docassemble test account."
+      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
       run: alkiln-takedown
       shell: bash
     
@@ -81,7 +104,7 @@ runs:
         path: ./alkiln-*
 
 # ##################################
-# # A developer's workflow should look similar to the below
+# # A developer's workflow should look similar to the below.
 # # In place of `uses: suffolkLITLab/ALKiln@v5`, they
 # # might use another version.
 #

package/action_for_github_server/action.yml

@@ -0,0 +1,141 @@
+name: "ALKiln/github_server: Isolated docassemble tests"
+description: "Download and start up a temporary docassemble server on GitHub's servers, in an isolated environment. Avoids docassemble reload errors and other external factors."
+
+# If we want to control the version of the docassemble image, we'd have
+# to make our own image:
+# You can build your own image by doing git clone jhpyle/docassemble  and then
+# using git checkout to select a particular version, and then using docker build
+# to build an image. https://docassemble.org/docs/docker.html#downgrading
+# If we just want to use an older version of da (as long as it works with
+# the latest image):
+# If you have an existing container you can use dainstall from the command
+# line to install docassemble.webapp==1.4.68
+
+inputs:
+  CONFIG_CONTENTS:
+    description: "The contents of the config file of the docassemble server"
+    required: false
+  MAX_SECONDS_FOR_DOCKER:
+    description: "Maximum amount of seconds to give the docassemble docker container to serve the site."
+    required: false
+    default: 600  # 10 min
+
+outputs:
+  DOCASSEMBLE_DEVELOPER_API_KEY:
+    description: "Use this inside `with:` for the ALKiln step. Temporary admin api key. It will be destroyed after the tests are done."
+    value: ${{ steps.api_key_output_step.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}
+  SERVER_URL:
+    description: "Use this inside `with:` for the ALKiln step. URL of the temporary docassemble server."
+    value: "http://localhost"
+  DA_ADMIN_EMAIL:
+    value: ${{ steps.api_key_output_step.outputs.DA_ADMIN_EMAIL }}
+  DA_ADMIN_PASSWORD:
+    value: ${{ steps.api_key_output_step.outputs.DA_ADMIN_PASSWORD }}
+
+
+runs:
+  using: "composite"
+  steps:
+      - uses: actions/checkout@v3
+
+      - name: "ALKiln github_server: Set environment variables"
+        run: |
+          echo "DA_ADMIN_API_KEY=abcd1234abcd1234abcd5678abdc5678" >> $GITHUB_ENV
+          echo "MAX_SECONDS_FOR_DOCKER=${{ inputs.MAX_SECONDS_FOR_DOCKER }}" >> $GITHUB_ENV
+          echo "DA_ADMIN_EMAIL=admin@example.com" >> $GITHUB_ENV
+          # Login will fail if this is "password"
+          echo "DA_ADMIN_PASSWORD=@123abcdefg" >> $GITHUB_ENV
+        shell: bash
+      - id: api_key_output_step
+        run: |
+          echo "DOCASSEMBLE_DEVELOPER_API_KEY=$DA_ADMIN_API_KEY" >> "$GITHUB_OUTPUT"
+          echo "DA_ADMIN_EMAIL=$DA_ADMIN_EMAIL" >> "$GITHUB_OUTPUT"
+          echo "DA_ADMIN_PASSWORD=$DA_ADMIN_PASSWORD" >> "$GITHUB_OUTPUT"
+        shell: bash
+
+      - name: "ALKiln github_server: Download and start docker"
+        run: |
+          mkdir /tmp/config
+          if [ -n "${{ inputs.CONFIG_CONTENTS }}" ]
+          then
+            echo "ALKiln github_server: The developer did provided a custom docassemble config file as an input into this action."
+            echo "${{ inputs.CONFIG_CONTENTS }}" > /tmp/config/myconfig.yml
+            echo "CONFIG_ARGS=--env DA_CONFIG=/tmp/config/myconfig.yml --volume /tmp/config:/tmp/config " >> $GITHUB_ENV
+          else
+            echo "ALKiln github_server: The developer did not provide a custom docassemble config file as an input into this action. Docassemble will use its default config."
+            echo "CONFIG_ARGS=" >> $GITHUB_ENV
+          fi
+        shell: bash
+      - run: |
+          docker pull jhpyle/docassemble
+          docker run --name docassemble_container \
+                     --env DA_ADMIN_EMAIL="${{ env.DA_ADMIN_EMAIL }}" \
+                     --env DA_ADMIN_PASSWORD="${{ env.DA_ADMIN_PASSWORD }}" \
+                     --env DA_ADMIN_API_KEY="${{ env.DA_ADMIN_API_KEY }}" \
+                     ${{ env.CONFIG_ARGS }} \
+                     --cap-add SYS_PTRACE \
+                     --memory="4gb" -d -p 80:80 jhpyle/docassemble
+        shell: bash
+      - name: "ALKiln github_server: Wait for server to start"
+        run: |
+          # ALKiln github_server: Wait for server to start
+
+          # Reset the SECONDS variable
+          SECONDS=0
+          # Wait 1 minute before pinging the server constantly
+          sleep 60
+
+          response="start"
+
+          while [[ $response != *"200"* ]]; do
+            echo "ALKiln github_server: Time elapsed: $SECONDS seconds"
+
+            # Check if max seconds till loading has passed
+            if [[ $SECONDS -ge $MAX_SECONDS_FOR_DOCKER ]]; then
+              echo "ALKiln github_server Error: Timed out waiting for docker container to serve the site. If you want to give your docker container more timem to install, set the MAX_SECONDS_FOR_DOCKER input for this action."
+              exit 1
+            fi
+
+            # Set the variable to a new string value in each iteration
+            response=$(curl -o /dev/null -s -w "%{http_code}\n" http://localhost:80/health_check?ready=1)
+            echo "ALKiln github_server: response is $response"
+
+            # Check if the string includes the desired text
+            if [[ $response == *"200"* ]]; then
+              echo "ALKiln github_server: Success! The docker container is ready!"
+            else
+              echo "ALKiln github_server: The docker container isn't ready yet. Will check again in 30 seconds."
+              sleep 30
+            fi
+
+          done
+        shell: bash
+
+      # Don't rely on the environment's version of python
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - run: pip install docassemblecli
+        shell: bash
+      # Install the current directory onto the docassemble server
+      - run: dainstall . --apiurl http://localhost --apikey $DA_ADMIN_API_KEY
+        shell: bash
+
+      # Upload artifacts that subscribers can download on the Actions summary page
+      - name: "ALKiln github_server: Get path names with date and time"
+        if: ${{ always() }}
+        run: |
+          echo "GITHUB_SERVER_LOG_FILE_NAME=/tmp/alkiln_docker_logs-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC.txt" >> $GITHUB_ENV
+          echo "GITHUB_SERVER_ARTIFACT_NAME=alkiln_github_server-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
+        shell: bash
+      - name: "ALKiln github_server: Docker logs"
+        if: ${{ always() }}
+        run: |
+          echo "$(docker logs docassemble_container)" > "${{ env.GITHUB_SERVER_LOG_FILE_NAME }}"
+        shell: bash
+      - name: "ALKiln github_server: Upload artifacts folder"
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.GITHUB_SERVER_ARTIFACT_NAME }}
+          path: ${{ env.GITHUB_SERVER_LOG_FILE_NAME }}

package/lib/docassemble/docassemble_api_REST.js

@@ -79,13 +79,21 @@ da.pull = async function ( timeout ) {
 };  // Ends da.pull()
 
 
+da.has_playground_task_finished = async function ( task_id, timeout ) {
+  return await da.has_task_finished( "/api/restart_status", task_id, timeout);
+}
+
+da.has_package_task_finished = async function ( task_id, timeout ) {
+  return await da.has_task_finished( "/api/package_update_status", task_id, timeout);
+}
+
 // node -e 'require("./lib/docassemble/docassemble_api_REST.js").has_task_finished()'
-da.has_task_finished = async function ( task_id, timeout ) {
+da.has_task_finished = async function ( api_endpoint, task_id, timeout ) {
   /* Check task status based on `task_id`. */
   let options = {
     method: 'GET',
     headers: {'X-API-Key': session_vars.get_dev_api_key()},
-    url: `${ session_vars.get_da_server_url() }/api/restart_status`,
+    url: `${ session_vars.get_da_server_url() }${ api_endpoint }`,
     params: {
       task_id: task_id,
     },

package/lib/docassemble/docassemble_api_interface.js

@@ -329,9 +329,8 @@ da_i.pull = async function ( pull_options ) {
   }
 };  // Ends da_i.pull()
 
-
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").has_task_finished()'
-da_i.has_task_finished = async function ( task_id, options ) {
+da_i.has_task_finished = async function ( api_endpoint, task_id, options ) {
   /** Check task status if it exists. If not, return true as task did
   *    not require a server restart. See da_i.pull().
   *    See https://docassemble.org/docs/api.html#restart_status. */
@@ -342,7 +341,7 @@ da_i.has_task_finished = async function ( task_id, options ) {
   try {
 
     // If server did need to restart, check if it's done.
-    let response = await _da_REST.has_task_finished( task_id, timeout );
+    let response = await _da_REST.has_task_finished( api_endpoint, task_id, timeout );
     log.debug({ pre: `Task status: ${ response.status }. Docassemble status text: ${ response.data.status }. Task id: ${ task_id }` });
     
     if ( response.data.status === 'completed' ) {
@@ -353,16 +352,15 @@ da_i.has_task_finished = async function ( task_id, options ) {
       return false;
 
     } else if ( response.data.status === 'unknown' ) {
-      // Server is working, but status 'unknown'? We shouldn't even
-      // get here according to the API docs, but it feels weird to have
-      // no default behavior. What to return? Throw?
+      // Server is working, but status 'unknown'? Bad design, but this
+      // does get returned when install packages, so return true
       log.info({
         pre: `\`task_id\` "${ task_id }" has expired. If it's been `
           + `less than 1 hour since the task started, the task is `
           + `complete. See https://docassemble.org/docs/api.html#restart_status.`,
-        data: response,
+        data: response.data,
       });
-      return null;
+      return true;
     }  // ends status type
 
   } catch ( error ) {
@@ -378,8 +376,15 @@ da_i.has_task_finished = async function ( task_id, options ) {
 
 };  // Ends da_i.has_task_finished()
 
+da_i.wait_for_playground_to_restart = async ( task_id, options ) => {
+  return await da_i.wait_for_server_to_restart( "/api/restart_status", task_id, options );
+};
+
+da_i.wait_for_package_to_restart = async ( task_id, options ) => {
+  return await da_i.wait_for_server_to_restart( "/api/package_update_status", task_id, options );
+};
 
-da_i.wait_for_server_to_restart = async ( task_id, options ) => {
+da_i.wait_for_server_to_restart = async ( api_endpoint, task_id, options ) => {
   /** Wait for the server to finish restarting in case a module needs to load.
   *     This is a polling function because things may be returned
   *     that aren't equivalent to the server being done with a task. */
@@ -410,7 +415,7 @@ da_i.wait_for_server_to_restart = async ( task_id, options ) => {
   while ( !done_restarting && num_tries <= max_loops ) {
     num_tries++;
     // Wait only a short time for the task to finish, not the full default timeout
-    done_restarting = await da_i.has_task_finished( task_id, { timeout: wait_for_response } );
+    done_restarting = await da_i.has_task_finished( api_endpoint, task_id, { timeout: wait_for_response } );
     if ( !done_restarting ) {
       if ( num_tries < max_loops ) {
         // Show a slightly different message after a number of tries to reassure

package/lib/docassemble/get_base_interview_url.js

@@ -10,10 +10,20 @@ let get_base_interview_url = async function () {
   *    When finishing a test, we go to the sign out page (which is supposed to help even
   *    when the user is not logged in.) We can't use `reset=2` because it caused an
   *    'Unable to locate interview session' error. */
+
   let server_url = session_vars.get_da_server_url();
-  let dev_id = await docassemble_api_interface.get_dev_id();
-  let project_name = session_vars.get_project_name();
-  return `${ server_url }/interview?new_session=1&i=docassemble.playground${ dev_id }${ project_name }%3A`;
+
+  if (session_vars.get_install_method() === `server`) {
+
+    return `${ server_url }/interview?new_session=1&i=docassemble.${session_vars.get_repo_folder_name()}%3Adata/questions/`;
+
+  } else {
+
+    let dev_id = await docassemble_api_interface.get_dev_id();
+    let project_name = session_vars.get_project_name();
+    return `${ server_url }/interview?new_session=1&i=docassemble.playground${ dev_id }${ project_name }%3A`;
+
+  }
 };
 
 module.exports = get_base_interview_url;

package/lib/docassemble/server_install.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const session_vars = require('../utils/session_vars');
+const log = require('../utils/log');
+const fg = require('fast-glob');
+
+const server_install = async () => {
+  session_vars.save_install_method(`server`);
+
+  let current_dir = process.cwd();
+  let path = `${ current_dir }/docassemble/*`;
+  let dirs = fg.sync(
+    [ path ],
+    {
+      suppressErrors: true,
+      onlyDirectories: true
+    }
+  );
+
+  let folders = dirs.map(function (dir) { return dir.split('/').pop(); })
+
+  let chosen_folder = folders[0];
+  if ( folders.length === 0 ) {
+    let msg = `There are 0 folders at ${path}. Tests won't run.`;
+    log.error({ type: `setup`, data: msg })
+    throw new ReferenceError( msg );
+  }
+
+  if ( folders.length > 1 ) {
+    log.warn({
+      type: `setup`,
+      data: `There are ${folders.length} folders at ${path}: "${folders.join('", "')}". ALKiln chose to use the folder "${chosen_folder}".`
+    })
+  }
+  
+  session_vars.save_repo_folder_name( chosen_folder );
+};  // Ends server_install();
+
+server_install();

package/lib/docassemble/setup.js

@@ -39,7 +39,7 @@ const setup = async () => {
   let task_id = await da_i.pull();
   // Task id will be null if server did not need to restart
   if ( task_id ) {
-    await da_i.wait_for_server_to_restart( task_id );
+    await da_i.wait_for_playground_to_restart( task_id );
   }
 
   // Finish

package/lib/scope.js

@@ -1246,7 +1246,7 @@ module.exports = {
             + `column, but it is empty. The test might get unexpected results. See `
             + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger.`
             + `\nThe row's data:\n${ row_as_story_table }`
-            + `\nThis field's data:\n${ JSON.stringify( field )}`;
+            + `\nThis field's data:\n${ JSON.stringify( field.guesses )}`;
           reports.addToReport(scope, { type: `warning`, value: row_trigger_warning });
           rows_without_a_trigger_name.push( row_that_matches_this_field );
         } else {
@@ -1401,8 +1401,7 @@ module.exports = {
       let elem = document.querySelector( selector );
       // If the element has a sibling that's a label, we need to
       // interact with that label instead.
-      // `elem` has never been null from what we've seen
-      if ( elem.nextSibling && elem.nextSibling.tag === `label` ) {
+      if ( elem && elem.nextSibling && elem.nextSibling.tag === `label` ) {
         return elem.nextSibling;
       } else { return elem; }
     // Pass in the selector as an argument
@@ -1422,14 +1421,15 @@ module.exports = {
       // future we should look into what happens with a `fieldset` for
       // `choices:`, etc.
       let custom_datatype = null, matches = null;
-      let group = elem.closest( `.da-form-group` );
-      if ( group && group.className ) {
-        matches = ` ${ group.className } `.match(/da-field-container-datatype-([^ ]+) /);
-      }
-      if ( matches ) {
-        custom_datatype = matches[1];
+      if (elem) {
+        let group = elem.closest( `.da-form-group` );
+        if ( group && group.className ) {
+          matches = ` ${ group.className } `.match(/da-field-container-datatype-([^ ]+) /);
+        }
+        if ( matches ) {
+          custom_datatype = matches[1];
+        }
       }
-
       return custom_datatype;
     });
 
@@ -1585,7 +1585,13 @@ module.exports = {
       /* Set value of some `input` element to the given value. */
       let row_was_used = true;
 
-      let type = await handle.evaluate( elem => { return elem.getAttribute('type'); });
+      let type = await handle.evaluate( elem => { 
+        if (elem) {
+          return elem.getAttribute('type'); 
+        } else {
+          return 'text';
+        }
+      });
       if ( type === `radio` || type === `checkbox` ) {
 
         let [label] = await handle.$x(`following-sibling::label`);
@@ -1596,8 +1602,11 @@ module.exports = {
           let name = await label.evaluate( elem => { return elem.getAttribute('for'); });
         }
 
-        if ( type === `radio` ) { await label.evaluate( elem => { return elem.click(); }); }
-        else { await scope.setCheckbox( scope, { label, answer }); }
+        if ( type === `radio` ) {
+          await label.evaluate( elem => { return elem.click(); });
+        } else {
+          await scope.setCheckbox( scope, { label, answer });
+        }
 
         await scope.afterStep(scope, { waitForShowIf: true });
         
@@ -2231,9 +2240,14 @@ module.exports = {
     }  // ends act depending values
   },  // Ends scope.getThereIsAnotherValue()
 
+  is_on_server_still: async function ( scope ) {
+    let server_url = session_vars.get_da_server_url();
+    return await scope.page.url().startsWith(server_url);
+  },
+
   // throw_if_no_interview_content()?
   has_interview_content: async function ( scope ) {
-    /** Return false if ther's no element indicating a da interview question,
+    /** Return false if there's no element indicating a da interview question,
     *    like a signature page, other fields, or interview text. Assumes that page has already
     *    finished navigating. */
     let elem_da_question = await scope.page.$( `#daMainQuestion` );
@@ -2437,6 +2451,7 @@ module.exports = {
       /** Sets a non-story table variable to a "secret" value (i.e. an env var) */
       // Prevent pictures of a screen with a secret.
       scope.disable_error_screenshot = true;
+
       let var_data = await scope.normalizeTable( scope, {
               var_data: [{
                 var: var_name,
@@ -2635,7 +2650,7 @@ module.exports = {
       */
       // Don't take a picture of a failed login in case one of the inputs is correct
       scope.disable_error_screenshot = true;
-
+      
       // If there is no browser open, start a new one
       if (!scope.browser) {
         scope.browser = await scope.driver.launch({ headless: !session_vars.DEBUG });
@@ -2737,7 +2752,30 @@ module.exports = {
     }, 
     buttons: async function (scope, { fields }) {
       // Get a random button
-      let field = faker.helpers.arrayElement( fields );
+      let back_btn = null;
+      fields = fields.filter((ff) => {
+        if (ff.selector.includes("daquestionbackbutton")) {
+          back_btn = ff;
+          return false;
+        }
+        return true;
+      });
+      let field = null;
+      if (back_btn != null && Math.random() > 0.9) {
+        // 10% chance of clicking the back button. Back buttons don't undo
+        // external network calls or saving things to Redis, so we make sure
+        // programs can handle (or least don't crash) when users press back
+        field = back_btn;
+      } else {
+        field = faker.helpers.arrayElement( fields );
+      }
+      if (field == null) {
+        // Just skip it? Shouldn't happen but has before. Dig in more
+        if (session_vars.get_debug()) {
+          console.log(`A random button field choice was null. These were the fields to choose from:\n${ JSON.stringify(fields, null, 2) }`);
+        }
+        return;
+      }
       let handle = await scope.get_handle_from_field( scope, { field: field });
       // Send it to be tapped
       await scope.funnel_the_answer( scope, { handle, field, answer: `doesn't matter` });
@@ -2806,7 +2844,6 @@ module.exports = {
       let custom_datatype = await scope.get_custom_datatype( scope, { handle });
       let is_custom_datatype = scope.get_random_input_for[ custom_datatype ] !== undefined;
       if ( is_custom_datatype ) {
-
         // And the custom datatype has a hidden field (which will be the original field)
         let hidden_field = await scope.get_custom_datatype_hidden_field( scope, { handle });
         if ( hidden_field !== null ) {
@@ -2846,7 +2883,7 @@ module.exports = {
           }  // ends if field type is one we cover
         }  // ends if field type exists
 
-      }  // ends if is custom datatype
+      }  // ends else after is custom datatype
 
     },  // ends scope.set_random_input_for.input
   },  // ends scope.set_random_input_for

package/lib/steps.js

@@ -827,6 +827,11 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
         if ( has_thrown ) { return; }
         else { has_thrown = true; }
 
+        if (!( await scope.is_on_server_still(scope))) {
+          await scope.page.goBack();
+          resolve();
+        }
+
         let has_content = await scope.has_interview_content( scope );
 
         if ( !has_content ) {
@@ -872,6 +877,10 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
               await scope.continue( scope );
             }  // ends if continue exists
           }  // ends if buttons_exist
+          if (!( await scope.is_on_server_still(scope))) {
+            await scope.page.goBack();
+            resolve();
+          }
 
           let has_content = await scope.has_interview_content( scope );
           if ( !has_content ) {
@@ -891,7 +900,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
 
           if ( buttons_exist ) {
             process.stdout.write(`\x1b[36m${ 'v' }\x1b[0m`);  // pressed button
-          }         
+          }
 
           resolve();
 
@@ -901,6 +910,11 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
           if ( has_thrown ) { return; }
           else { has_thrown = true; }
 
+          if (!( await scope.is_on_server_still(scope))) {
+            await scope.page.goBack();
+            resolve();
+          }
+
           // Throw a specific error if there's no interview content
           let has_content = await scope.has_interview_content( scope );
           if ( !has_content ) {

package/lib/utils/session_vars.js

@@ -167,14 +167,54 @@ session_vars.delete_project_name = function () {
   }
 };
 
-// The file storing the artifacts path contains the name of the current artifacts folder.
+// The filepath storing the artifacts path contains the name of the current artifacts folder.
 // The directory name it contains will be created or changed with each run of all the tests.
 // const file_storing_artifact_path = `_alkiln_test_artifacts_dir_name.json`;
 const artifacts_path_key = `artifacts_path`;
 session_vars.save_artifacts_path_name = function ( path_name ) {
   /* Save a key with the name of the current artifacts folder in case it doesn't exist. */
+  return session_vars.save_runtime_config_var({ key: artifacts_path_key, value: path_name });
+};  // Ends save_artifacts_path_name()
+session_vars.get_artifacts_path_name = function () {
+  /* Get the name of the current artifacts path. */
+  return session_vars.get_runtime_config_var( artifacts_path_key );
+};  // Ends get_artifacts_path_name()
+
 
-  // Ensure artifacts path file exists
+const install_method_key = `da_install_method`;
+session_vars.save_install_method = function ( install_method ) {
+  /* Save a key with the name of the current artifacts folder in case it doesn't exist. */
+  return session_vars.save_runtime_config_var({ key: install_method_key, value: install_method });
+};  // Ends save_install_method()
+session_vars.get_install_method = function () {
+  /* Get the name of the current install method. */
+  return session_vars.get_runtime_config_var( install_method_key );
+};  // Ends get_install_method()
+
+
+const repo_folder_key = `da_repo_folder_name`;
+session_vars.save_repo_folder_name = function (repo_folder_name) {
+  /** Save a key with the name of the main package folder in the repository. */
+  return session_vars.save_runtime_config_var({ key: repo_folder_key, value: repo_folder_name });
+};  // Ends session_vars.save_repo_folder_name()
+session_vars.get_repo_folder_name = function () {
+  /** Get the name of the main folder in the repository. */
+  return session_vars.get_runtime_config_var( repo_folder_key );
+};  // Ends session_vars.get_repo_folder_name()
+
+
+session_vars.save_runtime_config_var = function ({ key, value }) {
+  /** Write to the runtime config file by adding a key/value pair to
+  *   the json object there. The functions calling this are keeping
+  *   track of the key, so they're useful to keep around.
+  * 
+  * @param key {str} Key to use to store `value` in runtime config file
+  * @param value {any} Value to store in runtime config file
+  * 
+  * @returns file {binary?} Runtime config file
+  */
+
+  // Ensure runtime config file exists
   if ( !fs.existsSync( runtime_config_path ) ) {
     // If the file doesn't exist, make one because next we need to read it
     fs.writeFileSync( runtime_config_path, JSON.stringify( {}, null, 2 ) );
@@ -182,27 +222,35 @@ session_vars.save_artifacts_path_name = function ( path_name ) {
 
   // Get the json, changing it, and re-write the file from scratch
   let json = JSON.parse( fs.readFileSync( runtime_config_path ) );
-  json[ artifacts_path_key ] = path_name;
+  json[ key ] = value;
   let file = fs.writeFileSync( runtime_config_path, JSON.stringify( json, null, 2 ) );
 
   if ( session_vars.get_debug() ) {
-    console.log( `ALKiln debug: Stored name of artifacts directory "${ path_name }" locally.` );
+    console.log( `ALKiln debug runtime config var: Stored "${key}" locally as "${value}".` );
   }
   return file;
-};  // Ends save_artifacts_path_name()
+};  // Ends session_vars.save_runtime_config_var()
 
-session_vars.get_artifacts_path_name = function () {
-  /* Get the name of the current artifacts path. */
+session_vars.get_runtime_config_var = function ( key ) {
+  /** Get the value of the given key from the runtime config file.
+  * 
+  * @param key {str} Key in runtime config file that contains the desired value
+  * @returns value || null {any} Value of key in runtime config file. If it
+  *    doesn't exist, returns null.
+  */
   try {
     let json = JSON.parse( fs.readFileSync( runtime_config_path ));
-    let path_name = json[ artifacts_path_key ];
+    let value = json[ key ];
+    if ( session_vars.get_debug() ) {
+      console.log( `ALKiln debug runtime config var: "${key}"" is "${value}".` );
+    }
 
-    if ( session_vars.get_debug() ) { console.log( `ALKiln debug: Artifacts directory is "${ path_name }".` ); }
-    return path_name;
+    return value;
   } catch ( error ) {
     return null;
   }
-};  // Ends get_artifacts_path_name()
+};  // Ends session_vars.get_runtime_config_var()
+
 
 session_vars.set_sources_paths = function ( paths ) {
   /** Returns whether at least one of the given path exists. Store
@@ -235,7 +283,7 @@ session_vars.set_sources_paths = function ( paths ) {
   // Warn about missing paths
   if ( missing_paths.length > 0 ) {
     console.warn(
-      `ALKiln WARNING: ALKiln can't find folders at "${ paths.join(", ") }".`
+      `ALKiln WARNING: ALKiln can't find folders at "${ paths.join('", "') }".`
     );
   }
 
@@ -245,10 +293,14 @@ session_vars.set_sources_paths = function ( paths ) {
     return false;
   }
 
+  console.info(
+    `ALKiln info: Did find "sources" folder(s) at "${ existing_paths.join('", "') }".`
+  )
+
   // Otherwise, store valid paths
   session_vars._sources_paths = existing_paths;
   return true;
-};
+};  // End session_vars.set_sources_paths()
 
 session_vars.get_sources_paths = function () {
   /** Get the "sources" folder path. Should never be undefined during
@@ -259,6 +311,7 @@ session_vars.get_sources_paths = function () {
   return session_vars._sources_paths;
 };
 
+
 session_vars.validateEnvironment = function() {
   /** Throw a useful error for the developer if any of the env vars
   *    required by absolutely all tests are missing. Gather all

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.4.2",
+  "version": "5.5.0",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {
@@ -9,6 +9,7 @@
     "local": "npm run setup && npm run cucumber; npm run takedown",
     "setup": "./lib/docassemble/setup.js",
     "takedown": "./lib/docassemble/takedown.js",
+    "server_install": "./lib/docassemble/server_install.js",
     "unit": "mocha tests/unit_tests/*.test.*"
   },
   "repository": {
@@ -50,6 +51,7 @@
     "diff": "5.0.0"
   },
   "bin": {
+    "alkiln-server-install": "./lib/docassemble/server_install.js",
     "alkiln-setup": "./lib/docassemble/setup.js",
     "alkiln-takedown": "./lib/docassemble/takedown.js",
     "alkiln-run": "./lib/run_cucumber.js"

package/setup.py

@@ -50,10 +50,10 @@ setup(name='docassemble.ALKilnTests',
       author='plocket',
       author_email='example@example.com',
       license='The MIT License (MIT)',
-      url='https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing',
+      url='https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln',
       packages=find_packages(),
       namespace_packages=['docassemble'],
-      install_requires=['docassemble.ALToolbox>=0.5.1'],
+      install_requires=['docassemble.ALToolbox>=0.8.2', 'docassemble.AssemblyLine>=2.24.0'],
       zip_safe=False,
       package_data=find_package_data(where='docassemble/ALKilnTests/', package='docassemble.ALKilnTests'),
      )