@suffolklitlab/alkiln 5.13.2 → 5.13.4

package/lib/docassemble/setup.js

@@ -1,26 +1,33 @@
 #!/usr/bin/env node
 
-// TODO: Rename to playground_install?
-
 const child_process = require(`child_process`);
 
-const log = require(`../utils/log`);
+const Log = require(`../utils/Log`);
 const session_vars = require(`../utils/session_vars` );
+const files = require(`../utils/files` );
+const time = require(`../utils/time` );
+
+const context = `setup`;
 
 const setup = async () => {
-  /** In the docassemble testing account identified by the
-  *   DOCASSEMBLE_DEVELOPER_API_KEY secret, create a new Project,
-  *   pull code into that project, and, if needed, wait for the
-  *   server to reload.
-  */
+  /** This is for a package being installed in an author's account (Playground)
+   *  on their docassemble server. Using the author's
+   *   DOCASSEMBLE_DEVELOPER_API_KEY secret, create a new Project, pull code
+   *   into that project, and, if needed, wait for the server to reload.
+   */
   
   // Make and save project name
   let project_name = session_vars.get_project_base_name().replace(/[^A-Za-z0-9]/g, '') + `${Date.now()}`;
   session_vars.save_project_name( project_name );
 
-  log.info({ type: `setup`, code: `ALK0046`, pre: `Starting to upload this package to `
+  const starting_msg = `Starting to upload this package to `
     + `a new Project called ${project_name} in the Playground `
-    + `of your server's testing account. It may take a couple of minutes.` });
+    + `of your server's testing account. It may take a couple of minutes.`;
+  log.info({ code: `ALK0046`, context, },
+    starting_msg
+  );
+
+  // TODO: 1. Start listening to the normal console here (for debug logging)
 
   // dainstall . --apiurl https://site.org --apikey $API_KEY --playground --project=name
   // I think this won't run on windows? Why do I think this? Where on the
@@ -34,29 +41,37 @@ const setup = async () => {
       `--playground`, `--project=${ project_name }`
     ],
     // Prints messages from the process to the console while it's running
+    // result.stderr, result.stdout, etc. will be `null`
     { stdio: 'inherit', }
   );
 
-  // 403 is invalid API key, but I'm not sure how to output
-  // the response to find out the error code
+  // TODO: 2. Stop listening to the normal console here
 
+  // 403 is invalid API key, but I'm not sure how to output
+  // the response to find out the error code. stderr is `null`.
   if ( result.status !== 0 ) {
-    log.error({
-      type: `setup`,
-      code: `ALK0047`,
-      pre: `Status code ${ result.status }. Could not dainstall this package on your server. See above for more details.`
-    });
-    throw(result.stderr);
+    const install_err_msg = `Status code ${ result.status }. Could not `
+      + `dainstall this package on your server. See above for more details.`;
+    log.throw({ code: `ALK0047`, context,
+      before: `☝️ ☝️ ☝️  Error data ☝️ ☝️ ☝️\n`,
+      error: `Error while installing project` },
+      install_err_msg
+    );
   }
 
-  log.success({
-    type: `setup`,
-    code: `ALK0048`,
-    pre: `ALKiln created a Project in your Playground named "${ project_name }"!`
-  });
+  log.success({ code: `ALK0048`, context, },
+    `ALKiln created a Project in your Playground named "${ project_name }"!`
+  );
 };  // Ends setup();
 
-
-// Before everything, make sure all the required env vars exist
+// 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 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
 setup();

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();