@suffolklitlab/alkiln 5.17.1 → 5.17.2-deps

package/lib/scope.js

@@ -211,6 +211,7 @@ module.exports = {
      *
      *    TODO: discuss splitting into `afterField` and `afterStep` or something. Or just change name
      *    TODO: Update to latest cucumberjs, which has `AfterStep`
+     *    Discuss: Move system error detection to afterStep()?
      */
 
     if ( scope.page ) {
@@ -232,8 +233,8 @@ module.exports = {
         let error_text_prop = await error_elem.getProperty( 'textContent' );
         let system_error_text = await error_text_prop.jsonValue();
 
-        reports.addToReport(scope, { type: `error`, code: `ALK0101`, value: system_error_text });
-        throw system_error_text;
+        let rpt_msg = reports.addToReport(scope, { type: `error`, code: `ALK0101`, value: system_error_text });
+        throw Error( rpt_msg );
       };
 
       // Wait for elements that might get revealed
@@ -254,10 +255,44 @@ module.exports = {
     if ( options.waitForTimeout ) { await time.waitForTimeout( options.waitForTimeout ); }
   },  // Ends afterStep
 
-  tapElementAndNavigate: async function(scope, { elem, waitForTimeout=null }) {
-    /** Tap a given element, detect navigation, and do appropriate related things. */
+  tapElementAndNavigate: async function(scope, {
+    elem,
+    post_nav_handlers=null,
+    waitForTimeout=null
+  }) {
+    /** 
+     * Tap a given element and expect successful navigation. Can tap action
+     *   button, link, continue button, etc. Unfortunately, we need more ways to
+     *   detect navigation. Ideas for detecting navigation:
+     *   https://github.com/SuffolkLITLab/ALKiln/issues/229.
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} kwargs - Named arguments
+     * @param {ElementHandle} kwargs.elem - Valid puppeteer element handle
+     * @param {int} [kwargs.waitForTimeout] - Max seconds before timing out
+     * @param {[function]} [kwargs.post_nav_handlers] - Functions to handle page
+     *     errors like system errors or invalid answers' markers
+     * 
+     * @returns {Object} kwrvs - Named return values
+     * @returns {bool} kwrvs.was_found - True if the check found any errors
+     * @returns {bool} kwrvs.ok - False if the check found any errors. Discuss:
+     *   Should we only use `ok` for internal errors?
+     * @param {user|system} kwrvs.type - "user" with invalid answers, "system"
+     *   with da or AL server errors
+     * @param {[ElementHandle]} kwrvs.error_handles - List of puppeteer element
+     *   handles the check found. There can be multiple invalid answer elems.
+     * */
+    await scope.log_and_update_if_new_page_id( scope );
+  
+    // TODO: We sometimes log multiple error messages for an error because we're
+    //   logging at multiple levels. Can we refactor to log them just once?
+
+    let { id: initial_id } = await scope.examinePageID( scope, 'none to match' );
+    let error_data = await scope.checkForErrors( scope );
+    // Saves a lot of time in cases where we must otherwise wait for timeout
+    await scope.throw_on_system_error( scope, { error_data, id: initial_id });
 
-    let start_url = await scope.page.url();  // so we can later check for navigation
+    let start_url = await scope.page.url();  // for navigation detection later
 
     await scope.tapElementAndStayOnPage(scope, {
       elem,
@@ -267,30 +302,17 @@ module.exports = {
       ]
     });
 
-    // For other ideas for detecting navigation, see
-    // https://github.com/SuffolkLITLab/ALKiln/issues/229
-    let end_url = await scope.page.url();
-    let navigated = start_url !== end_url;
+    let navigated = false;
+    ({ error_data, navigated } = await scope.wait_until_continued( scope, {
+        url: start_url, id: initial_id, post_nav_handlers
+    }));
 
-    // Might be able to handle this in `scope.afterStep`
-    if ( navigated ) {
-
-      // 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: ( waitForTimeout || 200 ),
-        navigated: true
-      });
-    } else {
-      // Discuss: Fail here or later since the test didn't manage to navigate?
-      await scope.afterStep(scope, {
-        waitForTimeout: ( waitForTimeout || 0 ),
-        navigated: false
-      });
-    }
+    // If navigation, wait for 200ms to let things finish loading and moving
+    if ( navigated ) { waitForTimeout ??= 200; }
+    await scope.afterStep( scope, {
+      waitForTimeout: waitForTimeout, navigated,
+    });
+    return error_data;
   },  // Ends scope.tapElementAndNavigate()
 
   nav_race: function(scope, opts={}) {
@@ -344,16 +366,27 @@ module.exports = {
       // for that text too. Also, puppeteer will ensure proper timeout.
       await Promise.race([
         click_promises,
-        // This is meant to detect user-visible alerts/errors,
+        // This is meant to detect user-visible da or AL alerts/errors,
         // not breaking errors in the testing code.
         // No need for aborters since puppeteer has its own timeout
-        // TODO: Be more specific. Authors may use `.alert-danger` themselves.
-        scope.page.waitForSelector('.alert-danger', { visible: true }),
+
+        // If this accidentally navigates, these will detect that the page has
+        //   navigated.
+        // Discuss: Is intention to stay on this page? So throw on navigation?
+        
+        // Discuss: `validation code` message can be on a page even after user fixed
+        //   values. Always dismiss `validation code` before trying to continue? Or
+        //   just detect navigation through requests and responses, which we need to
+        //   switch to anyway.
+        // TODO: Do we need to check these elements' bounding boxes first since
+        //   puppeteer doesn't recognize if parents are hidden?
+        scope.page.waitForSelector(`#daflash .alert-danger`, { visible: true }),
         scope.page.waitForSelector('.da-has-error', { visible: true }),
       ]);
     } catch ( error ) {
       if ( error.name === `TimeoutError` ) {
-        let non_reload_report_msg = `After ALKiln tapped "${ tapperText }" it took too long to load the next page.`;
+        // TODO: Discuss - this is a navigation timeout even though the tap shouldn't navigate
+        let non_reload_report_msg = `After ALKiln tapped "${ tapperText }" it took too long to detect a change on the page.`;
         await scope.handle_page_timeout_error( scope, { non_reload_report_data: {
           code: `ALK0103`,
           message: non_reload_report_msg,
@@ -361,8 +394,8 @@ module.exports = {
       } else {
         // Throw any non-timeout error
         let err_msg = `An error occurred when ALKiln tried to tap "${ tapperText }".`
-        reports.addToReport( scope, { type: `error`, code: `ALK0104`, value: err_msg });
-        throw error;
+        let rpt_msg = reports.addToReport( scope, { type: `error`, code: `ALK0104`, value: [ err_msg, error ].join(`\n`) });
+        throw Error( rpt_msg );
       }  // ends if error is timeout error
 
     }  // ends try/catch
@@ -557,25 +590,39 @@ module.exports = {
     return false;
   },
 
+  // ⚠️ Any selectors I find seem somewhat precarious.
   continue_button_selector_da_v_1_9_n_and_earlier: `fieldset.da-field-buttons button[type="submit"].btn-primary`,
   continue_button_selector_da_v_1_10_n_and_later: `button[type="submit"]#da-continue-button`,
   continue_button_selector_backup_da_v_1_9_n_and_earlier: `.da-fieldset.da-field-buttons button[type="submit"].btn-primary`,
+  // Discuss: Use only the broadest selector or keep these first 2 as well?
   signature_cont_btn_selector_da_v_1_9_n_and_earlier: `fieldset .dasigsave`,
-
   signature_cont_btn_selector_backup_da_v_1_9_n_and_earlier: `.da-fieldset .dasigsave`,
   // ⚠️ docassemble >= 1.10.n, 2 signature page continue buttons. One visible on
   //   wide screen, one visible on narrow screen. We need to get the visible
   //   one, but puppeteer v22.15.0 doesn't recognize an element with a hidden
   //   ancestor as invisible, so we need to get both `.dasigsave` and test for
-  //   visibility our own way for now.
+  //   visibility with the bounding box for now.
   signature_cont_btn_selector_da_v_1_10_n_and_later: `.dasigsave`,
-  continue: async function ( scope ) {
+  continue: async function ( scope, { post_nav_handlers=null }={}) {
     /**
      * Presses whatever button it finds that might lead to the next page.
      * 
-     * @param {object} scope - Tests state object
+     * @param {Object} scope - Tests state object
+     * @param {Object} obj - Named arguments
+     * @param {[function]} [obj.post_nav_handlers] - Functions to handle page
+     *     errors like system errors or invalid answers' markers
+     * 
+     * @returns {Object} obj - Named return values
+     * @returns {bool} obj.was_found - True if the check found any errors
+     * @returns {bool} obj.ok - False if the check found any errors. Discuss:
+     *   Should we only use `ok` for internal errors?
+     * @param {user|system} obj.type - "user" with invalid answers, "system"
+     *   with da or AL server errors
+     * @param {[ElementHandle]} obj.error_handles - List of puppeteer element
+     *   handles the check found. There can be multiple invalid answer elems.
      * */
-    // ⚠️ Any selectors I find seem somewhat precarious.
+    await scope.log_and_update_if_new_page_id( scope );
+
     let elem_lists = [
       // non-signature pages (these are the most consistent ways)
       await scope.page.$$(scope.continue_button_selector_da_v_1_9_n_and_earlier, { visible: true }),
@@ -606,7 +653,10 @@ module.exports = {
     }
 
     // Waits for navigation or user error
-    await scope.tapElementAndNavigate( scope, { elem: continue_button });
+    let error_data = await scope.tapElementAndNavigate( scope, {
+      elem: continue_button, post_nav_handlers
+    });
+    return error_data;
   },  // Ends scope.continue()
 
   continue_exists: async function ( scope ) {
@@ -632,7 +682,6 @@ module.exports = {
     let signature_da_v_1_10_x = await scope.page.$(scope.signature_cont_btn_selector_da_v_1_10_n_and_later, { visible: true });
 
     return regular !== null || regular_da_v_1_10_x !== null || regular_backup !== null || signature !== null || signature_backup !== null || signature_da_v_1_10_x !== null;
-
   },  // Ends scope.continue_exists()
 
   tapTab: async function ( scope, tab_id ) {
@@ -646,8 +695,9 @@ module.exports = {
     await scope.waitForTab( scope, { tab_id });
   },
 
-  checkForA11y: async function (scope ) {
+  checkForA11y: async function ( scope ) {
     /** Return if there were any violations and the file containing aXe output with more details of the checks */
+    // Discuss: What problem was the page id solving? When was there a mismatch?
     let { id } = await scope.examinePageID( scope, 'none to match' );
     if ( scope.page_id !== id ) {
       reports.addToReport(scope, { type: `page_id info`, code: `ALK0108`, value: `${ id }`, });
@@ -682,13 +732,30 @@ module.exports = {
   },
 
   tapSelectorToNavigate: async function ( scope, selector, waitForTimeout ) {
+    /**
+     * Taps an element matching the selector string, expecting to navigate.
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {str} selector - Selector of the element to tap
+     * @param {int} waitForTimeout - Max seconds before timing out
+     * 
+     * @returns {Object} obj - Named return values
+     * @returns {bool} obj.was_found - True if the check found any errors
+     * @returns {bool} obj.ok - False if the check found any errors. Discuss:
+     *   Should we only use `ok` for internal errors?
+     * @param {user|system} obj.type - "user" with invalid answers, "system"
+     *   with da or AL server errors
+     * @param {[ElementHandle]} obj.error_handles - List of puppeteer element
+     *   handles the check found. There can be multiple invalid answer elems.
+     * */
     let elem = await scope.page.$(`${ selector }`);
-    let error_msg = `Couldn't find "${ selector }" on the page, is there a typo?`;
+    let error_msg = `Couldn't find "${ selector }" on the page. Is there a typo?`;
     if ( !elem ) {
       reports.addToReport(scope, { type: `error`, code: `ALK0111`, value: error_msg });
     }
     expect( elem, error_msg ).to.exist;
-    await scope.tapElementAndNavigate( scope, { elem, waitForTimeout });
+    let error_data = await scope.tapElementAndNavigate( scope, { elem, waitForTimeout });
+    return error_data;
   },
 
   tapSelectorAndStay: async function ( scope, { selector }) {
@@ -1132,7 +1199,6 @@ module.exports = {
         // TODO: Do we need daaota as well? ("all of the above")
       }
 
-      // Am I doing this wrong? the guesses aren't just the name, right?
       let var_names = await scope.getPossibleDecodedNames( scope, {
         not_decoded: encoded_name,
         field_like_names,
@@ -1155,6 +1221,8 @@ module.exports = {
         values.push( node.attribs.value );
       }
 
+      // TODO: Try replacing null coalescing with using the guesses as var
+      //   names.
       field_data.guesses ??= await scope.add_values_if_needed( scope, { var_names, values });
       if ( scope.is_button_ish( scope, { field: field_data }) ) {
         // Discuss: This makes sure buttons are matched with table rows last. Is
@@ -1195,12 +1263,21 @@ module.exports = {
      * */
     let question_data = { ok: false, status: -1 };
     let question_response = null;
-    let err_msg = `Docassemble couldn't process this page's JSON. ALKiln will`
-      + ` do its best, but may fail. We would love a report for this.`;
 
     try {
-      question_response = await scope?.page?.evaluate?.( async ( err_msg ) => {
+      question_response = await scope?.page?.evaluate?.( async () => {
         /**
+         * Return da "question data" from the server for the current page
+         * 
+         * ‼️ On system error caused by `GET` request, AL's da v1.9.n first
+         *   detects the error, but it stays invisible to the DOM since the
+         *   page hasn't been reloaded. Then, when the test presses to
+         *   continue, a new error appears. Unfortunately, the old error is
+         *   lost, so we won't be able to retrieve it through the DOM. We may
+         *   want to switch to catching errors during the field-getting part
+         *   of the life-cycle if we want to be able to handle this robustly.
+         *   I'm not sure what other issues will arise at that point.
+         * 
          * @returns {object} -
          *   { ok: false };  // ok -> response status or false
          *   | { ok, status, ...data, ...( await response.json() ) }
@@ -1208,7 +1285,9 @@ module.exports = {
          *   | { ok, status, alk_msg: err_msg }
          *   | { ok: false, alk_msg: err_msg, error: response_err.message }
          * */
-        let data = { ok: false, alk_msg: null };  // ok -> did we get JSON or not
+        let q_resp_err_msg = `Docassemble couldn't process this page's JSON. ALKiln's`
+        + ` will do its best, but may fail. We would love a report for this.`;
+        let data = { ok: false, alk_msg: null };
         try {
           let response = await fetch(
             window.location.href.replace(`interview?`, `interview?json=1&`)
@@ -1217,41 +1296,29 @@ module.exports = {
           data.ok = response.ok;
           data.status = response.status;
 
-          // ‼️ On system error caused by `GET` request, AL's da v1.9.n first
-          //   detects the error, but it stays invisible to the DOM since the
-          //   page hasn't been reloaded. Then, when the test presses to
-          //   continue, a new error appears. Unfortunately, the old error is
-          //   lost, so we won't be able to retrieve it through the DOM. We may
-          //   want to switch to catching errors during the field-getting part
-          //   of the life-cycle if we want to be able to handle this robustly.
-          //   I'm not sure what other issues will arise at that point.
-
           let content_type = response?.headers?.get?.(`content-type`);
           if ( content_type?.startsWith?.(`application/json`) ) {
             return { ...data, ...( await response.json() ) };
 
           } else if ( content_type?.startsWith?.(`text/plain`) ) {
-            // NOTE: Assembly Line will obscure docassemble error content it
-            //   doesn't handle, making its error page unhelpful. In future, we
-            //   do more with the actual page response.
-            return { ...data, alk_msg: err_msg, html: await response.text() };
+            return { ...data, alk_msg: q_resp_err_msg, html: await response.text() };
 
           } else {
-            // Research: How can we get in here? What other content-types that we
-            //   could get give response ok?
-            return { ...data, alk_msg: err_msg, content_type };
+            // Research: How can we get in here? What other content-types that
+            //   we could get give response ok?
+            return { ...data, alk_msg: q_resp_err_msg, content_type };
           }  // ends content-type check
 
         } catch ( response_err ) {
           // Error might be caused by non-da page author navigated to when, for
           //   example, testing an "Exit" destination.
-          return { ok: false, alk_msg: err_msg, error: response_err.message, }
+          return { ok: false, alk_msg: q_resp_err_msg, error: response_err.message, }
         }  // ends fetch try
         
         return data;
-      }, err_msg );  // ends page.evaluate() call
+      } );  // ends page.evaluate() call
     } catch ( question_data_error ) {
-      question_response = { ok: false, alk_msg: err_msg, error: question_data_error.message, }
+      question_response = { ok: false, alk_msg: q_resp_err_msg, error: question_data_error.message, }
     }
 
     question_data = question_response || question_data;
@@ -1444,7 +1511,13 @@ module.exports = {
     // Really need everything to be unique here if at all possible. Shall we resort
     // to parents and n-th child?
     // Exceptions: Some specific fields can be duplicates without being dangerous
-    if ( matching_nodes.length > 1 && !selector.includes(`[class="file-caption-name"]`) ) {
+    if (
+      matching_nodes.length > 1
+      && !selector.includes(`[class="file-caption-name"]`)
+      && !selector.includes(`fileinput-cancel`)  // File upload
+      && !selector.includes(`fileinput-remove`)  // File upload
+      && !selector.includes(`kv-file`)  // File upload
+    ) {
       let msg = `${ matching_nodes.length } items on this page matched the base64 encoded name '${ selector }'. You may be setting the same variable in multiple places on this page.`;
       reports.addToReport(scope, { type: `warning`, code: `ALK0125`, value: msg });
     }
@@ -1946,7 +2019,7 @@ module.exports = {
     );
     if ( final_matching_rows.length == 0) {
       log.debug({ code: `ALK0132`, context: `matching`, },
-        `0 matching rows. Field:`, field
+        `0 matching rows for this field on the page:`, field
       );
     }
 
@@ -2046,7 +2119,6 @@ module.exports = {
     // Pass in the selector as an argument
     }, field.selector );
 
-
     return handle;
   },  // Ends scope.get_handle_from_field()
 
@@ -2180,10 +2252,12 @@ module.exports = {
 
   enter_answer: {
     button: async function ( scope, { handle, answer }) {
+      // For ambiguous tap discussion, see https://github.com/SuffolkLITLab/ALKiln/issues/1127
       await scope.tapElementAndNavigate( scope, { elem: handle });
       return true;
     },
     a: async function ( scope, { handle, answer }) {
+      // For ambiguous tap discussion, see https://github.com/SuffolkLITLab/ALKiln/issues/1127
       await scope.tapElementAndNavigate( scope, { elem: handle });
       return true;
     },
@@ -2256,7 +2330,7 @@ module.exports = {
         await scope.afterStep(scope, { waitForShowIf: true });
         
       } else if ( type === `file` ) {
-        row_was_used = await scope.uploadFiles( scope, { handle, answer });
+        row_was_used = await scope.upload_files( scope, { handle, answer });
         await scope.afterStep(scope, { waitForShowIf: true });
 
       } else if (type == `date`) {
@@ -2336,7 +2410,7 @@ module.exports = {
     return valid_date;
   },  // Ends scope.today_to_date()
 
-  findFiles: async function( scope, {to_find_names}) {
+  find_files: async function( scope, {to_find_names}) {
     /** Returns a list of paths to the sources folder associated
     *    with the given list of file names.
     * 
@@ -2393,9 +2467,9 @@ module.exports = {
       return [];
     }
     return paths;
-  },  // Ends scope.findFiles()
+  },  // Ends scope.find_files()
 
-  uploadFiles: async function ( scope, { handle, answer }) {
+  upload_files: async function ( scope, { handle, answer }) {
     /* Try to upload one or more files to a file-type input field.
     *    Does not submit, so no danger of timeout with server reload.
     * 
@@ -2405,8 +2479,8 @@ module.exports = {
     // First make sure the list of files was defined. Don't remove spaces yet -
     // allow a typo where someone forgot to include a space after a comma.
     let to_find_names = answer.split(`,`);
-    let paths = await scope.findFiles(scope, {to_find_names});
-    if (paths.length == 0) {
+    let paths = await scope.find_files(scope, {to_find_names});
+    if ( paths.length == 0 ) {
       // The row wasn't used
       return false;
     }
@@ -2418,16 +2492,17 @@ module.exports = {
     //   it's not completely necessary. If the gobal `setTimeout` fires then the
     //   `evaluate` won't be far behind. They both use about the same timeout
     //   duration.
-    let finish_uploading = handle.evaluate( async function detect_finished_upload(
+    let finish_uploading = handle.evaluate( async function (
       elem, timeout, answer
     ) {
       return new Promise (( resolve, reject ) => {
         /**
          * Resolve when upload completes. Logging in here will log to the hidden
          *   browser. Must instead pass information out with `resolve`.
+         * 
+         * Warn about uploading the same file multiple times. It won't protect
+         * against accidentally uploading same file to a different field.
          * */
-        // Warn about uploading the same file multiple times
-        // Won't protect against accidentally uploading same file to diff field
 
         // If elem.files, the author has previously set this field. Warn them.
         // Example prev_filenames: "C:\\fakepath\\name_of_file.png"
@@ -2447,13 +2522,13 @@ module.exports = {
 
         let result = {
           ok: false, prev_filenames, type: null,
-          code: `ALK0283`, level: `debug`, msgs: [], error: null,
+          code: `ALK0283`, level: `info`, msgs: [], error: null,
         };
 
-        if ( prev_filenames ) {
+        if (( prev_filenames?.length || 0) > 0 ) {
           result.level = `warn`;  // log level
           result.type = `warning`;  // report type
-          shared_names = shared_names_list.join(`", "`);
+          let shared_names = shared_names_list.join(`", "`);
 
           if ( shared_names_list.length > 0 ) {
             if ( all_matched ) {
@@ -2471,9 +2546,10 @@ module.exports = {
 
         let timeout_id = null;
         let resolve_on_change = function() {
+          // bootstrap-fileinput starts reading
           result.ok = true;  // May contain warnings
           clearTimeout( timeout_id );
-          result.msgs.push(`Finished uploading these files: "${ answer }"`);
+          result.msgs.push(`Started uploading these files: "${ answer }"`);
           resolve( result );
         };
 
@@ -2494,7 +2570,7 @@ module.exports = {
       });  // ends Promise
 
     }, scope.timeout - 100, answer );  // ends page.evaluate()
-    
+
     await handle.uploadFile(...paths);
 
     // Wait for upload to finish. If already done, execution will continue
@@ -2515,9 +2591,31 @@ module.exports = {
     if ( level === `throw` ) { log_type = `throw`; }
     log[ log_type ]({ code, level, error, context: `file_upload`}, ...msgs );
 
+    // LLM Claude (version?) description: While the bootstrap-fileinput is
+    //   reading, it disables the input, adds `is-locked` to its container
+    //   (lock()), and adds `file-thumb-loading` (_toggleLoading("show")). We'll
+    //   wait till these are gone. See GitHub #1125. @plocket tested these
+    //   classes out and said they seem legit.
+    await scope.page.waitForFunction(
+      ( el ) => {
+        const container = el.closest(`.file-input`);
+        return (
+          !el.disabled
+          && !( container?.classList?.contains?.(`is-locked`)
+            || container?.classList?.contains?.(`file-thumb-loading`)
+        ));
+      },
+      { timeout: scope.timeout - 100 },
+      handle,
+    );
+
+    log.debug({ code: `ALK0297`, context: `file_upload`, level: `info`, },
+      `Finished uploading files`
+    );
+
     // Return whether successfully used row
     return ok;
-  },  // Ends scope.uploadFiles()
+  },  // Ends scope.upload_files()
 
   setCheckbox: async function ( scope, { label, answer }) {
     // Depending on the current value/status of a checkbox and the desired
@@ -2622,32 +2720,28 @@ module.exports = {
     return risky_id.toLowerCase().replace(/[^A-Za-z0-9]+/g, '-');
   },
 
-  examinePageID: async function ( scope, question_id = '' ) {
-    /* Looks for a sanitized version of the question id as it's written
-    *     in the .yml. docassemble's way in python:
-    *     re.sub(r'[^A-Za-z0-9]+', '-', interview_status.question.id.lower())
-    * 
-    * @returns { question_has_id: bool, id: str, id_matches: bool }
-    */
-    let id_as_class = question_id.toLowerCase().replace(/[^A-Za-z0-9]+/g, '-');
-    // `.className` is the node's list of classes as a string, separated by spaces
-    let classes_str = await scope.page.$eval(`body`, function (elem) { return elem.className });
-    let ids_found = classes_str.match(/question-([^ ]+)/);
-
-    // Data that we've decided is useful for our purposes
-    let found_any_question_id = ids_found !== null;
-    // If there is an id, see if it matches the class
-    let id = null;
-    let ids_match = false;
-    if ( found_any_question_id ) {
-      id = ids_found[1]
-      ids_match = id === id_as_class;
-    }
-
-    // TODO: What are good names for these properties?
-    // question_has_id? found_any_id?
-    // class_matches_id? class_and_id_do_match? id_and_page_id_match?
-    return { question_has_id: found_any_question_id, id: id, id_matches: ids_match };
+  examinePageID: async function ( scope, page_id = `` ) {
+    /** Looks for a sanitized version of the question id as it's written
+     *     in the .yml. docassemble's way in python:
+     *     re.sub(r'[^A-Za-z0-9]+', '-', interview_status.question.id.lower())
+     * 
+     * TODO: Replace use of this method with refactored functionality in
+     *   `current_id_matches`, `id_as_class_name`, and
+     *   `current_page_id_class_name`
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} obj - Named arguments
+     * @param {str} obj.id_to_match - A docassemble page id, possibly in .yml
+     *   format
+     * 
+     * @returns { question_has_id: bool, id: str, id_matches: bool }
+     * */
+    // let id_to_match = page_id.toLowerCase().replace(/[^A-Za-z0-9]+/g, '-');
+    let id_to_match = await scope.id_as_class_name( scope, { page_id });
+    let current_id = await scope.current_page_id_class_name( scope );
+    let question_has_id = !!current_id || false;
+    let id_matches = id_to_match === current_id;
+    return { id: current_id, question_has_id, id_matches };
   },  // Ends scope.examinePageID()
 
   // TODO: Rename var_data to input_data?
@@ -2659,7 +2753,7 @@ module.exports = {
     ensure_navigation=true,
     ensure_all_vars_used=false
   }) {
-    /* Non-recursive function to set as many variables as possible before
+    /** Non-recursive function to set as many variables as possible before
     * continuing to the next page. Important to avoid recursion because of async ops.
     * If it's not data in a table, the code can be more permissive about some input.
     * 
@@ -2669,19 +2763,23 @@ module.exports = {
     *     if navigation is not triggered another way.
     * @param ensure_all_vars_used {bool} [false] = Default false. If true, errors if any
     *     object in var_data is not used during running of this function.
-    */
-    log.debug({ code: `ALK0221`, before: `~~~~~~~~~~~~~~\n`, },
-      `scope.setFields()`
+    * 
+    * @returns {Object} obj - Named return values
+    * @returns {bool} obj.was_found - True if the check found any errors
+    * @returns {bool} obj.ok - False if the check found any errors. Discuss:
+    *   Should we only use `ok` for internal errors?
+    * @param {user|system} obj.type - "user" with invalid answers, "system"
+    *   with da or AL server errors
+    * @param {[ElementHandle]} obj.error_handles - List of puppeteer element
+    *   handles the check found. There can be multiple invalid answer elems.
+    * */
+    log.debug({ code: `ALK0221`, before: `\n~~~~~~~~~~~~~~\n`, },
+      `Starting scope.setFields()`
     );
 
     let error_data = null;
 
-    // Only record the page id once for each page to which we navigate
-    let { id } = await scope.examinePageID( scope, 'none to match' );
-    if ( scope.page_id !== id ) {
-      reports.addToReport(scope, { type: `page_id info`, code: `ALK0138`, value: `${ id }`, });
-      scope.page_id = id;
-    }
+    let id = await scope.log_and_update_if_new_page_id( scope );
 
     let html = await scope.page.content();
     // These are the fields on the current page. Their handles should all exist.
@@ -2692,7 +2790,6 @@ module.exports = {
     // again until nothing more can be set.
     let something_new_was_set = true;  // So loop can start
     while ( something_new_was_set ) {
-
       something_new_was_set = false;  // start fresh
       // Go through each field on the page, seeing if we can set its variable
       for ( let field of fields ) {
@@ -2728,13 +2825,11 @@ module.exports = {
     if ( session_vars.get_debug() ) { await time.waitForTimeout(2000); }
 
     // Press a continue button with a story table variable name if it exists
-    let did_navigate = false;
-    let error = {};
+    let navigated = false;
     for ( let field of fields ) {
       // All other fields should have been set
       if ( scope.is_button_ish( scope, { field }) && field.type === 'submit' ) {
         let page_url = await scope.page.url();
-
         let row_used = await scope.setVariable( scope, { field, var_data, });
         if ( row_used ) {
 
@@ -2746,23 +2841,12 @@ module.exports = {
 
           // Esp important for `.target_number`
           await scope.increment_row_use( scope, { row: row_used });
+          ({ error_data, navigated } = await scope.wait_until_continued( scope, {
+              url: page_url, id
+          }));
 
-          // TODO: special continue/navigation button function that handles url and all?
-          
-          // Have to catch errors right now or may get stuck in an infinite loop?
-          // TODO: Don't catch errors - maybe the developer expected/wanted an error
-          // For now they'll have to stop the story table early and do the rest the slow way
-          // TODO: Discuss: add the option of throwing when an error happens? Per page?
-
-          // The developer said to continue by defining this row.
-          // For now, that means this page should not cause any kind of error.
-          // Make sure no system or user error messages appear
-          // Discuss moving this out of here. Having to pass in `id` just for
-          // these messages smells bad. Con: Already a lot of code out there.
-          error_data = await scope.waitUntilContinued( scope, { url: page_url, id });
-
-          did_navigate = true;
-          log.stdout({}, `\x1b[36m${ 'v' }\x1b[0m`);  // pressed button successfully
+          // pressed button to set var successfully
+          log.stdout({}, `\x1b[36m${ 'v' }\x1b[0m`);
           break;
 
         }  // ends if row_used
@@ -2780,43 +2864,35 @@ module.exports = {
           let { id } = await scope.examinePageID( scope, 'none to match' );
           let msg = `In a linear Step all the values you give MUST be filled in, but ALKiln was unable `
             + `to find a field on the page with the "${ id }" for the variable "${ original_row.var }" that `
-            + `could be set to "${ original_row.value }". See this Scenario's HTML file for details.`;
-          reports.addToReport(scope, { type: `error`, code: `ALK0141`, value: msg });
-          expect( 'The page is missing a field', msg ).to.equal( '' );
+            + `could be set to "${ original_row.value }". Alternatively, you`
+            + ` may have duplicate rows in your table. See this Scenario's HTML`
+            + ` file for details.`;
+          let err_msg = reports.addToReport(scope, { type: `error`, code: `ALK0141`, value: msg });
+          throw err_msg;
         }
       }
     }
 
     // If didn't already press a continue button, press one now.
-    if ( !did_navigate && ensure_navigation  ) {
-      // All fields on this page should be taken care of
+    if ( !navigated && ensure_navigation  ) {
+      // All fields on this page should have been taken care of already
       let page_url = await scope.page.url();
-      await scope.continue( scope );
-      // Have to catch errors right now or may get stuck in an infinite loop?
-      // TODO: Don't catch errors - maybe the developer expected/wanted an error
-      // For now they'll have to stop the story table early and do the rest the slow way
-      // TODO: Discuss: add the option of throwing when an error happens? Per page?
-
-      // Make sure no system or user error messages appear
-      // Discuss moving this out of here. Having to pass in `id` just for
-      // these messages smells bad. Con: Already a lot of code out there.
+      error_data = await scope.continue( scope );
 
-      error_data = await scope.waitUntilContinued( scope, { url: page_url, id });
+      navigated = true;
+      log.stdout({}, `\x1b[36m${ '>' }\x1b[0m`);  // continued successfully automatically
+    }  // ends if !navigated && ensure_navigation
 
-      did_navigate = true;
-      log.stdout({}, `\x1b[36m${ '>' }\x1b[0m`);  // continued successfully
-    }  // ends if !did_navigate && ensure_navigation
-
-    if ( did_navigate && scope.check_all_for_a11y ) {
+    if ( navigated && scope.check_all_for_a11y ) {
       let { passed } = await scope.checkForA11y(scope);
       if (!passed) {
         scope.passed_all_for_a11y = false;
       }
     }
 
-    // TODO: Since we now continue only once no matter what, we can put
-    // the error in the caller of the function, though we may want
-    // to pass the symbol to print as well.
+    log.debug({ code: `ALK0288`, context: `scenario`, level: `note`,
+      before: `\n~~~~~~~~~~~~~~\n` }, `Finished scope.setFields()`
+    );
     return error_data;
     // TODO: Maybe we should return something else or something in addition about used vars
   },  // Ends scope.setFields()
@@ -2824,7 +2900,8 @@ module.exports = {
   is_button_ish: function ( scope, { field = null }) {
     /**
      * Return true if the field is similar enough to a button, else false. This
-     *   does NOT determine whether the field submits the form.
+     *   does NOT determine whether the field submits the form, but does
+     *   assume the intention is navigation.
      * 
      * Discuss: Use "btn" class as well?
      * 
@@ -2836,10 +2913,87 @@ module.exports = {
     if ( field.tag === `button`
           || field.selector.includes(`role="button"`)
           || field.selector.includes(`.dasigsave`)
+          || field.selector.includes(`.daquestionactionbutton`)
        ) { return true; }
     return false;
   },
 
+  log_and_update_if_new_page_id: async function ( scope ) {
+    /**
+     * Log the page id if we're on a new page. Abstracting this avoids adding
+     *   multiple log codes.
+     * 
+     * Discuss: This triggers 2 puppeteer evals. Only 1 is really necessary. How
+     *   many pages id checks would make that speed hit matter? Consider copying
+     *   `.current_id_matches()` code in here to get the id just once.
+     * 
+     * @param {Object} scope - Tests state object
+     * 
+     * @returns {str} - the current page .yml id as an HTML class
+     * */
+    let ids_match = await scope.current_id_matches( scope, {
+      id_to_match: scope.page_id
+    });
+    if ( !ids_match ) {
+      let new_id = await scope.current_page_id_class_name( scope );
+      reports.addToReport(scope, { type: `page_id info`, code: `ALK0138`, value: `${ new_id }`, });
+      scope.page_id = new_id;
+    }
+    return scope.page_id;
+  },
+
+  current_id_matches: async function ( scope, { id_to_match=`` }) {
+    /**
+     * Returns true if the given docassemble page id matches the current page id
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} obj - Named arguments
+     * @param {str} obj.id_to_match - A docassemble page id, possibly in .yml
+     *   format
+     * 
+     * @returns {bool} - true if the ids match, otherwise false. Missing ids will match.
+     * */
+    let class_to_match = scope.id_as_class_name( scope, { page_id: id_to_match });
+    let current_id_class = await scope.current_page_id_class_name( scope );
+    return class_to_match === current_id_class;
+  },
+
+  id_as_class_name: function ( scope, { page_id=`` }) {
+    /**
+     * Converts a given page id string (possibly originating from the interview
+     *   .yml) as a class name as docassemble does, then returns that value.
+     *   This is useful because the .yml page id is included in the DOM as a
+     *   class name. docassemble's python code:
+     * 
+     *     re.sub(r'[^A-Za-z0-9]+', '-', interview_status.question.id.lower())
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} obj - Named arguments
+     * @param {str} obj.page_id - A docassemble page id, possibly in .yml format
+     * 
+     * @returns {str | null} - the given str as a docassemble-formatted
+     *   HTML class name or `null` if `page_id` is not a string.
+     * */
+    return page_id?.toLowerCase?.().replace(/[^A-Za-z0-9]+/g, `-`) || null;
+  },
+
+  current_page_id_class_name: async function ( scope ) {
+    /**
+     * Returns the current page id as an HTML class name or null if missing
+     * 
+     * @param {Object} scope - Tests state object
+     * 
+     * @returns {str | null} - Current page id as a class name or `null` if none
+     *   exists
+     * */
+    // `.className` is a space-sparated list of the node's classes
+    let possible_id_classes = await scope.page.$eval(`body`, function (elem) {
+      return elem.className
+    });
+    let id_matches = possible_id_classes?.match(/question-([^ ]+)/);
+    return id_matches?.[1] || null;
+  },
+
   increment_row_use: async function ( scope, { row }) {
     /** Accumulate number of times this row was used. Esp important for `.target_number`.
     *   Mutates `row` and its props. */
@@ -3072,105 +3226,369 @@ module.exports = {
     }
   },  // Ends scope.has_interview_content()
 
-  waitUntilContinued: async function ( scope, { url = '', id = '' }) {
-    /** Given a url, attempt to continue until the page url changes or an error
-        is found. Return the error object no matter what. */
-    let prev_url = url;
-    let curr_url = await scope.page.url();
-    let error_data = await scope.checkForError( scope );
+  // ⚠️ Keep text of `id=...` unique from others to identify problems better
+  wait_until_continued: async function ( scope, {
+    url=``, id=`Unknown id`, post_nav_handlers=null
+  }) {
+    /**
+     * Given a url and id of an initial page, attempt to detect navigation.
+     *   After the results of the navigation attempt, run the post_nav_handlers.
+     * 
+     * ‼️ ALWAYS include required critical error handlers in `post_nav_handlers`
+     *   that will throw errors. We need the post-navigation handlers in this
+     *   order:
+     * 
+     * 1.(required) A page with a visible system error is a critical error and always
+     *   trumps other errors, so it comes first
+     * 2. (optional) Invalid answers and other mmore specific handlers trump unspecified
+     *   nav errs
+     * 3. (required) Navigation attempt that timed out is a critical error that lacks
+     *   further information
+     * 4. (optional) Unspecified non-navigation catchall comes last
+     * 
+     * See docs/decisions/017_post_navigation_custom_behavior_2026_10_26.md for
+     *   a deeper discussion.
+     * 
+     * Unfortunately, our navigation detection game is weaksauce. Navigation
+     *   detection thoughts: https://github.com/SuffolkLITLab/ALKiln/issues/229
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} kwargs - Named arguments
+     * @param {str} kwargs.url - Assumed to be the url of the initial page
+     * @param {str} kwargs.id - ID of the initial page
+     * @param {[function]} [kwargs.post_nav_handlers] - Functions to handle page
+     *   errors like system errors, user errors (invalid answers), and
+     *   navigation failure
+     * 
+     * @returns {Object} kwrvs - Named return values
+     * @returns {bool} kwrvs.navigated - True if the interview got to a new page
+     * @returns {Object} kwrvs.error_data - Data for any errors found
+     * @returns {bool} kwrvs.error_data.was_found - True if the check found any
+     *   errors
+     * @returns {bool} kwrvs.error_data.ok - False if the check found any errors.
+     *   Discuss: Should we only use `ok` for internal errors?
+     * @returns {`user`|`system`} kwrvs.error_data.type - "user" with invalid
+     *   answers, "system" with da or AL server errors
+     * @returns {[ElementHandle]} kwrvs.error_data.error_handles - List of
+     *   puppeteer element handles the check found. There can be multiple
+     *   invalid answer elements.
+     * */
+    await scope.log_and_update_if_new_page_id( scope );
 
-    let timedOut = false;  // Lazy timeout?
-    let cont_timeout = setTimeout(function(){ timedOut = true }, scope.timeout);
+    post_nav_handlers ??= [
+      scope.throw_on_system_error,
+      scope.throw_on_invalid_answers,
+      scope.throw_on_non_navigation_timeout,
+      scope.throw_on_non_navigation_catchall,
+    ];
+    scope.throw_if_missing_required_post_nav_handlers( scope, { handlers: post_nav_handlers })
 
-    // Attempt to solve weird race condition issues where page has not properly continued
-    while ( curr_url === prev_url && error_data.ok && !timedOut ) {
+    let initial_id = id;
+    let initial_url = url;
+    let curr_url = await scope.page.url();
+    let error_data = await scope.checkForErrors( scope );
+
+    // Attempt to solve weird race condition issues where page has not properly
+    //   continued. May exceed actual current timeout.
+    // Discuss: Use a global clock to properly track of remaining time to avoid
+    //   scope.timeout - 100 and such? Any such cucumber or puppeteer feature?
+    let timed_out = false;  // Lazy timeout?
+    let nav_timeout = setTimeout(function(){ timed_out = true }, scope.timeout - 100);
+    while ( curr_url === initial_url && error_data.ok && !timed_out ) {
       await time.waitForTimeout( 50 );
+      error_data = await scope.checkForErrors( scope );
       curr_url = await scope.page.url();
-      error_data = await scope.checkForError( scope );
     }
+    clearTimeout( nav_timeout );
+
+    // TODO: Review architecture - can we refactor nav out of global state?
+    scope.navigated = curr_url !== initial_url;
 
+    error_data = await scope.checkForErrors( scope );
     if ( !error_data.ok ) {
-      await scope.throw_system_error( scope, { error_data, id: id });
-      // If trying to continue, shouldn't be running into user errors either
-      await scope.throw_invalid_answer( scope, { error_data, id: id });
+      for ( let handler of post_nav_handlers ) {
+        await handler( scope, { id: initial_id, error_data, timed_out });
+      }
     }
 
-    let timeout_err_message = `The test tried to continue to the next page, but it took longer than ${ (scope.timeout/1000)/60 } min. Check the picture of this page. If a secret variable was used, there will be no picture.`
-    if ( timedOut ) { reports.addToReport(scope, { type: `error`, code: `ALK0146`, value: timeout_err_message }); }
-    expect( timedOut, timeout_err_message ).to.be.false;
+    return { error_data, navigated: curr_url !== initial_url };
+  },  // Ends scope.wait_until_continued()
 
-    clearTimeout( cont_timeout );
+  throw_if_missing_required_post_nav_handlers: function( scope, { handlers=[] }={}) {
+    /**
+     * Return true if the list of functions contains the required handlers,
+     *   otherwise throw an internal error.
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} kwargs - Named arguments
+     * @param {[func]} kwargs.handlers - List of functions
+     * 
+     * @returns {bool} - True if function completes successfully
+     * */
+    let missing_handler_errors = [];
+    if ( !handlers.includes( scope.throw_on_system_error ) ) {
+      let missing_system_msg = log.debug({ code: `ALK0295`, context: `internal nav_handlers`, level: `error` },
+        `ALKiln's internal list of post-navigation handlers must include "scope.throw_on_system_error()"`
+      );
+      missing_handler_errors.push( missing_system_msg );
+    }
+    if ( !handlers.includes( scope.throw_on_non_navigation_timeout ) ) {
+      let missing_timeout_msg = log.debug({ code: `ALK0296`, context: `internal nav_handlers`, level: `error` },
+        `ALKiln's internal list of post-navigation handlers must include "scope.throw_on_non_navigation_timeout()"`
+      );
+      missing_handler_errors.push( missing_timeout_msg );
+    }
 
-    return error_data;
-  },  // Ends scope.waitUntilContinued()
+    if ( missing_handler_errors.length > 0 ) {
+      throw ReferenceError( missing_handler_errors.join(`\n`) );
+    }
 
-  checkForError: async function ( scope ) {
-    /* Returns whether any system or user error elements were found and, if so,
-    * returns those elements. The error elements are probably exclusive, but
-    * we're not sure. */
+    return true;
+  },
 
-    // All results are lists to match puppeteerjs `$x`
+  validation_err_selector: `#daflash .alert-danger`,
+  // Discuss: `validation code` message can be on a page even after user fixed
+  //   values. Always dismiss `validation code` before trying to continue? Or
+  //   just detect navigation through requests and responses, which we need to
+  //   switch to anyway.
+  // ⚠️ 'display:' and 'none' MUST be separated by a space
+  invalid_field_selector: `xpath/.//*[contains(@class, "da-has-error")][not(contains(@style,"display: none"))]`,
+  // ⚠️ Assumptions: ": Error" stays in the metadata of the page and #damain
+  //   only appears on da error pages
+  sys_err_selector: `xpath/.//meta[contains(@content, ": Error")]|.//*[@id="damain"]//h1[contains(text(), "Error")]`,
+  // `al_custom_error_action` in base64. Replaces system error pages, but acts
+  //   like a question screen. Shows "The error details are no longer
+  //   available..." message when GET requests error (default da message?)
+  al_err_selector: `.question-custom-error-action .daattributions #trigger[data-variable="YWxfY3VzdG9tX2Vycm9yX2FjdGlvbg"]`,
+  checkForErrors: async function ( scope ) {
+    /**
+     * Return any elements from invalid user answers or system errors & other
+     *   data. Avoid throwing. Invalid answers may be the author's goal.
+     * 
+     * Note: May later want the actual text of the invalid answer messages.
+     * 
+     * @param {Object} scope - Tests state object
+     * 
+     * @returns {Object} obj - Named return values
+     * @returns {bool} obj.was_found - True if the check found any errors
+     * @returns {bool} obj.ok - False if the check found any errors. Discuss:
+     *   Should we only use `ok` for internal errors?
+     * @param {user|system} obj.type - "user" with invalid answers, "system"
+     *   with da or AL server errors
+     * @param {[ElementHandle]} obj.error_handles - List of puppeteer element
+     *   handles the check found. There can be multiple invalid answer elems.
+     * */
+    // ⚠️ Keep these error objs in this order. For now, the first item on the
+    //   list is the one we later use, and `system` errors have priority.
     let possible_error_types = [
-      // TODO: Be more specific. Author can also use a `.alert-danger` call out.
-      { type: `user`, handlers: await scope.page.$$(`.alert-danger`) },
-      // The below does not work if there's not a space between ':' and 'none'
-      { type: `user`, handlers: await scope.page.$$(`xpath/.//*[contains(@class, "da-has-error")][not(contains(@style,"display: none"))]`) },
-      { type: `system`, handlers: await scope.page.$$(`xpath/.//meta[@content="docassemble: Error"]` ) },
-      // Hardcoding the `al_custom_error_action` screen (that's what the base64 here is). It hides actual errors and looks like a continue screen, but isn't.
-      { type: `system`, handlers: await scope.page.$$('.question-custom-error-action .daattributions #trigger[data-variable="YWxfY3VzdG9tX2Vycm9yX2FjdGlvbg"]') },
+      { type: `system`, handles: await scope.page.$$( scope.sys_err_selector ) },
+      { type: `system`, handles: await scope.page.$$( scope.al_err_selector ) },
+      { type: `user`, handles: await scope.page.$$( scope.validation_err_selector ) },
+      { type: `user`, handles: await scope.page.$$( scope.invalid_field_selector ) },
     ];
 
-    let error_handlers = [];  // TODO: Refactor to be single item
+    // Can have multiple user errors which we may get the text of in future
+    let error_handles = [];
     let was_found = false;
     let type = null;
     for ( let one_err_type of possible_error_types ) {
-      if ( one_err_type.handlers[0] ) {
-        // If there's a page visible (locally), give us as much time to examine it as timeout allows.
-        // Because of previous actions, this may still be a bit too long.
-        // Also, if you're debugging and you close the window early, the process will still
-        // take this long to exit after the tests finish. Not sure how to account for that.
+      if ( one_err_type.handles?.[0] ) {
+        // If there's a page visible (locally), give us almost as much time to
+        //   examine it as timeout allows. Because of previous actions, this may
+        //   still be a bit too long.        
+        // Also, if you're debugging and you close the window early, the process
+        //   will still take this long to exit after the tests finish. May fix
+        //   in future, but it's just during debugging, so yolo for now!
         if ( session_vars.get_debug() ) {
           await time.waitForTimeout( ( scope.timeout - (1 * 1000)) );
         }
+
         was_found = true;
-        type = one_err_type.type
-        error_handlers.push( one_err_type.handlers[0] );
-        break;
-      }
-    }
+        error_handles = error_handles.concat( one_err_type.handles )
+        if ( !type || one_err_type.type == `system` ) {
+          type = one_err_type.type
+        }
+      }  // ends if first handler
+    }  // ends for each error type
 
-    return { was_found, ok: !was_found, type, error_handlers };
-  },  // Ends scope.checkForError()
+    return { was_found, ok: !was_found, type, error_handles };
+  },  // Ends scope.checkForErrors()
 
-  throw_system_error: async function ( scope, {
-    error_data = null, error_handlers = null, id = ``, error_text = ``
+  throw_on_system_error: async function ( scope, {
+    error_data=null, id=`Unknown ID`
   }) {
-    /** Throw a cucumber error with the error that appeared on the page. */
-    let was_system_error = error_data?.type === `system`
-      || error_handlers?.system_error !== undefined
-      || error_handlers?.al_custom_error !== undefined;
-
-    if ( was_system_error ) {
-      let err_msg = `The test ran into a system error when it tried to continue to the next page after "${ id }". Also check the picture of this page.`;
-      let report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0147`, value: err_msg });
-      expect( was_system_error, report_msg ).to.be.false;
+    /**
+     * Throw if there is a system/server error. Include some page text.
+     * 
+     * @param {Object} scope - Tests state object
+     * */
+    if ( error_data?.type === `system` ) {
+      let alk_msg = [`The test ran into a system error before or on the page with the id "${ id }". The picture of this page, if available, may show more.`];
+      let report_msg = reports.addToReport(scope, {
+        type: `error`, code: `ALK0147`,
+        value: [ alk_msg, ``, await scope.get_system_err( scope ) ].join(`\n`),
+      });
+      throw Error( report_msg );
     }
 
     return scope;
-  },  // Ends scope.throw_system_error()
+  },  // Ends scope.throw_on_system_error()
 
-  throw_invalid_answer: async function ( scope, {
-    error_data = {}, id = ''
-  }) {
-    // It was a user error, which the author may be expecting
+  get_system_err: async function ( scope, { num_lines=8 }={}) {
+    /**
+     * Returns a sample of error-related text on a docassemble or Assembly Line
+     *   system error page
+     * 
+     * Note: YWxfZm9ybWF0dGVkX2Vycm9yX21lc3NhZ2U is "al_formatted_error_message"
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} obj - Named arguments
+     * @param {int} obj.num_lines - Number of lines of HTML text to return
+     * 
+     * @returns {str} - A sample of the HTML related to the system error
+     * */
+    let truncated_text = `Unable to get the text on this page. Check the picture of this page if possible.`
+    try {
+      
+      let page_err_text = await scope.page.evaluate(() => {
+        return (
+            ( document.querySelector(`#YWxfZm9ybWF0dGVkX2Vycm9yX21lc3NhZ2U`)
+            || document.querySelector(`.dabody`)
+          ).textContent
+        );
+      });
+
+      log.debug({ code: `ALK0287`, context: `page_error`, level: `info` },
+        `Full text of page error:`, page_err_text
+      );
+
+      truncated_text = page_err_text.split(`\n`)
+        .slice( 0, num_lines )
+        .join(`\n`)
+        .trim()
+        + `\n...`;
+
+    } catch ( pupp_err ) {
+      log.debug({ code: `ALK0292`, context: `internal`, level: `note` },
+        `Skipped getting system error screen text with puppeteerjs:`, pupp_err,
+      );
+    }
+
+    return truncated_text;
+  },  // Ends scope.get_system_err()
+
+  throw_on_invalid_answers: async function ( scope, {
+    error_data={}, id=`Unknown ID`
+  }={}) {
+    /**
+     * Throw an error if the user has given invalid answers. If the author
+     *   simply wants to detect invalid answers and avoid throwing, use
+     *   `scope.checkForErrors()`.
+     * 
+     * Discuss: Change our architecture to handle throwing and reporting in some
+     *   central location down/up-stream. Here, for example, I want to add an
+     *   error to the report, but "I can't continue" is catching this error and
+     *   letting the test pass. How can we handle that? Allow editing the report
+     *   after the fact? Throwing the report message with log code and all and
+     *   count on the caller to report it?
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} [obj] - Named arguments
+     * @param {Object} [obj.error_data] - Maybe data for invalid answers' markers
+     * @param {str} [obj.id] - ID of the page that generated errors, if they exist
+     * 
+     * @returns {Object} - Error data given
+     * */
     if ( !error_data.ok && error_data.type === `user` ) {
-      let err_msg = `There was an invalid answer when the test tried to continue to the next page after ${ id }. Check the picture of this page.`;
-      let report_msg = reports.addToReport(scope, { type: `warning`, code: `ALK0148`, value: err_msg });
-      expect( error_data.type === `user`, report_msg ).to.be.false;
+      let err_msg = `The user got an invalid answer on the page with the id "${ id }". You can check the picture of this page unless you used secrets.`;
+      let report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0148`, value: err_msg });
+      throw Error( report_msg );
     }
 
-    return scope;
-  },  // Ends scope.throw_invalid_answer()
+    return error_data;
+  },  // Ends scope.throw_on_invalid_answers()
+
+  warn_on_invalid_answers: async function ( scope, {
+    error_data={}, id=`Unknown ID`
+  }={}) {
+    /**
+     * Add a warning to the report if the page has invalid answer indicators.
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} [obj] - Named arguments
+     * @param {Object} [obj.error_data] - Maybe data for invalid answers' markers
+     * @param {str} [obj.id] - ID of the page that generated errors, if they exist
+     * 
+     * @returns {Object} - Error data given
+     * */
+    let initial_id = id;
+    if ( !error_data.ok && error_data.type === `user` ) {
+      // TOOD: Add a deprecation message to Steps that call this
+      let report_msg = reports.addToReport(scope, {
+        type: `warning`, code: `ALK0290`, value: `The user got an invalid answer on the page with the id "${ initial_id }".`
+      });
+    }
+
+    return error_data;
+  },  // Ends scope.warn_on_invalid_answers()
+
+  throw_on_non_navigation_timeout: async function ( scope, {
+    timed_out=false, id=`Unknown ID`
+  }={}) {
+    /**
+     * Throw an error if the page hasn't navigated and the nav check timed out.
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} [obj] - Named arguments
+     * @param {Object} [obj.timed_out] - Whether navigation timed out
+     * @param {str} [obj.id] - ID of the page that generated errors, if they exist
+     * 
+     * @returns {undefined}
+     * */
+    let initial_id = id;
+    let timeout_err_message = `The test tried to navigate away from the page with the id "${ initial_id }", but it took longer than ${ (scope.timeout/1000)/60 } min. Unless you used a secret, you can check the picture of this page.`
+    if ( !scope.navigated && timed_out ) {
+      reports.addToReport(scope, { type: `error`, code: `ALK0146`, value: timeout_err_message });
+      throw Error( timeout_err_message );
+    }
+  },
+
+  throw_on_non_navigation_catchall: async function ( scope, { id=`Unknown ID` }={}) {
+    /**
+     * Throw an error if the page hasn't navigated. Used in cases where we
+     *   haven't identified why the interaction didn't navigate.
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} [obj] - Named arguments
+     * @param {str} [obj.id] - ID of the page that generated errors, if they exist
+     * 
+     * @returns {undefined}
+     * */
+    let initial_id = id;
+    if ( !scope.navigated ) {
+      let non_nav_msg = `Was unable to navigate away from page with the id "${ initial_id }".`
+      reports.addToReport(scope, { type: `error`, code: `ALK0291`, value: non_nav_msg });
+      throw Error( non_nav_msg );
+    }
+  },
+
+  warn_on_non_navigation_catchall: async function ( scope, { id=`Unknown ID` }={}) {
+    /**
+     * Warn if the page hasn't navigated. Used in cases where we haven't
+     *   identified why the interaction didn't navigate.
+     * 
+     * @param {Object} scope - Tests state object
+     * @param {Object} [obj] - Named arguments
+     * @param {str} [obj.id] - ID of the page that generated errors, if they exist
+     * 
+     * @returns {undefined}
+     * */
+    let initial_id = id;
+    if ( !scope.navigated ) {
+      let non_nav_msg = `Was unable to navigate away from page with the id "${ initial_id }".`
+      reports.addToReport(scope, { type: `warning`, code: `ALK0293`, value: non_nav_msg });
+    }
+  },
 
   take_a_screenshot: async ( scope,{ path }) => {
     /* Takes a jpeg screenshot. Avoids destroying signatures. */
@@ -3393,7 +3811,7 @@ module.exports = {
       /** Given a fetch response headers' Content-Disposition str, return the
        *  filename of the response's file.
        *
-       * @return { string | null } - Name of fetched file
+       * @returns { string | null } - Name of fetched file
        * */
       let filename = default_name;
       if ( disposition ) {
@@ -3415,7 +3833,7 @@ module.exports = {
     },  // Ends scope.steps.get_response_filename()
 
     compare_pdfs: async function (scope, {existing_pdf_path, new_pdf_path}) {
-      let existing_paths = await scope.findFiles(scope, {to_find_names: [existing_pdf_path]});
+      let existing_paths = await scope.find_files(scope, {to_find_names: [existing_pdf_path]});
       if (existing_paths.length == 0) {
         // The row wasn't used
         let msg = `Could not find the existing PDF at ${ existing_pdf_path }`;
@@ -3809,7 +4227,7 @@ module.exports = {
       let handle = await scope.page.waitForSelector(`#dasigcanvas`);
       // We cannot be sure of knowing the name of the signer and so want to
       //   indicate it's random, but we do want something unique
-      await scope.funnel_the_answer( scope, { field, handle, answer: `Random ${ faker.name.lastName() }` });
+      await scope.funnel_the_answer( scope, { field, handle, answer: `Random ${ faker.person.lastName() }` });
     },
     input: async function (scope, { field }) {
       /** Handles various `type`s of input element fields, except:
@@ -3912,7 +4330,7 @@ module.exports = {
       return `${ Math.random() > .5 }`;
     },
     text: async function ( scope ) {
-      return faker.random.word();
+      return faker.word.sample();
     },
     number: async function ( scope ) {
       let answer = faker.helpers.arrayElement( [`1`, `2`, `3`], 1 );
@@ -3938,7 +4356,7 @@ module.exports = {
       return `${ Math.random() * 100 }`;
     },
     email: async function ( scope ) {
-      return faker.internet.email( faker.random.word(), faker.random.word(), `example.com` );
+      return faker.internet.email( faker.word.adjective(), `-`, faker.word.noun(), `example.com` );
     },
     password: async function ( scope ) {
       return faker.internet.password();