@suffolklitlab/alkiln 4.6.0 → 4.7.0

package/lib/scope.js

@@ -4,6 +4,8 @@ const path = require('path');
 const fs = require('fs');
 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
+const faker = require('@faker-js/faker/locale/en').faker;
 
 // Ours
 const session_vars = require('./utils/session_vars');
@@ -11,6 +13,7 @@ const get_base_interview_url = require(`./docassemble/get_base_interview_url`);
 const time = require('./utils/time');
 const log = require('./utils/log');
 const { waitForTimeout } = require('./utils/time');
+const files = require('./utils/files' );
 
 
 let ordinal_to_integer = {
@@ -50,6 +53,7 @@ let is_secret_var = function(row) {
 }
 
 let proxies_regex = /(\bx\.)|(\bx\[)|(\[[ijklmn]\])/g;
+let misc_artifacts_dir = `_alkiln_test-misc_artifacts`;
 
 module.exports = {
   trigger_not_needed_flag: `ALKiln: no trigger variable needed`,
@@ -63,7 +67,22 @@ module.exports = {
     let scenario = await scope.makeSureReportPartsExist( scope );
     scenario.lines.push({ type, value });
 
-    log.add_to_debug_log(`Report:\ntype: ${ type }, value: ${ value }\n`);
+    // TODO: Not sure how to use .add_to_debug_log() here considering possibly dynamic filepath
+    // log.add_to_debug_log(`Report:\ntype: ${ type }, value: ${ value }\n`);
+
+    // Ensure filepath for saving local unit test logs
+    if ( !scope.paths ) {
+      // TODO: would it be useful to put in existing artifacts folder if possible.
+      // Can this be usefully abstracted?
+      scope.paths = { debug_log: `${ misc_artifacts_dir }/unit_tests_logs-${ files.readable_date() }.txt` };
+    }
+
+    try {
+      fs.appendFileSync(scope.paths.debug_log, `\nReport:\ntype: ${ type }, value: ${ value }`);
+    } catch (err) {
+      fs.mkdirSync( misc_artifacts_dir );
+      fs.appendFileSync(scope.paths.debug_log, `\nReport:\ntype: ${ type }, value: ${ value }`);
+    }
     return scenario;
     
   },  // Ends scope.addToReport()
@@ -72,7 +91,10 @@ module.exports = {
     /* If a part of the report needs to exist right now, but doesn't exist,
     * create it. */
     if ( !scope.report ) { scope.report = new Map(); }
-    if ( !scope.scenario_id ) { scope.scenario_id = `_report_${ Date.now() }` }
+    if ( !scope.scenario_id ) {
+      let date = files.readable_date();
+      scope.scenario_id = `_report_${ date }`;
+    }
     if ( !scope.report.get( scope.scenario_id )) {
       scope.report.set( scope.scenario_id, {} )
       scope.report.get( scope.scenario_id ).status = `in progress`;
@@ -187,41 +209,49 @@ module.exports = {
       name_parts.push( scope.language );
     }
     name_parts.push( scenario.pickle.name );
-    for ( let tag of scenario.pickle.tags ) {
-      name_parts.push( tag.name );
-    }
 
     let filename = name_parts.join(`-`);
+    let safe_name = safe_filename( filename, { replacement: `_` });
+    // Allow room for extensions, date, etc.
+    let safer_name = safe_name.substring(0, (255 - 45));
 
-    return safe_filename( filename, { replacement: `_` });
+    return safer_name;
   },  // Ends scope.getSafeScenarioBaseFilename()
 
-  getSafeScenarioFilename: async function( scope, options={} ) {
+  // TODO: Does this need a name change? getSafeScenarioBasedFilename?
+  getSafeScenarioFilename: async function( scope, options={ prefix: '' }) {
     /* Return a string that's safe to be a filename. Use a timestamp,
     *    a prefix the caller wants, and the base filename. We hope it can
     *    contain non-english characters too. We do not offer a suffix option
     *    because it may be cut off if the filename is too long.
     */
-    // Ensure prefix is a string
-    let prefix = options.prefix || '';
+    let name = options.prefix || '';
+
     // As long as it's not an empty string, add a separator between it and the rest of the name
-    // For now, it needs to be `_` for the action and .gitignore. In future,
-    // aiming for `-`.
-    if ( prefix ) {
-      prefix = `${ prefix }_`;
+    if ( name.length > 0 ) {
+      name += `-`;
+    }
+
+    if ( scope.page ) {
+      let { id } = await scope.examinePageID( scope, 'none to match' );
+      name += `${ id }-`;
     }
 
-    let safe_name = safe_filename(`${ prefix }${ Date.now() }-${ scope.base_filename }`, { replacement: `_` });
-    let safer_name = safe_name.substring(0, (255 - 10));  // Allow room for extensions
+    name += scope.base_filename;
+    name += `-${ files.readable_date() }`;
+
+    let safe_name = safe_filename( name, { replacement: `_` });
+    // Allow room for extensions, etc.
+    let safer_name = safe_name.substring(0, (255 - 10));
     return safer_name;
   },  // Ends scope.getSafeScenarioFilename()
 
   getJSONFilename: async function( scope ) {
-    let filename = await scope.getSafeScenarioFilename( scope, {
-      prefix: `downloads_${ scope.page_id }_JSON`
-    });
-    filename += `.json`;
-    return filename;
+    // Get a unique path for a json file
+    let { id } = await scope.examinePageID( scope, 'none to match' );
+    let date = files.readable_date();
+    let json_path = path.join( scope.paths.scenario, `json_for-${ id }-${ date }.json` );
+    return json_path;
   },
 
   savePageJSONData: async function( scope ) {
@@ -231,13 +261,12 @@ module.exports = {
     * @returns {string} info.filename The name of the file that was saved.
     * @returns {Object} info.json The variables object.
     */
-    // Get a unique json file filename
-    let filename = await scope.getJSONFilename( scope );
+    let json_path = await scope.getJSONFilename( scope );
     // Get the data
     let json = await scope.getPageJSON( scope );
     // Save the data
-    fs.writeFileSync( filename, JSON.stringify( json, null, 2 ));
-    return { filename, json };
+    fs.writeFileSync( json_path, JSON.stringify( json, null, 2 ));
+    return { json_path, json };
   },  // Ends scope.savePageJSONData()
 
   waitForShowIf: async function waitForShowIf(scope) {
@@ -386,7 +415,14 @@ module.exports = {
 
   detectDownloadComplete: async function detectDownloadComplete(scope, endTime) {
     /* Resolve if a download flag has changed. Timeout after a bit less than
-    *    the global permitted timeout */
+    *    the global permitted timeout
+    * 
+    * TODO: Properly wait for download to complete. See 
+    * https://github.com/SuffolkLITLab/ALKiln/issues/492 and
+    * https://stackoverflow.com/a/56951024 and
+    * https://github.com/puppeteer/puppeteer/issues/4676 and
+    * https://github.com/puppeteer/puppeteer/issues/299 and
+    */
 
     // Stop/resolve if too much time has passed
     let expirationTime = scope.timeout - 200;  // ms
@@ -454,7 +490,7 @@ module.exports = {
 
     // Do your own waiting if you need to in the step
     return to_manipulate;
-  },  // Ends setVar()
+  },  // Ends scope.setVar()
 
   continue: async function ( scope ) {
     /* Presses whatever button it finds that might lead to the next page. */
@@ -466,7 +502,25 @@ module.exports = {
     await elem.evaluate( el => { return el.className });
     // Waits for navigation or user error
     await scope.tapElement( scope, elem );
-  },
+  },  // Ends scope.continue()
+
+  continue_exists: async function ( scope ) {
+    /** Return true if a button that will allow continuing appears
+    *    on this page. Otherwise return false. */
+
+    // Possible to find this on an event screen with `buttons:`, like an exit button
+    // <button type="submit" class="btn btn-da btn-danger" name="X211bHRpcGxlX2Nob2ljZQ" value="0">exit</button>
+    // An actual continue button that doesn't set a variable
+    // <button class="btn btn-da btn-primary" type="submit">Continue</button>
+    // One that sets a variable:
+    // <button type="submit" class="btn btn-da btn-primary" name="Zm9v" value="True">Continue</button>
+    // `buttons:` can be used in question blocks as choices
+    let regular = await scope.page.$( `fieldset.da-field-buttons button[type="submit"]` );
+    let signature = await scope.page.$( `fieldset .dasigsave` );
+
+    return regular !== null || signature !== null;
+
+  },  // Ends scope.continue_exists()
 
   tapTab: async function ( scope, tab_id ) {
     let elem = await scope.page.$(`#${tab_id}`); 
@@ -497,12 +551,13 @@ module.exports = {
     axe_result.passes = [];
     axe_result.inapplicable = [];
 
-    let axe_filename = null;
+    let axe_path = null;
     const passed = axe_result.violations.length == 0;
     if (!passed) {
-      axe_filename = await scope.getSafeScenarioFilename( scope, {prefix: `aXe_failure_${ scope.page_id }`}) + '.json';
-      fs.writeFileSync( axe_filename, JSON.stringify( axe_result, null, 2 ));
-      let msg = `Found potential accessibility issues on the ${ scope.page_id } screen. Details in ${ axe_filename }.`;
+      let axe_filename = await scope.getSafeScenarioFilename( scope, {prefix: `aXe_failure`}) + '.json';
+      axe_path = `${ scope.paths.scenario }/${ axe_filename }`;
+      fs.writeFileSync( axe_path, JSON.stringify( axe_result, null, 2 ));
+      let msg = `Found potential accessibility issues on the ${ scope.page_id } screen. Details in ${ axe_path }.`;
       await scope.addToReport( scope, {
         type: `error`,
         value: msg
@@ -512,7 +567,7 @@ module.exports = {
     }
     return {
       passed: axe_result.violations.length == 0,
-      axe_filename: axe_filename
+      axe_filepath: axe_path
     };
   },
 
@@ -666,7 +721,7 @@ module.exports = {
     // All the different types of fields
     // buttons, canvases, inputs of all kinds, selects (dropdowns), textareas. Are there more?
     // Will deal with `option` once inside `select`
-    let all_nodes = $( `#dasigpage, fieldset button, .daquestionactionbutton, fieldset input, .da-form-group input, .da-form-group select, .da-form-group textarea` );
+    let all_nodes = $( `#dasigpage, fieldset button, .daquestionactionbutton, fieldset input, .da-form-group input, .da-form-group select, form select, .da-form-group textarea` );
     for ( let node of all_nodes ) {
       // Decision: Do not abstract the below. There's too much data to pass around for it to make sense
       let $node = $( node );
@@ -932,6 +987,9 @@ module.exports = {
       // names.var_names.push( layer_2_decoded );
     }
 
+    // Detecting valid variable names/characters
+    // https://stackoverflow.com/a/23377268
+
     return var_names;
   },  // Ends scope.getPossibleVarNames()
 
@@ -1198,13 +1256,7 @@ module.exports = {
       await scope.page.waitForSelector('#dasigcanvas');
     }
 
-    let handle = await scope.page.evaluateHandle(( selector, field ) => {
-      let elem = document.querySelector( selector );
-      // `elem` has never been null
-      if ( elem.nextSibling && elem.nextSibling.tag === `label` ) {
-        return elem.nextSibling;
-      } else { return elem; }
-    }, field.selector, field );
+    let handle = await scope.get_handle_from_field( scope, { field: field });
 
     let disabled = await handle.evaluate(( elem )=> {
       // da's header covers the top of the section containing the fields which means
@@ -1225,15 +1277,39 @@ module.exports = {
       await scope.page.waitForTimeout( 400 );
     }
 
-    let { tag, type } = field;
     // We use the last match. We wrote a warning for the user if there were
     // multiple matches in the story that the last value will be used. In future,
     // Steps will be able to set this data gradually and we don't want the developer
     // to get confused thinking that an earlier Step was used instead of a later one.
     let row = matching_input_rows[ matching_input_rows.length - 1 ];
-    let set_to = row.value;
+    let answer = row.value;
+
+    await scope.funnel_the_answer( scope, { handle, answer, field });
+
+    return row;
+  },  // Ends scope.setVariable()
+
+  get_handle_from_field: async function ( scope, { field }) {
+    /** Get the element's puppeteer handle using the field's selector. */
+
+    let handle = await scope.page.evaluateHandle(( selector ) => {
+      let elem = document.querySelector( selector );
+      // If the element has a sibling that's a label, we need to
+      // interact with that label instead.
+      // `elem` has never been null from what we've seen
+      if ( elem.nextSibling && elem.nextSibling.tag === `label` ) {
+        return elem.nextSibling;
+      } else { return elem; }
+    // Pass in the selector as an argument
+    }, field.selector );
+
+    return handle;
+  },  // Ends scope.get_handle_from_field()
+
+  get_custom_datatype: async function( scope, { handle }) {
+    /** If this is part of a custom datatype, returns an element,
+    *    otherwise returns null. */
 
-    // Detect a custom type and get the element of that custom type if it exists
     let custom_datatype = await handle.evaluate(( elem )=> {
       // If the element is in a form group**, then extract the form group's
       // datatype value.
@@ -1252,28 +1328,52 @@ module.exports = {
       return custom_datatype;
     });
 
-    // Set field
-    if ( scope.setCustomDatatype[ custom_datatype ] === undefined ) {
-      // If no custom datatype, set a regular field
-      await scope.setField[ tag ]( scope, { handle, set_to });
-    } else {
+    return custom_datatype;
+  },  // Ends scope.is_custom_datatype()
+  
+  funnel_the_answer: async function( scope, { handle, field, answer }) {
+    /** Use the tag or custom datatype to funnel the answer to the right
+    *    field. Pages without a handle should pass in `null` for the
+    *    handle.
+    */
+
+    let custom_datatype = null;
+    // Pages with elements like `canvas` for signatures won't have a handle
+    // to pass in. They should pass in `null` for the handle and shouldn't
+    // need a handle in order to function.
+    if ( handle !== null ) {
+      // Get the element of that custom type if it exists
+      custom_datatype = await scope.get_custom_datatype( scope, { handle });  
+    }
+
+    // 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, set_to });
+      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 });
     }
 
-    return row;
-  },  // Ends scope.setVariable()
+  },  // Ends scope.funnel_the_answer()
 
   // Handle setting values for da custom datatypes. E.g. `da-field-container-datatype-BirthDate`
   // TODO: Make this more easily extensible.
-  // TODO: Just put this in `scope.setField`? Find the custom handle in the setter itself.
+  // TODO: Just put this in `scope.enter_answer`? Find the custom handle in the setter itself.
   setCustomDatatype: {
-    "BirthDate": async function ( scope, { handle, set_to }) {
+    al_date: async function ( scope, { handle, answer, is_past }) {
       /* Given a date of the format 'mm/dd/yyyy' and the handle of the
-      * custom field container, sets the ALToolbox custom birthdate
+      * custom field container, sets an AssemblyLine three-part date's
       * field values. */
-      let date_parts = set_to.split(`/`);
+
+      // If it doesn't have the right format
+      if ( answer === null || !answer.includes(`/`) ) {
+        // Do nothing
+        return;
+      }
+
+      let date_parts = answer.split(`/`);
       let fields = await handle.$$(`select, input:not([type="hidden"])`);
       for ( let field_i = 0; field_i < fields.length; field_i++ ) {
         let field = fields[ field_i ];
@@ -1286,55 +1386,76 @@ module.exports = {
           // Set the month
           await field.select( date_parts[ 0 ] );
         } else {
-          // Set the day and year
+          // Set the day or year
           await scope.setText( scope, {
             handle: field,
-            set_to: date_parts[ field_i ]
+            answer: date_parts[ field_i ]
           });
         }
 
       }  // For each field
 
       await scope.afterStep( scope );
-    },  // Ends BirthDate()
+    },  // Ends scope.setCustomDatatype.al_date()
+
+    BirthDate: async function ( scope, { handle, answer }) {
+      /** Given a date of the format 'mm/dd/yyyy' and the handle of the
+      * custom field container, sets the ALToolbox custom birthdate
+      * field values. */
 
+      await scope.setCustomDatatype.al_date( scope, { handle, answer })
+    },  // Ends scope.setCustomDatatype.BirthDate()
+
+    ThreePartsDate: async function ( scope, { handle, answer }) {
+      /** Given a date of the format 'mm/dd/yyyy' and the handle of the
+      * custom field container, sets the ALToolbox custom ThreePartsDate
+      * field values. */
+      await scope.setCustomDatatype.al_date( scope, { handle, answer })
+    },  // Ends scope.setCustomDatatype.ThreePartsDate()
 
   },  // ends setCustomDatatype {}
 
-  setField: {
-    button: async function ( scope, { handle, set_to }) { await scope.tapElement( scope, handle ); },
-    textarea: async function ( scope, { handle, set_to }) {
-      await scope.setText( scope, { handle, set_to });
+  enter_answer: {
+    button: async function ( scope, { handle, answer }) { await scope.tapElement( scope, handle ); },
+    textarea: async function ( scope, { handle, answer }) {
+      await scope.setText( scope, { handle, answer });
       await scope.afterStep(scope);  // No showifs for this one?
     },
-    select: async function ( scope, { handle, set_to }) {
+    select: async function ( scope, { handle, answer }) {
+      // Note: I don't remember what's really going on in here.
+      // I will note that values of `select` elements are strings,
+      // not variables, so we don't need to check for variable names.
+
       // A dropdown's option value can be one of two things
       // Try to find the element using the first value
 
-      // TODO: Can we somehow pass in a `set_to` that is encoded correctly since
+      // TODO: Can we somehow pass in a `answer` that is encoded correctly since
       // we're getting the fields from the DOM to begin with? We'll probably
       // need another prop because we need the `option` human value to
       // match the story table
 
       // TODO: Change this to search in the actual handle instead of just $
-      let option = await scope.page.$(`option[value="${ set_to }"]`);
+      // There could be multiple fields on the page with the same option
+      // values.
+      // let option = await handle.$(`option[value="${ answer }"]`);
+      let option = await scope.page.$(`option[value="${ answer }"]`);
       if ( option ) {
-        await handle.select( set_to );  // And use that value to set it
+        await handle.select( answer );  // And use that value to set it
 
       // If that literal value isn't on the page, it should be a base64 encoded value
-      // TODO: Can these be double encoded?
+      // TODO: Can these be double encoded? Can they be encoded like objects?
       } else {
-        let base64_name = await scope.toBase64( scope, { utf8_str: set_to });
+        let base64_name = await scope.toBase64( scope, { utf8_str: answer });
         await handle.select( base64_name );
       }
       
       await scope.afterStep(scope, { waitForShowIf: true });
     },
-    canvas: async function ( scope, { handle, set_to }) {
+    canvas: async function ( scope, { handle, answer }) {
       await scope.sign( scope );
       await scope.afterStep( scope );
     },
-    input: async function ( scope, { handle, set_to }) {
+    input: async function ( scope, { handle, answer }) {
       /* Set value of some `input` element to the given value. */
 
       let type = await handle.evaluate( elem => { return elem.getAttribute('type'); });
@@ -1343,50 +1464,60 @@ module.exports = {
         let [label] = await handle.$x(`following-sibling::label`);
         
         if ( session_vars.get_debug() ) {
-          if ( set_to.toLowerCase() === 'false' ) { await label.evaluate( elem => { elem.style.background = 'tomato'; }); }
+          if ( answer.toLowerCase() === 'false' ) { await label.evaluate( elem => { elem.style.background = 'tomato'; }); }
           else { await label.evaluate( elem => { elem.style.background = 'teal'; }); }
           let name = await label.evaluate( elem => { return elem.getAttribute('for'); });
         }
 
         if ( type === `radio` ) { await label.evaluate( elem => { return elem.click(); }); }
-        else { await scope.setCheckbox( scope, { label, set_to }); }
+        else { await scope.setCheckbox( scope, { label, answer }); }
 
         await scope.afterStep(scope, { waitForShowIf: true });
         
       } else if ( type === `file` ) {
-        await scope.uploadFiles( scope, { handle, set_to });
+        await scope.uploadFiles( scope, { handle, answer });
         await scope.afterStep(scope, { waitForShowIf: true });
 
       } else if (type == `date`) {
-        let set_to_date = set_to;
+        let answer_date = answer;
         // If the date is specified in the format "today" or "today + 2" or "today-1"
         // it will need some pre-processing. 
-        if (set_to.indexOf(`today`) !== -1) {
+        if (answer.indexOf(`today`) !== -1) {
           // Find out how many days to add/subtract
-          let date_delta = set_to.replace(/\s/g, '');
+          let date_delta = answer.replace(/\s/g, '');
           date_delta = date_delta.match(/today([+-]\d+)?/)[1];
           date_delta = date_delta == undefined ? 0 : date_delta;
           date_delta = parseInt(date_delta);
           // Get today's date
-          set_to_date = new Date(); 
+          answer_date = new Date(); 
           // Add/subtract required number of days
-          set_to_date.setDate(set_to_date.getDate() + date_delta);
+          answer_date.setDate(answer_date.getDate() + date_delta);
           // Convert to the docassemble date field format: mm/dd/yyyy
           // Reference: https://gomakethings.com/setting-a-date-input-to-todays-date-with-vanilla-js/
-          set_to_date = ((set_to_date.getMonth() + 1).toString().padStart(2, 0) + '/' + 
-                         set_to_date.getDate().toString().padStart(2, 0) + '/' +
-                         set_to_date.getFullYear().toString());
+          answer_date = ((answer_date.getMonth() + 1).toString().padStart(2, 0) + '/' + 
+                         answer_date.getDate().toString().padStart(2, 0) + '/' +
+                         answer_date.getFullYear().toString());
         }
-        await scope.setText( scope, { handle, set_to: set_to_date });
+        await scope.setText( scope, { handle, answer: answer_date });
         await scope.afterStep(scope, { waitForShowIf: true });
       } else {
-        await scope.setText( scope, { handle, set_to });
+        await scope.setText( scope, { handle, answer });
         await scope.afterStep(scope, { waitForShowIf: true });
       }
-    },  // Ends scope.setField.input()
-  },
+    },  // Ends scope.enter_answer.input()
+    hidden: async function ( scope, { handle, answer }) {
+      // Do nothing. The only way the code should get here is if
+      // this wasn't a custom datatype we can handle.
+      // If we were to write a message, I don't know what we can
+      // write - this may be a different custom datatype or this
+      // could be a special da field that we shouldn't worry the
+      // dev about at all.
+      return;
+    },
+
+  },  // ends scope.enter_answer
 
-  uploadFiles: async function ( scope, { handle, set_to }) {
+  uploadFiles: async function ( scope, { handle, answer }) {
     /* Try to upload one or more files to a file-type input field. */
     
     // Tests could be in one of two places. Figure out which directory they're in
@@ -1419,7 +1550,7 @@ module.exports = {
     }
 
     // Allow a typo where someone forgot to include a space after a comma
-    let file_names = set_to.split(`,`);
+    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 = [];
@@ -1441,8 +1572,8 @@ module.exports = {
     }
 
     if ( paths.length === 0 ) {
-      await scope.addToReport( scope, { type: `error`, value: `Could not find "${set_to}".` });
-      throw ReferenceError(`Could not find "${set_to}".`)
+      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`); });
@@ -1467,20 +1598,20 @@ module.exports = {
 
   },  // Ends scope.uploadFiles()
 
-  setCheckbox: async function ( scope, { label, set_to }) {
+  setCheckbox: async function ( scope, { label, answer }) {
     // Depending on the current value/status of a checkbox and the desired
     // value to set, either taps the checkbox or leaves it alone.
     let status = await label.evaluate( elem => { return elem.getAttribute('aria-checked'); });
-    if ( set_to.toLowerCase() !== status ) {
+    if ( answer.toLowerCase() !== status ) {
       await label.evaluate( elem => { return elem.click(); });
     }
   },  // Ends scope.setCheckbox()
 
-  setText: async function ( scope, { handle, set_to }) {
+  setText: async function ( scope, { handle, answer }) {
     // Set text in some kind of field (input text, input date, textarea, etc.)
     await handle.evaluate( el => { el.value = '' });
     await handle.focus();
-    await handle.type( set_to );
+    await handle.type( answer );
     setTimeout(async () => {
     }, 500)
   },
@@ -1527,7 +1658,7 @@ module.exports = {
   },  // Ends scope.examinePageID()
 
   // TODO: Rename var_data to input_data?
-  // Note: Totally different from `setField` (which is singular)
+  // Note: Totally different from `enter_answer` (which is singular)
   // TODO: If a step triggers this and is not able to set a value, should it error?
   // TODO: Rename to setFieldsOfOnePage? setPageFields?
   setFields: async function ( scope, {
@@ -1656,7 +1787,8 @@ module.exports = {
         }
       }
       if ( num_unused_rows > 0 ) {
-        let msg = `Missing variable or variables on page.`;
+        let { id } = await scope.examinePageID( scope, 'none to match' );
+        let msg = `Missing variable or variables on page "${id}"`;
         await scope.addToReport(scope, { type: `error`, value: msg });
         expect( num_unused_rows, msg ).to.equal( 0 );
       }
@@ -1885,12 +2017,18 @@ module.exports = {
       /* Download and save a screenshot. `name` does not have to be
       * unique as the filename will be made unique. */
       name = name || '';
-      let safe_path = await scope.getSafeScenarioFilename(
-        scope, { prefix: `screenshot_${ name }` }
-      );
+
+      let date = files.readable_date();
+      let { id } = await scope.examinePageID( scope, 'none to match' );
+      // Include the custom name if it has one
+      if ( name.length > 0 ) {
+        name = `screenshot-${ name }-on-${ id }-${ date }`;
+      } else {
+        name = `screenshot_on-${ id }-${ date }`;
+      }
 
       await scope.page.screenshot({
-        path: `./${ safe_path }.jpg`,
+        path: `./${ scope.paths.scenario }/${ name }.jpg`,
         type: 'jpeg',
         fullPage: true
       });
@@ -1930,7 +2068,7 @@ module.exports = {
       await scope.afterStep(scope);
     },  // Ends link_works()
 
-    set_regular_var: async ( scope, var_name, set_to ) => {
+    set_regular_var: async ( scope, var_name, answer ) => {
       /** Set a non-story table variable (with or without a choice associated with it) to a value. Set:
       *  - Buttons associated with variables
       *  - Dropdowns
@@ -1941,23 +2079,23 @@ module.exports = {
       */
       // Let kiln know not to test against trigger variable values, even for proxy vars
       let var_data = await scope.normalizeTable( scope, {
-        var_data: [{ var: var_name, value: set_to, trigger: scope.trigger_not_needed_flag }],
+        var_data: [{ var: var_name, value: answer, trigger: scope.trigger_not_needed_flag }],
       });
       // Don't continue if the variable doesn't cause navigation itself. Also,
       // if this variable cannot be set on this page, trigger an error
       await scope.setFields( scope, { var_data, ensure_navigation: false, ensure_all_vars_used: true });
     },  // Ends set_regular_var()
 
-    set_secret_var: async ( scope, var_name, set_to_env_name ) => {
+    set_secret_var: async ( scope, var_name, answer_env_name ) => {
       /** Sets a non-story table variable to a "secret" value (i.e. an env var) */
       // Prevent pictures of a screen with a secret.
       scope.disable_error_screenshot = true;
       let var_data = await scope.normalizeTable( scope, {
               var_data: [{
                 var: var_name,
-                value: set_to_env_name,
+                value: answer_env_name,
                 trigger: scope.trigger_not_needed_flag,
-                flags: {secret_name: set_to_env_name}
+                flags: {secret_name: answer_env_name}
               }],
       });
       // Don't continue if the variable doesn't cause navigation itself. Also,
@@ -1990,6 +2128,9 @@ module.exports = {
       *    WARNING: Cannot download the same file twice in a single scenario.
       *    WARNING: Must not have any characters that are totally unique to that
       *    page load. It's usually just the name of the file.
+      * 
+      * TODO: Properly wait for download to complete. See notes in
+      * scope.js scope.detectDownloadComplete()
       */
       let [elem] = await scope.page.$x(`//a[contains(@href, "${ filename }")]`);
 
@@ -2126,10 +2267,235 @@ module.exports = {
       });
 
       await scope.afterStep(scope, {waitForShowIf: false});
-    },  // Ends sign_in
+    },  // Ends scope.steps.sign_in()
+
+    set_random_page_vars: async ( scope ) => {
+      /** Answer inputs randomly. */
+
+      let html = await scope.page.content();
+      // These are the fields on the current page. Their handles should all exist.
+      let fields = await scope.getAllFields( scope, { html: html });
+      let buttons = [];
+
+      // For every field on the page
+      for ( let field of fields ) {
+
+        // fields[n].tag is HTML tag of node, as a string
+
+        // If the field is a button, save it in a list of buttons that we'll deal with later
+        if ( field.tag === `button` ) {
+          buttons.push( field );
+        } else {
+          // Try to give a random answer for that element tag
+          await scope.set_random_input_for[ field.tag ]( scope, { field: field });
+          process.stdout.write(`\x1b[36m${ '*' }\x1b[0m`);  // assumes var was set if no error occurred
+        }
+
+      }  // End for all page fields
+
+      return buttons;
+
+    },  // Ends scope.steps.set_random_page_vars()
 
   },  // ends scope.steps
 
+  set_random_input_for: {
+    a: async function (scope, { fields }) {
+      // We don't do anything with links for random input tests
+    }, 
+    buttons: async function (scope, { fields }) {
+      // Get a random button
+      let field = faker.helpers.arrayElement( fields );
+      let handle = await scope.get_handle_from_field( scope, { field: field });
+      // Send it to be tapped
+      await scope.funnel_the_answer( scope, { handle, field, answer: `doesn't matter` });
+    },
+    textarea: async function (scope, { field }) {
+      // Get random paragraph of text
+      let answer = faker.lorem.paragraph();
+      // Get the element's puppeteer handler
+      let handle = await scope.get_handle_from_field( scope, { field: field });
+      // Type the random text into the textarea
+      await scope.funnel_the_answer( scope, { handle, field, answer: answer });
+    },
+    select: async function (scope, { field }) {
+      // Get the values of all the options of the field
+      let handle = await scope.get_handle_from_field( scope, { field: field });
+      // Get the values of all the choices
+      let answer_choices = await handle.evaluate(function ( elem ) {
+        let values = Array.from(elem.querySelectorAll(`option`)).map(element=>element.value);
+        return values;
+      });
+
+      // Remove the "no selection" option from the list ('')
+      // TODO: blue sky - for optional fields allow no selection
+      if ( answer_choices[0] === `` ) {
+        answer_choices.shift();
+      }
+
+      // Select randomly between them
+      let answer = faker.helpers.arrayElement( answer_choices );
+
+      // Set that value
+      await scope.funnel_the_answer( scope, { handle, field, answer: answer });
+
+    },
+    canvas: async function (scope, { field }) {
+      // WARNING: Do not test this in headless mode.
+      // If we do this in headless mode, the test will fail. It signs, but
+      // can't continue. Not sure why.
+      await scope.funnel_the_answer( scope, { field, handle: null, answer: `doesn't matter` });
+    },
+    input: async function (scope, { field }) {
+      /** Handles various `type`s of input element fields, except:
+      * 
+      * Does not handle "file" type
+      * Does not handle custom data values yet, like BirthDate, because they have
+      *    `type="hidden"` which also matches other special da fields on the
+      *    page that we SHOULDN'T interact with.
+      * Does not handle range, which is not a `type`, but it is an input element
+      */
+
+      // Use the type instead of the tag to get get the answer for
+      // an input field
+      let type = field.type;
+      
+      // Custom datatype question: Do all custom datatypes hide their
+      // original field? Probably not...
+      // TODO: Move custom datatype checking to the caller of this
+      // function somehow - in future, not all custom datatypes will
+      // be inputs _and_ this won't handle, for example, a `select` field
+      // that is part of a custom datatype with a hidden field - this
+      // doesn't take care of that situation.
+
+      let handle = await scope.get_handle_from_field( scope, { field: field });
+
+      // If this is a custom datatype
+      let custom_datatype = await scope.get_custom_datatype( scope, { handle });
+      let is_custom_datatype = scope.get_random_input_for[ custom_datatype ] !== undefined;
+      if ( is_custom_datatype ) {
+
+        // And the custom datatype has a hidden field (which will be the original field)
+        let hidden_field = await scope.get_custom_datatype_hidden_field( scope, { handle });
+        if ( hidden_field !== null ) {
+          // only set the value once - just for the original field
+          if ( type === `hidden` ) {
+
+            // set the value
+            let answer = await scope.get_random_input_for[ custom_datatype ]( scope );
+            await scope.funnel_the_answer( scope, { handle, field, answer });
+
+          }
+          // Otherwise ignore the non-original field
+
+        // Untested: If no hidden field exists, just try to set the custom
+        // datatype field
+        } else {
+          // set the value
+          let answer = await scope.get_random_input_for[ custom_datatype ]( scope );
+          await scope.funnel_the_answer( scope, { handle, field, answer });
+        }
+
+      // If this is not a custom datatype
+      } else {
+
+        // `file` type inputs come next to an input with a type of ''.
+        // Maybe others do too.
+        if ( type !== `` && type !== `hidden` ) {
+          // Field types that we can't yet handle, but plan to in future
+          if ( type === `file` ) {
+            await scope.addToReport( scope, {
+              type: `warning`,
+              value: `Sorry, ALKiln's random-input cannot yet handle "${ type }" fields.`
+            });
+          } else {
+            let answer = await scope.get_random_input_for[ type ]( scope );
+            await scope.funnel_the_answer( scope, { handle, field, answer });
+          }  // ends if field type is one we cover
+        }  // ends if field type exists
+
+      }  // ends if is custom datatype
+
+    },  // ends scope.set_random_input_for.input
+  },  // ends scope.set_random_input_for
+
+  get_custom_datatype_hidden_field: async function (scope, { handle }) {
+    /** If there's a hidden field in a custom datatype, returns that
+    *    DOM node, otherwise returns null. */
+
+    let hidden_field = await handle.evaluate(( elem )=> {
+      // If the element is in a form group**, then extract the form group's
+      // datatype value.
+      // ** For now the only custom datatype we have is in a form group. In
+      // future we should look into what happens with a `fieldset` for
+      // `choices:`, etc.
+      let custom_datatype = null, matches = null;
+      let group = elem.closest( `.da-form-group` );
+      // Returns an element or null
+      let hidden_child = group.querySelector( `[type="hidden"]` );
+
+      return hidden_child;
+    });
+
+    return hidden_field;
+  },  // Ends scope.get_custom_datatype_hidden_field()
+
+  get_random_input_for: {
+    checkbox: async function ( scope ) {
+      return `${ Math.random() > .5 }`;
+    },
+    radio: async function ( scope ) {
+      return `${ Math.random() > .5 }`;
+    },
+    text: async function ( scope ) {
+      return faker.random.word();
+    },
+    number: async function ( scope ) {
+      let answer = faker.helpers.arrayElement( [`1`, `2`, `3`], 1 );
+      return answer;
+    },
+    date: async function ( scope ) {
+      let past = faker.date.past(25);
+      let future = faker.date.future(1);
+
+      let date = null;
+      if ( Math.random() > .5 ) {
+        date = past;
+      } else {
+        date = future;
+      }
+      // Ensure 2-digit number for month and day
+      let month = ("0" + (date.getMonth() + 1)).slice(-2);
+      let day = ("0" + (date.getDay() + 1)).slice(-2);
+      // Format the string in the way ALKiln can read it
+      return `${ month }/${ day }/${ date.getFullYear() }`;
+    },
+    currency: async function ( scope ) {
+      return `${ Math.random() * 100 }`;
+    },
+    email: async function ( scope ) {
+      return faker.internet.email( faker.random.word(), faker.random.word(), `example.com` );
+    },
+    password: async function ( scope ) {
+      return faker.internet.password();
+    },
+    hidden: async function ( scope ) {
+      return null;
+    },
+    BirthDate: async function ( scope ) {
+      let date = faker.date.birthdate({ max: 70, min: 0, mode: `age` });
+      // Ensure 2-digit number for month and day
+      let month = ("0" + (date.getMonth() + 1)).slice(-2);
+      let day = ("0" + (date.getDay() + 1)).slice(-2);
+      // Format the string in the way ALKiln can read it
+      let date_str = `${ month }/${ day }/${ date.getFullYear() }`;
+      return date_str;
+    },
+    ThreePartsDate: async function ( scope ) {
+      return await scope.get_random_input_for.date( scope );
+    },
+  },  // ends scope.get_random_input_for()
+
 
   //#####################################
   //#####################################