@suffolklitlab/alkiln 5.13.4 → 5.15.0

package/lib/setup/artifacts.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const session_vars = require(`../utils/session_vars`);
+const files = require(`../utils/files`);
+const Log = require(`../setup/artifacts.js`);
+
+/** Reset and refresh artifacts path name */
+
+session_vars.delete_artifacts_path_name();
+
+// 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) );
+const artifacts_path = files.make_artifacts_folder( argv.path );
+
+session_vars.save_artifacts_path_name( artifacts_path );
+
+// Leave the config Project name value as it is. Local developers find it
+//    useful to re-use that value.

package/lib/setup/generate.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const Log = require(`../utils/Log`);
+const set_sources_paths = require(`../utils/set_sources_paths`);
+const TestGenerator = require(`./TestGenerator.js`);
+
+// 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) );
+const log = new Log({ path: argv.path, context: `generating files` });
+// Run script
+generate_constrained_random_test_files();
+
+
+function generate_constrained_random_test_files() {
+  /** Executable that generates constrained random answers tests and throws
+   *    errors.
+   * 
+   * Takes no arguments - uses command line arguments instead.
+   * */
+  let all_errors = [];
+
+  // Every file that's executed separately needs to figure out the location of
+  //    the sources folders.
+  let sources_paths = set_sources_paths({ log });
+  let generator = new TestGenerator();
+  for ( let sources_path of sources_paths ) {
+    let { errors: generating_errors } = generator.create({
+      sources_path,
+      logger: log
+    });
+    all_errors.push( ...generating_errors );
+  }
+
+  if ( all_errors.length > 0 ) {
+    log.throw({ code: `ALK0272`, context: `generating files`,
+      error: new Error( `ALKiln got error(s) when it tried to generate constrained random answers tests. See warnings and errors above.` )
+    });
+  };
+
+};

package/lib/setup/get_Gherkin_AST.js

@@ -0,0 +1,26 @@
+const Gherkin = require(`@cucumber/gherkin`);
+const Messages = require(`@cucumber/messages`);
+
+module.exports = function get_Gherkin_AST({ file_text }) {
+  /** Return Gherkin parser's abstract syntax tree of the given generator file
+   *
+   * @param {object} obj - Named arguments
+   * @param {string} file_text - The generator file's text contents
+   *
+   * @returns {object} - Gherkin parser's AST of the given generator file
+   * */
+  let AST = null;
+  let parse_errors = [];
+  try {
+    let uuidFn = Messages.IdGenerator.uuid();
+    let builder = new Gherkin.AstBuilder(uuidFn);
+    let matcher = new Gherkin.GherkinClassicTokenMatcher(); // or Gherkin.GherkinInMarkdownTokenMatcher()
+
+    let parser = new Gherkin.Parser(builder, matcher);
+    AST = parser.parse( file_text );
+  } catch ( gherkin_error ) {
+    parse_errors.push( gherkin_error );
+  }
+
+  return { AST, errors: parse_errors };
+}

package/lib/setup/validate.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+const fs = require(`fs`);
+const fast_glob = require(`fast-glob`);
+
+const globals = require(`../globals`);
+const Log = require(`../utils/Log`);
+const set_sources_paths = require(`../utils/set_sources_paths`);
+const get_Gherkin_AST = require(`./get_Gherkin_AST`);
+const get_error_stacks = require(`../utils/get_error_stacks`);
+
+
+/**
+ * TODO: Document that generator files need to have valid Gherkin syntax
+ * TODO: Document how to read Gherkin syntax errors. E.g.
+ *     (3:1): expected: #EOF, #Language, #TagLine, #FeatureLine, #Comment, #Empty, got 'Scenario: bar'
+ *     (6:1): expected: #EOF, #TableRow, #DocStringSeparator, #StepLine, #TagLine, #ExamplesLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got 'Feature: zoo'
+ * */
+
+
+// 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) );
+const log = new Log({ path: argv.path, context: `validating files` });
+// Run script
+validate_Gherkin_files();
+
+
+function validate_Gherkin_files() {
+  /** Accumulates syntax errors for all `.feature`` test files, including
+   *    generator files. If there are any, it logs those errors and then finally
+   *    throws an error. Uses the values in command line arguments.
+   * */
+
+  let sources_paths = set_sources_paths({ log });
+
+  let all_errors = [];
+  for ( let sources_path of sources_paths ) {
+    let { errors: files_errors } = parse_all_feature_files_in({ sources_path });
+    all_errors.push( ...files_errors );
+  }
+
+  // Discuss: If an author has only some files with syntax errors, should we try
+  //    to still run the tests for the files that had valid syntax?
+  if ( all_errors.length > 0 ) {
+    log.throw({ code: `ALK0230`, context: `validating files`,
+      error: new Error( `ALKiln ran into Gherkin syntax error(s) when parsing your test feature files. See warnings and errors above.` )
+    });
+  };
+}
+
+
+function parse_all_feature_files_in({ sources_path }) {
+  /** Returns accumulated list of Gherkin errors from all files in the
+   *    docassemble "sources" folder (or an empty list).
+   * 
+   * @param {object} obj - Named arguments
+   * @param {object} obj.sources_path - Path to the docassemble "sources" folder
+   * 
+   * @returns {{errors: [Error]}} Obj with an `error` prop that is a list of
+   *    Error instances. Follows the format of other functions that return
+   *    accumulated errors.
+   * */
+  let all_AST_errors = [];
+
+  let feature_file_paths = fast_glob.sync(
+    `${ sources_path }/**/*.feature`,
+    // These files were generated last time and will get deleted before the run
+    { ignore: [`${ sources_path }/${ globals.generated_files_folder_name }/*`] }
+  );
+
+  for ( let feature_path of feature_file_paths ) {
+
+    let file_text = fs.readFileSync( feature_path, { encoding: `utf8` });
+    let { AST, errors: these_AST_errors } = get_Gherkin_AST({ file_text });
+
+    if ( these_AST_errors.length > 0 ) {
+      all_AST_errors.push( ...these_AST_errors );
+      log.warn({ code: `ALK0276`, context: `validating files`, },
+        `There is a Gherkin syntax error(s) in "${ feature_path }"`,
+        ...get_error_stacks({ errors: these_AST_errors })
+      );
+    }
+
+  }  // ends for each file path
+
+  return { errors: all_AST_errors };
+}

package/lib/steps.js

@@ -5,6 +5,7 @@ const {
   Given,
   After,
   Before,
+  BeforeStep,
   AfterStep,
   BeforeAll,
   AfterAll,
@@ -98,17 +99,12 @@ BeforeAll(async function() {
   // Store path names for files and docs created for the tests
   scope.paths = {};
 
-  // // Make the folder to store all the files for this run of the tests
-  // scope.paths.artifacts = files.make_artifacts_folder();
-  // // Save its name in a file. `session_vars` can get it back later.
-  // // The value we are saving is used by at least run_cucumber.js.
-
   // A little indirect, but the artifacts path should always have already been
   // created by now, either by `run_cucumber.js` or the relevant test
-  scope.paths.artifacts = session_vars.get_artifacts_path_name();
-  log = new Log({ path: scope.paths.artifacts, context: `steps` });
+  log = new Log({ context: `steps` });
   scope.set_log({ log_obj: log });
 
+  scope.paths.artifacts = session_vars.get_artifacts_path_name();
   scope.paths.debug_log = `${ scope.paths.artifacts }/${ log.debug_log_filename }`;
   scope.paths.report_log = `${ scope.paths.artifacts }/${ log.report_log_filename }`;
   scope.paths.report = `${ scope.paths.artifacts }/${ log.report_filename }`;
@@ -179,6 +175,14 @@ Before(async (scenario) => {
 
 // Add a check for an error page before each step? After each step?
 
+BeforeStep(async function ( step ) {
+  // Discuss: In the report, add a way for the reports to add "✔" or "✖" to the
+  //    start of a Step after it's been completed, as cucumber already does. Add
+  //    a 'step' type and additional success/failure information, though that
+  //    may be challenging.
+  reports.addToReport(scope, { type: `row`, value: step.pickleStep.text });
+  reports.indent();
+});
 
 //#####################################
 //#####################################
@@ -343,17 +347,17 @@ Given(/the max(?:imum)? sec(?:ond)?s for each step (?:in this scenario )?is (\d+
 // Story
 //#####################################
 //#####################################
-// TODO: Consider more permissive sentences:
-// with(?: this data| these answers)?:?
-// with(?:.*):?
-When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)" with this data:?/, {timeout: -1}, async (target_id, raw_var_data) => {
+const INCLUDING_QUOTES_REGEX = /"([^"]*)"/g;
+When(/I? ?gets? to ?.*?(".*").*?with.*?(?:this data:)?/i, {timeout: -1}, async (target_ids, raw_var_data) => {
   /* NO CUCUMBER TIMEOUT. Must handle timeout ourselves:
   * https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/timeouts.md#disable-timeouts
   * Iterate in here to keep timeout reasonable */
 
   // Note: Why do we not just stop when we've used all the vars in the table or
   // reach the last var? Vars are not required to be given in sequence and pages that
-  // have non-button fields don't usually have a var assigned to the 'continue' button.
+  // have non-button fields often don't have a var assigned to the 'continue' button.
+  // It is optional for the table to use all the vars and some vars may be used
+  // multiple times.
   // Alternative: require vars even for 'continue' pages. Then in loop require at least one var
   // to be found on a page before hitting 'continue'. That requires detecting navigation because
   // pages with fields will not have a var for the continue button, so there will
@@ -361,10 +365,18 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
   // It also seems harsh, but more reliable.
   // Ask developers what they'd like.
 
+  let ids_as_list = Array.from(
+    target_ids.matchAll( INCLUDING_QUOTES_REGEX ),
+    ( match ) => { return match[ 1 ]; }
+  );
+  let sanitized_ids = ids_as_list.map(( risky_id ) => {
+    return scope.to_docassemble_sanitized_id( risky_id );
+  });
 
   let supported_table = await scope.normalizeTable( scope, { raw_var_data });
 
-  let { question_has_id, id, id_matches } = await scope.examinePageID( scope, target_id );
+  let id = await scope.get_page_id( scope );
+  let id_matches = id && sanitized_ids.includes( id );
   // Until we reach the target page, hit an error, or time out (take too long)
   while ( !id_matches ) {
     let custom_timeout = new Promise(function( resolve, reject ) {
@@ -372,8 +384,8 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
       // Set up the timeout that avoids infinite loops
       let on_page_timeout = async function() {
 
-        let non_reload_report_msg = `The target id was "${ target_id }", but it took `
-        + `too long to try to reach it (over ${ scope.timeout/1000/60 } min). The `
+        let non_reload_report_msg = `The target id or ids were ${ target_ids }, but it took `
+        + `too long to try to reach a valid id (over ${ scope.timeout/1000/60 } min). The `
         + `test got stuck on "${ id }".`
         let error = non_reload_report_msg;
         await scope.handle_page_timeout_error( scope, { non_reload_report_data: {
@@ -390,7 +402,7 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
       // Maybe list of timeout and/or interval ids in state that can all be cleared at once?
       (async function() {
         try {
-          let { question_has_id, id, id_matches } = await scope.examinePageID( scope );
+          let id = await scope.get_page_id( scope );
 
           // THIS FUNCTION ACTUALLY MATTERS
           // Add special rows. Basically, do weirder things.
@@ -408,10 +420,11 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
           // Some errors happen in there to be closer to the relevant code. We'd have to try/catch anyway.
           let error = await scope.setFields(scope, { var_data: ensured_var_data, id, ensure_navigation: true });
 
+          // Discuss: use Log class to throw this error?
           if ( error.was_found ) { await scope.throwPageError( scope, { id: id }); }
           resolve();
         } catch ( err ) {
-          let err_msg = `Error occurred when tried to answer fields on question "${ id }".`
+          let err_msg = `ALKiln ran into an error when it tried to answer fields on the page with the question id "${ id }". The text above might have more information.`
           reports.addToReport( scope, { type: `error`, code: `ALK0062`, value: err_msg });
           // Throw error instead?
           reject( err );
@@ -424,7 +437,8 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
     await custom_timeout;
 
     // Prep for next loop
-    ({ question_has_id, id, id_matches } = await scope.examinePageID( scope, target_id ));
+    id = await scope.get_page_id( scope );
+    id_matches = id && sanitized_ids.includes( id );
 
   }  // ends while !id_matches
   // Can anything unsatisfactory get through here?
@@ -443,7 +457,7 @@ 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?
   reports.addToReport( scope, { type: `note info`, code: `ALK0063`, value: `\n${ ' '.repeat(2) }Rows that got set:` });
-  reports.addToReport( scope, { type: `step info`, code: `ALK0064`, value: `${ ' '.repeat(4) }And I get to the question id "${ target_id }" with this data:` });
+  reports.addToReport( scope, { type: `step info`, code: `ALK0064`, value: `${ ' '.repeat(4) }And I get to any of the question ids ${ target_ids } with this data:` });
   reports.addToReport(scope, { type: `row info`, code: `ALK0065`, value: `${ ' '.repeat(6) }| var | value | trigger |`, });
   let at_least_one_row_was_NOT_used = false;
   for ( let row of sorted_rows ) {
@@ -707,39 +721,48 @@ Then(/the "([^"]+)" link opens in (a new window|the same window)/, async (linkTe
   await scope.afterStep(scope);
 });
 
-Then(/(?:the )?text(?: in)?(?: the)?(?: JSON)?(?: var)?(?:iable)?(?: )?"([^"]+)" should be/i, async (var_name, expected_value) => {
-  /* Check that the text string of the page's JSON var value matches
-  *    the given text string. Does not currently accept nested values
-  *    like "foo.bar". The word "text" is required.
-  *
-  * The format for this step is something like this:
-  * ```
-  * Then the text in the JSON variable "var_name" should be
-  * """
-  * A single or
-  * multiline string
-  * """
-  * ```
-  *
-  * Sentence combinations that will work:
-  * `the text in the JSON variable "variable_with_text_value" should be`
-  * `the text in the JSON var "variable_with_text_value" should be`
-  * `the text in "variable_with_text_value" should be`
-  * `text var "variable_with_text_value" should be`
-  */
+Then(/(?:the )?text(?: in)?(?: for)?(?: the)?(?: JSON)?(?: var)?(?:iable)?(?: )?"([^"]+)" should be/i, async (var_name, expected_value) => {
+  /** Check that the text string of the page's JSON var value matches
+   *    the given text string. Does not currently accept nested values
+   *    like "foo.bar". The word "text" is required.
+   *
+   * The format for this step is something like this:
+   * ```
+   * Then the text in the JSON variable "var_name" should be
+   * """
+   * A single or
+   * multiline string
+   * """
+   * ```
+   * 
+   * Note: ALKiln removes `\r` from both the expected and actual values.
+   *
+   * Sentence combinations that will work:
+   * the text in the JSON variable "variable_with_text_value" should be
+   * the text in the JSON var "variable_with_text_value" should be
+   * the text for "variable_with_text_value" should be
+   * text "variable_with_text_value" should be
+   * */
 
   // Get JSON variable value
   let { json_path, json } = await scope.savePageJSONData( scope );
+
+  // docassemble (at least sometimes) makes new lines with `\r\n`
   let actual_value = json.variables[ var_name ];
+  actual_value = actual_value.replace(/\r/, ``);
+  // Normalize `expected_value` as well for backwards compatibility in case any
+  //     authors are already compensating for docassemble
+  expected_value = expected_value.replace(/\r/, ``);
 
   // Add warning to report if value is not as expected
   if ( actual_value !== expected_value ) {
     reports.addToReport( scope, {
       type: `error`,
       code: `ALK0083`,
-      value: `The variable "${ var_name }" was not equal to the expected `
-        + `value on the "${ scope.page_id }" screen. Check `
-        + `${ json_path } to see the page's JSON variables.`
+      value: `The variable "${ var_name }" was different from the expected `
+        + `value on the "${ scope.page_id }" screen.`
+        + `The expected values was\n` + expected_value
+        + `\nwhile the actual value was\n` + actual_value
     });
   }
 
@@ -1044,6 +1067,22 @@ When(/I set the var(?:iable)? "([^"]+)" to "([^"]+)"/, { timeout: -1 }, async (
 
 });
 
+When(/I set the var(?:iable)? "([^"]+)" to\s*$/, { timeout: -1 }, async ( var_name, answer ) => {
+  /** Set a non-story table variable (with or without a choice associated with
+   *     it) to a value that can have new lines in it. Most useful for
+   *     `textarea`s.
+   *
+   * Example:
+   *   I set the var "benefits['SSI']" to
+   *     """
+   *     Some multline
+   *     value
+   *     """
+   * */
+  // `page` timeout will deal with custom timeout
+  await scope.steps.set_regular_var( scope, var_name, answer )
+});
+
 When(/I set the var(?:iable)? "([^"]+)" to ?(?:the)? ?(?:GitHub)? secret "([^"]+)"/i, { timeout: -1 }, async ( var_name, set_to_env_name ) => {
   /* Set a non-story table variable to a secrete value. Same as the above, but reads the value from `process.env` */
   // This could theoretically tap an element, so
@@ -1152,6 +1191,22 @@ When(/I set the address of ?(?:the var(?:iable)?)? "([^"]+)" to "([^"]+)"/, { ti
 // Next macro - download sequence?
 
 
+//#####################################
+//#####################################
+// Messages from ALKiln to author
+//#####################################
+//#####################################
+
+const LOG_CODE_REGEX = /ALKiln\d\d\d\d/;
+Given(/ALKiln warns the author/i, async ( warnings_text ) => {
+  /** Create a warning message for the author files they wrote to generate
+   *    constrained random answers tests.
+   * 
+   * @param {str} warnings_text - Warning text generated by ALKiln
+   * */
+  reports.addToReport( scope, { type: `as_is`, value: warnings_text });
+})
+
 
 //#####################################
 //#####################################
@@ -1189,6 +1244,8 @@ Given(/the Scenario report should not include/i, async ( report_text ) => {
 Given(/the final Scenario status should be "([^"]+)"/i, async ( expected_status ) => {
   /** WARNING: If a Step will fail, this Step must come first.
   * 
+  * TODO: Status "A" ambiguous (internal)
+  *
   * Prepare to test that the Scenario completes with the correct status. */
   scope.expected_status = expected_status.toUpperCase();
 });
@@ -1272,6 +1329,8 @@ AfterStep(async function({ result }) {
   else if ( result.status === `UNDEFINED` ) { log.stdout({ records_only: true }, `U`); }
   else if ( result.status === `SKIPPED` ) { log.stdout({ records_only: true }, `-`); }
   else if ( result.status === `PENDING` ) { log.stdout({ records_only: true }, `P`); }
+
+  reports.outdent();
 });
 
 After(async function(scenario) {