@suffolklitlab/alkiln 5.5.0 → 5.7.0-feature-tap1

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

@@ -67,6 +67,10 @@ to detect that.
 regex thoughts: https://stackoverflow.com/questions/171480/regex-grabbing-values-between-quotation-marks
 */
 
+// Make sure all the required env vars exist. Required to be
+// here as well as `setup`` specifically for local development.
+session_vars.validateEnvironment();
+
 // Hoping that most load and download times will be under 30 seconds.
 // TODO: Check what average load and download times are in our current interviews.
 let default_timeout = 30 * 1000
@@ -250,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, {
@@ -741,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 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 ([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 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 () => {
@@ -963,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 )
 
 });
@@ -971,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 )
 });
 
@@ -991,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 );
 });
 
@@ -1018,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/lib/utils/session_vars.js

@@ -371,8 +371,6 @@ session_vars.validateEnvironment = function() {
   errorMessage = errorMessage.trim();
 
   if (errorMessage !== '') {
-    throw new ReferenceError(`ALKiln error: ${errorMessage}`);
+    throw new ReferenceError(`ALKiln error:\n${errorMessage}`);
   }
 };
-
-session_vars.validateEnvironment();

package/package.json

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

package/.github/workflows/test_tests.yml

@@ -1,73 +0,0 @@
-name: Test the 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)'
-        default: ''
-
-jobs:
-
-  puppeteer-tests:
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [18.x]
-
-    env:
-      BASE_URL: ${{ secrets.SERVER_URL }}
-      PLAYGROUND_EMAIL: ${{ secrets.PLAYGROUND_EMAIL }}
-      PLAYGROUND_PASSWORD: ${{ secrets.PLAYGROUND_PASSWORD }}
-      PLAYGROUND_ID: ${{ secrets.PLAYGROUND_ID }}
-      DOCASSEMBLE_DEVELOPER_API_KEY: ${{ secrets.DOCASSEMBLE_DEVELOPER_API_KEY }}
-      USER1_EMAIL: ${{ secrets.USER1_EMAIL }}
-      USER1_PASSWORD: ${{ secrets.USER1_PASSWORD }}
-      SECRET_VAR1: secret-var1-value
-      SECRET_VAR2: secret-var2-value
-      SECRET_FOR_MISSING_FIELD: secret for missing field
-      _ORIGIN: github
-
-    name: Run Puppeteer tests
-    steps:
-      - name: Set Github-related environment variables
-        run: |
-          echo "REPO_URL=${{ github.server_url }}/${{ github.repository }}" >> $GITHUB_ENV
-          echo "BRANCH_PATH=${{ github.ref }}" >> $GITHUB_ENV
-      - name: Set name of artifact folder with date and UTC 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
-        run: |
-          echo "ARTIFACT_NAME=alkiln-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
-          echo "UNIT_TESTS_ARTIFACT_NAME=_alkiln-misc-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
-      # For the testing repo, the `REPO_URL` is that of a different repo and is created in `env:`
-      - run: echo "Repo address is $REPO_URL"
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup environment
-        uses: actions/setup-node@v3
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm install
-      - run: npm run setup
-      - run: npm run test ${{ github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
-      # Artifacts
-      - name: upload unit tests artifacts folder
-        uses: actions/upload-artifact@v3
-        # This will upload even if a previous step has failed
-        if: ${{ always() }}
-        with:
-          name: ${{ env.UNIT_TESTS_ARTIFACT_NAME }}
-          path: ./_alkiln-*
-      - name: upload integration tests artifacts folder
-        uses: actions/upload-artifact@v3
-        if: ${{ always() }}
-        with:
-          name: ${{ env.ARTIFACT_NAME }}
-          path: ./alkiln-*
-      # Delete Playground Project and project name file
-      - name: Cleanup
-        if: ${{ always() }}
-        run: npm run takedown