@suffolklitlab/alkiln 5.2.1 → 5.4.0

package/lib/steps.js

@@ -21,6 +21,7 @@ const scope = require('./scope');
 const log = require('./utils/log');
 const session_vars = require('./utils/session_vars');
 const files = require('./utils/files' );
+const reports = require(`./utils/reports`);
 
 /* Of Note:
 - We're using `*=` for selectors because sometimes da text has funny characters in it that are hard to anticipate
@@ -125,7 +126,7 @@ Before(async (scenario) => {
   scope.expected_not_in_report = null;
   scope.server_reload_promise = null;
 
-  await scope.addReportHeading(scope, {scenario});
+  reports.addReportHeading(scope, {scenario});
   // Make folder for this Scenario in the all-tests artifacts folder
   scope.base_filename = await scope.getSafeScenarioBaseFilename(scope, {scenario});
   // Add a date for uniqueness in case dev has accidentally copied a Scenario description
@@ -146,6 +147,7 @@ Before(async (scenario) => {
   scope.page_id = null;
   scope.check_all_for_a11y = false;
   scope.passed_all_for_a11y = true;
+  scope.failed_pdf_compares = [];
 
   // Reset default timeout
   scope.timeout = default_timeout;
@@ -353,7 +355,7 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
           resolve();
         } catch ( err ) {
           let err_msg = `Error occurred when tried to answer fields on question "${ id }".`
-          scope.addToReport( scope, { type: `error`, value: err_msg });
+          reports.addToReport( scope, { type: `error`, value: err_msg });
           // Throw error instead?
           reject( err );
         } finally {
@@ -372,7 +374,7 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
 
   // Add report strings from supported table, not an altered one
   for ( let row of supported_table ) {
-    row.report_str = `${ await scope.convertToOriginalStoryTableRow(scope, { row_data: row }) }`;
+    row.report_str = `${ reports.convertToOriginalStoryTableRow(scope, { row_data: row }) }`;
   }
   // Sort into alphabetical order, as is recommended for writing story tables
   let sorted_rows = supported_table.sort( function ( row1, row2 ) {
@@ -383,13 +385,13 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
 
   // Add full used table to report so it can be copied if needed.
   // TODO: Should we/How do we get this in the final scenario report instead of here?
-  await scope.addToReport( scope, { type: `note`, value: `\n${ ' '.repeat(2) }Rows that got set:` });
-  await scope.addToReport( scope, { type: `step`, value: `${ ' '.repeat(4) }And I get to the question id "${ target_id }" with this data:` });
-  await scope.addToReport(scope, { type: `row`, value: `${ ' '.repeat(6) }| var | value | trigger |`, });
+  reports.addToReport( scope, { type: `note`, value: `\n${ ' '.repeat(2) }Rows that got set:` });
+  reports.addToReport( scope, { type: `step`, value: `${ ' '.repeat(4) }And I get to the question id "${ target_id }" with this data:` });
+  reports.addToReport(scope, { type: `row`, value: `${ ' '.repeat(6) }| var | value | trigger |`, });
   let at_least_one_row_was_NOT_used = false;
   for ( let row of sorted_rows ) {
     if ( row.times_used > 0 ) {
-      await scope.addToReport(scope, { type: `row`, value: row.report_str, });
+      reports.addToReport(scope, { type: `row`, value: row.report_str, });
     } else {
       at_least_one_row_was_NOT_used = true;
     }
@@ -397,17 +399,17 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
 
   // Add unused rows if needed
   if ( at_least_one_row_was_NOT_used ) {
-    await scope.addToReport( scope, { type: `note`, value: `${ ' '.repeat(2) }Unused rows:` });
+    reports.addToReport( scope, { type: `note`, value: `${ ' '.repeat(2) }Unused rows:` });
     for ( let row of sorted_rows ) {
       if ( row.times_used === 0 ) {
-        await scope.addToReport(scope, { type: `row`, value: row.report_str, });
+        reports.addToReport(scope, { type: `row`, value: row.report_str, });
       }
     }
   } else {
-    await scope.addToReport(scope, { type: `note`, value: `${ ' '.repeat(2) }All rows were used` });
+    reports.addToReport(scope, { type: `note`, value: `${ ' '.repeat(2) }All rows were used` });
   }
 
-  await scope.addToReport(scope, { type: `note`, value: `` });
+  reports.addToReport(scope, { type: `note`, value: `` });
 });
 
 //#####################################
@@ -457,7 +459,7 @@ Then(/the (?:question|page|screen) id should be "([^"]+)"/i, { timeout: -1 }, as
   // No question id exists
   let no_id_msg = `Did not find any question id.`;
   if ( !question_has_id ) {
-    await scope.addToReport( scope, { type: `error`, value: no_id_msg });
+    reports.addToReport( scope, { type: `error`, value: no_id_msg });
   }
   expect( question_has_id , no_id_msg ).to.be.true;
 
@@ -465,7 +467,7 @@ Then(/the (?:question|page|screen) id should be "([^"]+)"/i, { timeout: -1 }, as
   let no_match_msg = `The question id was supposed to be "${ question_id }"`
     + `, but it's actually "${ id }".`;
   if ( !id_matches ) {
-    await scope.addToReport( scope, { type: `error`, value: no_match_msg });
+    reports.addToReport( scope, { type: `error`, value: no_match_msg });
   }
   expect( id_matches, no_match_msg ).to.be.true;
 
@@ -478,7 +480,7 @@ Then(/I ?(?:should)? see the phrase "([^"]+)"/i, async ( phrase ) => {  // √
   const bodyText = await scope.page.$eval('body', elem => elem.innerText);
 
   let msg = `The text "${ phrase }" SHOULD be on this page, but it's NOT.`;
-  if ( !bodyText.includes( phrase )) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !bodyText.includes( phrase )) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( bodyText, msg ).to.contain( phrase );
 
   await scope.afterStep(scope);
@@ -492,7 +494,7 @@ Then(/I should not see the phrase "([^"]+)"/i, async ( phrase ) => {  // √
   const bodyText = await scope.page.$eval('body', elem => elem.innerText);
 
   let msg = `The text "${ phrase }" should NOT be on this page, but it IS here.`;
-  if ( bodyText.includes( phrase )) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( bodyText.includes( phrase )) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( bodyText, msg ).not.to.contain( phrase );
 
   await scope.afterStep(scope);
@@ -502,7 +504,7 @@ Then('an element should have the id {string}', async ( id ) => {  // √
   const element = await scope.page.$('#' + id);
 
   let msg = `No element on this page has the ID "${ id }".`;
-  if ( !element ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !element ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( element, msg ).to.exist;
 
   await scope.afterStep(scope);
@@ -557,7 +559,7 @@ Then(/I (don't|can't|don’t|can’t|cannot|do not) continue/, async (unused) =>
   *    Can other things trigger navigation? Re: other inputs things
   *    like 'Enter' acting like a click is a test for docassemble */
   let msg = `The page should have stopped the user from continuing, but the user was able to continue.`;
-  if ( scope.navigated ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( scope.navigated ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( scope.navigated, msg ).to.be.false;
 
   await scope.afterStep(scope);
@@ -568,12 +570,12 @@ Then('I will be told an answer is invalid', async () => {  // √
   let { was_found, error_handlers } = await scope.checkForError( scope );
 
   let no_error_msg = `No error message was found on the page`;
-  if ( !was_found ) { await scope.addToReport(scope, { type: `error`, value: no_error_msg }); }
+  if ( !was_found ) { reports.addToReport(scope, { type: `error`, value: no_error_msg }); }
   expect( was_found, no_error_msg ).to.be.true;
 
   let was_user_error = error_handlers.complex_user_error !== undefined || error_handlers.simple_user_error !== undefined;
   let not_user_error_msg = `The error was a system error, not an invalid user answer. Check for the picture of the page's error if the step did not use any secret variables.`;
-  if ( !was_user_error ) { await scope.addToReport(scope, { type: `error`, value: not_user_error_msg }); }
+  if ( !was_user_error ) { reports.addToReport(scope, { type: `error`, value: not_user_error_msg }); }
   expect( was_user_error, not_user_error_msg ).to.be.true;
 
   await scope.afterStep(scope);
@@ -584,7 +586,7 @@ Then('I arrive at the next page', async () => {  // √
   *    Can other things trigger navigation? Re: other inputs things
   *    like 'Enter' acting like a click is a test for docassemble */
   let msg = `User did not arrive at the next page.`
-  if ( !scope.navigated ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !scope.navigated ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( scope.navigated, msg ).to.be.true;
   await scope.afterStep(scope);
 });
@@ -595,7 +597,7 @@ Then('I should see the link {string}', async ( linkText ) => {  // √
   let [link] = await scope.page.$x(`//a[contains(text(), "${linkText}")]`);
 
   let msg = `Cannot find a link with the text "${ linkText }".`;
-  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.afterStep(scope);
@@ -606,7 +608,7 @@ Then('I should see the link to {string}', async ( url ) => {  // √
   let link = await scope.page.$(`*[href="${ url }"]`);
 
   let msg = `Cannot find a link to "${ url }".`;
-  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.afterStep(scope);
@@ -622,7 +624,7 @@ Then(/the "([^"]+)" link leads to "([^"]+)"/, async (linkText, expected_url) =>
   let actual_url = await prop_obj.jsonValue();
 
   let msg = `Cannot find a link with the text "${ linkText }" leading to ${ expected_url }.`;
-  if ( actual_url !== expected_url ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( actual_url !== expected_url ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( actual_url ).to.equal( expected_url );
 
   await scope.afterStep(scope);
@@ -641,7 +643,7 @@ Then(/the "([^"]+)" link opens in (a new window|the same window)/, async (linkTe
     || ( !should_open_a_new_window && !opens_a_new_window );
 
   let msg = `The link "${ linkText }" does NOT open in ${ which_window }.`;
-  if ( !hasCorrectWindowTarget ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !hasCorrectWindowTarget ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( hasCorrectWindowTarget, msg ).to.be.true;
 
   await scope.afterStep(scope);
@@ -674,7 +676,7 @@ Then(/(?:the )?text(?: in)?(?: the)?(?: JSON)?(?: var)?(?:iable)?(?: )?"([^"]+)"
 
   // Add warning to report if value is not as expected
   if ( actual_value !== expected_value ) {
-    await scope.addToReport( scope, {
+    reports.addToReport( scope, {
       type: `error`,
       value: `The variable "${ var_name }" was not equal to the expected `
         + `value on the "${ scope.page_id }" screen. Check `
@@ -704,6 +706,19 @@ Then(/I get the(?: page's)?(?: JSON)? var(?:iable)?s and val(?:ue)?s/i, { timeou
   );
 });
 
+Then(/I expect the baseline PDF "([^"]+)" and the new PDF "([^"]+)" to be the same/i, async (existing_pdf_path, new_pdf_path) => {
+  /** Compare the text or fields of a baseline PDF and the newly downloaded PDF.
+  * 
+  * Variations:
+  * Then I expect the baseline PDF "simple-doc-Baseline.pdf" and the new PDF "simple-doc.pdf" to be the same
+  */
+  
+  return await wrapPromiseWithTimeout(
+    scope.steps.compare_pdfs(scope, {existing_pdf_path, new_pdf_path}),
+    scope.timeout
+  );
+});
+
 //#####################################
 //#####################################
 // Actions
@@ -781,7 +796,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
   let random_input_path = `${ scope.paths.scenario }/random${ timestamp }`
   scope.paths.random_screenshots = random_input_path;
   fs.mkdirSync( scope.paths.random_screenshots );
-  await scope.addToReport( scope, {
+  reports.addToReport( scope, {
     type: 'row',
     value: `Testing interview with random input (in ${ random_input_path })`
   });
@@ -816,7 +831,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
         let has_content = await scope.has_interview_content( scope );
 
         if ( !has_content ) {
-          await scope.addToReport( scope, {
+          reports.addToReport( scope, {
             type: `error`,
             value: no_content_err
           });
@@ -825,7 +840,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
         } else {
           let timeout_message = `The page with an id of "${ id }" took too long`
             + ` to fill with random answers (over ${ scope.timeout/1000/60 } min).`
-          await scope.addToReport( scope, { type: `error`, value: timeout_message });
+          reports.addToReport( scope, { type: `error`, value: timeout_message });
           reject( timeout_message );
         }
 
@@ -866,7 +881,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
             // Make sure to only throw once
             if ( !has_thrown ) {
               has_thrown = true;
-              await scope.addToReport( scope, {
+              reports.addToReport( scope, {
                 type: `error`,
                 value: no_content_err
               });
@@ -890,7 +905,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
           // Throw a specific error if there's no interview content
           let has_content = await scope.has_interview_content( scope );
           if ( !has_content ) {
-            await scope.addToReport( scope, {
+            reports.addToReport( scope, {
               type: `error`,
               value: no_content_err
             });
@@ -900,7 +915,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
           } else {
             let err_msg = `The page with the question id "${ id }" errored when trying to fill`
               + ` it with random answers: ${ error.name }`
-            await scope.addToReport( scope, { type: `error`, value: err_msg });
+            reports.addToReport( scope, { type: `error`, value: err_msg });
             reject( error );
           }  // ends if !has_content
 
@@ -1098,24 +1113,38 @@ Given(/the final Scenario status should be "(passed|failed)"/i, async ( expected
 
 After(async function(scenario) {
 
+  let changeable_test_status = scenario.result.status;
   // The accessibility failures don't happen til the end, so the rest of the test can continue
   if ( scope.check_all_for_a11y && !scope.passed_all_for_a11y) {
     // The fact that the scenario failed has already been noted earlier in the report
-    scenario.result.status = `FAILED`;
+    changeable_test_status = `FAILED`;
+    reports.addToReport(scope, {
+      type: `error`,
+      value: `Accessibility standards weren't met. See information above.`
+    });
+  }
+
+  if ( scope.failed_pdf_compares.length > 0) {
+    let msg = scope.failed_pdf_compares.reduce((str, new_msg) => `${ str }\n---\n${ new_msg }`)
+    changeable_test_status = `FAILED`;
+    reports.addToReport(scope, {
+      type: `error`,
+      value: `PDF comparison failed ${ scope.failed_pdf_compares.length } time(s)\n---\n${ msg }\n---\n`
+    });
   }
 
   // Record status before internal report tests can interfere with values
-  await scope.setReportScenarioStatus( scope, { status: scenario.result.status });
+  reports.setReportScenarioStatus( scope, { status: changeable_test_status });
 
-  if (scenario.result.status !== `PASSED`) {
+  if (changeable_test_status !== `PASSED`) {
     if ( session_vars.get_debug() ) {
-      console.log( `Non-passed status occurred while running test:`, scenario.result.status );
+      console.log( `Non-passed status occurred while running test:`, changeable_test_status );
     }
 
     if ( scope.page ) {
 
       if ( !!scope.disable_error_screenshot ) {
-        scope.addToReport(scope, {
+        reports.addToReport(scope, {
           type: `row`,
           value: `For security, ALKiln will avoid creating a picture of the page for this error. It's possible a secret is being used on this screen.`
         });
@@ -1139,21 +1168,19 @@ After(async function(scenario) {
     }  // ends if scope.page exists
 
     // This has to come after the security message or security message doesn't print. Not sure why.
-    if (scenario.result.status === `FAILED`) {
-      await scope.addToReport(scope, { type: `outcome`, value: `**-- Scenario Failed --**` });
+    if (changeable_test_status === `FAILED`) {
+      reports.addToReport(scope, { type: `outcome`, value: `**-- Scenario Failed --**` });
     }
 
   }  // ends if not passed
 
-  let original_scenario_status = scenario.result.status;
-
   // Internal tests of this framework
   if ( scope.expected_status ) {
     let expected = scope.expected_status;
     scope.expected_status = null;  // reset for next Scenario
-    expect( scenario.result.status ).to.equal( expected );
+    expect( changeable_test_status ).to.equal( expected );
     // If the status was as expected, pass this criteria
-    scenario.result.status = `PASSED`;
+    changeable_test_status = `PASSED`;
   }
   
   if ( scope.expected_in_report && scope.expected_in_report.length > 0) {
@@ -1162,8 +1189,8 @@ After(async function(scenario) {
     scope.expected_in_report = null;
     let all_were_included = await scope.reportIncludesAllExpected( scope, { expected });
 
-    if ( all_were_included ) { scenario.result.status = `PASSED`; }
-    else { scenario.result.status = `FAILED`; }
+    if ( all_were_included ) { changeable_test_status = `PASSED`; }
+    else { changeable_test_status = `FAILED`; }
   }
   
   if (scope.expected_not_in_report && scope.expected_not_in_report.length > 0) {
@@ -1173,9 +1200,9 @@ After(async function(scenario) {
     let all_were_not_there = await scope.reportDoesNotInclude( scope, { not_expected });
 
     if ( all_were_not_there ) {
-      scenario.result.status = `PASSED`;
+      changeable_test_status = `PASSED`;
     } else { 
-      scenario.result.status = `FAILED`;
+      changeable_test_status = `FAILED`;
     }
 
   }
@@ -1199,7 +1226,7 @@ After(async function(scenario) {
       } else {
         // Throw any non-timeout error
         let err_msg = `Error occurred when ALKiln tried to sign out in preparation for the next test.`
-        scope.addToReport( scope, { type: `error`, value: err_msg });
+        reports.addToReport( scope, { type: `error`, value: err_msg });
         throw error;
       }  // ends if error is timeout error
 
@@ -1210,16 +1237,29 @@ After(async function(scenario) {
   // Add report text to Scenario folder after everything has been added to the report
   let current_report_obj = scope.report.get( scope.scenario_id );
   let scenario_report_obj = [ scope.scenario_id, current_report_obj ];  // Mimic how loop works with `Map`
-  let report = await scope.getPrintableScenario( scope, { scenario: scenario_report_obj });
+  let report = reports.getPrintableScenario( scenario_report_obj );
   // Save the report as in the Scenario folder
   fs.writeFileSync( scope.paths.scenario_report, report );
+
+  if ( changeable_test_status === `FAILED` ) {
+    // If the result object status wasn't failure and we still want
+    // the tests to fail, as with a11y tests, we can't mess with the
+    // cucumber result.status object because it will cause unwanted
+    // errors. We have to throw an error here instead.
+    if ( scenario.result.status !== `FAILED` ) {
+      throw new Error(`The test failed. See the report for more information.`);
+    }
+  } else {
+    // Other types of errors should be ok
+    scenario.result.status = changeable_test_status;
+  }
 });
 
 AfterAll(async function() {
   // Stop collecting server response statuses
   scope.stop_tracking_server_status = true;
   
-  let report = await scope.getPrintableReport( scope );
+  let report = reports.getPrintableReport( scope );
   // Log the report. Can't get this.attach() or this.log() to work in `After()` or here.
   // May need newest version of cucumberjs
   console.log( `\n\n${ report }` );

package/lib/utils/pdf_reader.js

@@ -0,0 +1,113 @@
+// All functions dealing with getting information from PDFs
+
+const pdfjs_lib = require("pdfjs-dist/legacy/build/pdf.js");
+const diff_lib = require("diff");
+
+let _load_pdf = async function(pdf_path) {
+  // Simple wrapper to get the document
+  return await pdfjs_lib.getDocument({
+    url: pdf_path,
+    // https://github.com/mozilla/pdf.js/issues/4244#issuecomment-1479534301
+    useSystemFonts: true
+  }).promise;
+};
+
+let _get_content = async function(pdf_doc) {
+  let num_pages = pdf_doc.numPages;
+  let contents = "";
+  for (var i = 1; i <= num_pages; i++) {
+    const page_contents = await (await pdf_doc.getPage(i)).getTextContent();
+    contents += "\n" + page_contents.items.map((item) => item.str).join(" ");
+  }
+  return contents;
+};
+
+let pdf_reader = {};
+
+pdf_reader.get_content = async function(pdf_path) {
+  /* Gets the full text content from the PDF.
+   *
+   * @returns str
+   */
+
+  let doc = await _load_pdf(pdf_path);
+  return await _get_content(doc);
+}; // Ends get_content()
+
+pdf_reader.get_fields = async function(pdf_path) {
+  /* Gets all of the fields in the PDF
+   * 
+   * Example:
+   * {
+   *   "users1_name_first": [
+   *      {
+   *         "id": "6R",
+   *         "value": "aeu",
+   *         "defaultValue": "",
+   *         "multiline": false,
+   *         "password": false,
+   *         "charLimit": 0,
+   *         "comb": false,
+   *         "editable": true,
+   *         "hidden": false,
+   *         "name": "users1_name_first",
+   *         "rect": [
+   *             143.52,
+   *             660.72,
+   *             315.11,
+   *             674.88
+   *         ],
+   *         "actions": null,
+   *         "page": 0,
+   *         "strokeColor": null,
+   *         "fillColor": null,
+   *         "rotation": 0,
+   *         "type": "text"
+   *       }
+   *   ],
+   */
+  let doc = await _load_pdf(pdf_path);
+  const field_objects = await doc.getFieldObjects();
+  return field_objects;
+}; // Ends get_fields
+
+pdf_reader.get_field_value = async function(pdf_path, field_name) {
+  let field_objects = await pdf_reader.get_fields(pdf_path);
+  if (field_name in field_objects) {
+    for (let inst of field_objects[field_name]) {
+      if ("value" in inst) {
+        return inst["value"];
+      }
+    }
+  }
+  return null;
+}; // Ends get_field
+
+pdf_reader.compare_pdfs = async function(existing_pdf_path, new_pdf_path) {
+  /**
+   * Returns the change objects between the PDF fields, if there's any diff
+   */
+  let existing_doc = await _load_pdf(existing_pdf_path);
+  let new_doc = await _load_pdf(new_pdf_path);
+  let existing_content = await _get_content(existing_doc);
+  let new_content = await _get_content(new_doc);
+
+  // Assumption: authors won't be changing their PDF templates programmatically;
+  // so if the text of the PDFs are different, then it's actually the fields that are different,
+  // but they aren't editable / are flattened into the PDF. 
+  let change = diff_lib.diffWords(existing_content, new_content);
+  if (change.some(diff => diff.added || diff.removed)) {
+    return change;
+  }
+
+  const existing_fields = await existing_doc.getFieldObjects();
+  const new_fields = await new_doc.getFieldObjects();
+
+  let changeObjs = diff_lib.diffJson(existing_fields, new_fields);
+  if (changeObjs.some(diff => diff.added || diff.removed)) {
+    return changeObjs;
+  }
+  return null;
+}; // End compare_pdfs
+
+module.exports = pdf_reader;

package/lib/utils/reports.js

@@ -0,0 +1,147 @@
+const fs = require(`fs`);
+
+// Ours
+const session_vars = require(`./session_vars`);
+const files = require(`./files` );
+
+
+module.exports = reports = {};
+
+reports.addReportHeading = function (scope, { scenario }) {
+  /** Return printable heading based on Scenario name and tags.
+  *    Allow characters from other languages.
+  */
+  if ( session_vars.get_debug() ) { console.log(`reports.addReportHeading(): ${scenario.pickle.name} \n`); }
+
+  // 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---------------`;
+
+  reports.addToReport( scope, {
+    type: `heading`,
+    value: heading,
+  });
+};  // Ends reports.addReportHeading()
+
+reports.addToReport = 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(`reports.addToReport():\ntype: ${ type }, value: ${ value }\n`) }
+  let scenario = makeSureReportPartsExist( scope );
+  scenario.lines.push({ type, value });
+
+  const MISC_ARTIFACTS_DIR = `_alkiln-misc_artifacts`;
+  // 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 reports.addToReport()
+
+let makeSureReportPartsExist = 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 makeSureReportPartsExist()
+
+reports.setReportScenarioStatus = 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 reports.setReportScenarioStatus()
+
+reports.convertToOriginalStoryTableRow = 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 = trimJSON( original.var );
+  let value_str = trimJSON( original.value );
+  let trigger_str = trimJSON( 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 reports.convertToOriginalStoryTableRows()
+
+let trimJSON = function( 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 trimJSON()
+
+reports.getPrintableReport = 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 = reports.getPrintableScenario( 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 reports.getPrintableReport()
+
+reports.getPrintableScenario = function( 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 reports.getPrintableScenario()