@suffolklitlab/alkiln 5.13.2 → 5.13.3-feat-random-2

package/docs/kinds_of_errors.md

@@ -0,0 +1,26 @@
+# Kinds of Errors
+
+An error, or even an `Error` instance, can mean a lot of different things in the context of this testing framework. Throwing errors for failing tests is what we are most familiar with, but it is just one kind of error.
+
+## Interview `Error`s
+
+1. **Interview bugs**: For example, the interview says ALKiln's answer is invalid. The author expected that answer to be valid. ALKiln saves an error message to the report and throws an error to tell cucumber to mark the test as failed. Currently, these logs errors come with the 🤕 icon. When all the tests are done, the test suite will show as failing in the console, the report, and the various logs. In future, ALKiln will use a method like `report.throw()` to save to the various log files with the `error` level and then throw the error to let cucumber know the test failed.
+1. **Interview expected errors**: For example, the interview says ALKiln's answer is invalid. The author was testing their interview's field validation rules. The test passes.
+
+## Test file `Error`s
+
+1. **Test file syntax error**: For example, a row in a table in a test file has too many columns. cucumberjs throws an error and no tests are run. ALKiln should show the tests as failed. ALKiln is unable to get the output of that error into a log, but there should be an error in the console.
+1. **Test Step typo**: For example, `And I ta p to contcontinue`. cucumberjs will cause this test to fail, giving an "undefined" Step as the reason. The test suite will show as failing in the console, the report, and the various logs.
+1. **Test bugs**: For example, a test has old values that need to be updated. The test fails. This will look like an interview bug, as this document describes.
+
+## ALKiln `Error`s
+
+1. **ALKiln un-handled bugs**: For example, we have forgotten to define a variable and none of our tests has yet triggered that code. These are unexpected errors that force processes to abort or force individual tests to fail in uninformative ways. To an author that runs into that error, it looks like their test has failed, but the fault is ours and we need to troubleshoot it. We should make that clear.
+1. **ALKiln silent bugs**: For example, a debug log has an object that causes an error when ALKiln tries to turn it into a string. ALKiln should record the failure somewhere, but should avoid throwing it. We can troubleshoot those if we see them and add new internal tests. See decisions docs on when to use which kind of log level.
+1. **ALKiln expected errors**: For example, one promise won a `Promise.race()`, so ALKiln aborted the other promises. That causes those aborted promises to error. That is why ALKiln saves the "informational" Error to the debug files and it has a level of "info" or "debug".
+
+## ALKiln's internal tests
+
+1. **ALKiln internal success-handling test failures**: For example, the test fails to fill out radio buttons correctly.
+1. **ALKiln internal failure-handling test successes**: For example, we test that the summary report shows a specific log code when an interview fails to load and the log code shows up correctly. The "test" fails - the interview fails to load - but *our* test passes - the right log code was in the summary report.
+1. **ALKiln internal failure-handling test failures**: For example, we test that the report shows a specific log code when an interview fails to load, but the log code is missing. The "test" fails and *our* test fails.

package/docs/prioritize_constrained_random_tests.md

@@ -0,0 +1,60 @@
+# Prioritize constrained random answers tests over pure random answers tests
+
+## Context and Problem Statement
+
+We could develop constrained randomness first or pure randomness first. Is there a reason to prioritize one over another?
+
+## Considered Options
+
+- Purely random answers. They fill in fields without any guidance.
+- Constrained random answers tests. They make the test author list all the variable names and all the choices of answers they want to allow for those variables.
+- Hybrid approach. Allow an author to specify some values while letting other values stay completely random.
+
+## Decision Outcome
+
+Prioritize constrained random answers tests over pure random answers tests. Strangely, they seem to be the more flexible of the two options.
+
+## Pros and Cons of the Options
+
+The discussion about the general pros and cons of random answers tests will be in the `constrained_random_tests` doc for now.
+
+### Purely random answers
+
+Pros:
+
+- Very little work for test authors to write.
+- Because they're so free-form, they may do a better job finding unexpected behavior that authors didn't think to test for.
+
+Cons:
+
+- Unless we can find better ways of generating purely random test files for the authors, copying a random answers test to keep permanently might be very challenging.
+- Fields might get nonsensical answers. For example, a very large number for age or a very small number for income.
+- Impossible to use for fields that need very specific answers, like a real lawyer's bar number or a specific file name for uploading exhibits.
+
+### Constrained random answers
+
+Pros:
+
+- Useful for fields that need very specific answers, like a real lawyer's bar number or a specific file name for uploading exhibits.
+- An author can focus the tests' answers on important user stories. For example, they might want to focus some tests on users that have children while keeping other answers more random.
+- An author might be able to make more efficient random tests. For example, a multiple choice question may have multiple answers that, behind the scenes, set the same value. Authors might do this to help users who are confused about their options give more accurate answers. A purely random test would pick that repeated value too often and waste testing time.
+
+Cons:
+
+- They take more time to write.
+- They take more work to maintain.
+
+<!-- TODO: Add to docs - each `possible_values` cell should contain 1 or more possible answers. -->
+
+### Hybrid
+
+In future, we believe we can figure out how to let users have partially constrained tests where unspecified fields get purely random answers while constrained fields choose from a set of answers. It would need to be its own Step.
+
+Pros:
+
+- Offers the most flexibility and control.
+
+Cons:
+
+- Might be hard to avoid confusion about test behavior.
+- Means developing both methods of testing. That's out of scope for one PR.

package/lib/docassemble/docassemble_api_interface.js

@@ -1,5 +1,5 @@
 const _da_REST = require('./docassemble_api_REST');
-const log = require('../utils/log');
+const Log = require('../utils/Log');
 const session_vars = require('../utils/session_vars' );
 const time = require('../utils/time');
 
@@ -61,6 +61,10 @@ const time = require('../utils/time');
 let da_i = {};
 module.exports = da_i;
 
+const context = `da api`;
+const artifacts_path = session_vars.get_artifacts_path_name();
+const log = new Log({ path: artifacts_path, context });
+
 
 // Constants
 const DEFAULT_MAX_REQUEST_MS = session_vars.get_setup_timeout_ms();
@@ -92,7 +96,9 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
 
   // Defaults
   let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
-  log.info({ type: `da api`, code: `ALK0166`, pre: `Waiting for the docassemble server to respond. Will wait for ${ timeout/1000 } seconds at most.` });
+  log.info({ code: `ALK0166`, context, },
+    `Waiting for the docassemble server to respond. Will wait for ${ timeout/1000 } seconds at most.`
+  );
   
   try {
     let start_time = Date.now()
@@ -100,7 +106,9 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
     let response = await _da_REST.get_dev_id( timeout );
     let end_time = Date.now()
     if ( response && response.data && response.data.id ) {
-      log.info({ type: `da api`, code: `ALK0167`, pre: `The docassemble server responded after ${ (end_time - start_time)/1000 } seconds.` });
+      log.info({ code: `ALK0167`, context, },
+        `The docassemble server responded after ${ (end_time - start_time)/1000 } seconds.`
+      );
       return false;
     }
 
@@ -109,17 +117,16 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
     if ( is_timeout_error( error ) ) {
       // Anything that's waiting for the server to not be busy does not want
       // to move forward without a free server.
-      log.info({ type: `da api`, code: `ALK0168`, pre: `The docassemble server was still busy after ${ timeout/1000 } seconds.` });
+      log.info({ code: `ALK0168`, context, },
+        `The docassemble server was still busy after ${ timeout/1000 } seconds.`
+      );
     } else {
       // Not sure what to do for other errors. It could be a server
       // error, like an 'Access Denied' error, which should be handled.
-      log.error({
-        type: `da api`,
-        code: `ALK0169`,
-        pre: `Tried to check if the docassemble server was busy, but `
-        + `ran into an unexpected error. The error didn't indicate a busy server, though. Error message:\n`
-        + error
-      });
+      log.warning({ code: `ALK0169`, context, },
+        `Checked if the server was busy and ran into a different error`,
+        error
+      );
     }
 
     throw error;
@@ -187,7 +194,7 @@ da_i.get_api_key_access_status = async function ({ timeout = null, api_key = nul
   *    to allow for server request.
   */
 
-  let auth_data = {
+  let auth_feedback = {
     codes: [ 1 ],
     has_auth: null,
     messages: [`API key authorization is not yet determined.`],
@@ -196,16 +203,16 @@ da_i.get_api_key_access_status = async function ({ timeout = null, api_key = nul
 
   // Skip this for tests run from ALKilnInThePlayground
   if ( session_vars.get_origin() === 'playground' ) {
-    auth_data.codes.push( 2 );
-    auth_data.messages.push( `API keys are unnecessary for tests run in the Playground.` );
+    auth_feedback.codes.push( 2 );
+    auth_feedback.messages.push( `API keys are unnecessary for tests run in the Playground.` );
   }
 
   if ( typeof api_key !== `string` ) {
-    auth_data.codes.push( 3 );
-    auth_data.messages.push( `The given API key is not a string. Type: ${ typeof api_key }`);
+    auth_feedback.codes.push( 3 );
+    auth_feedback.messages.push( `The given API key is not a string. Type: ${ typeof api_key }`);
   }
 
-  if ( auth_data.codes.length === 1 ) {
+  if ( auth_feedback.codes.length === 1 ) {
     // Default timeouts
     timeout = timeout || DEFAULT_MAX_REQUEST_MS;
     try {
@@ -213,29 +220,31 @@ da_i.get_api_key_access_status = async function ({ timeout = null, api_key = nul
         api_key,
         server_url: session_vars.get_da_server_url(),
       });
-      auth_data.has_auth = true;
-      auth_data.codes = [ 6 ];
-      auth_data.messages = [ `This API key has at least basic authorization on this server.` ];
+      auth_feedback.has_auth = true;
+      auth_feedback.codes = [ 6 ];
+      auth_feedback.messages = [ `This API key has at least basic authorization on this server.` ];
 
     } catch ( error ) {
-      auth_data.error = error;
+      auth_feedback.error = error;
       if ( error.status === 403 ) {
-        auth_data.has_auth = false;
-        auth_data.codes = [ 4 ];
-        auth_data.messages = [ `This API is unverified on this server. It is probably missing or has been deleted.` ];
+        auth_feedback.has_auth = false;
+        auth_feedback.codes = [ 4 ];
+        auth_feedback.messages = [ `This API is unverified on this server. It is probably missing or has been deleted.` ];
       } else {
         // Note on 404, non-existent key: 404 == 403 - Since we're using the
         // key itself to get its own info, if it doesn't exist, we'll get 403
-        auth_data.codes = [ 5 ];
-        auth_data.messages = [ `This API key threw a non-403 error.` ];
+        auth_feedback.codes = [ 5 ];
+        auth_feedback.messages = [ `This API key threw a non-403 error.` ];
       }  // ends error status
     }  // ends try
-  }  // ends auth_data.codes only has the first code
+  }  // ends auth_feedback.codes only has the first code
 
-  log.debug({ type: `da api info`, code: `ALK0202`,
-    pre: `API key authentication info`, data: auth_data });
+  log.debug({ code: `ALK0202`, context, },
+    `API key - what happened during authentication:`,
+    auth_feedback
+  );
 
-  return auth_data;
+  return auth_feedback;
 };  // Ends da_i.get_api_key_access_status()
 
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").delete_project( "create1" )'
@@ -247,16 +256,19 @@ da_i.delete_project = async function ( delete_options ) {
   let { timeout } = delete_options || { timeout: DEFAULT_MAX_REQUEST_MS };
 
   let project_name = session_vars.get_project_name()
-  log.info({ type: `da api`, code: `ALK0170`, pre: `Trying to delete Project ${ project_name }` });
+  log.info({ code: `ALK0170`, context, },
+    `Trying to delete Project ${ project_name }`
+  );
 
   try {
     let response = await _da_REST.delete_project( timeout );
-    log.info({ type: `da api`, code: `ALK0171`, pre: `Deleted Project "${ project_name }"` });
+    log.info({ code: `ALK0171`, context, },
+      `Deleted Project "${ project_name }"`
+    );
   } catch ( error ) {
-    let msg = `Ran into an error when deleting Project "${ project_name }". See https://docassemble.org/docs/api.html#playground_delete_project.`
-    log.error({ type: `da api`, code: `ALK0172`, pre: msg });
-    log.debug({ type: `da api`, code: `ALK0173`, pre: msg });
-    throw error;
+    log.throw({ code: `ALK0172`, context, error: error },
+      `Ran into an error when deleting Project "${ project_name }". See https://docassemble.org/docs/api.html#playground_delete_project.`
+    );
   }
 
 };  // Ends da_i.delete_project()
@@ -280,7 +292,9 @@ da_i.quietly_try_to_delete_interviews = async function ({ interviews = {}, api_k
       });
       responses.push( sub_responses );
     } else {
-      log.debug({ type: `da api info`, code: `ALK0191`, pre: `There is no interview to delete.` });
+      log.debug({ code: `ALK0191`, context, },
+        `There is no interview to delete.`
+      );
     }
   }
   return responses;
@@ -295,9 +309,9 @@ da_i.quietly_delete_one_interview = async function ( timeout, { interview = {},
   let responses = [];
   for ( let api_key of api_keys ) {
     try {
-      log.debug({ type: `da api info`, code: `ALK0188`,
-        pre: `Trying to delete the interview with the id ${ interview.uid } and an API key.`
-      });
+      log.debug({ code: `ALK0188`, context, },
+        `Trying to delete the interview with the id ${ interview.uid } and an API key.`
+      );
 
       // Actual work:
       let response = await _da_REST.delete_interview( timeout, {
@@ -306,13 +320,15 @@ da_i.quietly_delete_one_interview = async function ( timeout, { interview = {},
       });
       responses.push( response );
 
-      log.debug({ type: `da api info`, code: `ALK0189`,
-        pre: `No error when trying to delete interview ${ interview.uid } at ${ interview.i }.`
-      });
+      log.debug({ code: `ALK0189`, context, },
+        `No error when trying to delete interview ${ interview.uid } at ${ interview.i }.`
+      );
     } catch ( error ) {
       error.interview = interview;
-      let msg = `Error when deleting the interview. See https://docassemble.org/docs/api.html#session_delete.`
-      log.debug({ type: `da api info`, code: `ALK0190`, pre: msg, data: error });
+      log.debug({ code: `ALK0190`, context, },
+        `Error when deleting the interview. See https://docassemble.org/docs/api.html#session_delete.`,
+        error
+      );
     }
   }  // ends for api keys
   return responses;
@@ -347,7 +363,9 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
   if ( interview && interview.uid ) {
     for ( let api_key of api_keys ) {
       try {
-        log.debug({ type: `da api info`, code: `ALK0192`, pre: `Trying to get the interview with the id ${ interview.uid } and an API key.` });
+        log.debug({ code: `ALK0192`, context, },
+          `Trying to get the interview with the id ${ interview.uid } and an API key.`
+        );
 
         // Actual work:
         let response = await _da_REST.get_interview( timeout, {
@@ -356,20 +374,28 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
         });
 
         if ( response && response.data && response.data.items && response.data.items[0] && response.data.items[0].session ) {
-          log.debug({ type: `da api info`, code: `ALK0193`, pre: `Status ${ response.status }. Got ${ response.data.items[0].session }.`});
+          log.debug({ code: `ALK0193`, context, },
+            `Status ${ response.status }. Got ${ response.data.items[0].session }.`
+          );
           return response.data.items[0];
         } else {
-          log.debug({ type: `da api info`, code: `ALK0194`, pre: `Status ${ response.status }. Cannot find ${ interview.uid }`});
+          log.debug({ code: `ALK0194`, context, },
+            `Status ${ response.status }. Cannot find ${ interview.uid }`
+          );
         }
 
       } catch ( error ) {
         error.interview = interview;
-        let msg = `${ error.status || `No error.status.` } ${ error.statusText || error.data || `No error.statusText.` } Ran into an error when getting the interview ${ interview.uid }. See https://docassemble.org/docs/api.html#interviews.`
-        log.debug({ type: `da api info`, code: `ALK0195`, pre: msg, data: error });
+        log.debug({ code: `ALK0195`, context, },
+          `${ error.status || `No error.status.` } ${ error.statusText || error.data || `No error.statusText.` } Ran into an error when getting the interview ${ interview.uid }. See https://docassemble.org/docs/api.html#interviews.`,
+          error
+        );
       }
     }  // ends for api_keys
   } else {
-    log.debug({ type: `da api info`, code: `ALK0196`, pre: `There is no interview to get.` });
+    log.debug({ code: `ALK0196`, context, },
+      `There is no interview to get.`
+    );
   }
 
   return null;

package/lib/docassemble/server_install.js

@@ -1,10 +1,20 @@
 #!/usr/bin/env node
 
 const session_vars = require('../utils/session_vars');
-const log = require('../utils/log');
+const Log = require('../utils/Log');
 const fg = require('fast-glob');
 
+const context = `server_install`;
+
 const server_install = async () => {
+  /** For packages we are installing on a temporary GitHub docassemble server.
+   *
+   *  - Store that the package is being installed globally on a server as
+   *    opposed to on a specific author's account (their Playground).
+   *  - In the repo, find and store the path to directory that stores the
+   *    package itself instead of the whole repo. For example, EvictionDefense
+   *    in the docassemble-EvictionDefense repo.
+   * */
   session_vars.save_install_method(`server`);
 
   // Get path to folders inside repo main "docassemble" folder
@@ -23,20 +33,33 @@ const server_install = async () => {
   // Get names of all folders in repo "docassemble" folder
   let chosen_folder = folders[0];
   if ( folders.length === 0 ) {
-    let msg = `There are 0 folders at ${path}. Stopping tests.`;
-    log.error({ type: `setup`, code: `ALK0044`, data: msg })
-    throw new ReferenceError( msg );
+    let msg = `ALKiln cannot find the package's files. There are 0 folders at "${ path }". Stopping tests.`;
+    log.throw({ code: `ALK0044`, context,
+      error: new ReferenceError( msg )  // no logs
+    });
   }
 
   if ( folders.length > 1 ) {
-    log.warn({
-      type: `setup`,
-      code: `ALK0045`,
-      data: `There are ${folders.length} folders at ${path}: "${folders.join('", "')}". ALKiln chose to use the folder "${chosen_folder}".`
-    })
+    log.warn({ code: `ALK0045`, context, },
+      `There are ${ folders.length } folders at "${ path }": "${ folders.join('", "') }". ALKiln chose to use the folder "${ chosen_folder }".`
+    );
+  } else {
+    log.info({ code: `ALK0218`, context, },
+      `ALKiln found the package folder at "${ chosen_folder }".`
+    );
   }
   
   session_vars.save_repo_folder_name( chosen_folder );
 };  // Ends server_install();
 
+// 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
 server_install();

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: new Error(`Error while installing project on your docassemble server`) },
+      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/globals.js

@@ -0,0 +1,10 @@
+let globals = {
+  // File name prefix ALKiln can use to identify random answer generator files
+  generators_prefix: `alkiln_random`,
+  generated_files_folder_name: `_alkiln_generated`,
+}
+
+module.exports = globals;
+
+// Would this be clearer as a config file instead?
+// If not, change name to `constants`?