@suffolklitlab/alkiln 5.7.0 → 5.8.1

package/.github/workflows/github_server.yml

@@ -2,7 +2,7 @@ name: GitHub server installation
 
 on:
   push:
-  # Default opened, reopened, synchronize. "edited" is something else.
+  # Default "opened", "reopened", "synchronize". "edited" fires when the PR title gets edited, etc.
   pull_request_target:
   workflow_dispatch:
     inputs:
@@ -44,7 +44,7 @@ jobs:
         id: github_server
         #### Developer note: you'll need to replace `.` with the path to
         #### the repo and branch. For example:
-        #### suffolkLITLab/ALKiln@v5/action_for_github_server
+        #### suffolkLITLab/ALKiln/action_for_github_server@v5
         uses: ./action_for_github_server
         with:
           CONFIG_CONTENTS: "${{ secrets.CONFIG_CONTENTS }}"

package/.github/workflows/playground.yml

@@ -54,3 +54,5 @@ jobs:
           #### Developer note: Useful for temporarily shortening ALKiln tests
           #### to debug the docker install step
           # ALKILN_TAG_EXPRESSION: @a_tag_expression
+          #### Developer note: you probalby don't need this
+          # ALKILN_VERSION: 5.7.0-feature-tap1

package/CHANGELOG.md

@@ -45,6 +45,28 @@ Format:
 
 <!-- ## [Unreleased] -->
 
+## [5.8.1] - 2023-12-28
+
+### Fixed
+- Restored previous behavior - Projects are now deleted even when a workflow fails. See [#831](https://github.com/SuffolkLITLab/ALKiln/issues/831).
+- Fixed typo of comment explaining how to reference the isolated GitHub server action.
+
+### Security
+- Harden security for action input handling. That said, the source of the problem would come from author workflows, so there's a lot more authors can do to help this situation than we can. Workflows triggered by pull requests are a specific place to watch. GitHub already has [some default safeguards](https://docs.github.com/en/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks#about-workflow-runs-from-public-forks) to prevent strangers, specifically first-time contributors, from triggering workflows like that. They can also set their [org](https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#configuring-required-approval-for-workflows-from-public-forks) or [repo](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories) to be more strict about pull requests from outside collaborators.
+
+### Internal
+- Freeze `docassemblecli` version at 0.0.17. See [#827](https://github.com/SuffolkLITLab/ALKiln/issues/827).
+
+## [5.8.0] - 2023-12-18
+
+### Added
+- Step to tap an element without navigating. See [#834](https://github.com/SuffolkLITLab/ALKiln/issues/834).
+
+### Internal
+- Use puppeteer `.click()`` again
+- Re-activate looking for terms on the page.
+
+
 ## [5.7.0] - 2023-11-14
 
 ### Added

package/action.yml

@@ -22,8 +22,6 @@ 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
@@ -31,6 +29,10 @@ inputs:
   ALKILN_TAG_EXPRESSION:
     description: "The tag expression to use to limit which tests to run. Default is no tag expression."
     required: false
+  DOCASSEMBLECLI_VERSION:
+    description: "The version of docassemblecli to install."
+    required: false
+    default: "0.0.17"
 
 runs:
   using: "composite"
@@ -40,18 +42,29 @@ runs:
 
     # Set environment variables
     - name: "ALKiln setup info: Set environment variables"
-      # Human-readable date/time:
-      # https://www.shell-tips.com/linux/how-to-format-date-and-time-in-linux-macos-and-bash/#how-to-format-a-date-in-bash
+      # Safe input handling. Avoid evaluating in bash.
+      env:
+        BRANCH_PATH: ${{ github.ref }}
+        BASE_URL: ${{ inputs.SERVER_URL }}
+        DOCASSEMBLE_DEVELOPER_API_KEY: ${{ inputs.DOCASSEMBLE_DEVELOPER_API_KEY }}
+        ALKILN_VERSION: ${{ inputs.ALKILN_VERSION }}
+        MAX_SECONDS_FOR_SETUP: ${{ inputs.MAX_SECONDS_FOR_SETUP }}
+        SERVER_RELOAD_TIMEOUT_SECONDS: ${{ inputs.SERVER_RELOAD_TIMEOUT_SECONDS }}
+        DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
       run: |
         # ALKiln setup info: Set environment variables
+        # Human-readable date/time: https://www.shell-tips.com/linux/how-to-format-date-and-time-in-linux-macos-and-bash/#how-to-format-a-date-in-bash
         echo "ARTIFACT_NAME=alkiln-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
         echo "REPO_URL=${{ github.server_url }}/${{ github.repository }}" >> $GITHUB_ENV
-        echo "BRANCH_PATH=${{ github.ref }}" >> $GITHUB_ENV
-        echo "BASE_URL=${{ inputs.SERVER_URL }}" >> $GITHUB_ENV
-        echo "DOCASSEMBLE_DEVELOPER_API_KEY=${{ inputs.DOCASSEMBLE_DEVELOPER_API_KEY }}" >> $GITHUB_ENV
-        echo "ALKILN_VERSION=${{ inputs.ALKILN_VERSION }}" >> $GITHUB_ENV
-        echo "MAX_SECONDS_FOR_SETUP=${{ inputs.MAX_SECONDS_FOR_SETUP }}" >> $GITHUB_ENV
-        echo "SERVER_RELOAD_TIMEOUT_SECONDS=${{ inputs.SERVER_RELOAD_TIMEOUT_SECONDS }}" >> $GITHUB_ENV
+        echo "BRANCH_PATH=$BRANCH_PATH" >> $GITHUB_ENV
+        # Workflow inputs
+        echo "BASE_URL=$BASE_URL" >> $GITHUB_ENV
+        echo "DOCASSEMBLE_DEVELOPER_API_KEY=$DOCASSEMBLE_DEVELOPER_API_KEY" >> $GITHUB_ENV
+        echo "ALKILN_VERSION=$ALKILN_VERSION" >> $GITHUB_ENV
+        echo "MAX_SECONDS_FOR_SETUP=$MAX_SECONDS_FOR_SETUP" >> $GITHUB_ENV
+        echo "SERVER_RELOAD_TIMEOUT_SECONDS=$SERVER_RELOAD_TIMEOUT_SECONDS" >> $GITHUB_ENV
+        echo "DOCASSEMBLECLI_VERSION=$DOCASSEMBLECLI_VERSION" >> $GITHUB_ENV
+        # Hard-coded internal ALKiln vars
         echo "_ORIGIN=github" >> $GITHUB_ENV
       shell: bash
     - name: "ALKiln setup info: confirm environment variables"
@@ -68,7 +81,7 @@ runs:
     - name: Install ALKiln directly from npm
       run: |
         # ALKiln setup info: Install ALKiln directly from npm
-        npm install -g @suffolklitlab/alkiln@$ALKILN_VERSION
+        npm install -g "@suffolklitlab/alkiln@$ALKILN_VERSION"
       shell: bash
 
     # Install on playground
@@ -82,7 +95,7 @@ runs:
       if: ${{ inputs.INSTALL_METHOD == 'playground' }}
       run: |
         # ALKiln setup info: Create a Project and install the package from GitHub
-        pip3 install docassemblecli
+        pip install "docassemblecli==$DOCASSEMBLECLI_VERSION"
         alkiln-setup
       shell: bash
     - name: "ALKiln setup ERROR"
@@ -103,12 +116,14 @@ runs:
     # run tests
     - name: "ALKiln info: Run tests"
       if: ${{ success() }}
-      run: alkiln-run ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
+      env:
+        ALKILN_TAG_EXPRESSION: ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
+      run: alkiln-run $ALKILN_TAG_EXPRESSION
       shell: bash
     
     # on playground, delete project
     - name: "ALKiln info: Try to delete the project from the playground of the docassemble test account."
-      if: ${{ inputs.INSTALL_METHOD == 'playground' }}
+      if: ${{ always() && inputs.INSTALL_METHOD == 'playground' }}
       run: alkiln-takedown
       shell: bash
     

package/action_for_github_server/action.yml

@@ -23,6 +23,10 @@ inputs:
     description: "Default is 600 seconds. Maximum amount of seconds to give the docassemble docker container to serve the site."
     required: false
     default: 600  # 10 min
+  DOCASSEMBLECLI_VERSION:
+    description: "The version of docassemblecli to install."
+    required: false
+    default: "0.0.17"
 
 outputs:
   DOCASSEMBLE_DEVELOPER_API_KEY:
@@ -44,11 +48,16 @@ runs:
       - uses: actions/checkout@v3
 
       - name: "ALKiln GitHub server - Set environment variables"
+        env:
+          MAX_SECONDS_FOR_DOCKER: ${{ inputs.MAX_SECONDS_FOR_DOCKER }}
+          DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
         run: |
+          # ALKiln GitHub server info: Set environment variables
+          echo "MAX_SECONDS_FOR_DOCKER=$MAX_SECONDS_FOR_DOCKER" >> $GITHUB_ENV
+          echo "DOCASSEMBLECLI_VERSION=$DOCASSEMBLECLI_VERSION" >> $GITHUB_ENV
           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"
+          # Login will fail if this value is "password"
           echo "DA_ADMIN_PASSWORD=@123abcdefg" >> $GITHUB_ENV
         shell: bash
       - id: api_key_output_step
@@ -59,14 +68,16 @@ runs:
         shell: bash
 
       - name: "ALKiln GitHub server - Get config"
+        env:
+          CONFIG: ${{ inputs.CONFIG_CONTENTS }}
         run: |
           # ALKiln GitHub server info: config values
           mkdir /tmp/config
           # Worth making this silent by defining a variable with > /dev/null...?
-          if [ -n "${{ inputs.CONFIG_CONTENTS }}" ]
+          if [ -n "$CONFIG" ]
           then
             echo "ALKiln GitHub server - The developer did provide a custom docassemble config file as an input into this action."
-            echo "${{ inputs.CONFIG_CONTENTS }}" > /tmp/config/myconfig.yml
+            echo "$CONFIG" > /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."
@@ -74,20 +85,20 @@ runs:
           fi
         shell: bash
 
-      # GitHub masks secret values like the config, so we don't really
-      # need to stop that yet, but users may start using variables, so
-      # a question: If in future we allow variables instead of just secrets,
+      # Question: If in future we allow GitHub variables instead of just secrets,
       # should we let those be visible or prevent them along with the docker logs?
-
-      # Also, does this leave GitHub job environment output While just
-      # hiding the output from the job console?
+      # Also, does GitHub hide job environment output of secrets as well as
+      # hiding the secrets' output from the job console?
 
       # Define the var to prevent/show docker output
+      # TODO: Why are we only doing this for manually triggered workflows?
       - name: Env var for showing docker output
+        env:
+          SHOW_DOCKER_OUTPUT: ${{ inputs.SHOW_DOCKER_OUTPUT }}
         run: |
           # ALKiln GitHub server info: Docker logs visibility decision
           if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            echo "OUTPUT_DOCKER=${{ inputs.SHOW_DOCKER_OUTPUT }}" >> $GITHUB_ENV
+            echo "OUTPUT_DOCKER=$SHOW_DOCKER_OUTPUT" >> $GITHUB_ENV
           else
             echo "OUTPUT_DOCKER=false" >> $GITHUB_ENV
           fi
@@ -105,31 +116,36 @@ runs:
           printf '===\nALKiln GitHub server - GitHub will now show the output of docker creation. 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==='
         shell: bash
 
+      # TODO: Reduce these to 1 block by putting ` > /dev/null 2>&1` into an env var
       # No output
       - name: "ALKiln GitHub server - Download and start docker silently"
         if: ${{ env.OUTPUT_DOCKER == 'false' }}
+        env:
+          CONFIG_ARGS: ${{ env.CONFIG_ARGS }}
         run: |
           # ALKiln GitHub server info: Silent docker pull/run
           docker pull jhpyle/docassemble > /dev/null 2>&1
           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 }} \
+                     --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
+                     --env DA_ADMIN_PASSWORD="$DA_ADMIN_PASSWORD" \
+                     --env DA_ADMIN_API_KEY="$DA_ADMIN_API_KEY" \
+                     $CONFIG_ARGS \
                      --cap-add SYS_PTRACE \
                      --memory="4gb" -d -p 80:80 jhpyle/docassemble > /dev/null 2>&1
         shell: bash
       # With output
       - name: "ALKiln GitHub server - Download and start docker"
         if: ${{ env.OUTPUT_DOCKER == 'true' }}
+        env:
+          CONFIG_ARGS: ${{ env.CONFIG_ARGS }}
         run: |
           # ALKiln GitHub server info: Docker pull/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 }} \
+                     --env DA_ADMIN_EMAIL="$DA_ADMIN_EMAIL" \
+                     --env DA_ADMIN_PASSWORD="$DA_ADMIN_PASSWORD" \
+                     --env DA_ADMIN_API_KEY="$DA_ADMIN_API_KEY" \
+                     $CONFIG_ARGS \
                      --cap-add SYS_PTRACE \
                      --memory="4gb" -d -p 80:80 jhpyle/docassemble
         shell: bash
@@ -188,7 +204,7 @@ runs:
         with:
           python-version: '3.10'
       # No output
-      - run: pip install docassemblecli > /dev/null 2>&1
+      - run: pip install "docassemblecli==$DOCASSEMBLECLI_VERSION" > /dev/null 2>&1
         if: ${{ env.OUTPUT_DOCKER == 'false' }}
         shell: bash
       # Install the package, the current directory (.), onto the docassemble server
@@ -197,7 +213,7 @@ runs:
         shell: bash
 
       # With output
-      - run: pip install docassemblecli
+      - run: pip install "docassemblecli==$DOCASSEMBLECLI_VERSION"
         if: ${{ env.OUTPUT_DOCKER == 'true' }}
         shell: bash
       # Install the package, the current directory (.), onto the docassemble server

package/lib/scope.js

@@ -174,14 +174,14 @@ module.exports = {
     if ( showif ) { await scope.page.waitForTimeout( scope.showif_timeout ); }
   },
 
-  waitForTab: async function waitForTab(scope, tab_to_show) {
+  waitForTab: async function waitForTab(scope, { tab_id }) {
     /**
-     * @param {tab_to_show} the aria-labeledby text of the tab panel, which
+     * @param { tab_id } the aria-labeledby text of the tab panel, which
      *   we use to query and wait for that tab panel to be shown.
      */
     // Implementation linked to https://github.com/SuffolkLITLab/docassemble-ALToolbox/blob/4aa1069389d2ca9cadb586f309dd73d791f081d1/docassemble/ALToolbox/misc.py#L127
     // I think `.$()` does not use a timeout
-    if ( tab_to_show.length == 0) { return }
+    if ( tab_id.length == 0) { return }
     // waiting for the transitionend event: https://stackoverflow.com/a/57955251/11416267
     await scope.page.evaluate((element_query) => {
       return new Promise((resolve) => {
@@ -198,13 +198,16 @@ module.exports = {
           resolve();
         }
       });
-    }, `div[aria-labelledby="${tab_to_show}"]`);
+    }, `div[aria-labelledby="${ tab_id }"]`);
   },
 
-  afterStep: async function afterStep(scope, options = {waitForShowIf: false, tabToWaitFor: '', navigated: false, waitForTimeout: 0}) {
-    /* Common things to do after a step, including take care of errors.
-    *    TODO: discuss splitting into `afterField` and `afterStep` or something. Or just change name
-    *    TODO: Update to latest cucumberjs, which has `AfterStep` */
+  afterStep: async function afterStep(scope, options = {waitForShowIf: false, navigated: false, waitForTimeout: 0}) {
+    /** Common things to do after a step, including take care of errors.
+     *    `waitForShowIf` is automatically `false` for observation/non-interactive steps, etc.
+     *
+     *    TODO: discuss splitting into `afterField` and `afterStep` or something. Or just change name
+     *    TODO: Update to latest cucumberjs, which has `AfterStep`
+     */
 
     if ( scope.page ) {
       // Use a while loop until the below does not error with `Error: Execution context was destroyed`
@@ -231,7 +234,6 @@ module.exports = {
 
       // Wait for elements that might get revealed
       if ( options.waitForShowIf ) { await scope.waitForShowIf( scope ); }
-      if ( options.tabToWaitFor ) { await scope.waitForTab( scope, options.tabToWaitFor); }
     }  // ends if scope.page
 
     if ( options.navigated ) {
@@ -248,39 +250,56 @@ module.exports = {
     if ( options.waitForTimeout ) { await time.waitForTimeout( options.waitForTimeout ); }
   },  // Ends afterStep
 
-  tapElement: async function tapElement(scope, elem, tabToWaitFor='', waitForTimeout=0) {
-    /* Tap a given element, detect navigation, and do appropriate related things. */
+  tapElementAndNavigate: async function(scope, { elem, waitForTimeout=0 }) {
+    /** Tap a given element, detect navigation, and do appropriate related things.
+     *  TODO: not quite sure if we'll be using `waitForTimeout`. */
 
-    // This check might never be needed now as we try to match fields on the page
-    // first in user-triggered cases - users used to be able to access this almost
-    // directly, but they can't anymore. Our functions should know to only pass good things.
-    let msg = `Cannot find the element to tap.`;
-    if ( !elem ) { reports.addToReport(scope, { type: `error`, value: msg }); }
+    let start_url = await scope.page.url();  // so we can later check for navigation
 
-    expect( elem, msg ).to.exist;
+    await scope.tapElementAndStayOnPage(scope, {
+      elem,
+      click_promise: Promise.all([
+        scope.page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
+        elem.evaluate( (el) => { return el.click(); })
+      ])
+    });
 
-    // Get the text on the button or link for a potential error message later
-    let tapperText = await (await elem.getProperty('textContent')).jsonValue();
+    // TODO: Not sure how to detect navigation landing at same page, such as
+    // with a user input validation error. Does that count as navigating?
+    // Maybe url change + trigger var change? Maybe just trigger var?
+    let end_url = await scope.page.url();
+    let navigated = start_url !== end_url;
 
-    let start_url = await scope.page.url();  // so we can later check for navigation
+    // Might be able to handle this in `scope.afterStep`
+    if ( navigated ) {
 
-    // We'll wait for the click itself at the very least
-    let click_promises = [ elem.evaluate( (el) => { return el.click(); }) ];
-    
-    // If we're possibly navigating, wait for navigation as well
-    if ( !tabToWaitFor ) {
-      click_promises.push( scope.page.waitForNavigation({ waitUntil: 'domcontentloaded' }) );
+      // TODO: Can we remove this?
+      // Save the id that comes next
+      let { question_has_id, id, id_matches } = await scope.examinePageID( scope, 'none to match' );
+
+      // If navigation, wait for 200ms to let things finish loading and moving
+      await scope.afterStep(scope, { waitForTimeout: 200, navigated: true });
+    } else {
+      await scope.afterStep(scope, { waitForTimeout, navigated: false });
     }
-    let clickWait = Promise.all( click_promises );
+  },  // Ends scope.tapElementAndNavigate()
 
-    let winner = null;
+  tapElementAndStayOnPage: async function(scope, { elem, click_promise }) {
+    /** Tap a given element, detect navigation, and do appropriate related things.
+    *  `click_promise can be any kind of Promise, including a Promise.all()
+    */
+    let msg = `Cannot find the element to tap.`;
+    if ( !elem ) { reports.addToReport(scope, { type: `error`, value: msg }); }
+    expect( elem, msg ).to.exist;
 
+    click_promise = click_promise || elem.click();
+    
     // TODO: implement and use scope.handle_possible_timeout()
     try {
-      // Error loads page, so no need to detect to keep things short
-      // Also, puppeteer will ensure proper timeout.
-      winner = await Promise.race([
-        clickWait,
+      // Serever error loads page, so keeping things shorter by not looking
+      // for that text too. Also, puppeteer will ensure proper timeout.
+      await Promise.race([
+        click_promise,
         // This is meant to detect user-visible alerts/errors,
         // not breaking errors in the testing code.
         scope.page.waitForSelector('.alert-danger', { visible: true }),
@@ -292,6 +311,9 @@ module.exports = {
         let non_reload_report_msg = `ALKiln tapped "${ tapperText }", but the interview took to long to finish.`;
         await scope.handle_page_timeout_error( scope, { non_reload_report_msg, error });
       } else {
+
+        // Get the text on the button or link for a potential error message later
+        let tapperText = await (await elem.getProperty('textContent')).jsonValue();
         // Throw any non-timeout error
         let err_msg = `Error occurred when ALKiln tried to tap "${ tapperText }".`
         reports.addToReport( scope, { type: `error`, value: err_msg });
@@ -299,30 +321,7 @@ module.exports = {
       }  // ends if error is timeout error
 
     }  // ends try/catch
-
-    // TODO: Not sure how to detect navigation landing at same page, such as
-    // with a user input validation error. Does that count as navigating?
-    // Maybe url change + trigger var change? Maybe just trigger var?
-    let end_url = await scope.page.url();
-    let navigated = start_url !== end_url;
-
-    // Might be able to handle this in `scope.afterStep`
-    if ( navigated ) {
-      // Save the id that comes next
-      let { question_has_id, id, id_matches } = await scope.examinePageID( scope, 'none to match' );
-      // If navigation, wait for 200ms to let things settle down
-      await scope.afterStep(scope, {waitForTimeout: 200, navigated: navigated});
-    } else {
-      // If stay on page, wait for `show if`, the new tab to be loaded, or feedback elements to be move around
-      options = {waitForShowIf: !tabToWaitFor, tabToWaitFor: tabToWaitFor, navigated: navigated};
-      if (waitForTimeout > 0) {
-        options = {waitForTimeout: waitForTimeout, navigated: navigated};
-      }
-      await scope.afterStep(scope, options); 
-    }
-
-    return winner;
-  },  // Ends scope.tapElement()
+  },  // Ends scope.tapElementAndStayOnPage()
 
   // Handle server reload errors
   server_statuses: [],
@@ -516,7 +515,7 @@ module.exports = {
     ]);
     await elem.evaluate( el => { return el.className });
     // Waits for navigation or user error
-    await scope.tapElement( scope, elem );
+    await scope.tapElementAndNavigate( scope, { elem });
   },  // Ends scope.continue()
 
   continue_exists: async function ( scope ) {
@@ -545,7 +544,8 @@ module.exports = {
       reports.addToReport(scope, { type: `error`, value: error_msg }); 
     }
     expect( elem, error_msg ).to.exist;
-    await scope.tapElement( scope, elem, tab_id );
+    await scope.tapElementAndStayOnPage(scope, { elem });
+    await scope.waitForTab( scope, { tab_id });
   },
 
   checkForA11y: async function (scope ) {
@@ -586,14 +586,25 @@ module.exports = {
     };
   },
 
-  tapElementBySelector: async function ( scope, selector, waitForTimeout ) {
-    let elem = await scope.page.$(`${selector}`);
-    let error_msg = `Couldn't find "${selector}" on the page, is there a typo?`;
+  tapSelectorToNavigate: async function ( scope, selector, waitForTimeout ) {
+    let elem = await scope.page.$(`${ selector }`);
+    let error_msg = `Couldn't find "${ selector }" on the page, is there a typo?`;
+    if ( !elem ) {
+      reports.addToReport(scope, { type: `error`, value: error_msg });
+    }
+    expect( elem, error_msg ).to.exist;
+    await scope.tapElementAndNavigate( scope, { elem, waitForTimeout });
+  },
+
+  tapSelectorAndStay: async function ( scope, { selector }) {
+    let elem = await scope.page.$(`${ selector }`);
+    let error_msg = `Couldn't find "${ selector }" on the page, is there a typo?`;
     if ( !elem ) {
       reports.addToReport(scope, { type: `error`, value: error_msg });
     }
     expect( elem, error_msg ).to.exist;
-    await scope.tapElement( scope, elem, '', waitForTimeout );
+    await scope.tapElementAndStayOnPage(scope, { elem });
+    await scope.afterStep(scope, { waitForShowIf: false, navigated: false, waitForTimeout: 0 });
   },
 
   load: async function ( scope, file_name ) {
@@ -1539,7 +1550,7 @@ module.exports = {
 
   enter_answer: {
     button: async function ( scope, { handle, answer }) {
-      await scope.tapElement( scope, handle );
+      await scope.tapElementAndNavigate( scope, { elem: handle });
       return true;
     },
     textarea: async function ( scope, { handle, answer }) {
@@ -2466,16 +2477,16 @@ module.exports = {
     },  // Ends scope.steps.set_secret_var
 
     tap_term: async ( scope, phrase ) => {
-      /** Tap a link that doesn't navigate. Depends on the language of the text. */
+      /** Tap a link that doesn't navigate. Depends on the language of the text.
+       *  TODO: This may be broken at this point.
+       * */
       const [link] = await scope.page.$x(`//a[contains(text(), "${phrase}")]`);
 
       let msg = `The term "${ phrase }" seems to be missing.`;
       if ( !link ) { reports.addToReport(scope, { type: `error`, value: msg }); }
       expect( link, msg ).to.exist;
-
-      await scope.tapElement( scope, link );
-
-      await scope.afterStep(scope, {waitForShowIf: true});
+      await scope.tapElementAndStayOnPage(scope, { elem: link });
+      await scope.page.waitForTimeout(10000);
     },  // Ends scope.steps.tap_term()
 
     sign: async ( scope, name ) => {
@@ -2529,7 +2540,7 @@ module.exports = {
       if (failed_to_download) {
         reports.addToReport(scope, { type: `warning`, value: `Could not download file using fetch (${ err_msg }). ALKiln will now fallback to the click download method` });
         scope.toDownload = filename;
-        // Should this be using `scope.tapElement()`?
+        // Should this be using `scope.tapElement`?
         await elem.evaluate( elem => { return elem.click(); });
         await scope.detectDownloadComplete( scope );
       }
@@ -2702,7 +2713,7 @@ module.exports = {
       await scope.page.type( `#email`, email );
       await scope.page.type( `#password`, password );
       let elem = await scope.page.$( `button[name="submit"]` );
-      await scope.tapElement( scope, elem );
+      await scope.tapElementAndNavigate( scope, { elem });
 
       // Wait to see the success message.
       // This is a bit of an assumption and needs success and failure testing

package/lib/steps.js

@@ -254,7 +254,7 @@ Given(/I (?:sign|log) ?(?:in)?(?:on)?(?:to the server)? with(?: the email)? "([^
   * I sign on with the email "USER1_EMAIL" and the password "USER1_PASSWORD" SECRETs
   * I log in with "USER1_EMAIL" and "USER1_PASSWORD"
   */
-  // Exiting the custom timeout happens in scope.tapElement() if needed
+  // `page` timeout will deal with custom timeout
   // Couldn't test the timeout for tapping the button because there's not
   // enough of a pause between initial navigation and pressing button.
   await scope.steps.sign_in( scope, {
@@ -745,24 +745,32 @@ When(/I tap to continue/i, { timeout: -1 }, async () => {
   // Any selectors for this seem somewhat precarious
   // No data will cause an automatic continue when `ensure_navigation` is true
 
-  // Exiting the custom timeout happens in scope.tapElement() where we can
+  // `page` timeout will deal with custom timeout
   // check if the server is reloading
   await scope.setFields( scope, { var_data: [], ensure_navigation: true });
 });
 
 When(/I tap the "([^"]+)" tab/i, { timeout: -1 }, async ( tabId ) => {
-  // Exiting the custom timeout happens in scope.tapElement() if needed
+  // `page` timeout will deal with custom timeout
   await scope.tapTab( scope, tabId );
 });
 
-When(/I tap the "([^"]+)" element$/i, { timeout: -1 }, async ( elemSelector ) => {
-  // Exiting the custom timeout happens in scope.tapElement() if needed
-  await scope.tapElementBySelector( scope, elemSelector, 2000 );
+When(/I tap the "([^"]+)" element(?: and go to (?:a new|the next) page)?$/i, { timeout: -1 }, async ( elemSelector ) => {
+  // `page` timeout will deal with custom timeout
+  await scope.tapSelectorToNavigate( scope, elemSelector, 2000 );
 });
 
-When(/I tap the "([^"]+)" element and wait ([0-9]+) second(?:s)?/i, { timeout: -1 }, async ( elemSelector, waitTime ) => {
-  // Exiting the custom timeout happens in scope.tapElement() if needed
-  await scope.tapElementBySelector( scope, elemSelector, waitTime * 1000 )
+When(/I tap the "([^"]+)" element and stay(?: on the same page)?$/i, { timeout: -1 }, async ( selector ) => {
+  // `page` timeout will deal with custom timeout
+  await scope.tapSelectorAndStay( scope, { selector });
+});
+
+When(/I tap the "([^"]+)" element and wait (?:for )?([0-9]+) second(?:s)?/i, { timeout: -1 }, async ( elemSelector, waitTime ) => {
+  // TODO: Why is it the developer can't just wait after the step?
+  // Also, this is always supposed to navigate, and that handles its own waiting.
+
+  // `page` timeout will deal with custom timeout
+  await scope.tapSelectorToNavigate( scope, elemSelector, waitTime * 1000 )
 });
 
 When(/I check the page for (?:accessibility|a11y) issues/i, {timeout: -1}, async () => {
@@ -967,7 +975,7 @@ When(/I set the var(?:iable)? "([^"]+)" to "([^"]+)"/, { timeout: -1 }, async (
   * 1. I set the var "benefits['SSI']" to "false"
   * 1. I set the variable "rent_interval" to "weekly"
   */
-  // Exiting the custom timeout happens in scope.tapElement() if needed
+  // `page` timeout will deal with custom timeout
   await scope.steps.set_regular_var( scope, var_name, answer )
 
 });
@@ -975,7 +983,7 @@ When(/I set the var(?:iable)? "([^"]+)" to "([^"]+)"/, { timeout: -1 }, async (
 When(/I set the var(?:iable)? "([^"]+)" to ?(?:the)? ?(?:GitHub)? secret "([^"]+)"/i, { timeout: -1 }, async ( var_name, set_to_env_name ) => {
   /* Set a non-story table variable to a secrete value. Same as the above, but reads the value from `process.env` */
   // This could theoretically tap an element, so
-  // exiting the custom timeout happens in scope.tapElement() if needed
+  // `page` timeout will deal with custom timeout
   await scope.steps.set_secret_var( scope, var_name, set_to_env_name )
 });
 
@@ -995,7 +1003,7 @@ Then(/I upload "([^"]+)" to "([^"]+)"/, { timeout: -1 }, async ( filenames, var_
 
 When('I tap the defined text link {string}', { timeout: -1 }, async ( phrase ) => {
   /** Tap a link that doesn't navigate. Depends on the language of the text. */
-  // exiting the custom timeout happens in scope.tapElement() if needed
+  // `page` timeout will deal with custom timeout
   await scope.steps.tap_term( scope, phrase );
 });
 
@@ -1022,7 +1030,7 @@ When(/I download "([^"]+)"$/, { timeout: -1 }, async ( filename ) => {
   *    page load. Just stick to the name of the file.
   */
   // TODO:
-  // This should be using `scope.tapElement()`? When someone clicks on a link to
+  // This should be using `scope.tapElementAndStayOnPage()`? When someone clicks on a link to
   // download a document, it sends a request to the server, which could be reloading
   return wrapPromiseWithTimeout(
     scope.steps.download( scope, filename ),

package/package.json

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