@suffolklitlab/alkiln 5.13.2 → 5.13.4

package/lib/utils/files.js

@@ -21,20 +21,27 @@ files.readable_date = function() {
   return fancy_str;
 };  // Ends files.readable_date()
 
-files.make_artifacts_folder = function (folder_name) {
-  /** Makes a folder in the root of the project, either with the given name
-  *   or with a default name.
-  * 
-  * Works for local development as well, unlike action.yml or the workflow file.
-  */
-  if (folder_name) {
-    folder_name = safe_filename( folder_name );
+files.make_artifacts_folder = function (path) {
+  /** Makes a folder in the root of the project if it doesn't
+   *  already exist, either with the given name or with a default name.
+   *
+   * Works for local development as well, without action.yml or workflow files.
+   * */
+  if (path) {
+    let name_parts = path.split(`/`);
+    let safe_parts = [];
+    for ( let part of name_parts ) {
+      safe_parts.push(safe_filename( part ));
+    }
+    path = safe_parts.join(`/`);
   } else {
-    folder_name = `alkiln-${ files.readable_date() }`
+    path = `alkiln-${ files.readable_date() }`
   }
 
-  fs.mkdirSync( folder_name );
-  return folder_name;
+  // `recursive` avoids errors if folder already exists
+  // https://nodejs.org/docs/latest-v18.x/api/fs.html#fspromisesmkdirpath-options
+  fs.mkdirSync( path, { recursive: true });
+  return path;
 };  // Ends files.make_artifacts_folder()
 
 module.exports = files;

package/lib/utils/get_sources_paths.js

@@ -0,0 +1,162 @@
+/**
+fast_glob (fast glob)
+
+files
+session_vars
+*/
+
+
+// let log = null;
+
+// function set_log ( artifacts_path ) {
+//   log = Log( artifacts_path );
+// }
+
+// TODO: Remove after merging Log class PR
+let artifacts_path = files.make_artifacts_folder();
+session_vars.save_artifacts_path_name( artifacts_path );
+
+
+function proccess_command_line_args({ log }) {
+
+  // Discuss: Wouldn't have to use log if we moved this up.
+  const environment = { cwd: process.cwd() };
+  log.info({ type: `run`, code: `ALK0049`, pre: `environment`, data: environment });
+
+  // We'll use the user info to construct the possible paths to /sources
+  let id = session_vars.get_user_id();
+  // `project` is the name in the server docassemble "Project" page
+  let project = session_vars.get_user_project_name();
+
+  // process.argv is a list of strings of commands and args.
+  // Internal note: If using `npm run cucumber`, use `--` before
+  //    `--sources=./foo`
+  let command_line_args = require(`minimist`)( process.argv.slice(2), {
+    default: {
+      sources: [
+        `./docassemble/*/data/sources`,  // In GitHub folder
+        `/usr/share/docassemble/files/playgroundsources/${id}/${project}/*.feature`, // From playground without S3
+        `/tmp/playgroundsources/${id}/${project}/*.feature` // From playground with S3
+      ],
+    }
+  });
+
+  let processed = {};
+  processed.sources = get_sources_paths({ command_line_args });
+  let tags = get_tags({ command_line_args });
+
+  return command_line_args;
+}
+
+
+function get_sources_paths({ command_line_args }) {
+
+  // Make sure `sources` is always a list
+  let sources_list = command_line_args.sources;
+  if ( typeof command_line_args.sources === `string` ) {
+    sources_list = [ command_line_args.sources ];
+  }
+
+  // Check every path, tracking which exist and which are missing
+  let existing_paths = [];
+  let missing_paths = [];
+  for ( let path of paths ) {
+    let dirs = fast_glob.sync(
+      [ path ],
+      { onlyFiles: false, suppressErrors: true }
+    );
+
+    if ( dirs.length > 0 ) {
+      existing_paths.push( ...dirs );
+    } else {
+      missing_paths.push( path );
+    }
+  }
+
+  // If no paths were valid
+  if ( existing_paths.length <= 0 ) {
+    // session_vars.set_sources_paths( null );
+
+    // Discuss: Wouldn't have to use log if we moved this up.
+    // 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 });
+    // pass error up instead?
+    throw new ReferenceError(`🤕 ${ code } run ERROR: ${ msg }`);
+  }
+
+  // TODO: move this out a level
+  console.info(
+    `lightbulb ALK0042 INFO: Did find "sources" file(s) at "${ existing_paths.join('", "') }".`
+  )
+
+  // session_vars.set_sources_paths( existing_paths );
+  return existing_paths;
+}
+
+
+function get_tags({ command_line_args }) {
+  // Normalize tag expressions, if there are any Joining and splitting handles
+  //    both tags surrounded with `""` or those without `""`
+  let tags = command_line_args[`_`].join(` `).split(` `);
+  // If there was no tag expression, `tags` is ['']. Remove that item.
+  tags = tags.filter(function(entry) { return entry !== ""; })
+  if ( tags.length > 0 ) {
+    let joined_tags = '';
+    // Cucumber expects tags in boolean expressions, like (@a0 or @a1) and
+    //    @random. If we get a list of only tags, then "or" them all together
+    if (tags.every((val) => val.startsWith(`@`))) {
+      joined_tags = tags.join(` or `);
+    }
+    // If we get a list of seemingly no tags, assume they meant to use tags
+    else if (tags.every((val) => !val.startsWith(`@`))) {
+      joined_tags = tags.map((val) => `@` + val).join(` or `);
+    }
+    // If it's a mix of tags and no tags, it's probably a boolean expression!
+    else {
+      joined_tags = tags.join(` `);
+    }
+
+    // config.tags = joined_tags;
+    return joined_tags;
+  }
+
+  return null;
+}
+
+
+/**
+ * get sources paths
+ * generate feature files
+ * try to parse everything
+ * pass on the feature files?
+ * 
+ * When running run_cucumber, pass whether files have yet been parsed
+ * Alternatively, have 2 setup steps? The second one parses before run_cucumber
+ * That seems maybe better...? Have to pass on the feature files somehow, though
+ * 
+ * setup_server_stuff
+ * get_feature_files
+ * run_cucumber(with files list somehow... runtime_config?)
+ * */
+
+function get_feature_paths() {
+  // Turn all the paths to the sources folders into paths to the feature files
+  let sources_paths = session_vars.get_sources_paths();
+  let feature_paths = [];
+
+  // Get all the paths for the right feature files (for cucumber to use)
+  for ( let sources_path of sources_paths ) {
+    const generators_prefix = `alkiln_random`;
+    constrained_random_tests.create({ generators_prefix, sources_path });
+    // Ignore feature files that we parsed ourselves
+    let glob = fast_glob.sync(
+      `${ sources_path }/**/*.feature`,
+      { ignore: [`${ sources_path }/${ generators_prefix }*.feature`] }
+    );
+    feature_paths.push( ...glob );
+  }
+}
+
+

package/lib/utils/parse.js

@@ -0,0 +1 @@
+parse.js

package/lib/utils/proccess_command_line_args.js

@@ -0,0 +1,267 @@
+/**
+ * before everything else
+ *  error if there are generator errors
+ * 
+ * problem:
+ * 
+ * because of the 3 (4) env of ALKiln, have to be able to generate and error in
+ *    2 places: run_cucumber, at the start of the GitHub action
+ * 
+ * If there's an error, no problem (nothing will run twice)
+ * 
+ * Otherwise (success, warnings, etc.), generation/parsing will be run 2x. Do we
+ *    care?
+ * 
+ * Note that generation cleans out its folder before generating.
+ * 
+ * Warnings are the problem if we log them at the top (not if we log them along
+ *    with the other test errors/warnings).
+ * 
+ * Error:
+ *    Action: Errors, nothing else is run
+ *    Local/Playground: Errors, nothing else is run
+ *    TODO: Need to generate error files?
+ * 
+ * Success:
+ *    Action: Generate twice
+ *    Local/Playground: Generate once
+ * 
+ * Warnings (same warnings):
+ *    Action: Generate, warn?, generate, warn?, warn at end of test run
+ *      Do we need a "dry run" env var?
+ *    Local/Playground: Generate, warn, warn at end of test run
+ * 
+ * Maybe run_cucumber needs an idea of whether it's running as the first
+ *    operation or as a follow-up
+ * `is_followup` (general state of affairs)
+ * `don't_generate` (a command of a specific action to take)
+ * previous_steps = [`pre_parse`, `server_setup`/`github_playground_setup`]
+ * 
+ * Maybe do this completely separately and call it in different places in
+ *    different processes.
+ * 
+ * 
+ * action needs:
+ *  pre-setup needs:
+ *   `generate` which needs:
+ *     (really??) trigger_any_parsing_errors which needs:
+ *       feature files list/glob which needs:
+ *        sources paths which needs
+ *          command line args
+ *        and
+ *          prints environment PROBLEM TO REPEAT
+ *          potentially errors
+ *     and
+ *      potentially errors
+ * 
+ * run_cucumber needs
+ *  pre-setup
+ *  (maybe) generate which needs:
+ *  (maybe) trigger_any_parsing_errors etc.
+ *  (maybe) trigger_any_parsing_errors which needs:
+ *    feature files, etc.
+ *    
+ *  feature files list/glob which needs:
+ *    sources paths which needs
+ *      command line args
+ *    and
+ *      prints environment PROBLEM TO REPEAT
+ *      potentially errors (not a problem. won't run if the other errors)
+ *  tags needs
+ *    command line args
+ * 
+ * ## Problem 1 - printing environment in 2 places
+ * Fix: Move print environment into run_cucumber
+ * 
+ * ====
+ * 
+ * ## Problem 2 - parsing in both places.
+ * Parsing errors will prevent duplicate parsing.
+ * What about when there are no errors?
+ * Fix: I guess we can check for parsing errors again without harm, though it'll
+ *    take an extra second. Errors will only be parsed once because they'll
+ *    prevent execution.
+ * 
+ * ## Problem 3 - generating in both places
+ * Fix: flag? Or maybe re-generating isn't a problem if it doesn't take too long
+ * 
+ * ## Problem 4
+ * Parse before generating or after generating?
+ * - Can generating create files that have parsing errors without already
+ *   having parsing errors? If so, parse before.
+ * - Generating can create its own errors, though. So generate before?
+ * - Also, errors for generated tests may be confusing because author may think,
+ *    "I didn't write those tests."
+ * Maybe:
+ * 1. test all files before generating
+ * 2. generate (and pass back errors or just throw?)
+ * 3. test generated files and throw just generator process errors and parsing
+ *    errors
+ * 
+ * All:
+ * 0. Get command line args
+ * 1. Get sources
+ * 2. Get feature files
+ * 3. Parse all current (can throw) (accumulated errors?)
+ * 4. Generate (with possible errors) (can throw accumulated errors)
+ * 5. Parse generated (can throw)
+ * Should those throw all together? Probably not. They can affect each other.
+ * 
+ * run_cucumber also independently needs:
+ * 1. sources
+ * 2. feature files
+ * */
+
+/**
+ * get sources paths
+ * generate feature files
+ * try to parse everything
+ * pass on the feature files?
+ * 
+ * When running run_cucumber, pass whether files have yet been parsed
+ * Alternatively, have 2 setup steps? The second one parses before run_cucumber
+ * That seems maybe better...? Have to pass on the feature files somehow, though
+ * 
+ * setup_server_stuff
+ * get_feature_files
+ * run_cucumber(with files list somehow... runtime_config?)
+ * */
+
+/**
+fast_glob (fast glob)
+
+files
+session_vars
+*/
+
+// let log = null;
+
+// function set_log ( artifacts_path ) {
+//   log = Log( artifacts_path );
+// }
+
+// TODO: Remove after merging Log class PR
+let artifacts_path = files.make_artifacts_folder();
+session_vars.save_artifacts_path_name( artifacts_path );
+
+function get_command_line_args({ log }) {
+
+  // We'll use the user info to construct the possible paths to /sources
+  let id = session_vars.get_user_id();
+  // `project` is the name in the author's server's docassemble "Project" page
+  let project = session_vars.get_user_project_name();
+
+  // process.argv is a list of strings of commands and args.
+  // Internal note: If using `npm run cucumber`, use `--` before
+  //    `--sources=./foo`
+  let command_line_args = require(`minimist`)( process.argv.slice(2), {
+    default: {
+      sources: [
+        `./docassemble/*/data/sources`,  // In GitHub folder
+        `/usr/share/docassemble/files/playgroundsources/${id}/${project}/*.feature`, // From playground without S3
+        `/tmp/playgroundsources/${id}/${project}/*.feature` // From playground with S3
+      ],
+    }
+  });
+
+  // let processed = {};
+  // processed.sources = get_sources_paths({ command_line_args });
+  // let tags = get_tags({ command_line_args });
+
+  return command_line_args;
+}
+
+
+function get_sources_paths({ command_line_args }) {
+
+  // Make sure `sources` is always a list
+  let sources_list = command_line_args.sources;
+  if ( typeof command_line_args.sources === `string` ) {
+    sources_list = [ command_line_args.sources ];
+  }
+
+  // Check every path, tracking which exist and which are missing
+  let existing_paths = [];
+  let missing_paths = [];
+  for ( let path of paths ) {
+    let dirs = fast_glob.sync(
+      [ path ],
+      { onlyFiles: false, suppressErrors: true }
+    );
+
+    if ( dirs.length > 0 ) {
+      existing_paths.push( ...dirs );
+    } else {
+      missing_paths.push( path );
+    }
+  }
+
+  // If no paths were valid
+  if ( existing_paths.length <= 0 ) {
+    // session_vars.set_sources_paths( null );
+
+    // Discuss: Wouldn't have to use log if we moved this up.
+    // 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 });
+    // pass error up instead?
+    throw new ReferenceError(`🤕 ${ code } run ERROR: ${ msg }`);
+  }
+
+  // TODO: move this out a level
+  console.info(
+    `lightbulb ALK0042 INFO: Did find "sources" file(s) at "${ existing_paths.join('", "') }".`
+  )
+
+  // session_vars.set_sources_paths( existing_paths );
+  return existing_paths;
+}
+
+
+function get_tags({ command_line_args }) {
+  // Normalize tag expressions, if there are any Joining and splitting handles
+  //    both tags surrounded with `""` or those without `""`
+  let tags = command_line_args[`_`].join(` `).split(` `);
+  // If there was no tag expression, `tags` is ['']. Remove that item.
+  tags = tags.filter(function(entry) { return entry !== ""; })
+  if ( tags.length > 0 ) {
+    let joined_tags = '';
+    // Cucumber expects tags in boolean expressions, like (@a0 or @a1) and
+    //    @random. If we get a list of only tags, then "or" them all together
+    if (tags.every((val) => val.startsWith(`@`))) {
+      joined_tags = tags.join(` or `);
+    }
+    // If we get a list of seemingly no tags, assume they meant to use tags
+    else if (tags.every((val) => !val.startsWith(`@`))) {
+      joined_tags = tags.map((val) => `@` + val).join(` or `);
+    }
+    // If it's a mix of tags and no tags, it's probably a boolean expression!
+    else {
+      joined_tags = tags.join(` `);
+    }
+
+    // config.tags = joined_tags;
+    return joined_tags;
+  }
+
+  return null;
+}
+
+function get_feature_paths() {
+  // Turn all the paths to the sources folders into paths to the feature files
+  let sources_paths = session_vars.get_sources_paths();
+  let feature_paths = [];
+
+  // Get all the paths for the right feature files (for cucumber to use)
+  for ( let sources_path of sources_paths ) {
+    const generators_prefix = `alkiln_random`;
+    constrained_random_tests.create({ generators_prefix, sources_path });
+    // Ignore feature files that we parsed ourselves
+    let glob = fast_glob.sync(
+      `${ sources_path }/**/*.feature`,
+      { ignore: [`${ sources_path }/${ generators_prefix }*.feature`] }
+    );
+    feature_paths.push( ...glob );
+  }
+}

package/lib/utils/reports.js

@@ -66,14 +66,20 @@ reports.addToReport = function( scope, { type, code, value }) {
   const MISC_ARTIFACTS_DIR = `_alkiln-misc_artifacts`;
   if ( !scope.paths ) {
     // Can this be usefully abstracted?
-    scope.paths = { debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_logs-${ files.readable_date() }.txt` };
+    let date = files.readable_date();
+    scope.paths = {
+      debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_debug_log-${ date }.txt`,
+      report_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_report_log-${ date }.txt`,
+    };
   }
 
   try {
     fs.appendFileSync( scope.paths.debug_log, `\nReport:\n${debug_line}` );
-  } catch ( err ) {
+    fs.appendFileSync( scope.paths.report_log, `\nReport:\n${debug_line}` );
+  } catch ( file_error ) {
     fs.mkdirSync( MISC_ARTIFACTS_DIR );
     fs.appendFileSync( scope.paths.debug_log, `\nReport:\n${debug_line}` );
+    fs.appendFileSync( scope.paths.report_log, `\nReport:\n${debug_line}` );
     // An error in here should throw (for now)
   }
 
@@ -115,25 +121,66 @@ reports.saveFinalScenarioData = function( scope, { status=`in progress` }) {
   this.setReportScenarioStatus( scope, { status });
   let scenario = scope.report.get( scope.scenario_id );
   let report = this.getPrintableScenario( scenario );
-  if ( scenario.status === `FAILED` ) { this.failures.push( report ); }
-  else if ( scenario.status === `PASSED` ) { this.successes.push( report ); }
-  // else if ( scenario.status === `WARNING` ) { passed_reports += report; this.warnings.push( report ); }
-  // else if ( scenario.status === `UNDEFINED` ) { passed_reports += report; this.undefineds.push( report ); }
-  else { this.others.push( report ); }
-
-  // Save to failures.txt (worry about optimization later)
-  if ( this.failures.length > 1 || this.others.length > 1 ) {
-    fs.writeFileSync(
-      scope.paths.failures,
-      this.title + this.getPrintableUnexpected( scope )
-    );
+  if ( scenario.status === `PASSED` ) {
+    this.successes.push( report );
+  } else {
+    this._save_unexpected( scope, { status: scenario.status, report });
   }
+  // if ( scenario.status === `FAILED` ) {
+  //   this.failures.push( report );
+  // }
+  // else if ( scenario.status === `PASSED` ) { this.successes.push( report ); }
+  // // else if ( scenario.status === `WARNING` ) { passed_reports += report; this.warnings.push( report ); }
+  // // else if ( scenario.status === `UNDEFINED` ) { passed_reports += report; this.undefineds.push( report ); }
+  // else { this.others.push( report ); }
+
+  // // Save to unexpected results files (worry about optimization later)
+  // if ( this.failures.length > 1 || this.others.length > 1 ) {
+  //   let unexpected_results = this.title + this.getPrintableUnexpected( scope );
+  //   fs.writeFileSync( scope.paths.report_of_unexpected, unexpected_results );
+  //   fs.appendFileSync( scope.paths.debug_of_unexpected, unexpected_results );
+  // }
+
   // Save to reports.txt (worry about optimization later)
   fs.writeFileSync( scope.paths.report, this.getPrintableReport( scope ) );
 
   return scenario;
 };  // Ends reports.saveFinalScenarioData()
 
+reports._save_unexpected = function(scope, { status, report }) {
+  /** Store the unexpected report and write to the unexpected report file.
+   *
+   * @param {Object} scope - State and methods of the current tests
+   * @param {Object} data
+   * @param {Object} data.status - Status of the current scenario
+   * @param {string} data.report - Report for the current scenario
+   * */
+  if ( status === `FAILED` ) {
+    this.failures.push( report );
+  // } else if ( status === `WARNING` ) { passed_reports += report; this.warnings.push( report );
+  // } else if ( status === `UNDEFINED` ) { passed_reports += report; this.undefineds.push( report ); }
+  } else {
+    this.others.push( report );
+  }
+
+  // If it's our first unexpected result, add the title to the top of the page
+  let already_unexpected = ``;
+  try { already_unexpected = fs.readFileSync( scope.paths.report_of_unexpected ); }
+  catch ( ignore_non_critical_error ) {}
+  if ( already_unexpected === `` ) {
+    try { fs.appendFileSync( scope.paths.report_of_unexpected, this.title ); }
+    catch ( ignore_non_critical_error ) {}
+  }
+
+  try { fs.appendFileSync( scope.paths.report_of_unexpected, report ); }
+  catch ( ignore_non_critical_error ) {}
+
+  return this;
+}
+
+reports.progress = function ({ logs=[] }) {
+  // TODO: save stdout-style to report_log, object, and getting printable scenario
+};
 
 reports.setReportScenarioStatus = function( scope, { status=`PASSED` }) {
   /** Add final status of scenario to scenario report object - passed, failed, etc. */
@@ -203,7 +250,7 @@ reports.getPrintableScenario = function( scenario ) {
   return report;
 };  // Ends reports.getPrintableScenario()
 
-let getLineText = function ({ type=`no type`, code=`ALK0000`, value=`` }) {
+let getLineText = function ({ type=`no type`, code=`ALK00rl`, value=`` }) {
   let start = ``;
   if ( type.includes(`page_id`) ) { start += `screen id: `; }
   else if ( type.includes(`outcome`) ) { start += `\n`; }  // extra new line
@@ -212,7 +259,7 @@ let getLineText = function ({ type=`no type`, code=`ALK0000`, value=`` }) {
   return `${ start }${ value }`;
 };  // Ends getLine()
 
-let getDebugLine = function ({ type=``, code=`ALK0000`, value=`` }) {
+let getDebugLine = function ({ type=``, code=`ALK00rd`, value=`` }) {
   /** In debug log lines, include all the information possible. */
 
   // `plain` is usually used for visual clarity and shouldn't have
@@ -222,7 +269,7 @@ let getDebugLine = function ({ type=``, code=`ALK0000`, value=`` }) {
   let start = ``;
 
   // Get all the relevant emoji
-  if ( type.includes(`debug`) ) { start += `🐞`; }
+  if ( type.includes(`debug`) ) { start += `🐛`; }
   if ( type.includes(`info`) ) { start += `💡`; }
   if ( type.includes(`success`) ) { start += `🌈`; }
   if ( type.includes(`warning`) ) { start += `🔎`; }