@suffolklitlab/alkiln 4.11.6 → 5.0.0-experimental2

package/lib/scope.js

@@ -2,6 +2,7 @@ const { expect } = require('chai');
 const cheerio = require('cheerio');
 const path = require('path');
 const fs = require('fs');
+const { globSync } = require('glob');
 const { AxePuppeteer } = require('@axe-core/puppeteer');
 const safe_filename = require("sanitize-filename");
 // "en" is faster to import: https://github.com/faker-js/faker/issues/1114#issuecomment-1169532948
@@ -1528,7 +1529,10 @@ module.exports = {
     let row = matching_input_rows[ matching_input_rows.length - 1 ];
     let answer = row.value;
 
-    await scope.funnel_the_answer( scope, { handle, answer, field });
+    // Will implement `was_used` in cases as they come along. For now, this is
+    // necessary for file uploads to be as flexible as any other Story Table row.
+    let was_used = await scope.funnel_the_answer( scope, { handle, answer, field });
+    if ( was_used === false ) { row = null; }
 
     return row;
   },  // Ends scope.setVariable()
@@ -1590,16 +1594,18 @@ module.exports = {
       custom_datatype = await scope.get_custom_datatype( scope, { handle });  
     }
 
+    let row_was_used = true;
     // If there is a custom datatype function available, use it to set the field
     if ( scope.setCustomDatatype[ custom_datatype ] !== undefined ) {
       // Set da package custom fields. TODO: find `custom_handle` in the setter?
       let custom_handle = await handle.evaluateHandle(( elem )=> { return elem.closest( `.da-form-group` ) });
-      await scope.setCustomDatatype[ custom_datatype ]( scope, { handle: custom_handle, answer });
+      row_was_used = await scope.setCustomDatatype[ custom_datatype ]( scope, { handle: custom_handle, answer });
     } else {
       // If no custom datatype, set a regular field
-      await scope.enter_answer[ field.tag ]( scope, { handle, answer });
+      row_was_used = await scope.enter_answer[ field.tag ]( scope, { handle, answer });
     }
 
+    return row_was_used;
   },  // Ends scope.funnel_the_answer()
 
   // Handle setting values for da custom datatypes. E.g. `da-field-container-datatype-BirthDate`
@@ -1660,10 +1666,14 @@ module.exports = {
   },  // ends setCustomDatatype {}
 
   enter_answer: {
-    button: async function ( scope, { handle, answer }) { await scope.tapElement( scope, handle ); },
+    button: async function ( scope, { handle, answer }) {
+      await scope.tapElement( scope, handle );
+      return true;
+    },
     textarea: async function ( scope, { handle, answer }) {
       await scope.setText( scope, { handle, answer });
       await scope.afterStep(scope);  // No showifs for this one?
+      return true;
     },
     select: async function ( scope, { handle, answer }) {
       // Note: I don't remember what's really going on in here.
@@ -1692,13 +1702,16 @@ module.exports = {
       }
       
       await scope.afterStep(scope, { waitForShowIf: true });
+      return true;
     },
     canvas: async function ( scope, { handle, answer }) {
       await scope.draw_signature( scope );
       await scope.afterStep( scope );
+      return true;
     },
     input: async function ( scope, { handle, answer }) {
       /* Set value of some `input` element to the given value. */
+      let row_was_used = true;
 
       let type = await handle.evaluate( elem => { return elem.getAttribute('type'); });
       if ( type === `radio` || type === `checkbox` ) {
@@ -1717,7 +1730,7 @@ module.exports = {
         await scope.afterStep(scope, { waitForShowIf: true });
         
       } else if ( type === `file` ) {
-        await scope.uploadFiles( scope, { handle, answer });
+        row_was_used = await scope.uploadFiles( scope, { handle, answer });
         await scope.afterStep(scope, { waitForShowIf: true });
 
       } else if (type == `date`) {
@@ -1746,6 +1759,8 @@ module.exports = {
         await scope.setText( scope, { handle, answer });
         await scope.afterStep(scope, { waitForShowIf: true });
       }
+
+      return row_was_used;
     },  // Ends scope.enter_answer.input()
     hidden: async function ( scope, { handle, answer }) {
       // Do nothing. The only way the code should get here is if
@@ -1762,80 +1777,57 @@ module.exports = {
   uploadFiles: async function ( scope, { handle, answer }) {
     /* Try to upload one or more files to a file-type input field.
     *    Does not submit, so no danger of timeout with server reload.
+    * 
+    * Returns whether the row was used or not.
     */
+    console.log( process.cwd() );
 
-    // Tests should be one place: docassemble/*/data/sources, where * is the only folder in `docassemble`.
-    // Makes an absolute path from the folder in which `npm run` was used plus our internal folders
-    let docassemble_pkg_path = `${ process.cwd() }/docassemble`;
-    let subpackage_name = session_vars.get_package_name().substring(12);
-    let pkg_paths = [];
-    try {
-      fs.accessSync(docassemble_pkg_path);
-      // https://stackoverflow.com/a/24594123/11416267
-      let dirs = fs.readdirSync(docassemble_pkg_path, {withFileTypes: true}).filter(dirent => dirent.isDirectory()).map(dirent => dirent.name);
-      if (dirs.length < 1) {
-        let msg = `You can store files to upload in 'docassemble/${ subpackage_name }/data/source'. These tests could not find a folder like that starting at ${ process.cwd() }.`;
-        await scope.addToReport( scope, { type: `warning`, value: msg});
-        throw Error(msg);  // Most people will want to know the sources folder path;
-      }
-      for (let dir of dirs) {
-        pkg_paths.push(`${docassemble_pkg_path}/${dir}`);
-      }
-    } catch ( error_da ) {
-      let msg = `You can store files to upload in 'docassemble/${ subpackage_name }/data/source'. ` +
-          `These tests could not find a folder like that. The current directory is ` +
-          ` ${ process.cwd() }; is that in the top level folder of your docassemble package? (${ session_vars.get_package_name() })?`;
-      await scope.addToReport( scope, { type: `warning`, value: msg});
-      throw error_da;  // Most people will want to know the sources folder path;
-    }
-
-    let chosen_dir = null;
-    let err_paths = [];
-    for (let pkg_path of pkg_paths) {
-      let dir = `${ pkg_path }/data/sources`;
-      try {
-        fs.accessSync(dir);
-        chosen_dir = dir;
-        break;
-      } catch ( error_full ) {
-        err_paths.push(`'${dir}'`);
-      }
-    }
-    if (chosen_dir === null) {
-      let msg = `You can store files to upload in ${err_paths.join(", or ")}. These tests could not find any of those folders.`;
-      await scope.addToReport( scope, { type: `warning`, value: msg });
-      throw Error(msg);  // Most people will want to know the sources folder path;
+    // First make sure the list of files is of the correct format
+    // Allow a typo where someone forgot to include a space after a comma
+    let uploads_names = answer.split(`,`);
+    if ( uploads_names.length === 0 ) {
+      await scope.addToReport( scope, {
+        type: `error`,
+        value: `Your list of files to upload is empty.`
+      });
+      return false;
     }
 
-    if (pkg_paths.length > 1 && pkg_paths.length - err_paths.length > 1) {
-      await scope.addToReport( scope, { type: `warning`, value: `You have multiple folders in the 'docassemble' folder (${ pkg_paths }). These tests will use the first folder with a "data/sources" subfolder (${chosen_dir}).` });
+    // Make sure sources directory exists
+    let dirs = globSync( `**/data/sources` );
+    if ( dirs.length === 0 ) {
+      await scope.addToReport( scope, {
+        type: `warning`,
+        value: `ALKiln couldn't find a "sources" directory in "${ process.cwd() }" where it could get files to upload.`
+      });
+      return false;
     }
+    let dir = dirs[0];
 
-    // Allow a typo where someone forgot to include a space after a comma
-    let file_names = answer.split(`,`);
-
-    // If a file exist, add it to a list of files to be uploaded. If it doesn't, add a warning.
     let paths = [];
-    for ( let name of file_names ) {
+    let missing_files = [];
+    for ( let name of uploads_names ) {
+      let trimmed_name = name.trim();
+      let matching_paths = globSync( `${ dir }/${ trimmed_name }` );
+      if ( matching_paths.length === 0 ) {
+        missing_files.push( trimmed_name );
+      } else {
+        paths.push( matching_paths[0] );
+      }
+    }
 
-      // If the developer correctly used a ", ", there will be a space at the
-      // start of the string. Remove it. If they forgot the space, that's fine too.
-      name = name.replace(/^\s/, '');
-      let file_path = path.join( chosen_dir, name );
+    if ( missing_files.length > 0 ) {
+      await scope.addToReport( scope, {
+        type: `warning`,
+        value: `ALKiln could not find "${ missing_files.join('", "') }" in "${ dir }".`
+      });
+    }
 
-      try {
-        fs.accessSync( file_path );
-        paths.push( file_path );
-      } catch ( err ) {
-        // TODO: Should this throw an error?
-        await scope.addToReport( scope, { type: `warning`, value: `Could not find "${ name }" in "${ chosen_dir }"` });
-      }
+    // If all files missing, return that the row wasn't used
+    if ( missing_files.length === uploads_names.length ) {
+      return false;
     }
 
-    if ( paths.length === 0 ) {
-      await scope.addToReport( scope, { type: `error`, value: `Could not find "${answer}".` });
-      throw ReferenceError(`Could not find "${answer}".`)
-    } 
     // Prepare to wait for upload to complete
     let name = await handle.evaluate( elem => { return elem.getAttribute(`name`); });
     let selector = `*[name="${ name }"]`
@@ -1855,8 +1847,9 @@ module.exports = {
     await wait_for_disable;
     // When it's again enabled, the files have finished loading. Or so I have observed.
     await scope.page.waitForSelector( enabled_selector );
-  
 
+    // Return that the row was used
+    return true;
   },  // Ends scope.uploadFiles()
 
   setCheckbox: async function ( scope, { label, answer }) {
@@ -1877,16 +1870,26 @@ module.exports = {
     }, 500)
   },
 
-  draw_signature: async function ( scope ) {
+  draw_signature: async function ( scope, name ) {
     /* On a signature page, there should only be a single signature canvas
     * and a continue button. Draw in the #dasigcanvas element. `<canvas>`
     * takes a while to load. */
-    let handle = await scope.page.waitForSelector( `#dasigcanvas` );
+    let canvas = await scope.page.waitForSelector( `#dasigcanvas` );
     let msg = `Could not find a signature field.`;
-    if ( !handle ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
-    expect( handle, msg ).to.exist;
-
-    let bounding_box = await handle.boundingBox();
+    if ( !canvas ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+    expect( canvas, msg ).to.exist;
+
+    // Provides functionality to draw name arg on canvas
+    if (name !== undefined) {
+      await scope.page.$eval(`#dasigcanvas`, (canvas, name) => {
+        const ctx = canvas.getContext("2d");
+        ctx.font = "24px serif";
+        ctx.fillText(name, 10, 50);
+      }, name);
+    }
+    let bounding_box = await canvas.boundingBox();
+    // We draw the dot because it allows the developer to tap continue
+    // Docassemble does not allow to tap continue unless the user interacts with the canvas
     await scope.page.mouse.move(bounding_box.x + bounding_box.width / 2, bounding_box.y + bounding_box.height / 2);
     await scope.page.mouse.down();
     // await scope.page.mouse.move(1, 1);  // Too big? Wait a while before drawing?
@@ -2415,9 +2418,9 @@ module.exports = {
       await scope.afterStep(scope, {waitForShowIf: true});
     },  // Ends scope.steps.tap_term()
 
-    sign: async ( scope ) => {
+    sign: async ( scope, name ) => {
       /** Sign on a signature page. */
-      await scope.draw_signature( scope );
+      await scope.draw_signature( scope, name );
       await scope.afterStep(scope);
     },  // Ends scope.steps.sign()
 

package/lib/steps.js

@@ -92,7 +92,7 @@ BeforeAll(async () => {
   // Make the folder to store all the files for this run of the tests
   scope.paths.artifacts = files.make_artifacts_folder();
   // Save its name in a file. `session_vars` can get it back later.
-  // This is used by at least clean_reports.js.
+  // The value we are saving is used by at least run_cucumber.js.
   session_vars.save_artifacts_path_name( scope.paths.artifacts );
 
   scope.paths.report = `${ scope.paths.artifacts }/report.txt`;
@@ -103,7 +103,14 @@ BeforeAll(async () => {
 Before(async (scenario) => {
   // Create browser, which can't be created in BeforeAll() where .driver doesn't exist for some reason
   if (!scope.browser) {
-    scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug(), devtools: session_vars.get_debug() });
+    if (session_vars.get_origin() === 'playground') {
+      // Will only run in the Playground outside of a sandbox. TODO: There's a
+      // better way to do this, though it's more complicated. See comments in
+      // https://github.com/SuffolkLITLab/ALKiln/issues/661
+      scope.browser = await scope.driver.launch({ args: ['--no-sandbox'] });
+    } else {
+      scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug(), devtools: session_vars.get_debug() });
+    }
   }
   // Clean up all previously existing pages
   for (const page of await scope.browser.pages()) { 
@@ -973,13 +980,21 @@ When('I tap the defined text link {string}', { timeout: -1 }, async ( phrase ) =
   await scope.steps.tap_term( scope, phrase );
 });
 
-Then('I sign', { timeout: -1 }, async () => {
+Then(/^I sign$/, { timeout: -1 }, async () => {
   return wrapPromiseWithTimeout(
     scope.steps.sign( scope ),
     scope.timeout
   );
 });
 
+Then('I sign with the name {string}', { timeout: -1 }, async ( name ) => {
+  /* Signs with the string argument */
+  return wrapPromiseWithTimeout(
+    scope.steps.sign( scope, name ),
+    scope.timeout
+  );
+});
+
 When(/I download "([^"]+)"$/, { timeout: -1 }, async ( filename ) => {
   /* Taps the link that leads to the given filename to trigger downloading.
   *    and waits till the file has been downloaded before allowing the tests to continue.

package/lib/utils/session_vars.js

@@ -23,9 +23,27 @@ module.exports = session_vars;
 // These default to null
 // TODO: How to isolate debug elsewhere so this file can use the logger?
 session_vars.get_debug = function () { return process.env.DEBUG || null; };
+session_vars.is_dev_env = function () { return process.env.DEV || null; }
+
 session_vars.get_dev_api_key = function () { return process.env.DOCASSEMBLE_DEVELOPER_API_KEY || null; };
 session_vars.get_repo_url = function () { return process.env.REPO_URL || null; };
-session_vars.is_dev_env = function () { return process.env.DEV || null; }
+
+session_vars.get_origin = function () {
+  /** The location from which the tests are being run. Possible
+  *    valid return values: 'playground', 'github', or 'local'.
+  *    Default is 'local' for ease of our own onboarding process.
+  */
+  return process.env._ORIGIN || 'local';
+};
+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 () {
@@ -130,7 +148,10 @@ session_vars.save_project_name = function ( project_name ) {
 };  // Ends save_project_name()
 
 session_vars.get_project_name = function () {
-  /* Get the name of the current docassemble Project  */
+  /* Get the name of the current docassemble Project */
+  if ( session_vars.get_origin() === 'playground' ) {
+    return session_vars.get_user_project_name();
+  }
   let json = JSON.parse( fs.readFileSync( runtime_config_path ));
   let project_name = json[ project_name_key ] || null;
   if ( session_vars.get_debug() ) { console.log( `ALKiln debug: Project name from file is "${ project_name }".` ); }
@@ -174,7 +195,7 @@ session_vars.save_artifacts_path_name = function ( path_name ) {
     console.log( `ALKiln debug: Stored name of artifacts directory "${ path_name }" locally.` );
   }
   return file;
-};  // Ends get_project_name()
+};  // Ends save_artifacts_path_name()
 
 session_vars.get_artifacts_path_name = function () {
   /* Get the name of the current artifacts path. */
@@ -187,48 +208,69 @@ session_vars.get_artifacts_path_name = function () {
   } catch ( error ) {
     return null;
   }
-};  // Ends get_project_name()
-
-/**
- * Ensure all required environment variables exist. Add each missing variable
- *    to an error that will be thrown at the end.
- * 
- * @throws ReferenceError with a message for all missing variables. 
- */
- session_vars.validateEnvironment = function() {
-  /** Throw a useful error for the developer if any of the required env vars
-  *    are missing. For most devs, these will be GitHub secrets. */
-
-  // Note: We are checking for BASE_URL, but we are referring it as SERVER_URL as that
-  // is the name used in GitHub secrets, which is what most devs will be using.
+};  // Ends get_artifacts_path_name()
 
+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
+  *    missing var names into one message to ease dev process.
+  * 
+  * Rational for doing it all in here:
+  * 1. Easier to test
+  * 2. Will avoid piecemeal errors in separate locations
+  * 
+  * TODO: Also validate format of variables?
+  * 
+  * @throws ReferenceError with a message for all missing variables. 
+  */
   let errorMessage = '';
 
-  // Since this code will most often be run in GitHub, I'm going to build a single error message that outlines all missing variables.  Otherwise, a developer
-  // will have to run their pipeline an incredible number of times to discover all the missing variables.
-  if ( !session_vars.get_dev_api_key() )
-  {
-    errorMessage += `\nThe DOCASSEMBLE_DEVELOPER_API_KEY GitHub secret must be defined. The DOCASSEMBLE_DEVELOPER_API_KEY is a docassemble API key you created for your server's testing account. It should have developer permissions.`
-  }
-  if ( !session_vars.get_da_server_url() )
-  {
+  // Env vars required for any tests
+  if ( !session_vars.get_da_server_url() ) {
     errorMessage += `\nThe SERVER_URL GitHub secret must be defined. The SERVER_URL is the URL of the Docassemble Server where the tests should be run.`;
   }
-  if ( !session_vars.get_repo_url() )
-  {
-    errorMessage += `\nThe REPO_URL GitHub secret must be defined. The REPO_URL is the URL to the Git repo whose Actions are being run.`;
-  }
-  // The branch name is always automatically defined in Github, it'll be missing only if you're running locally and missing an env var.
-  if ( !session_vars.get_branch_name() )
-  {
-    errorMessage += `\nThe BRANCH_NAME environment variable must be defined. The BRANCH_NAME is the name of the repository branch that should be pulled into the docassemble project.`;
-  }
+
+  let origin = session_vars.get_origin();
+  if ( origin !== 'github' && origin !== 'local' && origin !== 'playground' ) {
+    errorMessage += `\nThe _ORIGIN environment variable should be set to a valid value automatically. If you see this error, file an issue at https://github.com/suffolkLITLab/docassemble-ALKilnInThePlayground. It must be defined as either 'playground', 'github', or 'local', but its value was ${origin}`;
+
+  // If origin has one of the allowed values, we can do the rest of the validations
+  } else {
+
+    // Env vars required for github or local runs, as both create Projects
+    // in the Playground and pull the repo from GitHub
+    if ( origin === 'github' || origin === 'local' ) {
+      if ( !session_vars.get_dev_api_key() ) {
+        errorMessage += `\nThe DOCASSEMBLE_DEVELOPER_API_KEY GitHub secret must be defined. The DOCASSEMBLE_DEVELOPER_API_KEY is a docassemble API key you created for your server's testing account. It should have developer permissions.`
+      }
+      // Github automatically gives this, but may be missing locally.
+      if ( !session_vars.get_repo_url() ) {
+        errorMessage += `\nThe REPO_URL environment variable must be defined. The REPO_URL is the URL to the GitHub repo whose Actions are being run.`;
+      }
+      // Github automatically gives this, but may be missing locally.
+      if ( !session_vars.get_branch_name() ) {
+        errorMessage += `\nThe BRANCH_NAME environment variable must be defined. The BRANCH_NAME is the name of the repository branch that should be pulled into the docassemble project.`;
+      }
+    }  // ends github and local env vars
+
+    // We're the ones ensuring these exist for Playground runs
+    if ( origin === 'playground' ) {
+      if ( !session_vars.get_user_project_name() ) {
+        errorMessage += `\nThe _PROJECT_NAME environment variable should automatically exist. If you see this error, file an issue at https://github.com/suffolkLITLab/docassemble-ALKilnInThePlayground. It is the name of the Project the developer chose to test.`
+      }
+      if ( !session_vars.get_user_id() ) {
+        errorMessage += `\nThe _USER_ID environment variable should automatically exist. If you see this error, file an issue at https://github.com/suffolkLITLab/docassemble-ALKilnInThePlayground. It is the user ID of the developer on the server.`
+      }
+      // Tags are optional
+    }  // ends Playground env vars
+
+  }  // ends validation based on origin
 
   errorMessage = errorMessage.trim();
 
   if (errorMessage !== '') {
-    throw new ReferenceError(errorMessage);
+    throw new ReferenceError(`ALKiln error: ${errorMessage}`);
   }
 };
-  
+
 session_vars.validateEnvironment();