@suffolklitlab/alkiln 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -44,6 +44,14 @@ Format:
 -->
 <!-- ## [Unreleased] -->
 
+## [5.4.0] - 2023-10-14
+
+### Added
+
+- New step to compare PDFs!
+    - An example: `I expect the baseline PDF "something-in-sources.pdf" and the new PDF "downloaded.pdf" to be the same`
+    - See [#774](https://github.com/SuffolkLITLab/ALKiln/pull/774) for more details.
+
 ## [5.3.0] - 2023-10-14
 
 ### Added

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');
@@ -1679,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 ) {
+    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 = [];
@@ -1717,7 +1711,7 @@ 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
@@ -1727,14 +1721,13 @@ module.exports = {
         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 = [];
@@ -1760,9 +1753,27 @@ module.exports = {
       });
     }
 
-    // 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
@@ -2503,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.
@@ -2930,4 +2967,5 @@ module.exports = {
 
     return none_included;
   },
+
 };

package/lib/steps.js

@@ -147,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;
@@ -705,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
@@ -1104,12 +1118,21 @@ After(async function(scenario) {
   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
     changeable_test_status = `FAILED`;
-    scope.addToReport(scope, {
+    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
   reports.setReportScenarioStatus( scope, { status: changeable_test_status });
 

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;