@suffolklitlab/alkiln 5.17.1 → 5.17.2

package/lib/steps.js

@@ -117,6 +117,7 @@ BeforeAll(async function() {
 Before(async (scenario) => {
 
   // Start the running "progress bar" for the Scenario
+  log.debug({ code: `ALK0289`, context: `before`, }, `%%%%%%%%%%%%%%%%%%`);
   log.stdout({}, `\nScenario: ${ scenario.pickle.name }: `);
 
   // Create browser, which can't be created in BeforeAll() where .driver doesn't exist for some reason
@@ -400,7 +401,7 @@ When(/I? ?gets? to ?.*?(".*").*?with.*?(?:this data:)?/i, {timeout: -1}, async (
       // If we need to call recursively, signature function might look like:
       // func( scope, { resolve, reject, supported_table, page_timeout_id })
       // Maybe list of timeout and/or interval ids in state that can all be cleared at once?
-      (async function() {
+      let error_data = (async function() {
         try {
           let id = await scope.get_page_id( scope );
 
@@ -416,28 +417,34 @@ When(/I? ?gets? to ?.*?(".*").*?with.*?(?:this data:)?/i, {timeout: -1}, async (
             `Rows, including special rows:`, ensured_var_data
           );
 
-          // THIS FUNCTION ACTUALLY MATTERS
-          // Some errors happen in there to be closer to the relevant code. We'd have to try/catch anyway.
-          let error_data = await scope.setFields(scope, { var_data: ensured_var_data, id, ensure_navigation: true });
+          let error_data = await scope.setFields(scope, {
+            var_data: ensured_var_data, id, ensure_navigation: true
+          });
+          clearTimeout( page_timeout_id );  // prevent temporary hang at end of tests
 
           // Story Table assumes we require navigation while other Steps don't.
           // Throw here in case something sneaks through.
-          if ( error_data?.was_found ) { await scope.throw_system_error( scope, {
-            error_handlers: error_data.handlers, id: id
-          }); }
-          resolve();
+          await scope.throw_on_system_error( scope, { id, error_data });
+          await scope.throw_on_invalid_answers( scope, { id, error_data });
+          await scope.throw_on_non_navigation_timeout( scope, { id, timed_out: false });
+          await scope.throw_on_non_navigation_catchall( scope, { id });
+          resolve( error_data );
+
         } catch ( err ) {
-          let err_msg = `ALKiln ran into an error when it tried to answer fields on the page with the question id "${ id }". The text above might have more information.`
-          reports.addToReport( scope, { type: `error`, code: `ALK0062`, value: err_msg });
-          // Throw error instead?
-          reject( err );
+          // Catching here allows us to clear the timeout if needed
+          clearTimeout( page_timeout_id );  // prevent temporary hang at end of tests
+          log.debug({
+            code: `ALK0062`, level: `error`, error: err, context: `story_table`,
+          }, `ALKiln ran into an error when it tried to answer fields on the page with the id "${ id }"` );
+          throw err;
+
         } finally {
           clearTimeout( page_timeout_id );  // prevent temporary hang at end of tests
         }
       })();
-    });  // ends custom_timeout for setFields
+    });  // ends custom_timeout for filling in fields
 
-    await custom_timeout;
+    let page_result = await custom_timeout;
 
     // Prep for next loop
     id = await scope.get_page_id( scope );
@@ -529,7 +536,7 @@ Then(/the (?:question|page|screen) id should be "([^"]+)"/i, { timeout: -1 }, as
   let { question_has_id, id, id_matches } = await scope.examinePageID( scope, question_id );
 
   // No question id exists
-  let no_id_msg = `Did not find any question id.`;
+  let no_id_msg = `Did not find any question id`;
   if ( !question_has_id ) {
     reports.addToReport( scope, { type: `error`, code: `ALK0070`, value: no_id_msg });
   }
@@ -625,44 +632,20 @@ Then('an element should have the id {string}', async ( id ) => {  // √
 //   await scope.afterStep(scope);
 // });
 
-// This phrase is confusing. It sounds like it's going to at least try to continue.
-Then(/I (don't|can't|don’t|can’t|cannot|do not) continue/, async (unused) => {  // √
-  /** Press to continue. Succeeds when navigation then fails. */
-
-  // Must catch "failure to navigate"-type error.
-  // TODO: Explore using .continue + .checkForError (see "invalid answer" Step)
-  try {
-    let error_data = await scope.setFields( scope, { var_data: [], ensure_navigation: true });
-    // TODO: Add test for excluding AL..075 msg when Step succeeds
-    if ( scope.navigated ) {
-      let report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0075`,
-        value: `The page should have stopped the user from continuing, but the user was able to continue.`
-      });
-      expect( scope.navigated, report_msg ).to.be.false;
-    }
+Then(/I will be told (?:an answer is)?(?:some )?(?:all )?(?:answers are)? invalid/i, async () => {  // √
 
-  } catch ( continue_attempt_error ) {
-    // Discuss: Too deeply coupled? Alternatives?
-    if ( !continue_attempt_error.message?.includes(`ALK0148`) ) {
-      throw continue_attempt_error;
-    }
-  }
-
-  await scope.afterStep(scope);
-});
-
-Then('I will be told an answer is invalid', async () => {  // √
-
-  let { ok, type, error_handlers } = await scope.checkForError( scope );
+  let { ok, type } = await scope.checkForErrors( scope );
 
   let report_msg = null;
-  if ( ok ) { report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0076`, value: `Sorry, you expected at least one invalid answer, but all answers were valid` }); }
-  expect( ok, report_msg ).to.be.false;
-
+  if ( ok ) {
+    report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0076`, value: `Sorry, you expected one or more invalid answers, but ALKiln only sees valid answers.` });
+    throw Error( report_msg );
+  }
   if ( type !== `user` ) {
     report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0077`,
       value: `The error was a system error, not an invalid user answer. Check for the picture of the page's error if the Step did not use any secret variables.`
     });
+    throw Error( report_msg );
   }
   expect( type, report_msg ).to.equal( `user` );
 
@@ -826,13 +809,105 @@ Then(/the "([^"]+)" link opens a working page/, { timeout: -1 }, async ( linkTex
   );
 });
 
-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
+Then(/I continue(?: to the next )?(?:page|screen)?/i, i_continue );
+async function i_continue() {
+  /**
+   * Press to continue. If navigation fails, tests fail. This Step implicitly
+   *   assumes the user is able to continue. Some reasons navigation can fail:
+   * 
+   * - Invalid answers (client-side or `validation code`)
+   * - Missing continue button
+   * - System error
+   * - Timeout
+   * - Infinite loop page (unsatisfied `show if:`) (in future implementation)
+   * - Others?
+   * 
+   * @example
+   * And I continue
+   * @example
+   * And I continue to the next page
+   * @example
+   * And I continue to the next screen
+   * 
+   * */
+  let error_data = await scope.continue( scope );
+  await scope.afterStep(scope);
+};  // Ends i_continue()
 
-  // `page` timeout will deal with custom timeout
-  // check if the server is reloading
-  await scope.setFields( scope, { var_data: [], ensure_navigation: true });
+Then(/I (don't|don’t|do not|can’t|can't|cannot|(?:am unable to)) continue/, async (_unused) => {
+  /**
+   * Press to continue. If navigation fails in the following ways, succeed:
+   * 
+   * - Invalid answers (client-side or `validation code`)
+   * - Missing continue button
+   * - Can we think of any others?
+   * 
+   * The following failures to navigate should still fail:
+   * 
+   * - System error
+   * - Timeout
+   * - Infinite loop page (unsatisfied `show if:`) (in future implementation)
+   * - Others?
+   * 
+   * @example
+   * And I can't continue
+   * @example
+   * And I can’t continue
+   * @example
+   * And I am unable to continue
+   * */  `I do have to try/catch. Right? No? Why would scope.navigated be not False?`
+  let error_data = await scope.continue(
+    scope, { post_nav_handlers: [
+      scope.throw_on_system_error,
+      scope.throw_on_non_navigation_timeout,
+    ]}
+  );
+  if ( scope.navigated ) {
+    let report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0075`,
+      value: `The page should have stopped the user from continuing, but the user was able to continue.`
+    });
+    throw Error( report_msg );
+  }
+
+  await scope.afterStep(scope);
+});
+
+When(/I tap to continue/i, async () => {
+  /**
+   * This functionality supports legacy behavior. Deprecate this behavior and
+   *   break it in v6. In v6 this Step will stop suppressing errors completely.
+   *   The current "I can't continue" Step will fully take over this behavior.
+   *   The current behavior:
+   * 
+   * Press to continue. If navigation fails in the following ways, succeed:
+   * 
+   * - Invalid answers (client-side or `validation code`)
+   * - Can we think of any others?
+   * 
+   * The following failures to navigate should still fail:
+   * 
+   * - Missing continue button
+   * - System error
+   * - Timeout
+   * - Infinite loop page (unsatisfied `show if:`) (in future implementation)
+   * - Others?
+   * */
+
+  await scope.continue(
+    scope, { post_nav_handlers: [
+      scope.throw_on_system_error,  // Throw system errors if any first
+      // Author may not expect success with invalid answers. Warn them.
+      scope.warn_on_invalid_answers,
+      scope.throw_on_non_navigation_timeout,
+      scope.warn_on_non_navigation_catchall,
+    ]}
+  );
+
+  reports.addToReport( scope, { type: `warning`, code: `ALK0294`,
+    value: `You are using the old "I tap to continue" Step. We recommend you switch to a newer Step. Use "I continue" if you need to continue to the next page. Use "I can't continue" if you want to check for invalid answer messages or if there is no continue button.`
+  });
+
+  await scope.afterStep(scope);
 });
 
 When(/I tap the "([^"]+)" tab/i, { timeout: -1 }, async ( tabId ) => {
@@ -855,7 +930,7 @@ When(/I tap the "([^"]+)" element and wait (?:for )?([0-9]+) second(?:s)?/i, { t
   // 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 )
+  await scope.tapSelectorToNavigate( scope, elemSelector, waitTime * 1000 );
 });
 
 When(/I check the page for (?:accessibility|a11y) issues/i, {timeout: -1}, async () => {
@@ -1464,18 +1539,20 @@ After(async function(scenario) {
       // test), it failed. If is was supposed to pass and failed, it also
       // failed. E.g. a11y failures let the Scenario pass initially, but
       // should cause a failure here.
-      changeable_test_status = `FAILED`;
-      // Flag this failure to trigger an error later, so cucumber shows
-      // it as failed too.
-      expected_status_was_met = false;
-      // Keep it general. Users may see this message, e.g. for a11y tests.
+
+      // Keep this msg general. Users may see this message, e.g. for a11y tests.
       let msg = `Test ${ changeable_test_status }. `
-          + `Expected status: ${scope.expected_status}. `
+          + `Expected status: ${ scope.expected_status }. `
           + `See the report for details.`;
       let code = `ALK0099`;
       expected_status_err_msg = log.debug({ code: code, level: `error`, },
         msg
       );
+
+      // Flag this failure to trigger an error later, so cucumber shows
+      // it as failed too.
+      changeable_test_status = `FAILED`;
+      expected_status_was_met = false;
     }
   }
   scope.expected_status = null;  // reset for next Scenario
@@ -1609,7 +1686,7 @@ After(async function(scenario) {
 
   // Find the race condition.
   log.debug({ code: `ALK0100`, context: `scenario`, },
-    `Scenario After() message:`, scenario.result.message
+    `%%%%%%%%%%%%%%%%%%`, `Scenario After() message:`, scenario.result.message
   );
 
 });

package/package.json

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

package/tests/log_codes/log_code_expected_instances.txt

@@ -160,7 +160,7 @@ ALK0144:1
 ALK0145:1
 ALK0146:1
 ALK0147:1
-ALK0148:2
+ALK0148:1
 ALK0149:1
 ALK0150:1
 ALK0151:1
@@ -301,3 +301,12 @@ ALK0285:1
 ALK0286:1
 ALK0287:1
 ALK0288:1
+ALK0289:1
+ALK0290:1
+ALK0291:1
+ALK0292:1
+ALK0293:1
+ALK0294:1
+ALK0295:1
+ALK0296:1
+ALK0297:1

package/tests/unit_tests/navigation.test.js

@@ -0,0 +1,72 @@
+const chai = require('chai');
+const expect = chai.expect;
+const fs = require(`fs`);
+
+const scope = require(`../../lib/scope.js`);
+
+scope.log_and_update_if_new_page_id = async function() {
+  /** Mock this `scope` function to avoid extraneous errors. */
+  return `mock-page-id`;
+};
+
+describe(`The deepest navigation logic`, function () {
+
+  it(`will handle a missing required system error handler by throwing ALK0295`, async function() {
+    let error = null
+    try {
+      await scope.wait_until_continued( scope, { post_nav_handlers: [
+        scope.throw_on_invalid_answers,
+        scope.throw_on_non_navigation_timeout,
+      ] });
+    } catch (err) {
+      error = err;
+    }
+    expect( error instanceof ReferenceError, `Not a ReferenceError` ).to.be.true;
+    expect( error.message.includes(`ALK0295`), `Missing log code ALK0295` ).to.be.true;
+    expect( error.message.includes(`ALK0296`), `Unwanted log code ALK0296 is present`).to.be.false;
+  });
+
+  it(`will handle a missing required navigation timeout handler by throwing ALK0296`, async function() {
+    let error = null
+    try {
+      await scope.wait_until_continued( scope, { post_nav_handlers: [
+        scope.throw_on_system_error,
+        scope.throw_on_invalid_answers,
+      ] });
+    } catch (err) {
+      error = err;
+    }
+    expect( error instanceof ReferenceError, `Not a ReferenceError` ).to.be.true;
+    expect( error.message.includes(`ALK0295`), `Unwanted log code ALK0295 is present`).to.be.false;
+    expect( error.message.includes(`ALK0296`), `Missing log code ALK0296` ).to.be.true;
+  });
+
+  it(`will handle the absence of both critical error throwers by throwing ALK0295 and ALK0296`, async function() {
+    let error = null
+    try {
+      await scope.wait_until_continued( scope, { post_nav_handlers: [
+        scope.throw_on_invalid_answers,
+      ] });
+    } catch (err) {
+      error = err;
+    }
+    expect( error instanceof ReferenceError, `Not a ReferenceError` ).to.be.true;
+    expect( error.message.includes(`ALK0295`), `Missing log code ALK0295` ).to.be.true;
+    expect( error.message.includes(`ALK0296`), `Missing log code ALK0296` ).to.be.true;
+  });
+
+  it(`will not throw ALK0295 or ALK0296 if all required handlers are present`, async function() {
+    let error = null
+    try {
+      await scope.wait_until_continued( scope, { post_nav_handlers: [
+        scope.throw_on_system_error,
+        scope.throw_on_non_navigation_timeout,
+      ] });
+    } catch (err) {
+      error = err;
+    }
+    expect( error.message.includes(`ALK0295`), `Unwanted log code ALK0295 is present` ).to.be.false;
+    expect( error.message.includes(`ALK0296`), `Unwanted log code ALK0296 is present` ).to.be.false;
+  });
+
+});