@suffolklitlab/alkiln 5.14.0 → 5.15.0

package/lib/utils/reports.js

@@ -26,14 +26,14 @@ reports.addReportHeading = function (scope, { scenario }) {
     tag_names.push( tag.name );
   }
 
-  let heading = `\n―――――――――――――――\n`
+  let heading = `\n━━━━━━━━━━━━━━━\n`
     + `Scenario: ${ scenario.pickle.name }`;
 
   if ( tag_names.length > 0 ) {
     heading += `\nTags: ${ tag_names.join(' ') }`;
   }
 
-  heading += `\n―――――――――――――――`;
+  heading += `\n━━━━━━━━━━━━━━━`;
 
   reports.addToReport( scope, {
     code: `ALK0176`,
@@ -57,7 +57,7 @@ reports.addToReport = function( scope, { type, code, value }) {
   // thrown errors if needed.
 
   // Debugging logs
-  let debug_line = getDebugLine({ type, code, value });
+  let debug_line = getDebugLine({ type, code, value, indent: global_indent });
   if ( session_vars.get_debug() ) {
     console.log( `Report: ${ debug_line }` );
   }
@@ -85,11 +85,24 @@ reports.addToReport = function( scope, { type, code, value }) {
 
   // Report stuff
   let scenario = reports.makeSureScenarioExists( scope );
-  scenario.lines.push({ type, code, value });
+  scenario.lines.push({ type, code, value, indent: global_indent });
 
-  return getLineText({ type, code, value });
+  return getLineText({ type, code, value, indent: global_indent });
 };  // Ends reports.addToReport()
 
+
+let indent_num = 0;
+let global_indent = ``;
+reports.indent = function() {
+  indent_num += 2;
+  global_indent = ` `.repeat( indent_num );
+}
+reports.outdent = function() {
+  indent_num = Math.max( 0, indent_num - 2 );
+  global_indent = ` `.repeat( indent_num );
+}
+
+
 reports.create = function( scope ) {
   reports.makeSureReportExists( scope );
 }
@@ -244,31 +257,39 @@ reports.getPrintableScenario = function( scenario ) {
   /** Return a string generated from scenario list of report items. */
   let report = ``;
   for ( let line of scenario.lines ) {
-    let { type, code, value } = line;
-    report += `${ getLineText({ type, code, value }) }\n`;
+    let { type, code, value, indent } = line;
+    report += `${ getLineText({ type, code, value, indent }) }\n`;
   }
   return report;
 };  // Ends reports.getPrintableScenario()
 
-let getLineText = function ({ from_log, type=`no type`, code=`ALK00rl`, value=`` }) {
-  let start = ``;
+let getLineText = function ({ from_log, type=`no type`, code=`ALK00rl`, value=``, indent=`` }) {
+
+  value = `${ value.replace( /\n/g, `\n` + indent ) }`;
+
+  if ( type === `as_is` ) { return `${ indent }${ value }`; }
+
+  let start = indent;
+  if ( type.includes(`outcome`) ) { start = `\n`; }  // extra new line
+
   if ( type.includes(`page_id`) ) { start += `screen id: `; }
-  else if ( type.includes(`outcome`) ) { start += `\n`; }  // extra new line
   else if ( type.includes(`warning`) && !from_log ) { start += `🔎 ${ code } WARNING: `; }
-  else if ( type.includes(`error`) && !from_log ) { start += `\n🤕 ${ code } ERROR: `; }  // extra new line
+  else if ( type.includes(`error`) && !from_log ) { start += `🤕 ${ code } ERROR: `; } // extra new line
+
   return `${ start }${ value }`;
-};  // Ends getLine()
 
-let getDebugLine = function ({ from_log, type=``, code=`ALK00rd`, value=`` }) {
-  /** In lines for the debug file, include all the information possible. */
+}; // Ends getLine()
+
+let getDebugLine = function ({ from_log, type=``, code=`ALK00rd`, value=``, indent=`` }) {
+  /** In debug log lines, include all the information possible. */
 
-  // `plain` is usually used for visual clarity and shouldn't have
-  // codes and such associated with it. Return right away.
-  if ( type.includes(`plain`) ) { return value; }
   // Discuss: How to prevent saving in the debug log twice
   if ( from_log ) { return value; }
+  // `plain` is usually used for visual clarity and shouldn't have
+  // codes and such associated with it. Return right away.
+  if ( type.includes(`plain`) ) { return `${ indent }${ value }`; }
 
-  let start = ``;
+  let start = indent;
 
   // Get all the relevant emoji
   if ( type.includes(`debug`) ) { start += `🐛`; }
@@ -277,16 +298,15 @@ let getDebugLine = function ({ from_log, type=``, code=`ALK00rd`, value=`` }) {
   if ( type.includes(`warning`) ) { start += `🔎`; }
   if ( type.includes(`error`) ) { start += `🤕`; }
   // Default
-  if ( start === `` ) { start += `?`; }
+  if ( start === indent ) { start += `?`; }
 
   start += ` ${ code }`;
 
-  // TODO: This doesn't take care
+  let description_parts = [];
   let extra_types = type.replace(/debug|info|success|warning|error/i, ``).replace(/  +/g, ' ').trim();
-  if ( extra_types.length > 0 ) { start += ` ${ extra_types } `; }
+  if ( extra_types.length > 0 ) { description_parts = extra_types.split(` `); }
 
-  // Get all the relevant descriptive text
-  let description_parts = [];
+  // Get all the main descriptive text
   if ( type.includes(`debug`) ) { description_parts.push( `DEBUG` ); }
   if ( type.includes(`info`) ) { description_parts.push( `INFO` ); }
   if ( type.includes(`success`) ) { description_parts.push( `SUCCESS` ); }

package/lib/utils/session_vars.js

@@ -20,6 +20,17 @@ require('dotenv').config();
  * easier to test.
  * */
 
+/**
+ * Discuss: We don't like logging directly to the console in here. Consider
+ *    returning most logs (info, error, warning) so that the calling functions
+ *    can use a `Log` to log them properly instead of logging to the console.
+ *    Alternatively, move everything in here that `Log` uses into its own file
+ *    so that `session_vars` can have its own `Log` instance. For example, put
+ *    artifacts path name related functions in `Log`. That "get/set/delete"
+ *    behavior would be inconsistent with other similar functions. Other places
+ *    need to use artifacts path name too.
+ * */
+
 const session_vars = {};
 
 module.exports = session_vars;
@@ -62,6 +73,18 @@ session_vars.get_setup_timeout_ms = function () {
   return timeout;
 };
 
+session_vars.get_max_tests_per_template_scenario = function() {
+  /** Returns the maximum number of tests to generate for any one generator
+   *    Scenario.
+   * 
+   * Assumes an average of 30 secs per test with a max of 20 min. for all tests
+   *    for that one generator Scenario.
+   * 
+   * @returns {int} - Max number of tests for one generator Scenario
+   * */
+  return process.env.ALKILN_MAX_RANDOM_TESTS_PER_SCENARIO || 40;
+}
+
 session_vars.get_da_server_url = function () {
   try {
     let url = process.env.SERVER_URL || process.env.BASE_URL;
@@ -176,16 +199,18 @@ session_vars.delete_project_name = function () {
 const artifacts_path_key = `artifacts_path`;
 session_vars.save_artifacts_path_name = function ( path_name ) {
   /** Save a key with the name of the current artifacts folder
-   *  in case it doesn't exist. Should we create the path in here
-   *  if it doesn't exist? Should we reserve this file for getting
-   *  and setting?
+   *    in case it doesn't exist.
    * */
   return session_vars.save_runtime_config_var({ key: artifacts_path_key, value: path_name });
 };  // Ends save_artifacts_path_name()
 session_vars.get_artifacts_path_name = function () {
-  /* Get the name of the current artifacts path. */
+  /** Get the name of the current artifacts path. */
   return session_vars.get_runtime_config_var( artifacts_path_key );
 };  // Ends get_artifacts_path_name()
+session_vars.delete_artifacts_path_name = function () {
+  /** Delete the runtime config value of the artifacts path. */
+  return session_vars.delete_runtime_config_var({ key: artifacts_path_key });
+};
 
 
 /** We use `da_install_method` for temp server vs. author's account (Playground)
@@ -221,10 +246,11 @@ session_vars.save_runtime_config_var = function ({ key, value }) {
   *   the json object there. The functions calling this are keeping
   *   track of the key, so they're useful to keep around.
   * 
-  * @param key {str} Key to use to store `value` in runtime config file
-  * @param value {any} Value to store in runtime config file
+  * @param {object} obj - Named arguments
+  * @param {str} obj.key - Key to use to store `value` in runtime config file
+  * @param {any} obj.value - Value to store in runtime config object
   * 
-  * @returns file {binary?} Runtime config file
+  * @returns {binary?} file Runtime config file
   */
 
   // Ensure runtime config file exists
@@ -246,75 +272,69 @@ session_vars.save_runtime_config_var = function ({ key, value }) {
 
 session_vars.get_runtime_config_var = function ( key ) {
   /** Get the value of the given key from the runtime config file.
-  * 
-  * @param key {str} Key in runtime config file that contains the desired value
-  * @returns value || null {any} Value of key in runtime config file. If it
-  *    doesn't exist, returns null.
-  */
+   * 
+   * @param {str} key - Key in runtime config file that contains the desired val
+   * 
+   * @returns {any} - Value of given key in runtime config file or null
+   */
   try {
     let json = JSON.parse( fs.readFileSync( runtime_config_path ));
     let value = json[ key ];
     if ( session_vars.get_debug() ) {
-      console.debug( `🐛 ALK0041 DEBUG: Runtime config var "${key}" is "${value}".` );
+      console.debug( `🐛 ALK0041 DEBUG: Runtime config var "${ key }" is "${ value }".` );
     }
-
     return value;
-  } catch ( error ) {
+  } catch ( get_var_error ) {
+
+    console.debug(`🖊️ ALK0273 NOTE: Skipped getting runtime config var "${ key }".`, get_var_error.stack );
     return null;
+
   }
 };  // Ends session_vars.get_runtime_config_var()
 
+session_vars.delete_runtime_config_var = function ({ key }) {
+  /** Delete the runtime config var of the given `key`
+   * 
+   * @param {object} obj - Named arguments
+   * @param {str} obj.key - Key in runtime config file object to delete
+   * 
+   * @returns {null}
+   * */
+  try {
+    if ( !fs.existsSync( runtime_config_path )) { return null; }
+    
+    let json = JSON.parse( fs.readFileSync( runtime_config_path ));
+    delete json[ key ];
+    fs.writeFileSync( runtime_config_path, JSON.stringify( json, null, 2 ));
+    return null;
 
-session_vars.set_sources_paths = function ( paths ) {
-  /** Returns whether at least one of the given path exists. Store
-  *   a list of the existing paths. Warn of any missing paths. Can be
-  *   used for getting, e.g .feature files, files to upload, etc.
-  * 
-  * Our code should ensure this gets run before cucumber tests get triggered.
-  * 
-  * @param paths { [str] } List of paths to the 'sources' folder.
-  * 
-  * @returns bool
-  */
+  } catch ( delete_var_error ) {
 
-  // Check every path, tracking which exist and which are missing
-  let existing_paths = [];
-  let missing_paths = [];
-  for ( let path of paths ) {
-    let dirs = fg.sync(
-      [ path ],
-      { onlyFiles: false, suppressErrors: true }
-    );
-
-    if ( dirs.length > 0 ) {
-      existing_paths.push( ...dirs );
-    } else {
-      missing_paths.push( path );
-    }
-  }
+    console.debug( `🖊️ ALK0274 NOTE: Skipped deleting runtime config var "${ key }".`, delete_var_error.stack );
+    return null
 
-  // If no paths were valid
-  if ( existing_paths.length <= 0 ) {
-    session_vars._sources_paths = null;
-    return false;
   }
+};  // Ends session_vars.delete_runtime_config_var()
 
-  console.info(
-    `🌈 ALK0042 SUCCESS: Did find "sources" file(s) at "${ existing_paths.join('", "') }".`
-  )
 
-  // Otherwise, store valid paths
-  session_vars._sources_paths = existing_paths;
-  return true;
+session_vars.set_sources_paths = function ( paths ) {
+  /** Set the globally accessible value of the paths to the sources folder.
+   *    Saves and returns the argument it was given.
+   * 
+   * @param paths {[string]} List of paths to the 'sources' folder.
+   * 
+   * @returns {null | [string]}
+   * */
+  session_vars._sources_paths = paths;
+  return paths || null;
 };  // End session_vars.set_sources_paths()
 
 session_vars.get_sources_paths = function () {
-  /** Get the "sources" folder path. Should never be undefined during
-  *   a run of the test. run_cucumber.js should make sure it has
-  *   a default value.
-  * 
-  * @returns str || null */
-  return session_vars._sources_paths;
+  /** Get the previously stored "sources" folder paths.
+   * 
+   * @returns {null | [string]}
+   * */
+  return session_vars._sources_paths || null;
 };
 
 

package/lib/utils/set_sources_paths.js

@@ -0,0 +1,98 @@
+const fast_glob = require(`fast-glob`);
+
+const session_vars = require(`./session_vars`);
+
+
+module.exports = function set_sources_paths({ log }) {
+  /** Set the globally accessible value of the paths to the sources folder,
+   *    where authors store tests and other relevant test files. Can throw an
+   *    error.
+   * 
+   * @param {object} obj - Named arguments
+   * @param {Log} obj.log - Logs and saves useful info for later debugging.
+   * 
+   * @returns {[string]} - All paths found for package sources folders.
+   * */
+  session_vars.validateEnvironment();
+
+  let maybe_paths = get_potential_paths();
+
+  let sources_paths = get_sources_paths({ maybe_paths });
+  if ( sources_paths === 0 ) {
+    // If we don't throw, it'll be more confusing when no tests run
+    log.throw({ code: `ALK0050`, context: `sources`,
+      error: new ReferenceError(
+        `ALKiln can't find your "sources" folder(s) which should contain tests and their related files.`
+      ),
+    });
+  }
+
+  log.info({ code: `ALK0042`, context: `sources` },
+    `Did find "sources" file(s) at "${ sources_paths.join('", "') }".`
+  );
+  session_vars.set_sources_paths( sources_paths );
+  
+  return sources_paths;
+}
+
+
+function get_potential_paths() {
+  /** Use command line args and session vars to return a list of strings of
+   *    possible sources files paths.
+   * 
+   * @returns {[string]} - Potential sources paths.
+   * */
+  // `project` is the name in the server docassemble "Project" page
+  let project = session_vars.get_user_project_name();
+  let id = session_vars.get_user_id();
+
+  // process.argv is a list of strings of commands and args.
+  // Internal note: If using `npm run cucumber`, use `--` before
+  //    `--sources=./foo`
+  let cli_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
+      ],
+    }
+  });
+
+  // Make sure `sources` is always a list
+  let potential_paths_list = cli_args.sources;
+  if ( !Array.isArray( cli_args.sources )) {
+    potential_paths_list = [ cli_args.sources ];
+  }
+
+  return potential_paths_list;
+}
+
+
+function get_sources_paths({ maybe_paths }) {
+  /** Of the given possible paths, return the paths that actually exist. Maybe
+   *    none.
+   * 
+   * @param {object} obj - Named arguments
+   * @param {[string]} obj.maybe_paths - All possible paths
+   * 
+   * @returns {[string]} - List of all existing paths
+   * */
+  // Check every path, tracking which exist and which are missing
+  let existing_paths = [];
+  let missing_paths = [];
+  for ( let path of maybe_paths ) {
+    let dirs = fast_glob.sync(
+      [ path ],
+      { onlyFiles: false, suppressErrors: true }
+    );
+
+    if ( dirs.length > 0 ) {
+      existing_paths.push( ...dirs );
+    } else {
+      missing_paths.push( path );
+    }
+  }
+
+  return existing_paths;
+}

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.14.0",
+  "version": "5.15.0",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {
     "test": "npm run unit && npm run codes && npm run cucumber",
-    "cucumber": "./lib/run_cucumber.js",
     "local": "npm run setup && npm run cucumber; npm run takedown",
-    "pass": "npm run cucumber 'not @error and not @temp_error'",
-    "fail": "npm run cucumber '@error'",
-    "setup": "./lib/docassemble/setup.js",
+
     "takedown": "./lib/docassemble/takedown.js",
+    "setup": "./lib/docassemble/setup.js",
     "server_install": "./lib/docassemble/server_install.js",
-    "unit": "mocha tests/unit_tests/*.test.*",
+
+    "pass": "npm run cucumber 'not @error and not @temp_error'",
+    "fail": "npm run cucumber '@error'",
+    "cucumber": "npm run build && ./lib/run_cucumber.js",
+
+    "build": "npm run artifacts && npm run validate && npm run generate",
+    "validate": "./lib/setup/validate.js",
+    "generate": "./lib/setup/generate.js",
+    "artifacts": "./lib/setup/artifacts.js",
+    
+    "unit": "npm run artifacts && mocha --recursive 'tests/unit_tests/**/*.test.*'",
     "codes": "tests/log_codes/check_codes.sh ."
   },
   "repository": {
@@ -57,6 +65,9 @@
     "alkiln-server-install": "./lib/docassemble/server_install.js",
     "alkiln-setup": "./lib/docassemble/setup.js",
     "alkiln-takedown": "./lib/docassemble/takedown.js",
-    "alkiln-run": "./lib/run_cucumber.js"
+    "alkiln-run": "./lib/run_cucumber.js",
+    "alkiln-artifacts": "./lib/setup/artifacts.js",
+    "alkiln-validate": "./lib/setup/validate.js",
+    "alkiln-generate": "./lib/setup/generate.js"
   }
 }

package/tests/log_codes/check_codes.sh

@@ -11,12 +11,13 @@ exit_code=0
 
 echo " -------------------------------------------------------
 | Usage:                                                |
-| bash $(basename $0) [dir] [c file] [c folder] [-l arg]
+| bash $(basename $0) [dir] [c file] [c folder]         |
 | dir:      The directory in which to search for logs   |
 | c file:   Name of the log instance counter file       |
 | c folder: Path to the folder of the log counter file  |
-| -l arg:   \"1\" prints extra logs                       |
  -------------------------------------------------------"
+# | bash $(basename $0) [dir] [c file] [c folder] [-l arg]
+# | -l arg:   \"1\" prints extra logs                       |
 
 # Get flags and their values
 loudness="0"
@@ -56,7 +57,7 @@ fi
 # removed and are no longer used. Syntax used works with GitHub cli - [[:digit:]]
 # https://stackoverflow.com/a/6901221
 # Exclude files and paths
-instances=$(find "$where_to_look" -type f ! -name "CONTRIBUTING.md" ! -name "$expected_instances_file" ! -name "debug_log.txt" ! -name "cucumber-report.txt" ! -path "*/tests/*" ! -path "*/node_modules/*" ! -path "*/ALKilnTests/*" ! -path "*/alkiln-*/*" ! -path "*/_alkiln*/*" ! -path "*/docs/decisions/*" ! -path "*/\.*" -print0 | xargs -0 -P 4 grep -0 -ro 'ALK[[:digit:]][[:digit:]][[:digit:]][[:digit:]]' | grep -v -- '--' )
+instances=$(find "$where_to_look" -type f ! -name "CONTRIBUTING.md" ! -name "$expected_instances_file" ! -name "debug_log.txt" ! -name "cucumber-report.txt" ! -name "_alkiln*" ! -path "*/tests/*" ! -path "*/node_modules/*" ! -path "*/ALKilnTests/*" ! -path "*/alkiln-*/*" ! -path "*/_alkiln*/*" ! -path "*/docs/*" ! -path "*/\.*" -print0 | xargs -0 -P 4 grep -0 -ro 'ALK[[:digit:]][[:digit:]][[:digit:]][[:digit:]]' | grep -v -- '--' )
 
 if [[ "$loudness" != "0" ]]; then
   total_instances=$(echo "$instances" | wc -l)
@@ -101,7 +102,7 @@ fi
 indx=0
 too_many=()
 missing=()
-while [ "$indx" -lt "$highest_code" ]; do
+while [ "$indx" -le "$highest_code" ]; do
   # Turn the index into a log code by prepending ALK and adding leading zeros
   log_code=$(printf "ALK%04d" "$indx")
   # Count ";" - a stand-in for the number of
@@ -126,24 +127,27 @@ while [ "$indx" -lt "$highest_code" ]; do
   # To add to the list of strings to print later
   short_msg="$log_code $num_paths/$num_expected"
   long_msg="$log_code act/exp "
-  long_msg+="$num_paths/$num_expected:"
+  long_msg+="$num_paths/$num_expected"
+  if [ "$num_paths" -gt "$num_expected" ]; then
+    long_msg+=":"
+  fi
   long_msg+=$(echo "${codes_unique_paths[$indx]}" | sed 's/;/\n  - /g')
 
   # missing
   if [ "$num_paths" -lt "$num_expected" ]; then
-    if [[ "$loudness" != "0" ]]; then
+    # if [[ "$loudness" != "0" ]]; then
       missing+=("$long_msg")
-    else
-      missing+=("$short_msg")
-    fi
+    # else
+    #   missing+=("$short_msg")
+    # fi
 
   # too_many
   elif [ "$num_paths" -gt "$num_expected" ]; then
-    if [[ "$loudness" != "0" ]]; then
+    # if [[ "$loudness" != "0" ]]; then
       too_many+=("$long_msg")
-    else
-      too_many+=("$short_msg")
-    fi
+    # else
+    #   too_many+=("$short_msg")
+    # fi
   fi
 
   let indx++

package/tests/log_codes/log_code_expected_instances.txt

@@ -5,8 +5,11 @@ Why we need duplicate codes sometimes: GitHub actions sometimes don't have ways
 The script that tests the log codes will ignore this file (or any file with this name), and any file with these names: check_codes.sh, debug_log.txt, cucumber-report.txt. It will also ignore files in folders with these names:, node_modules, ALKilnTests, alkiln-*, _alkiln*. That list might get updated, so for an up-to-date list, always check the file check_codes.sh where we use `--exclude=` and such.
 
 Reasons for deletion:
+0000 - unknown
 0053 - duplicate log
 0173 - redundant
+0181 - unknown
+0223 - changed Log behavior ("Only logs that throw should give a value to `error`.")
 
 ALK0000:0
 ALK0001:1
@@ -231,3 +234,58 @@ ALK0219:1
 ALK0220:1
 ALK0221:1
 ALK0222:1
+ALK0223:0
+ALK0224:1
+ALK0225:1
+ALK0226:1
+ALK0227:1
+ALK0228:1
+ALK0229:1
+ALK0230:1
+ALK0231:1
+ALK0232:1
+ALK0233:1
+ALK0234:1
+ALK0235:1
+ALK0236:1
+ALK0237:1
+ALK0238:1
+ALK0239:1
+ALK0240:1
+ALK0241:1
+ALK0242:1
+ALK0243:1
+ALK0244:1
+ALK0245:1
+ALK0246:1
+ALK0247:1
+ALK0248:1
+ALK0249:1
+ALK0250:1
+ALK0251:1
+ALK0252:1
+ALK0253:1
+ALK0254:1
+ALK0255:1
+ALK0256:1
+ALK0257:1
+ALK0258:1
+ALK0259:1
+ALK0260:1
+ALK0261:1
+ALK0262:1
+ALK0263:1
+ALK0264:1
+ALK0265:1
+ALK0266:1
+ALK0267:1
+ALK0268:1
+ALK0269:1
+ALK0270:1
+ALK0271:1
+ALK0272:1
+ALK0273:1
+ALK0274:1
+ALK0275:1
+ALK0276:1
+ALK0277:1