@suffolklitlab/alkiln 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -40,6 +40,9 @@ Format:
 -->
 <!-- ## [Unreleased] -->
 
+## [4.5.0] - 2022-05-23
+- Steps that tap tabs (made using the `tabbed_templates_html` function from ALToolbox) and other arbitrary elements on the page.
+
 ## [4.4.0] - 2022-05-23
 ### Added
 - Appends the results of the cucumber [summary formatter](https://github.com/cucumber/cucumber-js/blob/main/docs/formatters.md#summary) to the `debug_log.txt`, which includes useful stack traces into the Kiln code when tests fail.

package/lib/scope.js

@@ -244,10 +244,37 @@ module.exports = {
     if ( showif ) { await scope.page.waitForTimeout( scope.showif_timeout ); }
   },
 
-  afterStep: async function afterStep(scope, options = {waitForShowIf: false, navigated: false, waitForTimeout: 0}) {
+  waitForTab: async function waitForTab(scope, tab_to_show) {
+    /**
+     * @param {tab_to_show} 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 }
+    // waiting for the transitionend event: https://stackoverflow.com/a/57955251/11416267
+    await scope.page.evaluate((element_query) => {
+      return new Promise((resolve) => {
+        const elem = document.querySelector(element_query); 
+        // Taken from jQuery: https://stackoverflow.com/a/33456469/11416267
+        const is_visible = !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length );
+        if (!is_visible) {
+          const onEnd = function() {
+            elem.removeEventListener('transitionend', onEnd);
+            resolve();
+          };
+          elem.addEventListener('transitionend', onEnd); 
+        } else {
+          resolve();
+        }
+      });
+    }, `div[aria-labelledby="${tab_to_show}"]`);
+  },
+
+  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 as `AfterStep` */
+    *    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`
@@ -274,6 +301,7 @@ 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 ) {
@@ -290,7 +318,7 @@ module.exports = {
     if ( options.waitForTimeout ) { await time.waitForTimeout( options.waitForTimeout ); }
   },  // Ends afterStep
 
-  tapElement: async function tapElement(scope, elem) {
+  tapElement: async function tapElement(scope, elem, tabToWaitFor='', waitForTimeout=0) {
     /* Tap a given element, detect navigation, and do appropriate related things. */
 
     // This check might never be needed now as we try to match fields on the page
@@ -303,25 +331,32 @@ module.exports = {
 
     let start_url = await scope.page.url();  // so we can later check for navigation
 
-    let winner;
-    winner = await Promise.race([
-      Promise.all([  // Error loads page, so no need to detect to keep things short
-        // Click with no navigation will end immediately
-        // Can't use elem[ scope.activate ](). It works locally, but errors on GitHub
-        // with "Node is not visible or not an HTMLElement". We're not using a custom Chromium version
-        // Unfortunately, this won't catch an invisible element. Hopefully we'd catch it before now...?
-        // "Tap" on mobile is more complex to implement ourselves.
-        // See https://stackoverflow.com/a/56547605/14144258
-        // and other convos around it. We haven't made it public that the device
-        // can customized. Until we do that, we'll just use "click" all the time.
+    let clickWait;
+    // Can't use elem[ scope.activate ](). It works locally, but errors on GitHub
+    // with "Node is not visible or not an HTMLElement". We're not using a custom Chromium version
+    // Unfortunately, this won't catch an invisible element. Hopefully we'd catch it before now...?
+    // "Tap" on mobile is more complex to implement ourselves.
+    // See https://stackoverflow.com/a/56547605/14144258
+    // and other convos around it. We haven't made it public that the device
+    // can customized. Until we do that, we'll just use "click" all the time.
+    if (!tabToWaitFor) {
+      // Click with no navigation will end immediately
+      clickWait = Promise.all([
         elem.evaluate( (el) => { return el.click(); }),
         scope.page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
-      ]),
+      ]);
+    } else {
+      // Same thing as above, but the promise doesn't wait for navigation.
+      clickWait = elem.evaluate( (el) => {return el.click(); });
+    }
+    // Error loads page, so no need to detect to keep things short
+    let winner = await Promise.race([
+      clickWait,
       // This is meant to detect user-visible alerts/errors,
       // not breaking errors in the testing code.
       scope.page.waitForSelector('.alert-danger', { visible: true }),
       scope.page.waitForSelector('.da-has-error', { visible: true }),
-    ]);
+    ])
 
     // TODO: Not sure how to detect navigation landing at same page.
     // Maybe url change + trigger var change? Maybe just trigger var?
@@ -335,8 +370,12 @@ module.exports = {
       // 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` or feedback elements to be move around
-      await scope.afterStep(scope, {waitForShowIf: true, navigated: navigated});
+      // 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;
@@ -426,13 +465,33 @@ module.exports = {
     await scope.tapElement( scope, elem );
   },
 
+  tapTab: async function ( scope, tab_id ) {
+    let elem = await scope.page.$(`#${tab_id}`); 
+    let error_msg = `Couldn't find the tab with id "#${tab_id}" on the page, is there a typo?`;
+    if ( !elem ) {
+      await scope.addToReport(scope, { type: `error`, value: error_msg }); 
+    }
+    expect( elem, error_msg ).to.exist;
+    await scope.tapElement( scope, elem, tab_id );
+  },
+
+  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?`;
+    if ( !elem ) {
+      await scope.addToReport(scope, { type: `error`, value: error_msg });
+    }
+    expect( elem, error_msg ).to.exist;
+    await scope.tapElement( scope, elem, '', waitForTimeout );
+  },
+
   load: async function ( scope, file_name ) {
     /* Try to load the page. Should we also pass a `timeout` arg or just
     *    use scope.timeout? */
 
     // If there is no browser open, start a new one
     if (!scope.browser) {
-      scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug() });
+      scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug(), devtools: session_vars.get_debug() });
     }
     if ( !scope.page ) { scope.page = await scope.browser.newPage(); }
 

package/lib/steps.js

@@ -391,7 +391,7 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
 //#####################################
 //#####################################
 
-When(/I wait (\d*\.?\d+) seconds?/, { timeout: -1 }, async ( seconds ) => {
+When(/I wait ?(?:for)? (\d*\.?\d+) seconds?/, { timeout: -1 }, async ( seconds ) => {
   /** Wait for a specified amount of time. Can help with some race conditions.
   *    We're working on reducing race conditions, but it'll never be perfect.
   *
@@ -707,6 +707,27 @@ When('I tap to continue', { timeout: -1 }, async () => {
   );
 });
 
+When(/I tap the "([^"]+)" tab/i, { timeout: -1 }, async ( tabId ) => {
+  return wrapPromiseWithTimeout(
+    scope.tapTab( scope, tabId ),
+    scope.timeout
+  )
+});
+
+When(/I tap the "([^"]+)" element$/i, { timeout: -1 }, async ( elemSelector ) => {
+  return wrapPromiseWithTimeout(
+    scope.tapElementBySelector( scope, elemSelector, 2000 ),
+    scope.timeout
+  )
+});
+
+When(/I tap the "([^"]+)" element and wait ([0-9]+) second(?:s)?/i, { timeout: -1 }, async ( elemSelector, waitTime ) => {
+  return wrapPromiseWithTimeout(
+    scope.tapElementBySelector( scope, elemSelector, waitTime * 1000 ),
+    scope.timeout
+  )
+});
+
 
 //#####################################
 // UI element interaction

package/package.json

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

package/tests/features/interactive_steps.feature

@@ -101,3 +101,25 @@ Scenario: handles settings from Github secrets
   Then I see the phrase "secret-var2-value"
   When I tap to continue
   And I set the variable "third_text_entry" to secret "SECRET_NOT_THERE"
+
+@i3 @tap-elements @tabs
+Scenario: tap elements
+  Given I start the interview at "test_taps"
+  And I tap the "Tests-first_template-tab" tab
+  Then I see the phrase "Mechanics"
+  And I tap the "Tests-second_template-tab" tab
+  Then I see the phrase "villify"
+  And I tap the "Tests-third_template-tab" tab
+  Then I see the phrase "museum"
+  And I tap the "#special_event" element and wait 1 second
+  Then I see the phrase "Portishead"
+
+@i4 @tap-elements @tabs
+Scenario: tap element with an error
+  Given the final Scenario status should be "failed"
+  And the Scenario report should include:
+  """
+  is there a typo?
+  """
+  Given I start the interview at "test_taps"
+  And I tap the "Tests-not_there-tab" tab