@suffolklitlab/alkiln 5.2.1 → 5.4.0

package/lib/scope.js

@@ -9,6 +9,7 @@ const safe_filename = require("sanitize-filename");
 const faker = require('@faker-js/faker/locale/en').faker;
 
 // Ours
+const pdf_reader = require('./utils/pdf_reader');
 const session_vars = require('./utils/session_vars');
 const get_base_interview_url = require(`./docassemble/get_base_interview_url`);
 const time = require('./utils/time');
@@ -17,6 +18,7 @@ const { waitForTimeout } = require('./utils/time');
 const files = require('./utils/files' );
 const server = require('./docassemble/docassemble_api_interface');
 const wrapPromiseWithTimeout = require('./cucumber_8_shim');
+const reports = require(`./utils/reports`);
 
 
 let ordinal_to_integer = {
@@ -82,152 +84,10 @@ let toBase64 = function ( utf8_str, exclude_padding=true) {
 
 let proxies_regex = /(\bx\.)|(\bx\[)|(\[[ijklmn]\])/g;
 let da_base64_regex = /^[A-Za-z0-9+/]+$/;
-let misc_artifacts_dir = `_alkiln-misc_artifacts`;
 
 module.exports = {
   trigger_not_needed_flag: `ALKiln: no trigger variable needed`,
 
-  addToReport: async function( scope, { type, value }) {
-    /* Add an item to a specific list in a scenario's report.
-    * Create report if necessary.
-    * 
-    * The report has a key for each scenario and each of those
-    * keys should correspond to a list containing the relevant data. */
-    if ( session_vars.get_debug() ) { console.log(`Report:\ntype: ${ type }, value: ${ value }\n`) }
-    let scenario = await scope.makeSureReportPartsExist( scope );
-    scenario.lines.push({ type, value });
-
-    // TODO: Not sure how to use .add_to_debug_log() here considering possibly dynamic filepath
-    // log.add_to_debug_log(`Report:\ntype: ${ type }, value: ${ value }\n`);
-
-    // Ensure filepath for saving local unit test logs
-    if ( !scope.paths ) {
-      // TODO: would it be useful to put in existing artifacts folder if possible.
-      // Can this be usefully abstracted?
-      scope.paths = { debug_log: `${ misc_artifacts_dir }/unit_tests_logs-${ files.readable_date() }.txt` };
-    }
-
-    try {
-      fs.appendFileSync(scope.paths.debug_log, `\nReport:\ntype: ${ type }, value: ${ value }`);
-    } catch (err) {
-      fs.mkdirSync( misc_artifacts_dir );
-      fs.appendFileSync(scope.paths.debug_log, `\nReport:\ntype: ${ type }, value: ${ value }`);
-    }
-    return scenario;
-    
-  },  // Ends scope.addToReport()
-
-  makeSureReportPartsExist: async function( scope ) {
-    /* If a part of the report needs to exist right now, but doesn't exist,
-    * create it. */
-    if ( !scope.report ) { scope.report = new Map(); }
-    if ( !scope.scenario_id ) {
-      scope.scenario_id = `_report_${ Date.now() }`;
-    }
-    if ( !scope.report.get( scope.scenario_id )) {
-      scope.report.set( scope.scenario_id, {} )
-      scope.report.get( scope.scenario_id ).status = `in progress`;
-    }
-
-    let scenario = scope.report.get( scope.scenario_id );
-    if ( !scenario.lines ) { scenario.lines = []; }
-
-    return scenario;
-  },  // Ends scope.makeSureReportPartsExist()
-
-  setReportScenarioStatus: async function( scope, { status=`PASSED` }) {
-    /* Add final status of scenario to scenario report object - passed, failed, etc. */
-    scope.report.get( scope.scenario_id ).status = status;
-  },  // Ends scope.setReportScenarioStatus()
-
-  convertToOriginalStoryTableRow: async function( scope, { row_data }) {
-    /* Returns the original data of row into a string formatted as a story table row.
-    * Should this show the actual row data that was used instead? That could
-    * be pretty confusing to most devs. */
-    let source_row = row_data.source || row_data;
-    let original = source_row.original;
-    let var_str = await scope.toTrimmedJSON( scope, { str: original.var });
-    let value_str = await scope.toTrimmedJSON( scope, { str: original.value });
-    let trigger_str = await scope.toTrimmedJSON( scope, { str: original.trigger });
-    if ( trigger_str === scope.trigger_not_needed_flag ) {
-      // This text was added by ALKiln itself. It's not part of the user's data
-      trigger_str = ``;
-    }
-    return `${ ' '.repeat(6) }| ${ var_str } | ${ value_str } | ${ trigger_str } |`;
-  },  // Ends scope.convertToOriginalStoryTableRows()
-
-  toTrimmedJSON: async function( scope, { str='' }) {
-    /* Turn into JSON string then trim quotes from the start and end. */
-    let json = JSON.stringify( str );
-    let trimmed = json.replace( /^"/, '' ).replace( /"$/, '' ).replace( /\\\\/g, `\\`);
-    return trimmed;
-  },  // Ends scope.toTrimmedJSON()
-
-  addReportHeading: async function (scope, { scenario }) {
-    /** Return printable heading based on Scenario name and tags.
-    *    Allow characters from other languages.
-    */
-    if ( session_vars.get_debug() ) { console.log( scenario.pickle.name ); }
-
-    // Collect all tag names
-    let tag_names = [];
-    for ( let tag of scenario.pickle.tags ) {
-      tag_names.push( tag.name );
-    }
-
-    let heading = `\n---------------\n`
-      + `Scenario: ${ scenario.pickle.name }`;
-
-    if ( tag_names.length > 0 ) {
-      heading += `\nTags: ${ tag_names.join(' ') }`;
-    }
-
-    heading += `\n---------------`;
-
-    await scope.addToReport( scope, {
-      type: `heading`,
-      value: heading,
-    });
-  },  // Ends scope.addReportHeading()
-
-  getPrintableReport: async function( scope ) {
-    /* Return a string generated from test report data. */
-    let report = `Assembly Line Kiln Automated Testing Report - ${ (new Date()).toUTCString() }\n`;
-
-    // First list failed scenarios, then non-passed scenarios, then passed scenarios
-    let failed_reports = ``;
-    let passed_reports = ``;
-    let other_reports = ``;
-    for ( let scenario of scope.report ) {
-
-      let report = await scope.getPrintableScenario( scope, { scenario });
-      let [ scenario_id, data ] = scenario;
-      if ( data.status === `FAILED` ) { failed_reports += report; }
-      else if ( data.status === `PASSED` ) { passed_reports += report; }
-      else { other_reports += report; }
-    }  // ends for every scenario
-
-    if ( failed_reports !== `` ) { report += `\n\n===============================\n===============================\nFailed scenarios:\n${ failed_reports }`; }
-    if ( other_reports !== `` ) { report += `\n\n===============================\n===============================\nScenarios that did not pass:\n${ other_reports }`; }
-    if ( passed_reports !== `` ) { report += `\n\n===============================\n===============================\nPassed scenarios:\n${ passed_reports }`; }
-
-    return report;
-  },  // Ends scope.getPrintableReport()
-
-  getPrintableScenario: async function( scope, { scenario }) {
-    /* Return a string generated from scenario list of report items. */
-    let [ scenario_id, data ] = scenario;
-    let report = ``;
-    for ( let line of data.lines ) {
-      if ( line.type === `page_id` ) { report += `screen id: `; }
-      else if ( line.type === `outcome` ) { report += `\n`; }
-      else if ( line.type === `warning` ) { report += `WARNING: `; }
-      else if ( line.type === `error` ) { report += `\nERROR: ` }
-      report += `${ line.value }\n`;
-    }
-    return report;
-  },  // Ends scope.getPrintableScenario()
-
   getSafeScenarioBaseFilename: async function( scope, { scenario }) {
     /** Return a string that's safe to be a filename. Include the Scenario
     *    description and tags.
@@ -275,6 +135,15 @@ module.exports = {
     return safe_name;
   },  // Ends scope.getSafeScenarioFilename()
 
+  getA11yPath: async function( scope ) {
+    // Get a unique path for a json file
+    let { id } = await scope.examinePageID( scope, 'none to match' );
+    let short_id = `${ id }`.substring(0, 20);
+    // Need timestamp in case of a loop where the same page gets assessed for a11y multiple times
+    let a11y_path = path.join( scope.paths.scenario, `aXe_failure-${ short_id }-${ Date.now() }.json` );
+    return a11y_path;
+  },
+
   getJSONFilename: async function( scope ) {
     // Get a unique path for a json file
     let { id } = await scope.examinePageID( scope, 'none to match' );
@@ -356,7 +225,7 @@ module.exports = {
         let error_text_prop = await error_elem.getProperty( 'textContent' );
         let system_error_text = await error_text_prop.jsonValue();
 
-        await scope.addToReport(scope, { type: `error`, value: system_error_text });
+        reports.addToReport(scope, { type: `error`, value: system_error_text });
         throw system_error_text;
       };
 
@@ -386,7 +255,7 @@ module.exports = {
     // first in user-triggered cases - users used to be able to access this almost
     // directly, but they can't anymore. Our functions should know to only pass good things.
     let msg = `Cannot find the element to tap.`;
-    if ( !elem ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+    if ( !elem ) { reports.addToReport(scope, { type: `error`, value: msg }); }
 
     expect( elem, msg ).to.exist;
 
@@ -425,7 +294,7 @@ module.exports = {
       } else {
         // Throw any non-timeout error
         let err_msg = `Error occurred when ALKiln tried to tap "${ tapperText }".`
-        scope.addToReport( scope, { type: `error`, value: err_msg });
+        reports.addToReport( scope, { type: `error`, value: err_msg });
         throw error;
       }  // ends if error is timeout error
 
@@ -517,7 +386,7 @@ module.exports = {
       await scope.get_server_reload_promise( scope );
     } else {
       // Otherwise just throw the error
-      await scope.addToReport( scope, {
+      reports.addToReport( scope, {
         type: `error`,
         value: non_reload_report_msg });
       throw error;
@@ -579,7 +448,7 @@ module.exports = {
           + `${ Math.round( ms_till_server_timeout/1000 ) } seconds to respond. `
           + `If the server was just reloading and needed more time, try setting the `
           + `"SERVER_RELOAD_TIMEOUT_SECONDS" GitHub secret to a longer amount of time.`
-        await scope.addToReport( scope, { type: `error`, value: timeout_message });
+        reports.addToReport( scope, { type: `error`, value: timeout_message });
       }
 
       // Once server has responded, throw an error to end the test. After the first
@@ -599,8 +468,8 @@ module.exports = {
     let reload_failure_msg = `The test was unable to continue because the `
       + `server was reloading. ALKiln will try this Scenario a total of 2 times. An `
       + `error will still be printed for this attempt.`;
-    await scope.addToReport( scope, { type: `error`, value: reload_failure_msg });
-    // await scope.addToReport( scope, { type: `error`, value: timeout_message });
+    reports.addToReport( scope, { type: `error`, value: reload_failure_msg });
+    // reports.addToReport( scope, { type: `error`, value: timeout_message });
     // clearTimeout( server_timeout_id );
     throw( reload_failure_msg );
   },  // Ends scope.throw_server_was_reloading_error()
@@ -673,7 +542,7 @@ module.exports = {
     let elem = await scope.page.$(`#${tab_id}`); 
     let error_msg = `Couldn't find the tab with id "#${tab_id}" on the page, is there a typo?`;
     if ( !elem ) {
-      await scope.addToReport(scope, { type: `error`, value: error_msg }); 
+      reports.addToReport(scope, { type: `error`, value: error_msg }); 
     }
     expect( elem, error_msg ).to.exist;
     await scope.tapElement( scope, elem, tab_id );
@@ -683,7 +552,7 @@ module.exports = {
     /** Return if there were any violations and the file containing aXe output with more details of the checks */
     let { id } = await scope.examinePageID( scope, 'none to match' );
     if ( scope.page_id !== id ) {
-      await scope.addToReport(scope, { type: `page_id`, value: `${ id }`, });
+      reports.addToReport(scope, { type: `page_id`, value: `${ id }`, });
       scope.page_id = id;
     }
     const axe = new AxePuppeteer(scope.page);
@@ -701,16 +570,15 @@ module.exports = {
     let axe_path = null;
     const passed = axe_result.violations.length == 0;
     if (!passed) {
-      let axe_filename = await scope.getSafeScenarioFilename( scope, {prefix: `aXe_failure`}) + '.json';
-      axe_path = `${ scope.paths.scenario }/${ axe_filename }`;
+      axe_path = await scope.getA11yPath( scope );
       fs.writeFileSync( axe_path, JSON.stringify( axe_result, null, 2 ));
       let msg = `Found potential accessibility issues on the ${ scope.page_id } screen. Details in ${ axe_path }.`;
-      await scope.addToReport( scope, {
+      reports.addToReport( scope, {
         type: `error`,
         value: msg
       });
     } else {
-      await scope.addToReport(scope, { type: `info`, value: `Accessibility on ${ scope.page_id } passed!`})
+      reports.addToReport(scope, { type: `info`, value: `Accessibility on ${ scope.page_id } passed!`})
     }
     return {
       passed: axe_result.violations.length == 0,
@@ -722,7 +590,7 @@ module.exports = {
     let elem = await scope.page.$(`${selector}`);
     let error_msg = `Couldn't find "${selector}" on the page, is there a typo?`;
     if ( !elem ) {
-      await scope.addToReport(scope, { type: `error`, value: error_msg });
+      reports.addToReport(scope, { type: `error`, value: error_msg });
     }
     expect( elem, error_msg ).to.exist;
     await scope.tapElement( scope, elem, '', waitForTimeout );
@@ -748,7 +616,7 @@ module.exports = {
       interview_url = `${ base_url }${ file_name }`;
     }
 
-    await scope.addToReport(scope,{
+    reports.addToReport(scope,{
       type: `row`,
       value: `Trying to load the interview at "${interview_url}"`
     });
@@ -772,7 +640,7 @@ module.exports = {
       } else {
 
         // Throw any non-timeout error
-        scope.addToReport( scope, {
+        reports.addToReport( scope, {
           type: `error`,
           value: `Error occurred when ALKiln tried to go to the interview url`
         });
@@ -784,7 +652,7 @@ module.exports = {
     let load_result = await scope.getLoadData( scope );
     // Errors, or reaching timeout, causes an exception and is shown to the developer at the end
     if ( load_result.error ) {
-      await scope.addToReport(scope, { type: `error`, value: `On final attempt to load interview, got "${ load_result.error }"` });
+      reports.addToReport(scope, { type: `error`, value: `On final attempt to load interview, got "${ load_result.error }"` });
       expect( load_result.error ).to.equal( '' );
     }
 
@@ -854,7 +722,7 @@ module.exports = {
     if (!var_data && ! raw_var_data) {
       let no_data_msg = `ALKiln Internal error: normalizeTable called w/o var_data or raw_var_data:` +
           ` open an issue at https://github.com/SuffolkLITLab/ALKiln/issues/new if you see this!`;
-      await scope.addToReport( scope, { type: `error`, value: no_data_msg });
+      reports.addToReport( scope, { type: `error`, value: no_data_msg });
       throw Error(no_data_msg);
     }
 
@@ -869,7 +737,7 @@ module.exports = {
             let bad_table_msg = `Your Story Table definition needs to be changed. The best practice`
                 + ` is to make your table 3 columns wide with a first row in this format: "| var | value | trigger |".`
                 + ` The first row of your table is actually "${ raw_array[0] }"`;
-            await scope.addToReport( scope, { type: `error`, value: bad_table_msg})
+            reports.addToReport( scope, { type: `error`, value: bad_table_msg})
             throw Error(bad_table_msg);
           } else if (row_raw.length == 2) {
             var_data.push({var: row_raw[0], value: row_raw[1]});
@@ -889,7 +757,7 @@ module.exports = {
         actual_var_value = process.env[row.flags.secret_name];
         if ( actual_var_value === undefined ) {
           let not_in_env_msg = `The GitHub SECRET "${ row.flags.secret_name }" doesn't exist. Check for a typo and check your workflow file.`;
-          await scope.addToReport( scope, { type: `error`, value: not_in_env_msg })
+          reports.addToReport( scope, { type: `error`, value: not_in_env_msg })
           throw ReferenceError(`Could not find "${row.flags.secret_name }": ${not_in_env_msg}.`)
         }
       }
@@ -941,7 +809,7 @@ module.exports = {
     let encoded_trigger_var = $( trigger_elem ).data( `variable` );  // This should come out to 'None' at the very least
     if ( !encoded_trigger_var ) {
       // TODO: Add documentation and then link to it in this message.
-      await scope.addToReport(scope, { type: `warning`, value: `You are missing an element containing the data for the page's trigger variable. Some fields, like loops with index variables, may not work correctly in these tests. See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#a-missing-trigger-variable.` });
+      reports.addToReport(scope, { type: `warning`, value: `You are missing an element containing the data for the page's trigger variable. Some fields, like loops with index variables, may not work correctly in these tests. See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#a-missing-trigger-variable.` });
       encoded_trigger_var = toBase64( `None` );
     }
     let trigger = fromBase64( encoded_trigger_var );
@@ -1080,7 +948,7 @@ module.exports = {
     // Exceptions: Some specific fields can be duplicates without being dangerous
     if ( matching_nodes.length > 1 && !selector.includes(`[class="file-caption-name"]`) ) {
       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.`;
-      await scope.addToReport(scope, { type: `warning`, value: msg });
+      reports.addToReport(scope, { type: `warning`, value: msg });
     }
 
     return selector;
@@ -1359,7 +1227,7 @@ module.exports = {
           + `variable or a generic object, but the page does not `
           + `contain the trigger variable's name in its HTML. See `
           + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#a-missing-trigger-variable.`;
-        await scope.addToReport(scope, { type: `warning`, value: page_trigger_warning });
+        reports.addToReport(scope, { type: `warning`, value: page_trigger_warning });
       }
 
       for ( let row_that_matches_this_field of rows_that_match_field_names ) {
@@ -1373,13 +1241,13 @@ module.exports = {
           // a useful message.
 
           // First, make the row data more readable to humans.
-          let row_as_story_table = await scope.convertToOriginalStoryTableRow( scope, { row_data: row_that_matches_this_field });
+          let row_as_story_table = reports.convertToOriginalStoryTableRow( scope, { row_data: row_that_matches_this_field });
           let row_trigger_warning = `This story table row needs a value in the "trigger" `
             + `column, but it is empty. The test might get unexpected results. See `
             + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger.`
             + `\nThe row's data:\n${ row_as_story_table }`
             + `\nThis field's data:\n${ JSON.stringify( field )}`;
-          await scope.addToReport(scope, { type: `warning`, value: row_trigger_warning });
+          reports.addToReport(scope, { type: `warning`, value: row_trigger_warning });
           rows_without_a_trigger_name.push( row_that_matches_this_field );
         } else {
           let triggers_match = await scope.matchNeutralizedQuotes( scope, { value1: page_trigger_name, value2: table_row_trigger_name });
@@ -1405,7 +1273,7 @@ module.exports = {
         // First, make the row data more readable to humans.
         let conflicts_as_story_table_rows = [];
         for ( let row of rows_with_conflicting_trigger_names ) {
-          let table_str = await scope.convertToOriginalStoryTableRow( scope, { row_data: row });
+          let table_str = reports.convertToOriginalStoryTableRow( scope, { row_data: row });
           conflicts_as_story_table_rows.push( table_str );
         }
 
@@ -1416,7 +1284,7 @@ module.exports = {
           + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger.`
           + `\nThe data of row(s) with conflicting trigger name(s):\n${ conflicts_as_story_table_rows.join( `\n` )}`
           + `\nThis field's data:\n${ JSON.stringify( field )}`;
-        await scope.addToReport(scope, {
+        reports.addToReport(scope, {
           type: `warning`,
           value: all_trigger_names_conflict_msg
         });
@@ -1433,7 +1301,7 @@ module.exports = {
       // First, make the row data more readable to humans.
       let rows_as_story_table = [];
       for ( let row of final_matching_rows ) {
-        let table_str = await scope.convertToOriginalStoryTableRow( scope, { row_data: row });
+        let table_str = reports.convertToOriginalStoryTableRow( scope, { row_data: row });
         rows_as_story_table.push( table_str );
       }
 
@@ -1443,7 +1311,7 @@ module.exports = {
         + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger.`
         + `\nThe matching rows:\n${ rows_as_story_table.join(`\n`) }`
         + `\nThis field's data:\n${ JSON.stringify( field )}`;
-      await scope.addToReport(scope, { type: `warning`, value: multiple_matches_msg });
+      reports.addToReport(scope, { type: `warning`, value: multiple_matches_msg });
     }
 
     if ( session_vars.get_debug() ) { 
@@ -1617,7 +1485,7 @@ module.exports = {
       // If it doesn't have the right format
       if ( answer === null || !answer.includes(`/`) ) {
         // Return field unused.
-        await scope.addToReport( scope, {
+        reports.addToReport( scope, {
           type: `warning`,
           value: `Invalid date. Value given: "${ answer }".`
         });
@@ -1812,22 +1680,15 @@ module.exports = {
     return valid_date;
   },  // Ends scope.today_to_date()
 
-  uploadFiles: 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.
-    * 
-    * Returns whether the row was used or not.
-    */
-
+  findFiles: async function( scope, {to_find_names}) {
     // 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 uploads_names = answer.split(`,`);
-    if ( uploads_names.length === 0 ) {
-      await scope.addToReport( scope, {
+    if ( to_find_names.length === 0 ) {
+      reports.addToReport( scope, {
         type: `error`,
-        value: `Your list of files to upload is empty.`
+        value: `Your list of files to find is empty.`
       });
-      return false;  // The row wasn't used
+      return [];
     }
 
     let dirs = [];
@@ -1850,24 +1711,23 @@ module.exports = {
     }
 
     if ( session_vars.get_debug() ) {
-      console.log( `All discovered dirs to upload from:`, dirs );
+      console.log( `All discovered dirs to find files from:`, dirs );
     }
 
     // Make sure sources directory exists and has files in it
     if ( dirs.length === 0 ) {
-      await scope.addToReport( scope, {
+      reports.addToReport( scope, {
         type: `warning`,
         value: `The test files need to be in the "sources" directory, `
           + `but ALKiln couldn't find the directory or it was empty.`
       });
-      return false;  // The row wasn't used
+      return [];
     }
 
     // Get the full paths of all the files
-    let dir = null;
     let paths = [];
     let missing_files = [];  // For any user warnings
-    for ( let name of uploads_names ) {
+    for ( let name of to_find_names) {
      
       let trimmed_name = name.trim();
       let matching_paths = [];
@@ -1887,15 +1747,33 @@ module.exports = {
     }  // ends for each file
 
     if ( missing_files.length > 0 ) {
-      await scope.addToReport( scope, {
+      reports.addToReport( scope, {
         type: `warning`,
         value: `ALKiln could not find "${ missing_files.join('", "') }" in any of these folders: "${ dirs.join('", "') }".`
       });
     }
 
-    // If all files missing, return that the row wasn't used
-    if ( missing_files.length === uploads_names.length ) {
-      return false;  // The row wasn't used
+    // If all files missing, return an empty array
+    if ( missing_files.length === to_find_names.length ) {
+      return [];
+    }
+    return paths;
+  },
+
+  uploadFiles: 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.
+    * 
+    * Returns whether the row was used or not.
+    */
+
+    // 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) {
+      // The row wasn't used
+      return false;
     }
 
     // Prepare to wait for upload to complete
@@ -1944,7 +1822,7 @@ module.exports = {
     * takes a while to load. */
     let canvas = await scope.page.waitForSelector( `#dasigcanvas` );
     let msg = `Could not find a signature field.`;
-    if ( !canvas ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+    if ( !canvas ) { reports.addToReport(scope, { type: `error`, value: msg }); }
     expect( canvas, msg ).to.exist;
 
     // Provides functionality to draw name arg on canvas
@@ -2017,7 +1895,7 @@ module.exports = {
     // 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 ) {
-      await scope.addToReport(scope, { type: `page_id`, value: `${ id }`, });
+      reports.addToReport(scope, { type: `page_id`, value: `${ id }`, });
       scope.page_id = id;
     }
 
@@ -2047,9 +1925,9 @@ module.exports = {
 
           something_new_was_set = true;
           field.was_set = true;
-          await scope.addToReport(scope, {
+          reports.addToReport(scope, {
             type: `row`,
-            value: `${ await scope.convertToOriginalStoryTableRow(scope, { row_data: row_used }) }`
+            value: `${ reports.convertToOriginalStoryTableRow(scope, { row_data: row_used }) }`
           });
 
           // Accumulate number of times this row was used. Esp important for `.target_number`
@@ -2072,9 +1950,9 @@ module.exports = {
         let row_used = await scope.setVariable( scope, { field, var_data, });
         if ( row_used ) {
 
-          await scope.addToReport(scope, {
+          reports.addToReport(scope, {
             type: `row`,
-            value: `${ await scope.convertToOriginalStoryTableRow(scope, { row_data: row_used }) }`
+            value: `${ reports.convertToOriginalStoryTableRow(scope, { row_data: row_used }) }`
           });
 
           // Esp important for `.target_number`
@@ -2116,13 +1994,13 @@ module.exports = {
           if ( row.source ) { source_row = row.source; }
           let original_row = source_row.original;
           let msg = `Did not find a field on this page for the variable "${ original_row.var }" that could be set to "${ original_row.value }"`;
-          await scope.addToReport(scope, { type: `warning`, value: msg });
+          reports.addToReport(scope, { type: `warning`, value: msg });
         }
       }
       if ( num_unused_rows > 0 ) {
         let { id } = await scope.examinePageID( scope, 'none to match' );
         let msg = `Missing variable or variables on page "${id}"`;
-        await scope.addToReport(scope, { type: `error`, value: msg });
+        reports.addToReport(scope, { type: `error`, value: msg });
         expect( num_unused_rows, msg ).to.equal( 0 );
       }
     }
@@ -2312,7 +2190,7 @@ module.exports = {
         // probably add a confusing message to the report, so mutating seems, sadly, more useful.
         var_datum.value = `False`;  // The original value is still preserved
         // Warn the developer not to use `.there_is_another`.
-        await scope.addToReport( scope, { type: `warning`, 
+        reports.addToReport( scope, { type: `warning`, 
             value: 'The attribute `.there_is_another` is invalid in story table tests. Replace it with '
               + '`.target_number` in your `var` and `trigger` columns. Set the `value` to the number of items in '
               + `that list. This test will now set this row's \`value\` to \`False\`. See `
@@ -2346,10 +2224,10 @@ module.exports = {
     } else if ( value.match( /(true|yes|checked|check|selected|select)/i )) {
       if ( from_story_table && !row.artificial ) {
         if ( row.var.match( /\.there_is_another$/ ) ) {
-          await scope.addToReport( scope, { type: `warning`, value: `The attribute \`.there_is_another\` is invalid in story table tests. Replace it with \`.target_number\` in your \`var\` column. Set the \`value\` to the number of items in that list. This test will now set this row's \`value\` to \`False\`. See https://suffolklitlab.github.io/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing#there_is_another-loop. The row data is\n${ JSON.stringify( row.original )}` });
+          reports.addToReport( scope, { type: `warning`, value: `The attribute \`.there_is_another\` is invalid in story table tests. Replace it with \`.target_number\` in your \`var\` column. Set the \`value\` to the number of items in that list. This test will now set this row's \`value\` to \`False\`. See https://suffolklitlab.github.io/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing#there_is_another-loop. The row data is\n${ JSON.stringify( row.original )}` });
         } else {
           // If `target_number` is set to True instead of a number
-          await scope.addToReport( scope, { type: `warning`, value: `${ val_to_print } value is not a valid value for ${ row.var } here. This test will default to \`False\` to avoid problems.` });
+          reports.addToReport( scope, { type: `warning`, value: `${ val_to_print } value is not a valid value for ${ row.var } here. This test will default to \`False\` to avoid problems.` });
         }
         return `False`;
       } else { return `True`; }
@@ -2357,7 +2235,7 @@ module.exports = {
     } else if ( isNaN( desired_num )) {  // Story table loop will end
       // I can't figure out how to trigger this warning, so maybe we're
       // already handling everything we need to
-      await scope.addToReport( scope, { type: `warning`, value: `${ val_to_print } value is not a valid value for ${ row.var } here. This test will default to \`False\` to avoid problems.` });
+      reports.addToReport( scope, { type: `warning`, value: `${ val_to_print } value is not a valid value for ${ row.var } here. This test will default to \`False\` to avoid problems.` });
       return `False`;
 
 	    // Check that the number of elements in the list hits our desired number.
@@ -2408,7 +2286,7 @@ module.exports = {
     }
 
     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 ) { await scope.addToReport(scope, { type: `error`, value: timeout_err_message }); }
+    if ( timedOut ) { reports.addToReport(scope, { type: `error`, value: timeout_err_message }); }
     expect( timedOut, timeout_err_message ).to.be.false;
 
     clearTimeout( cont_timeout );
@@ -2452,13 +2330,13 @@ module.exports = {
     /* Throw a cucumber error with the error that appeared on the page. */
     if ( error_handlers.system_error !== undefined ) {
       let sys_err_message = `The test tried to continue to the next page after ${ id }, but there was a system error. Check the picture of this page.`
-      await scope.addToReport(scope, { type: `error`, value: sys_err_message });
+      reports.addToReport(scope, { type: `error`, value: sys_err_message });
       expect( was_system_error, sys_err_message ).to.be.false;
 
     } else {
       // If it wasn't a system error, it was a user error
       let user_err_message = `The test tried to continue to the next page after ${ id }, but the user got an error. Check the picture of this page.`
-      await scope.addToReport(scope, { type: `error`, value: user_err_message });
+      reports.addToReport(scope, { type: `error`, value: user_err_message });
       expect( true, user_err_message ).to.be.false;
     }
 
@@ -2480,6 +2358,22 @@ module.exports = {
       fullPage: fullPage,
     });
 
+    let html_path = path;
+    if (path.endsWith(".jpg")) {
+      html_path = html_path.substring(0, html_path.length - 4) + ".html";
+    } else {
+      html_path = html_path + ".html";
+    }
+
+    // Also save the HTML of the page
+    await scope.page.content().then(content => {
+      let server_url = session_vars.get_da_server_url();
+      content = content.replaceAll(/"(\/static\/.*\.css\?v=[^"]+")/g, server_url + "$1");
+      content = content.replaceAll(/"(\/static\/.*\.js\?v=[^"]+")/g, server_url + "$1");
+      content = content.replaceAll(/"(\/packagestatic\/.*\.css\?v=[^"]+")/g, server_url + "$1");
+      content = content.replaceAll(/"(\/packagestatic\/.*\.js\?v=[^"]+")/g, server_url + "$1");
+      fs.writeFileSync(html_path, content)
+    });
   },  // Ends scope.take_a_screenshot()
 
 
@@ -2519,7 +2413,7 @@ module.exports = {
       });
 
       // In future, may be saved to artifact file
-      await scope.addToReport( scope, {
+      reports.addToReport( scope, {
         type: `json`,
         value: JSON.stringify( data, null, 2 )
       });
@@ -2535,7 +2429,7 @@ module.exports = {
       let response = await linkPage.goto( actual_url, { waitUntil: 'domcontentloaded' });
 
       let msg = `The "${ linkText }" link is broken.`;
-      if ( !response.ok() ) { await scope.addToReport( scope, { type: `error`, value: msg }); }
+      if ( !response.ok() ) { reports.addToReport( scope, { type: `error`, value: msg }); }
       expect( response.ok(), msg ).to.be.true;
 
       // This may cause problems if the linked page is the interview page
@@ -2584,7 +2478,7 @@ module.exports = {
       const [link] = await scope.page.$x(`//a[contains(text(), "${phrase}")]`);
 
       let msg = `The term "${ phrase }" seems to be missing.`;
-      if ( !link ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+      if ( !link ) { reports.addToReport(scope, { type: `error`, value: msg }); }
       expect( link, msg ).to.exist;
 
       await scope.tapElement( scope, link );
@@ -2611,7 +2505,7 @@ module.exports = {
       let [elem] = await scope.page.$x(`//a[contains(@href, "${ filename }")]`);
 
       let msg = `"${ filename }" seems to be missing. Cannot find a link to that document.`;
-      if ( !elem ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+      if ( !elem ) { reports.addToReport(scope, { type: `error`, value: msg }); }
       expect( elem, msg ).to.exist;
 
       scope.toDownload = filename;
@@ -2620,6 +2514,32 @@ module.exports = {
       await scope.detectDownloadComplete( scope );
     },  // Ends scope.steps.download()
 
+    compare_pdfs: async function (scope, {existing_pdf_path, new_pdf_path}) {
+      let existing_paths = await scope.findFiles(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 }`;
+        reports.addToReport(scope, { type: `error`, value: msg });
+        scope.failed_pdf_compares.push(msg);
+        // Return early since we couldn't find the PDF
+        return;
+      }
+      let full_existing_path = existing_paths[0];
+      let full_new_pdf_path = `${scope.paths.scenario}/${new_pdf_path}`;
+      let diffs = await pdf_reader.compare_pdfs(full_existing_path, full_new_pdf_path);
+      if (diffs) {
+        let added_str = diffs.filter(part => part.added).reduce((err_str, part) => {
+          return err_str + `- ${ part.value }\n`
+        }, 'The new PDF added: \n');
+        let removed_str = diffs.filter(part => part.removed).reduce((err_str, part) => {
+          return err_str + `- ${ part.value }\n`
+        }, 'The new PDF removed: \n');
+        let msg = `The PDFs were not the same.\n${ added_str }\n${removed_str}\n\n You can see the full PDFs at ${ full_existing_path } and ${ full_new_pdf_path}`;
+        reports.addToReport(scope, { type: `error`, value: msg });
+        scope.failed_pdf_compares.push(msg);
+      }
+    },
+
     set_al_name: async ( scope, var_base, name_str ) => {
       /** Given a variable name and a space-separated string, fills the
       *    appropriate fields on an Assembly Line name question.
@@ -2647,7 +2567,7 @@ module.exports = {
         name_parts_slice.push(name_parts_last);
         name_parts = name_parts_slice;
       
-        await scope.addToReport(scope, {
+        reports.addToReport(scope, {
           type: `warning`,
           value: `The name "${name_str}" has more than 4 parts, but 4 is the maximum allowed. The test will set the name to "${name_parts.join(" ")}".`
         });
@@ -2733,7 +2653,7 @@ module.exports = {
           await scope.handle_page_timeout_error( scope, { non_reload_report_msg, error });
         } else {
           // Throw any non-timeout error
-          scope.addToReport( scope, { type: `error`, value: err_msg });
+          reports.addToReport( scope, { type: `error`, value: err_msg });
           throw error;
         }  // ends if error is timeout error
 
@@ -2747,11 +2667,11 @@ module.exports = {
       // this is complex
       let email_msg = `The email address GitHub SECRET "${ email_secret_name }" doesn't exist. Check for a typo and check your workflow file.`
       if ( email === undefined ) {
-        await scope.addToReport( scope, { type: `error`, value: email_msg })
+        reports.addToReport( scope, { type: `error`, value: email_msg })
       }
       let password_msg = `The password GitHub SECRET "${ password_secret_name }" doesn't exist. Check for a typo and check your workflow file.`
       if ( password === undefined ) {
-        await scope.addToReport( scope, { type: `error`, value: password_msg })
+        reports.addToReport( scope, { type: `error`, value: password_msg })
       }
 
       expect( email, email_msg ).to.not.equal( undefined );
@@ -2768,7 +2688,7 @@ module.exports = {
       // TODO: use a Promise.race to fail faster.
       await scope.page.waitForSelector( `.datopcenter .alert-success` );
 
-      await scope.addToReport( scope, {
+      reports.addToReport( scope, {
         type: `row`,
         value: `Signed into ${ session_vars.get_da_server_url() }/user/sign-in successfully.`
       });
@@ -2910,7 +2830,7 @@ module.exports = {
         if ( type !== `` && type !== `hidden` ) {
           // Field types that we can't yet handle, but plan to in future
           if ( type === `file` ) {
-            await scope.addToReport( scope, {
+            reports.addToReport( scope, {
               type: `warning`,
               value: `Sorry, ALKiln's random input tests cannot yet handle "${ type }" fields.`
             });
@@ -3016,7 +2936,7 @@ module.exports = {
     */
     let current_report_obj = scope.report.get( scope.scenario_id );
     let scenario = [ scope.scenario_id, current_report_obj ];  // Mimic how loop works with `Map`
-    let report = await scope.getPrintableScenario( scope, { scenario });
+    let report = reports.getPrintableScenario( scenario );
     let all_are_included = true;
     for ( let one_expectation of expected ) {
       if ( !report.includes( one_expectation )) {
@@ -3036,7 +2956,7 @@ module.exports = {
     */
     let current_report_obj = scope.report.get( scope.scenario_id );
     let scenario = [ scope.scenario_id, current_report_obj ];  // Mimic how loop works with `Map`
-    let report = await scope.getPrintableScenario( scope, { scenario });
+    let report = reports.getPrintableScenario( scenario );
     let none_included = true;
     for ( let one_expectation of not_expected ) {
       if ( report.includes( one_expectation )) {
@@ -3047,4 +2967,5 @@ module.exports = {
 
     return none_included;
   },
+
 };