@suffolklitlab/alkiln 5.13.3 → 5.13.4

package/lib/docassemble/takedown.js

@@ -1,26 +1,49 @@
 #!/usr/bin/env node
 
 const da_i = require('./docassemble_api_interface');
-const log = require('../utils/log');
-const session_vars = require('../utils/session_vars' );
+const session_vars = require('../utils/session_vars');
+const Log = require('../utils/Log');
+
+const context = `takedown`;
 
 const takedown = async () => {
-  /* In the docassemble testing account identified by the
-  *   DOCASSEMBLE_DEVELOPER_API_KEY secret, delete the
-  *   Project created for this test.
-  *   For local development, clean up project name file. */
-  log.info({ type: `takedown`, code: `ALK0177`, pre: `Trying to remove the docassemble Project from the testing account.` });
+  /** In the docassemble testing account identified by the
+   *  DOCASSEMBLE_DEVELOPER_API_KEY secret, delete the Project created for this
+   *  test. For local development, clean up Project name in the runtime_config
+   *  file.
+   * */
+  log.info({ code: `ALK0177`, context, },
+    `Trying to remove the docassemble Project from the testing account.`
+  );
   // Explicit try-catch prevents "Unhandled promise rejection error"
   // avoids showing confusing node errors to users that they shouldn't have to fix
   try {
     await da_i.delete_project();
     session_vars.delete_project_name();
-    log.success({ type: `takedown`, code: `ALK0178`, pre: `Test takedown has finished successfully!` });
+    log.info({ code: `ALK0178`, context, },
+      `Test takedown finished successfully!`
+    );
   } catch (error) {
-    log.error({type: `takedown`, code: `ALK0179`, pre: `Could not delete project`, data: JSON.stringify(error, null, 4)})
-    // we don't re-throw the exception, so make sure to exit with 1 to let GitHub Actions know the script failed
+    log.throw({ code: `ALK0179`, context, error: error },
+      `Unable to delete project`,
+    );
+    // we don't re-throw the exception, so make sure to exit
+    // with 1 to let GitHub Actions know the script failed
     process.exitCode = 1;
   }
+
+  // TODO: ? Build the final setup, run, & takedown verbose log
+  // file in here. Add to it in the GitHub action ?
 };
 
+// 1. session_vars - make sure all the required env vars exist
+session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// Local devs: This will be separate from your test artifacts paths
+// unless you pass a `path` argument into the `cucumber` run command
+const argv = require(`minimist`)( process.argv.slice(2) );
+const log = new Log({ path: argv.path, context, });
+
+// 3. run
 takedown();

package/lib/parse.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+let log = `log`;
+let args = get_command_line_args();
+let sources_paths = get_sources_paths( args );
+let feature_files_paths = get_feature_files( sources_paths );
+
+let all_errors = [];
+// Just see if any error when Gherkin parses them
+for ( let file_path of feature_files_paths ) {
+  try {
+    Gherkin.parse( file_path );
+  } catch ( error ) {
+    all_errors.push( error );
+  }
+}
+// let generated_files_paths = constrained_random_answer_tests.generate();
+// // Just see if any error when Gherkin parses them
+// for ( let generated_path of generated_files_paths ) {
+//   try {
+//     Gherkin.parse( generated_path );
+//   } catch ( error ) {
+//     all_errors.push( error );
+//   }
+// }
+
+let generator_errors = constrained_random_answer_tests.generate();
+all_errors = [ ...all_errors, ...generator_errors ];
+
+if ( all_errors.length > 0 ) {
+  // Use the Log class in here
+  for ( let one_error of all_errors ) {
+    console.log( `An error:`, one_error );
+  }
+  throw new Error( `ALKiln ran into an error when parsing the test files. See above for more details` );
+}

package/lib/run_cucumber.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
+const path = require(`path`);
 const cucumber_api = require('@cucumber/cucumber/api');
 
-const log = require('./utils/log');  // These always log in the console
+const Log = require('./utils/Log');
 const session_vars = require('./utils/session_vars');
 
 const SUMMARY_FILENAME = `cucumber-report.txt`;
@@ -53,11 +54,14 @@ function build_config( command_args ) {
 };  // Ends build_config()
 
 
-(async function main() {
+async function main() {
   /** Create the cucumber config, run the tests, create and
   *   manipluate the output. */
+
   const environment = { cwd: process.cwd() };
-  log.info({ type: `run`, code: `ALK0049`, pre: `environment`, data: environment });
+  log.info({ code: `ALK0049`, context: `pre_run environment` },
+    environment
+  );
 
   // We'll use the user info to construct the possible paths to /sources
   let id = session_vars.get_user_id();
@@ -65,8 +69,9 @@ function build_config( command_args ) {
   let project = session_vars.get_user_project_name();
 
   // process.argv is a list of strings of commands and args.
-  // If using `npm run cucumber`, use `--` before `--sources=./foo`
-  let argv = require(`minimist`)( process.argv.slice(2), {
+  // If using `npm run cucumber` (as opposed to the bin commands),
+  // use `--` before `--sources=./foo`
+  const argv = require(`minimist`)( process.argv.slice(2), {
     default: {
       sources: [
         `./docassemble/*/data/sources`,  // In GitHub folder
@@ -85,35 +90,52 @@ function build_config( command_args ) {
   let one_dir_exists = session_vars.set_sources_paths( sources_list );
   if ( !one_dir_exists ) {
     // If we don't throw, it'll be more confusing when no tests run
-    let msg = `ALKiln can't find your "sources" folder(s). See above for details.`;
-    let code = `ALK0050`
-    log.error({ type: `run`, code: code, pre: msg });
-    throw new ReferenceError(`🤕 ${ code } run ERROR: ${ msg }`);
+    log.throw({ code: `ALK0050`, context: `pre_run`,
+      error: new ReferenceError(
+        `ALKiln can't find your "sources" folder(s). See above for details.`
+      ),
+    });
   }
   
   const { runConfiguration } = await cucumber_api.loadConfiguration({
     provided: build_config( argv ),
   }, environment);
-
-  log.info({ type: `run`, code: `ALK0051`, pre: `runConfiguration`, data: runConfiguration });
-
-  var path = require(`path`);
-  var codeDir = path.dirname(require.main.filename);
-  log.info({ type: `run`, code: `ALK0052`, pre: `working directory`, data: codeDir });
+  log.info({ code: `ALK0051`, context: `pre_run config`, },
+    runConfiguration
+  );
+
+  const codeDir = path.dirname(require.main.filename);
+  log.info({ code: `ALK0052`, context: `pre_run directory`, },
+    codeDir, `\n\n`
+  );
   const support = await cucumber_api.loadSupport({ support: {
     requireModules: [ `${ codeDir }/index.js` ],
     requirePaths: [ `${ codeDir }/index.js` ],
     importPaths: [],
   }, sources: {paths: []}}, environment);
 
-  log.info({ type: `run`, code: `ALK0053`, pre: `working directory`, data: codeDir });
-  log.info({ type: `plain`, pre: `\n\n` });
-
+  // ====================
+  /** Run */
+  // ====================
   const { success } = await cucumber_api.runCucumber({...runConfiguration, support});
+  // ====================
+
+  /** Write to files.
+   *
+   * Note: Don't add to the purely report-focused files. Those are files where
+   *    authors can focus on the info we give them, which they often miss in
+   *    the GitHub action.
+   */
+
   if ( success ) {
-    log.success({ type: `run`, code: `ALK0054`, pre: `Tests succeeded!` });
+    log.success({ code: `ALK0054`, context: `post_run`, },
+      `Tests succeeded!`
+    );
   } else {
-    log.error({ type: `run`, code: `ALK0055`, pre: `The test run ran into something unexpected. Look above for more details.` });
+    // Don't want to throw error here, so don't pass error object
+    log.warn({ code: `ALK0055`, context: `post_run`, },
+      `The tests ran into something unexpected. Look above for more details.`
+    );
   }
   // Custom exit code. May overlap with other systems.
   // Best info I've found via stack overflow: https://tldp.org/LDP/abs/html/exitcodes.html
@@ -123,10 +145,12 @@ function build_config( command_args ) {
   // This is hardcoded information from `provide_config` above.
   // This code isn't used for anything other than detecting and removing color codes.
   let summary_file_name = SUMMARY_FILENAME;
-  fs.readFile(summary_file_name, 'utf8', (err, text) => {
-    if (err) {
+  fs.readFile(summary_file_name, 'utf8', (read_error, text) => {
+    if ( read_error ) {
       // Something else will probably show an error that's more relevant
-      log.info({ type: `run`, code: `ALK0056`, pre: `Failed to read cucumber report`, data: err });
+      log.warn({ code: `ALK0056`, context: `post_run error`, },
+        `Failed to read cucumber report`, read_error
+      );
       return;
     }
 
@@ -134,20 +158,75 @@ function build_config( command_args ) {
     // https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797#colors--graphics-mode
     text = text.replace(/\x1b\[[0-9][0-9]?[0-9]?m/g, '');
 
-    // Put it in the correct file in the correct folder
-    let artifacts_path = session_vars.get_artifacts_path_name();
-    try {
-      fs.appendFileSync( `${ artifacts_path }/${ log.debug_log_file }`, `\n\n${text}`);
-    } catch ( error ) {
-      log.info({ type: `run`, code: `ALK0182`, pre: `Something probably went wrong earlier. Look above for more details, but here is more information just in case: ALKiln was unable to write to ${ artifacts_path }/${ log.debug_log_file }.`, data: error });
-    }
     try {
-      // Add to a unexpected results file when tests themselves fail
+      // Add to the debug and non-passed test output files
       if ( exitCode === 50 ) {
-        fs.appendFileSync( `${ artifacts_path }/${ log.unexpected_filename }`, `\n\n${ text }` );
+        // Save only non-passing test output to cut out cruft.
+        // Our reports save only non-passing tests to this file.
+        log.debug({ icon: `🔎`, code: `ALK0216`, context: `post_run`, level: `warn` },
+          `\n\n`, text
+        );
+      } else {
+        log.debug({ code: `ALK0225`, context: `post_run`, },
+          `\n\n`, text
+        );
       }
-    } catch ( error ) {
-      log.info({ type: `run`, code: `ALK0181`, pre: `Something probably went wrong earlier. Look above for more details, but here is more information just in case: ALKiln was unable to write to ${ artifacts_path }/${ log.unexpected_filename }.`, data: error });
-    }
+
+      /** Include debug info at the bottom of the unexpected results file if
+       *  needed. Avoid creating the file if its not necessary. */
+      let temp_debug_unexpected_content = ``;
+      try {
+        temp_debug_unexpected_content = fs.readFileSync(`${ log.path }/${ log.temp_unexpected_debug_log_filename }`);
+      } catch ( ignore_err ) { /* Missing debug info is ok */ }
+
+      if ( temp_debug_unexpected_content !== `` ) {
+        // Add spacing before the debug content if file already has content
+        try {
+          fs.readFileSync(`${ log.path }/${ log.unexpected_filename }`);  // Does it have contents?
+          fs.appendFileSync(`${ log.path }/${ log.unexpected_filename }`, `\n\n\n\n\n` );
+        } catch ( ignore_err ) { /* Missing unexpected file is ok */ }
+
+        // Add the heading for debug content
+        fs.appendFileSync( `${ log.path }/${ log.unexpected_filename }`,
+`≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡
+🐛        Full DEBUG info (some repeated content)        🐛
+≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡\n\n`
+        );
+        // Add the debug content itself
+        fs.appendFileSync(`${ log.path }/${ log.unexpected_filename }`, temp_debug_unexpected_content );
+      }
+
+    } catch ( writing_cucumber_error ) {
+      let code = `ALK0182`;
+      let context = `post_run error`
+      let msg = `Something probably went wrong earlier. Look above for more details. Skipped writing to ${ log.path }/${ log.debug_log_filename }.`;
+      try {
+        log.warn({ code, context, }, msg, writing_cucumber_error );
+      } catch ( all_writing_error ) {
+        console.warn( `🔎 ${ code } ${ context } WARNING ${ Date.now() }: ${ msg }` );
+        console.warn( writing_cucumber_error );
+        console.warn( all_writing_error );
+      }
+
+    }  // ends try writing to debug files
+
+    return;
   });
-})();
+}
+
+
+// 1. session_vars - make sure all the required env vars exist
+session_vars.validateEnvironment();
+
+// 2. Prepare logs
+// process.argv is a list of strings of commands and args.
+// If using `npm run cucumber` (as opposed to the bin commands),
+// use `--` before `--sources=./foo`
+const argv = require(`minimist`)( process.argv.slice(2) );
+// The artifacts folder might be getting created for the first
+// time right here. The tests themselves should avoid creating
+// their own file.
+const log = new Log({ path: argv.path, context: `run` });
+
+// 3. run
+main();

package/lib/scope.js

@@ -13,14 +13,12 @@ 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');
-const log = require('./utils/log');
 const { waitForTimeout } = require('./utils/time');
 const files = require('./utils/files' );
 const da_api = require('./docassemble/docassemble_api_interface');
 const wrapPromiseWithTimeout = require('./cucumber_8_shim');
 const reports = require(`./utils/reports`);
 
-
 let ordinal_to_integer = {
   only: 0, first: 0, second: 1, third: 2, fourth: 3, fifth: 4,
   sixth: 5, seventh: 6, eighth: 7, ninth: 8, tenth: 9,
@@ -84,10 +82,16 @@ let toBase64 = function ( utf8_str, exclude_padding=true) {
 
 let proxies_regex = /(\bx\.)|(\bx\[)|(\[[ijklmn]\])/g;
 let da_base64_regex = /^[A-Za-z0-9+/]+$/;
+let log = null;
 
 module.exports = {
   trigger_not_needed_flag: `ALKiln: no trigger variable needed`,
 
+
+  set_log: function ({ log_obj }) {
+    log = log_obj;
+  },
+
   getSafeScenarioBaseFilename: async function( scope, { scenario }) {
     /** Return a string that's safe to be a filename. Include the Scenario
     *    description and tags.
@@ -698,7 +702,7 @@ module.exports = {
       });
       expect( load_result.error ).to.equal( '' );
     } else {
-      reports.addToReport(scope, { type: `row info`, code: `ALK0117`, value: `Successfully found the interview at "${ interview_url }"` });
+      reports.addToReport(scope, { type: `row info`, code: `ALK0117`, value: `Successfully found the interview` });
     }
 
     return scope.page;
@@ -717,19 +721,19 @@ module.exports = {
       if ( !scenario.interviews ) { scenario.interviews = {}; }
       if ( !scenario.interviews[ vars.uid ] ) {
         scenario.interviews[ vars.uid ] = vars;
-        log.debug({
-          code: `ALK0185`, type: `info`,
-          pre: `Saved new interview data. File path: ${ vars.i }. Session id: ${ vars.uid }.`
-        });
+        log.debug({ code: `ALK0185`, context: `session_id_etc` },
+          `Saved new interview data. File path: ${ vars.i }. Session id: ${ vars.uid }.`
+        );
       } else {
-        log.debug({
-          code: `ALK0186`, type: `info`,
-          pre: `Interview data already existed. File path: ${ vars.i }. Session id: ${ vars.uid }.`
-        });
+        log.debug({ code: `ALK0186`, context: `session_id_etc` },
+          `Interview data already existed. File path: ${ vars.i }. Session id: ${ vars.uid }.`
+        );
       }
       return vars;
     } else {
-      log.debug({ code: `ALK0187`, type: `info`, pre: `Found no interview data.` });
+      log.debug({ code: `ALK0187`, context: `session_id_etc` },
+        `Found no interview data.`
+      );
       return null;
     }
   },  // Ends scope.set_interview_session_data()
@@ -876,11 +880,9 @@ module.exports = {
       supported_table.push( result );
     }  // ends for every row
 
-    log.debug({
-      code: `ALK0122`,
-      type: `info`,
-      pre: `scope.normalizedTable():\n ${JSON.stringify( supported_table )}`
-    });
+    log.debug({ code: `ALK0122`, context: `table`, },
+      `scope.normalizedTable():`, supported_table
+    );
 
     return supported_table;
   },  // Ends scope.normalizeTable()
@@ -1030,11 +1032,9 @@ module.exports = {
       fields.push( field_data );
     }  // ends for every node
 
-    log.debug({
-      code: `ALK0124`,
-      type: `info`,
-      pre: `page fields:\n${ JSON.stringify( fields )}`
-    });
+    log.debug({ code: `ALK0124`, context: `page fields`, },
+      fields
+    );
     return fields;
   },  // Ends scope.getAllFields()
 
@@ -1084,11 +1084,9 @@ module.exports = {
     /* Return variable names and values combined in ways that can
     * try to match table rows. Tables can have two properties:
     * variable name and value. */
-    log.debug({
-      code: `ALK0126`,
-      type: `info`,
-      pre: `scope.getPossibleTableRowMatchers() var_names: ${JSON.stringify(var_names)} values: ${JSON.stringify(values)}`
-    });
+    log.debug({ code: `ALK0126`, context: `matching`, },
+      `scope.getPossibleTableRowMatchers() var_names:`, var_names, `values:`, values
+    );
     let possible_table_rows = [];
     for ( let var_name of var_names ) {
       // Inputs like textareas don't have values
@@ -1563,17 +1561,13 @@ module.exports = {
       reports.addToReport(scope, { type: `warning`, code: `ALK0130`, value: multiple_matches_msg });
     }
 
-    log.debug({
-      code: `ALK0131`,
-      type: `info`,
-      pre: `final_matching_rows:\n${JSON.stringify( final_matching_rows )}`
-    });
+    log.debug({ code: `ALK0131`, context: `matching`, },
+      `final_matching_rows:`, final_matching_rows
+    );
     if ( final_matching_rows.length == 0) {
-      log.debug({
-        code: `ALK0132`,
-        type: `info`,
-        pre: `field:\n${JSON.stringify( field )}`
-      });
+      log.debug({ code: `ALK0132`, context: `matching`, },
+        `0 matching rows. Field:`, field
+      );
     }
 
     return final_matching_rows;
@@ -1659,11 +1653,9 @@ module.exports = {
 
   get_handle_from_field: async function ( scope, { field }) {
     /** Get the element's puppeteer handle using the field's selector. */
-    log.debug({
-      code: `ALK0133`,
-      type: `info`,
-      pre: `scope.get_handle_from_field() field.selector: ${JSON.stringify(field.selector)}`
-    });
+    log.debug({ code: `ALK0133`, },
+      `scope.get_handle_from_field() field.selector:`, field.selector
+    );
     let handle = await scope.page.evaluateHandle(( selector ) => {
       let elem = document.querySelector( selector );
       // If the element has a sibling that's a label, we need to
@@ -2175,7 +2167,9 @@ module.exports = {
     * @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({ type: `plain`, pre: `~~~~~~~~~~~~~~ scope.setFields() ~~~~~~~~~~~~~~` });
+    log.debug({ code: `ALK0221`, before: `~~~~~~~~~~~~~~\n`, },
+      `scope.setFields()`
+    );
 
     // Only record the page id once for each page to which we navigate
     let { id } = await scope.examinePageID( scope, 'none to match' );
@@ -2219,8 +2213,7 @@ module.exports = {
           // Accumulate number of times this row was used. Esp important for `.target_number`
           await scope.increment_row_use( scope, { row: row_used });
 
-          process.stdout.write(`\x1b[36m${ '*' }\x1b[0m`);  // assumes var was set if no error occurred
-
+          log.stdout({}, `\x1b[36m${ '*' }\x1b[0m`);  // assumes var was set if no error occurred
         }
       }  // ends for every non-submit-button field on the page
     }  // ends while fields are still being set
@@ -2265,7 +2258,7 @@ module.exports = {
           // }
 
           did_navigate = true;
-          process.stdout.write(`\x1b[36m${ 'v' }\x1b[0m`);  // pressed button successfully
+          log.stdout({}, `\x1b[36m${ 'v' }\x1b[0m`);  // pressed button successfully
           break;
 
         }  // ends if row_used
@@ -2312,7 +2305,7 @@ module.exports = {
       // }
 
       did_navigate = true;
-      process.stdout.write(`\x1b[36m${ '>' }\x1b[0m`);  // continued successfully
+      log.stdout({}, `\x1b[36m${ '>' }\x1b[0m`);  // continued successfully
     }  // ends if !did_navigate && ensure_navigation
 
     if ( did_navigate && scope.check_all_for_a11y ) {
@@ -3109,36 +3102,30 @@ module.exports = {
       let redirect_promise = scope.page.waitForResponse(function ( response ) {
         return response.status() === 302;
       }, { signal: controller.signal })
-      .catch(( error ) => {
-        log.debug({
-          code: `ALK0204`, type: `info`,
-          pre: `302 sign-in wait error: ${ error.name }`,
-          data: error,
-        });
+      .catch(( catch_info ) => {
+        log.debug({ code: `ALK0204`, context: `nav`, },
+          `302 sign-in wait catch error:`, catch_info.name, catch_info,
+        );
       });
 
       // Invalid credentials, no navigation, no sign in
       let wrong_sign_in_promise = scope.page.waitForResponse(function ( response ) {
         return response.status() >= 200 && response.status() < 300 && response.url().includes(`/sign-in`);
       }, { signal: controller.signal })
-      .catch(( error ) => {
-        log.debug({
-          code: `ALK0205`, type: `info`,
-          pre: `200s sign-in wait error: ${ error.name }`,
-          data: error,
-        });
+      .catch(( catch_info ) => {
+        log.debug({ code: `ALK0205`, context: `nav`, },
+          `200s sign-in wait catch error:`, catch_info.name, catch_info,
+        );
       });
 
       // System error
       let error_promise = scope.page.waitForResponse(function ( response ) {
         return response.status() >= 500 && response.status() < 600;
       }, { signal: controller.signal })
-      .catch(( error ) => {
-        log.debug({
-          code: `ALK0206`, type: `info`,
-          pre: `500s sign-in wait error: ${ error.name }`,
-          data: error,
-        });
+      .catch(( catch_info ) => {
+        log.debug({ code: `ALK0206`, context: `nav`, },
+          `500s sign-in wait catch error:`, catch_info.name, catch_info,
+        );
       });
 
       let click_promise = elem.click();  // MUST complete
@@ -3157,10 +3144,9 @@ module.exports = {
       // Clean up unresolved promises
       controller.abort();
 
-      log.debug({
-        code: `ALK0208`, type: `info`,
-        pre: `Sign-in winner:`, data: winner,
-      });
+      log.debug({ code: `ALK0208`, context: `nav` },
+        `Sign-in winner:`, winner
+      );
 
       return winner;
     },
@@ -3183,7 +3169,7 @@ module.exports = {
         } else {
           // Try to give a random answer for that element tag
           await scope.set_random_input_for[ field.tag ]( scope, { field: field });
-          process.stdout.write(`\x1b[36m${ '*' }\x1b[0m`);  // assumes var was set if no error occurred
+          log.stdout({}, `\x1b[36m${ '*' }\x1b[0m`);  // assumes var was set if no error occurred
         }
 
       }  // End for all page fields
@@ -3219,11 +3205,10 @@ module.exports = {
       }
       if (field == null) {
         // Just skip it? Shouldn't happen but has before. Dig in more
-        log.debug({
-          code: `ALK0164`,
-          type: `info`,
-          pre: `A random button field choice was null. These were the fields to choose from:\n${ JSON.stringify(fields, null, 2) }`,
-        });
+        log.debug({ code: `ALK0164`, context: `random`, },
+          `A random button field choice was null. These were the fields to choose from:`,
+          fields
+        );
         return;
       }
       let handle = await scope.get_handle_from_field( scope, { field: field });