@suffolklitlab/alkiln 5.4.0 → 5.4.1

package/CHANGELOG.md

@@ -44,6 +44,11 @@ Format:
 -->
 <!-- ## [Unreleased] -->
 
+## [5.4.1] - 2023-10-18
+
+### Internal
+- BREAKS ALKilnInThePlayground v1.2.0 and below (as we discussed) as that project is still exploratory. Can now take the location of the "sources" folder or folders as an argument in the command line. The formats are `npm run cucumber @tags -- --sources=./foo` and `alkiln-run @tags --sources=./foo`.
+
 ## [5.4.0] - 2023-10-14
 
 ### Added

package/lib/run_cucumber.js

@@ -6,64 +6,97 @@ const session_vars = require('./utils/session_vars');
 
 const cucumber_api = require('@cucumber/cucumber/api');
 
-(async function main() {
-  let argv = process.argv;
-
-  const environment = { cwd: process.cwd() };
-  console.log("alkiln-run: environment: %o", environment);
-  const provided_config = {
-    "publishQuiet": true,
-    "require": "./lib/index.js",
-    "format": ["progress", "summary:cucumber-report.txt"],
-    "paths": ["docassemble/*/data/sources/*.feature"],
-    "retry": 1,
-  }
-
-
-  // If they're running it from an interview on their server instead of from GitHub
-  if ( session_vars.get_origin() === `playground` ) {
-    provided_config.paths.push(`/usr/share/docassemble/files/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}/*.feature`);
-    // For S3
-    provided_config.paths.push(`/tmp/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}/*.feature`);
+function build_config( command_args ) {
+  // 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 = [];
+  for ( let source of sources_paths ) {
+    feature_paths.push( `${ source }/*.feature` );
   }
 
-  let tags = argv.slice(2);
-  if ( session_vars.get_origin() === `playground` ) {
-    tags = session_vars.get_tags();
+  const config = {
+    publishQuiet: true,
+    require: `./lib/index.js`,
+    format: [`progress`, `summary:cucumber-report.txt`],
+    paths: feature_paths,
+    retry: 1,
   }
 
+  // Normalize tag expressions, if there are any
+  let tags = command_args[`_`];
   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 (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 ');
+    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(' ');
+      joined_tags = tags.join(` `);
     }
 
-    provided_config.tags = joined_tags;
-  }  // end if there are tags
+    config.tags = joined_tags;
+  }
+
+  return config;
+};  // Ends build_config()
+
+
+(async function main() {
+  /** Create the cucumber config, run the tests, create and
+  *   manipluate the output. */
+  const environment = { cwd: process.cwd() };
+  console.log("alkiln-run: environment: %o", 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.
+  // If using `npm run cucumber`, use `--` before `--sources=./foo`
+  let argv = 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 sources_list = argv.sources;
+  if ( typeof argv.sources === `string` ) {
+    sources_list = [ argv.sources ];
+  }
 
+  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
+    throw new ReferenceError( `ALKiln ERROR: ALKiln can't find your "sources" folder(s). See above for details.`);
+  }
+  
   const { runConfiguration } = await cucumber_api.loadConfiguration({
-    provided: provided_config
+    provided: build_config( argv ),
   }, environment);
+
   console.log("alkiln-run: runConfiguration: %o", runConfiguration);
+
   var path = require('path');
   var codeDir = path.dirname(require.main.filename);
+  console.log("alkiln-run: working directory: %o", codeDir);
   const support = await cucumber_api.loadSupport({ support: {
-    requireModules: [`${ codeDir }/index.js`],
-    requirePaths: [ `${ codeDir }/index.js`],
+    requireModules: [ `${ codeDir }/index.js` ],
+    requirePaths: [ `${ codeDir }/index.js` ],
     importPaths: [],
   }, sources: {paths: []}}, environment);
 
-  console.log("alkiln-run: working directory: %o", codeDir);
   console.log(`\n\n`);
 
   const { success } = await cucumber_api.runCucumber({...runConfiguration, support});
@@ -86,6 +119,6 @@ const cucumber_api = require('@cucumber/cucumber/api');
 
     // Put it in the correct file in the correct folder
     let artifacts_path = session_vars.get_artifacts_path_name();
-    fs.appendFileSync( `${ artifacts_path}/${ log.debug_log_file }`, data);
+    fs.appendFileSync( `${ artifacts_path }/${ log.debug_log_file }`, data);
   });
 })();

package/lib/scope.js

@@ -1681,75 +1681,52 @@ module.exports = {
   },  // Ends scope.today_to_date()
 
   findFiles: async function( scope, {to_find_names}) {
+    /** Returns a list of paths to the sources folder associated
+    *    with the given list of file names.
+    * 
+    * @param to_find_names { [str] } List of file names
+    * 
+    * @returns { [str] } sources folder paths
+    */
     // 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.
+    // TODO: wish we had the var name here that folks are trying to set
     if ( to_find_names.length === 0 ) {
-      reports.addToReport( scope, {
-        type: `error`,
-        value: `Your list of files to find is empty.`
-      });
-      return [];
-    }
-
-    let dirs = [];
-    if ( session_vars.get_origin() === `playground` ) {
-      let files_playground = fg.sync(
-        [ `/usr/share/docassemble/files/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}` ],
-        { onlyFiles: false, suppressErrors: true }
-      );
-      let files_s3 = fg.sync(
-        [ `/tmp/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}` ],
-        { onlyFiles: false, suppressErrors: true }
-      );
-
-      dirs = files_playground.concat( files_s3 );
-    } else {
-      dirs = fg.sync(
-        [ `**/docassemble/**/data/sources` ],
-        { onlyFiles: false, suppressErrors: true }
-      );
-    }
-
-    if ( session_vars.get_debug() ) {
-      console.log( `All discovered dirs to find files from:`, dirs );
-    }
-
-    // Make sure sources directory exists and has files in it
-    if ( dirs.length === 0 ) {
       reports.addToReport( scope, {
         type: `warning`,
-        value: `The test files need to be in the "sources" directory, `
-          + `but ALKiln couldn't find the directory or it was empty.`
+        value: `Your Step is missing the names of which file(s) to use.`
       });
       return [];
     }
 
-    // Get the full paths of all the files
+    let sources_dirs = session_vars.get_sources_paths();
+    // Get the full paths of all the existing files
     let paths = [];
     let missing_files = [];  // For any user warnings
-    for ( let name of to_find_names) {
-     
+    for ( let name of to_find_names ) {
+
       let trimmed_name = name.trim();
       let matching_paths = [];
-
-      for ( let one_dir of dirs ) {
-        // accumulate all matching paths
-        let new_paths = fg.sync([ `${ one_dir }/${ trimmed_name }` ]);
+      // Look for the file in all "sources" folders
+      for ( let one_dir of sources_dirs ) {
+        let new_paths = fg.sync(
+          [ `${ one_dir }/${ trimmed_name }` ],
+          { suppressErrors: true }
+        );
         matching_paths.push( ...new_paths );
-      }  // ends for each dir
+      }
 
       if ( matching_paths.length === 0 ) {
         missing_files.push( trimmed_name );
       } else {
         paths.push( ...matching_paths );
       }
-
     }  // ends for each file
 
     if ( missing_files.length > 0 ) {
       reports.addToReport( scope, {
         type: `warning`,
-        value: `ALKiln could not find "${ missing_files.join('", "') }" in any of these folders: "${ dirs.join('", "') }".`
+        value: `ALKiln could not find "${ missing_files.join('", "') }" in the folder(s) at "${ sources_dirs.join('", "') }".`
       });
     }
 
@@ -1758,7 +1735,7 @@ module.exports = {
       return [];
     }
     return paths;
-  },
+  },  // Ends scope.findFiles()
 
   uploadFiles: async function ( scope, { handle, answer }) {
     /* Try to upload one or more files to a file-type input field.
@@ -1999,7 +1976,7 @@ module.exports = {
       }
       if ( num_unused_rows > 0 ) {
         let { id } = await scope.examinePageID( scope, 'none to match' );
-        let msg = `Missing variable or variables on page "${id}"`;
+        let msg = `Error on page "${id}". See screenshot and see text above for more details.`;
         reports.addToReport(scope, { type: `error`, value: msg });
         expect( num_unused_rows, msg ).to.equal( 0 );
       }

package/lib/utils/session_vars.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const fg = require('fast-glob');
 const path = require('path'); 
 require('dotenv').config();
 
@@ -37,13 +38,6 @@ session_vars.get_origin = function () {
 };
 session_vars.get_user_project_name = function () { return process.env._PROJECT_NAME || null; };
 session_vars.get_user_id = function () { return process.env._USER_ID || null; };
-session_vars.get_tags = function () {
-  if ( process.env._TAGS ) {
-    return process.env._TAGS.split(` `);
-  } else {
-    return [];
-  }
-};
 
 // More complex logic
 session_vars.get_server_reload_timeout = function () {
@@ -210,6 +204,61 @@ session_vars.get_artifacts_path_name = function () {
   }
 };  // Ends get_artifacts_path_name()
 
+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
+  */
+
+  // 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 );
+    }
+  }
+
+  // Warn about missing paths
+  if ( missing_paths.length > 0 ) {
+    console.warn(
+      `ALKiln WARNING: ALKiln can't find folders at "${ paths.join(", ") }".`
+    );
+  }
+
+  // If no paths were valid
+  if ( existing_paths.length <= 0 ) {
+    session_vars._sources_paths = null;
+    return false;
+  }
+
+  // Otherwise, store valid paths
+  session_vars._sources_paths = existing_paths;
+  return true;
+};
+
+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;
+};
+
 session_vars.validateEnvironment = function() {
   /** Throw a useful error for the developer if any of the env vars
   *    required by absolutely all tests are missing. Gather all