@suffolklitlab/alkiln 5.17.0 → 5.17.1-detect-upload-1

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
@@ -383,7 +384,7 @@ When(/I? ?gets? to ?.*?(".*").*?with.*?(?:this data:)?/i, {timeout: -1}, async (
 
       // Set up the timeout that avoids infinite loops
       let on_page_timeout = async function() {
-
+        // Will throw
         let non_reload_report_msg = `The target id or ids were ${ target_ids }, but it took `
         + `too long to try to reach a valid id (over ${ scope.timeout/1000/60 } min). The `
         + `test got stuck on "${ id }".`
@@ -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,25 +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 = 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.
+          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 );
 
-          // Discuss: use Log class to throw this error?
-          if ( error.was_found ) { await scope.throwPageError( scope, { id: id }); }
-          resolve();
         } 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 );
@@ -498,12 +508,9 @@ When(/I wait ?(?:for)? (\d*\.?\d+) seconds?/, { timeout: -1 }, async ( seconds )
   * - I wait 1 second
   * - I wait .5 seconds
   *
-  * Questions:
-  * - Should this really reset the 'navigated' flag? Should the below
-  *     return succeed or fail? e.g:
-  *     I tap to continue; I wait 10 seconds; I arrive at the next page;
-  *     Maybe the 'navigated' flag should only be reset just before trying to
-  *     navigate (after pressing a button)
+  * Discuss: Should this reset the 'navigated' flag? Maybe the 'navigated' flag
+  *     should only be reset just before trying to navigate (after pressing a
+  *     button.)
   */
   return wrapPromiseWithTimeout(
     scope.afterStep(scope, {waitForTimeout: (parseFloat( seconds ) * 1000)}),
@@ -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,41 +632,23 @@ 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) => {  // √
-  /* Tests for detection of url change from button or link tap.
-  *    Can other things trigger navigation? Re: other inputs things
-  *    like 'Enter' acting like a click is a test for docassemble */
-  let msg = `The page should have stopped the user from continuing, but the user was able to continue.`;
-  if ( scope.navigated ) { reports.addToReport(scope, { type: `error`, code: `ALK0075`, value: msg }); }
-  expect( scope.navigated, msg ).to.be.false;
-
-  await scope.afterStep(scope);
-});
-
-Then('I will be told an answer is invalid', async () => {  // √
-
-  let { was_found, error_handlers } = await scope.checkForError( scope );
+Then(/I will be told (?:an answer is)?(?:some )?(?:all )?(?:answers are)? invalid/i, async () => {  // √
 
-  let no_error_msg = `No error message was found on the page`;
-  if ( !was_found ) { reports.addToReport(scope, { type: `error`, code: `ALK0076`, value: no_error_msg }); }
-  expect( was_found, no_error_msg ).to.be.true;
+  let { ok, type } = await scope.checkForErrors( scope );
 
-  let was_user_error = error_handlers.complex_user_error !== undefined || error_handlers.simple_user_error !== undefined;
-  let not_user_error_msg = `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.`;
-  if ( !was_user_error ) { reports.addToReport(scope, { type: `error`, code: `ALK0077`, value: not_user_error_msg }); }
-  expect( was_user_error, not_user_error_msg ).to.be.true;
-
-  await scope.afterStep(scope);
-});
+  let report_msg = null;
+  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` );
 
-Then('I arrive at the next page', async () => {  // √
-  /* Tests for detection of url change from button or link tap.
-  *    Can other things trigger navigation? Re: other inputs things
-  *    like 'Enter' acting like a click is a test for docassemble */
-  let msg = `User did not arrive at the next page.`
-  if ( !scope.navigated ) { reports.addToReport(scope, { type: `error`, code: `ALK0078`, value: msg }); }
-  expect( scope.navigated, msg ).to.be.true;
   await scope.afterStep(scope);
 });
 
@@ -820,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 ) => {
@@ -849,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 () => {
@@ -1458,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
@@ -1603,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/lib/utils/Log.js

@@ -284,8 +284,9 @@ class Log {
    *
    * @param { Object } console_opts - Required. Metadata and functional flags
    *     and data.
-   * @param { "success"|"info"|"warn"|"error" } console_opts.level - Required.
-   *     The log level. Functional and metadata. Defined by the internal caller.
+   * @param { "success"|"info"|"warn"|"error"|"throw" } console_opts.level -
+   *     Required. The log level. Functional and metadata. Defined by the
+   *     internal caller.
    * @param { string } console_opts.before - Optional. Text to add before the
    *     metadata of the log. Metadata. Default "".
    * @param { string } console_opts.icon - Required. Unicode char put at the
@@ -426,9 +427,9 @@ class Log {
      *
      * @param { Object } console_opts - Required. Metadata and functional flags
      *     and data.
-     * @param { "success"|"info"|"warn"|"error" } console_opts.level - Required.
-     *     The log level. Functional and metadata. Defined by the internal
-     *     caller.
+     * @param { "success"|"info"|"warn"|"error"|"throw" } console_opts.level -
+     *     Required. The log level. Functional and metadata. Defined by the
+     *     internal caller.
      * @param { string } console_opts.before - Optional. Text to add before the
      *     metadata of the log. Metadata. Default "".
      * @param { string } console_opts.icon - Required. Unicode char put at the
@@ -459,6 +460,7 @@ class Log {
      *
      * @example
      * log.debug()
+     * // In debug_log.txt, not in the console:
      * // 🐛 ALK000d DEBUG [2024-08-16 00:38:49UTC]:
      * */
 
@@ -809,7 +811,7 @@ class Log {
      * @returns { string } Formatted metadata and logs.
      *
      * @example
-     * log.warn({
+     * log.success({
      *   before: "~~~",
      *   code: "ALK00d3",
      *   context: "demo",
@@ -843,7 +845,7 @@ class Log {
      * @returns { string } Formatted metadata and logs.
      *
      * @example
-     * log.warn({
+     * log.info({
      *   before: "~~~",
      *   code: "ALK00d4",
      *   context: "demo",
@@ -910,7 +912,7 @@ class Log {
      * @returns { string } Formatted metadata, logs, and, if given, the error.
      *
      * @example
-     * log.warn({
+     * log.error({
      *   before: "~~~",
      *   code: "ALK00d5",
      *   context: "demo",

package/lib/utils/session_vars.js

@@ -90,6 +90,9 @@ session_vars.get_max_tests_per_template_scenario = function() {
 }
 
 session_vars.get_da_server_url = function () {
+  /** 
+   * @returns { string } - the server url. Example: https://awesome_law.example
+   * */
   try {
     let url = process.env.SERVER_URL || process.env.BASE_URL;
     return url.replace(/\/$/g, '');  // Remove any trailing slash for safety
@@ -99,7 +102,10 @@ session_vars.get_da_server_url = function () {
 };
 
 session_vars.get_branch_name = function () {
-  /* Get the name of the repository's branch that is being tested */
+  /**
+   * @returns {string} - the name of the branch that is being tested. Example:
+   *   the_branch
+   * */
   let branch_name = null;
   if ( process.env.BRANCH_PATH ) {
       branch_name = process.env.BRANCH_PATH.replace( `refs/heads/`, '' );
@@ -110,13 +116,21 @@ session_vars.get_branch_name = function () {
 };
 
 session_vars.get_package_name = function () {
-  /* Make an un-incremented project name based on the repo name and branch name. */
+  /**
+   * @returns {string} - an un-incremented package name based on the repo
+   *   name. Example: ThePackage
+   * 
+   * */
   let repo_url_without_trailing_slash = session_vars.get_repo_url().replace(/\/$/, '');
   let repo_name_parts = repo_url_without_trailing_slash.split('/');
   return repo_name_parts[ repo_name_parts.length - 1 ];
 };
 
 session_vars.get_project_base_name = function () {
+  /**
+   * @returns {string} - a valid docassemble Playground Project name, without
+   *   any attempt to make it unique. Example: ALKilnTestThePackagethebranch
+   * */
   let name = `ALKilnTest${ session_vars.get_package_name() }${ session_vars.get_branch_name() }`;
   let sanitized_name = name.replace( /[^A-Za-z0-9]/g, '' );
   return sanitized_name;
@@ -139,12 +153,15 @@ session_vars.get_languages = function () {
 
 const project_name_key = `da_project_name`;
 session_vars.save_project_name = function ( project_name ) {
-  /* Saves the name of the project to a json obj so deletion can use it later.
-  *    Built for local as well as remote testing. Assumes a kosher string.
-  *    We avoided a list because of concerns over getting out of date.
-  *    Should we try to prevent someone overwriting a previous project name?
-  * 
-  * @param project_name { string } - purely alphanumeric string */
+  /**
+   * Saves the name of the project to a json obj so deletion can use it later.
+   *   Built for local as well as remote testing. Assumes a kosher string.
+   *   We avoided a list because of concerns over getting out of date.
+   *   Should we try to prevent someone overwriting a previous project name?
+   * 
+   * @param project_name { string } - purely alphanumeric string
+   * @returns {Object} - node fs file
+   * */
   const runtime_config_path = session_vars.get_runtime_config_path();
 
   // Warn local developers if file already exists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.17.0",
+  "version": "5.17.1-detect-upload-1",
   "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

@@ -10,6 +10,7 @@ Reasons for deletion:
 0173 - redundant
 0181 - unknown
 0223 - changed Log behavior ("Only logs that throw should give a value to `error`.")
+0078 - removed unsupported Step "I arrive at the next page" and moved responsibility to Steps that navigate
 
 ALK0000:0
 ALK0001:1
@@ -89,7 +90,7 @@ ALK0074:1
 ALK0075:1
 ALK0076:1
 ALK0077:1
-ALK0078:1
+ALK0078:0
 ALK0079:1
 ALK0080:1
 ALK0081:1
@@ -291,3 +292,21 @@ ALK0276:1
 ALK0277:1
 ALK0278:1
 ALK0279:1
+ALK0280:1
+ALK0281:1
+ALK0282:1
+ALK0283:1
+ALK0284:1
+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/constrained_random_answers/valid.fixtures.js

@@ -573,7 +573,9 @@ Scenario: Keeps comment after table
   Given I start the interview at "file.yml"
   And ALKiln will get to "end" with:
     | var | possible_values |
-    | user_choice | correct;; wrong |
+    | choice_1 | correct;; wrong |
+    | choice_2 | a;; b;; c |
+    | choice_3 | 1;; 2;; 3 |
     # Comment 1 keep and repeat
 
 # Comment 2 keep and repeat`;

package/tests/unit_tests/fields.fixtures.js

@@ -3,6 +3,8 @@ let fields =  {};
 /** The fixtures in here are used in at least 2 types of tests:
  * - getAllFields
  * - getMatchignRows
+ * 
+ * ✏️ Fixtures are using HTML from docassemble versions <= 1.9.n
  * */
 
 // ============================
@@ -885,20 +887,22 @@ fields.proxy_substitution_i_is_1 = [
 // ============================
 // Signature
 // ============================
-// Signature page continue buttons are contained in a different DOM structure than regular ones
-// Also, there's an additional hidden continue button on the page with similar selectors
+// Signature page continue buttons are contained in a different DOM structure
+//   than other pages. Also, there's an additional continue button on the page
+//   with similar selectors. One continue button is hidden on wide screens while
+//   the other is hidden on narrow screens.
 fields.signature = [
   {
-    "selector": "#daquestion canvas",
+    "selector": "#daquestion canvas[id=\"dasigcanvas\"]",
     "tag": "canvas",
     "guesses": [
       {
-        "var": "c2lnbmF0dXJlXzE",
-        "value": ""
+        "value": "",
+        "var": "c2lnbmF0dXJlXzE"
       },
       {
-        "var": "signature_1",
-        "value": ""
+        "value": "",
+        "var": "signature_1"
       }
     ],
     "type": "",
@@ -1129,7 +1133,7 @@ fields.ajax = [
     "trigger": ""
   },
   {
-    "selector": "#daquestion input[id=\"ZmF2b3JpdGVfd29yZA\"][class=\"form-control da-ajax-combobox\"]",
+    "selector": "#daquestion input[id=\"ZmF2b3JpdGVfd29yZA\"][class=\"form-control da-ajax-combobox\"][role=\"combobox\"]",
     "tag": "input",
     "guesses": [
       {
@@ -1160,6 +1164,13 @@ fields.ajax = [
     "type": "",
     "trigger": ""
   },
+  {
+    "selector": "#daquestion button[class=\"btn btn-outline-secondary dacomboboxtoggle\"]",
+    "tag": "button",
+    "guesses": [],
+    "type": "button",
+    "trigger": ""
+  },
   {
     "selector": "#daquestion button[id=\"da-continue-button\"][class=\"btn btn-da btn-primary\"]",
     "tag": "button",

package/tests/unit_tests/getAllFields.test.js

@@ -2,7 +2,7 @@ const chai = require('chai');
 const expect = chai.expect;
 const deepEqualInAnyOrder = require('deep-equal-in-any-order');
 chai.use(deepEqualInAnyOrder);
-// We need jest or something, right? To do fancy stuff.
+// jest may let us store and update snapshots, but may discourage hand-checking
 
 const html = require('./html.fixtures.js');
 const fields = require('./fields.fixtures.js');

package/tests/unit_tests/html.fixtures.js

@@ -4,6 +4,8 @@
 * #trigger element is added into #daquestion, though it's not at
 * that location on the actual page. Otherwise, we'd have a lot more
 * html in here. In scope.js, it's found just using its id selector.
+* 
+* ✏️ Fixtures are using HTML from docassemble versions <= 1.9.n
 */
 
 let html = {};
@@ -586,7 +588,7 @@ html.proxy_substitution_i_is_0 = `
       <legend class="visually-hidden">Press one of the following buttons:</legend>
       <button class="btn btn-da btn-primary" id="da-continue-button" type="submit">Continue</button>
     </fieldset>
-    <input type="hidden" name="csrf_toke" value="ImNlMGRmOWY5NmQ4MGRjMjI0ZDQyNGFjMWRiYjdiODAzOTk2ZThhY2Ui.Zb7dOA.Fvil0jDP4mebaBoPmtM7sXv6wSQ"/>
+    <input type="hidden" name="csrf_token" value="ImNlMGRmOWY5NmQ4MGRjMjI0ZDQyNGFjMWRiYjdiODAzOTk2ZThhY2Ui.Zb7dOA.Fvil0jDP4mebaBoPmtM7sXv6wSQ"/>
     <input type="hidden" name="_event" value="WyJwcm94eV9saXN0WzBdLm5hbWUuZmlyc3QiXQ"/>
     <input type="hidden" name="_question_name" value="ID proxy vars"/>
     <input type="hidden" name="_tracker" value="3"/>

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;
+  });
+
+});