@suffolklitlab/alkiln 4.6.2 → 4.7.2

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');
@@ -12,6 +14,8 @@ const time = require('./utils/time');
 const log = require('./utils/log');
 const { waitForTimeout } = require('./utils/time');
 const files = require('./utils/files' );
+const server = require('./docassemble/docassemble_api_interface');
+const wrapPromiseWithTimeout = require('./cucumber_8_shim');
 
 
 let ordinal_to_integer = {
@@ -55,6 +59,7 @@ let misc_artifacts_dir = `_alkiln_test-misc_artifacts`;
 
 module.exports = {
   trigger_not_needed_flag: `ALKiln: no trigger variable needed`,
+
   addToReport: async function( scope, { type, value }) {
     /* Add an item to a specific list in a scenario's report.
     * Create report if necessary.
@@ -189,6 +194,7 @@ module.exports = {
     let report = ``;
     for ( let line of data.lines ) {
       if ( line.type === `page_id` ) { report += `screen id: `; }
+      else if ( line.type === `outcome` ) { report += `\n`; }
       else if ( line.type === `warning` ) { report += `WARNING: `; }
       else if ( line.type === `error` ) { report += `\nERROR: ` }
       report += `${ line.value }\n`;
@@ -354,41 +360,54 @@ module.exports = {
     // This check might never be needed now as we try to match fields on the page
     // first in user-triggered cases - users used to be able to access this almost
     // directly, but they can't anymore. Our functions should know to only pass good things.
-    let msg = `Cannot find that element.`;
+    let msg = `Cannot find the element to tap.`;
     if ( !elem ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
 
     expect( elem, msg ).to.exist;
 
+    // Get the text on the button or link for a potential error message later
+    let tapperText = await (await elem.getProperty('textContent')).jsonValue();
+
     let start_url = await scope.page.url();  // so we can later check for navigation
 
-    let clickWait;
-    // Can't use elem[ scope.activate ](). It works locally, but errors on GitHub
-    // with "Node is not visible or not an HTMLElement". We're not using a custom Chromium version
-    // Unfortunately, this won't catch an invisible element. Hopefully we'd catch it before now...?
-    // "Tap" on mobile is more complex to implement ourselves.
-    // See https://stackoverflow.com/a/56547605/14144258
-    // and other convos around it. We haven't made it public that the device
-    // can customized. Until we do that, we'll just use "click" all the time.
-    if (!tabToWaitFor) {
-      // Click with no navigation will end immediately
-      clickWait = Promise.all([
-        elem.evaluate( (el) => { return el.click(); }),
-        scope.page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
-      ]);
-    } else {
-      // Same thing as above, but the promise doesn't wait for navigation.
-      clickWait = elem.evaluate( (el) => {return el.click(); });
+    // We'll wait for the click itself at the very least
+    let click_promises = [ elem.evaluate( (el) => { return el.click(); }) ];
+    
+    // If we're possibly navigating, wait for navigation as well
+    if ( !tabToWaitFor ) {
+      click_promises.push( scope.page.waitForNavigation({ waitUntil: 'domcontentloaded' }) );
     }
-    // Error loads page, so no need to detect to keep things short
-    let winner = await Promise.race([
-      clickWait,
-      // This is meant to detect user-visible alerts/errors,
-      // not breaking errors in the testing code.
-      scope.page.waitForSelector('.alert-danger', { visible: true }),
-      scope.page.waitForSelector('.da-has-error', { visible: true }),
-    ])
-
-    // TODO: Not sure how to detect navigation landing at same page.
+    let clickWait = Promise.all( click_promises );
+
+    let winner = null;
+
+    // TODO: implement and use scope.handle_possible_timeout()
+    try {
+      // Error loads page, so no need to detect to keep things short
+      // Also, puppeteer will ensure proper timeout.
+      winner = await Promise.race([
+        clickWait,
+        // This is meant to detect user-visible alerts/errors,
+        // not breaking errors in the testing code.
+        scope.page.waitForSelector('.alert-danger', { visible: true }),
+        scope.page.waitForSelector('.da-has-error', { visible: true }),
+      ]);
+    } catch ( error ) {
+
+      if ( error.name === `TimeoutError` ) {
+        let non_reload_report_msg = `ALKiln tapped "${ tapperText }", but the interview took to long to finish.`;
+        await scope.handle_page_timeout_error( scope, { non_reload_report_msg, error });
+      } else {
+        // Throw any non-timeout error
+        let err_msg = `Error occurred when ALKiln tried to tap "${ tapperText }".`
+        scope.addToReport( scope, { type: `error`, value: err_msg });
+        throw error;
+      }  // ends if error is timeout error
+
+    }  // ends try/catch
+
+    // TODO: Not sure how to detect navigation landing at same page, such as
+    // with a user input validation error. Does that count as navigating?
     // Maybe url change + trigger var change? Maybe just trigger var?
     let end_url = await scope.page.url();
     let navigated = start_url !== end_url;
@@ -411,6 +430,156 @@ module.exports = {
     return winner;
   },  // Ends scope.tapElement()
 
+  // Handle server reload errors
+  server_statuses: [],
+  server_check_interval_ms: 1 * 1000,
+  stop_tracking_server_status: false,
+  track_server_status: async function( scope ) {
+    /** Updates server_statuses list by checking if server is responding until,
+    *    eventually, it is told to stop. */
+    let server_check_start_time = Date.now();
+
+    while ( !scope.stop_tracking_server_status ) {
+      // This code assumes a reasonable response time would be n seconds if the
+      // server is up and that a server reload/restart won't take less than n seconds.
+      // Also, it's non-blocking, so it doesn't slow down tests
+      let is_up = await server.is_server_responding({ timeout: scope.server_check_interval_ms });
+      // Add status to the beginning of the list to make truncating easier
+      scope.server_statuses.unshift( is_up );
+
+      // Ensure we wait longer if a full second hasn't yet passed
+      let ms_passed = Date.now() - server_check_start_time;
+      // Use Math.max to ensure no negative numbers
+      let ms_remaining = Math.max( 0, scope.server_check_interval_ms - ms_passed );
+      await time.waitForTimeout( ms_remaining );
+      // Prepare for next check
+      server_check_start_time = Date.now()
+
+      // To make it easier to check past server statuses, remove defunct server statuses
+      let max_length = Math.round( scope.timeout/scope.server_check_interval_ms );
+      // Trying to extract more items than the actual length is ok
+      scope.server_statuses = scope.server_statuses.slice( 0, max_length );
+    }  // ends while !scope.stop_tracking_server_status
+    
+  },  // Ends scope.track_server_status()
+
+  did_server_reload: async function( scope ) {
+    return scope.server_statuses.includes( false );
+  },  // Ends scope.did_server_reload()
+
+  // handle_possible_timeout: async function( scope, {
+  //   promise: ,
+  //   non_timeout_msg: ,
+  //   normal_timeout_msg: ,
+  //   actual_error: ,
+  // }) {},  // Ends scope.handle_possible_timeout()
+
+  handle_page_timeout_error: async function( scope, { non_reload_report_msg, error } ) {
+    /* For a page timeout error, handles server reload vs. other timeout errors
+    
+    @param options.non_reload_report_msg { str } Non-reload message to add to
+        the report as an error.
+    @param options.error { object | str } Error to throw. It can be the actual
+        error object or a string that will show up as a message in the error.
+    */
+    // If the server was reloading during that time, wait for the server to
+    // respond again so the next test has a better chance of passing. Then
+    // throw an error. The command-line script will re-try the Scenario after.
+    let server_reloaded_during_interval = await scope.did_server_reload( scope );
+    if ( server_reloaded_during_interval ) {
+      // Wait for the server to reload just to make sure the next test
+      // doesn't also fail because of this same server reload.
+      await scope.get_server_reload_promise( scope );
+    } else {
+      // Otherwise just throw the error
+      await scope.addToReport( scope, {
+        type: `error`,
+        value: non_reload_report_msg });
+      throw error;
+    }
+  },  // Ends scope.handle_page_timeout_error()
+
+  get_server_reload_promise: async function( scope ) {
+    /** If the promise already exists in state, return it because it can
+    *    be used anywhere with `await`. Otherwise, make the promise, store
+    *    it in state, and return that.
+    */
+    if ( scope.server_reload_promise !== null ) {
+      // Return the existing promise of the func that will check on reloading the server
+      return scope.server_reload_promise
+
+    } else {
+      // Create and return the promise of the func that will check on reloading the server
+      scope.server_reload_promise = scope.wait_for_server_response( scope );
+      return scope.server_reload_promise;
+    }
+  },  // Ends scope.get_server_reload_promise()
+
+  wait_for_server_response: async function( scope ) {
+    /** Wait for the server to respond using a multiple of scope.timeout
+    *    (or a custom timeout?) so the tests don't fail just because the
+    *    server isn't responding. Should this take an argument of an amount
+    *    of time to check or just assume we're using scope.timeout?
+    *
+    * This should only be called if the server failed to respond at some point.
+    * 
+    * This currently assumes we're either using scope.timeout as basis for
+    * the amount of time in which to detect a finished reload or that
+    * there's a test input that defines a different timeout.
+    */
+    
+    let ms_till_server_timeout;
+    if ( session_vars.get_server_reload_timeout() !== null ) {
+      // Should we require the expected value to be seconds instead of ms?
+      ms_till_server_timeout = parseInt( session_vars.get_server_reload_timeout() );
+    } else {
+      // Default server timeout will always be based on scope.timeout even if it changes
+      ms_till_server_timeout = 5 * scope.timeout;
+    }
+
+    let throw_after_server_reloads = async function () {
+
+      // Continue waiting until server has responded or until it's taken too long
+      let time_accumulator = 0;
+      let max = ms_till_server_timeout/scope.server_check_interval_ms
+
+      while ( scope.server_statuses[0] !== true && time_accumulator < max ) {
+        await time.waitForTimeout( scope.server_check_interval_ms );
+        time_accumulator += 1;
+      }
+
+      // If the server hasn't responded yet even now, let the developer know
+      if ( time_accumulator >= max ) {
+        let timeout_message = `The server took longer than `
+          + `${ Math.round( ms_till_server_timeout/1000 ) } seconds to respond. `
+          + `If the server was just reloading and needed more time, try setting the `
+          + `"SERVER_RELOAD_TIMEOUT_SECONDS" GitHub secret to a longer amount of time.`
+        await scope.addToReport( scope, { type: `error`, value: timeout_message });
+      }
+
+      // Once server has responded, throw an error to end the test. After the first
+      // failure, the whole Scenario should retry because of command line flag. Hopefully
+      // it'll get through the next time. We considered trying to redo the input on the
+      // page instead of re-doing the whole test, but that wouldn't work - we don't
+      // know how many Steps to back to do that and we can't redo Steps anyway.
+      await scope.throw_server_was_reloading_error( scope )
+    };
+
+    await throw_after_server_reloads();
+
+  },  // Ends scope.wait_for_server_response()
+
+  throw_server_was_reloading_error: async function( scope ) {//, { server_timeout_id, timeout_message } ) {
+    /* Throw the server reload error with appropriate side effects. */
+    let reload_failure_msg = `The test was unable to continue because the `
+      + `server was reloading. ALKiln will try this Scenario a total of 2 times. An `
+      + `error will still be printed for this attempt.`;
+    await scope.addToReport( scope, { type: `error`, value: reload_failure_msg });
+    // await scope.addToReport( scope, { type: `error`, value: timeout_message });
+    // clearTimeout( server_timeout_id );
+    throw( reload_failure_msg );
+  },  // Ends scope.throw_server_was_reloading_error()
+
   detectDownloadComplete: async function detectDownloadComplete(scope, endTime) {
     /* Resolve if a download flag has changed. Timeout after a bit less than
     *    the global permitted timeout
@@ -488,7 +657,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. */
@@ -500,7 +669,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}`); 
@@ -565,18 +752,36 @@ module.exports = {
     /* Try to load the page. Should we also pass a `timeout` arg or just
     *    use scope.timeout? */
 
-    // If there is no browser open, start a new one
-    if (!scope.browser) {
-      scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug(), devtools: session_vars.get_debug() });
-    }
-    if ( !scope.page ) { scope.page = await scope.browser.newPage(); }
-
     if ( !file_name.includes('.yml') ) { file_name = `${ file_name }.yml` }
     let base_url = await get_base_interview_url();
     let interview_url = `${ base_url }${ file_name }`;
     if ( session_vars.get_debug() ) { console.log( interview_url ); }
 
-    await scope.page.goto(interview_url, { waitUntil: 'domcontentloaded', timeout: scope.timeout })
+    if ( !scope.page ) { scope.page = await scope.browser.newPage(); }
+
+    // TODO: implement and use scope.handle_possible_timeout()
+    try {
+
+      await scope.page.goto(interview_url, { waitUntil: 'domcontentloaded', timeout: scope.timeout })
+
+    } catch ( error ) {
+
+      if ( error.name === `TimeoutError` ) {
+
+        let non_reload_report_msg = `Timeout error occurred when ALKiln tried to go to the interview url "${ interview_url }".`;
+        await scope.handle_page_timeout_error( scope, { non_reload_report_msg, error });
+
+      } else {
+
+        // Throw any non-timeout error
+        scope.addToReport( scope, {
+          type: `error`,
+          value: `Error occurred when ALKiln tried to go to the interview url "${ interview_url }".`
+        });
+        throw( error );
+      }  // ends if error is timeout error
+
+    }  // ends try/catch
 
     let load_result = await scope.getLoadData( scope );
     // Errors, or reaching timeout, causes an exception and is shown to the developer at the end
@@ -597,6 +802,9 @@ module.exports = {
     let result = { error: ``, elem: null };
 
     let winner = await Promise.race([
+      // Signature page
+      scope.page.waitForSelector( `#dasigpage`, { timeout: scope.timeout }),
+      // Any other valid page
       scope.page.waitForSelector( `#daMainQuestion`, { timeout: scope.timeout }),
       scope.page.waitForSelector( `#da-retry`, { timeout: scope.timeout }),
     ]);
@@ -606,10 +814,14 @@ module.exports = {
     let error_id_elem = await scope.page.$( `#da-retry` );
     if ( error_id_elem ) {
       let error_elem = await scope.page.$( `blockquote` );
-      let error_handle = await error_elem.getProperty( `textContent` );
-      let system_error_text = await error_handle.jsonValue();
+      if (error_elem !== null) {
+        let error_handle = await error_elem.getProperty( `textContent` );
+        let system_error_text = await error_handle.jsonValue();
 
-      result.error = system_error_text;
+        result.error = system_error_text;
+      } else {
+        result.error = "Docassemble ran into an error on the page, but ALKiln does not know what the error is. If a screenshot was taken, check the screenshot";
+      }
     }
 
     return result;
@@ -630,9 +842,40 @@ module.exports = {
     }
   },  // Ends scope.setLanguage()
 
-  normalizeTable: async function ( scope, { var_data, from_story_table=true }) {
-    /* Return data derived from cucumber variable-setting data.
-     * Table must have headers. Arrays are not supported. */
+  normalizeTable: async function ( scope, { var_data=null, raw_var_data=null }) {
+    /* Return data derived from cucumber variable-setting data, from either an object format
+     * (var_data) or an array format (raw_var_data). `var_data` only is used when calling
+     * normalizeTable internally.
+     */
+
+    if (!var_data && ! raw_var_data) {
+      let no_data_msg = `ALKiln Internal error: normalizeTable called w/o var_data or raw_var_data:` +
+          ` open an issue at https://github.com/SuffolkLITLab/ALKiln/issues/new if you see this!`;
+      await scope.addToReport( scope, { type: `error`, value: no_data_msg });
+      throw Error(no_data_msg);
+    }
+
+    // Always use the raw var data if present; it has the full first row
+    if (raw_var_data) {
+      var_data = raw_var_data.hashes();
+      if (!('var' in var_data[0]) || !('value' in var_data[0])) {
+        let raw_array = raw_var_data.raw();
+        var_data = [];
+        for (let row_raw of raw_array) {
+          if (row_raw.length < 2) {
+            let bad_table_msg = `Your Story Table definition needs to be changed. The best practice`
+                + ` is to make your table 3 columns wide with a first row in this format: "| var | value | trigger |".`
+                + ` The first row of your table is actually "${ raw_array[0] }"`;
+            await scope.addToReport( scope, { type: `error`, value: bad_table_msg})
+            throw Error(bad_table_msg);
+          } else if (row_raw.length == 2) {
+            var_data.push({var: row_raw[0], value: row_raw[1]});
+          } else {
+            var_data.push({var: row_raw[0], value: row_raw[1], trigger: row_raw[2]});
+          }
+        }
+      }
+    }
 
     // Support tables with no 'trigger' column
     let supported_table = [];
@@ -967,6 +1210,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()
 
@@ -1233,13 +1479,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
@@ -1260,15 +1500,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.
@@ -1287,28 +1551,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 ];
@@ -1321,55 +1609,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'); });
@@ -1378,51 +1687,63 @@ 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;
+    },
 
-  uploadFiles: async function ( scope, { handle, set_to }) {
-    /* Try to upload one or more files to a file-type input field. */
+  },  // ends scope.enter_answer
+
+  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.
+    */
     
     // Tests could be in one of two places. Figure out which directory they're in
     // Makes an absolute path from the directory in which `npm run` was used plus our internal folders
@@ -1454,7 +1775,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 = [];
@@ -1476,8 +1797,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`); });
@@ -1502,20 +1823,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)
   },
@@ -1562,7 +1883,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, {
@@ -1691,7 +2012,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 );
       }
@@ -1837,6 +2159,20 @@ module.exports = {
     }
   },  // Ends scope.getThereIsAnotherValue()
 
+  // throw_if_no_interview_content()?
+  has_interview_content: async function ( scope ) {
+    /** Return false if ther's no element indicating a da interview question,
+    *    like a signature page, other fields, or interview text. Assumes that page has already
+    *    finished navigating. */
+    let elem_da_question = await scope.page.$( `#daMainQuestion` );
+    let elem_da_signature = await scope.page.$( `#dasigpage` );
+    if ( elem_da_question === null && elem_da_signature === null ) {
+      return false;
+    } else {
+      return true;
+    }
+  },  // Ends scope.has_interview_content()
+
   waitUntilContinued: async function ( scope, { url = '', id = '' }) {
     /** Given a url, attempt to continue until the page url changes or an error
         is found. Return the error object no matter what. */
@@ -1960,18 +2296,20 @@ module.exports = {
       let actual_url = await prop_obj.jsonValue();
 
       let linkPage = await scope.browser.newPage();
+      // This should not check for a server reload timeout error - it could be going anywhere.
       let response = await linkPage.goto( actual_url, { waitUntil: 'domcontentloaded' });
 
       let msg = `The "${ linkText }" link is broken.`;
       if ( !response.ok() ) { await scope.addToReport( scope, { type: `error`, value: msg }); }
       expect( response.ok(), msg ).to.be.true;
 
+      // This may cause problems if the linked page is the interview page
       linkPage.close()
 
       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
@@ -1982,23 +2320,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,
@@ -2014,7 +2352,7 @@ module.exports = {
       if ( !link ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
       expect( link, msg ).to.exist;
 
-      await link.evaluate( elem => { return elem.click(); });
+      await scope.tapElement( scope, link );
 
       await scope.afterStep(scope, {waitForShowIf: true});
     },  // Ends tap_term()
@@ -2042,6 +2380,7 @@ module.exports = {
       expect( elem, msg ).to.exist;
 
       scope.toDownload = filename;
+      // Should this be using `scope.tapElement()`?
       await elem.evaluate( elem => { return elem.click(); });
       await scope.detectDownloadComplete( scope );
     },  // Ends download()
@@ -2134,8 +2473,26 @@ module.exports = {
 
       // Go to the sign in page
       let login_url = `${ session_vars.get_da_server_url() }/user/sign-in`;
-      await scope.page.goto( login_url, { waitUntil: `domcontentloaded`, timeout: scope.timeout })
-      await scope.page.waitForSelector( `.dabody` );
+      
+      // TODO: implement and use scope.handle_possible_timeout()
+      try {
+        // puppeteer will ensure proper timeout.
+        await scope.page.goto( login_url, { waitUntil: `domcontentloaded`, timeout: scope.timeout });
+        await scope.page.waitForSelector( `.dabody` );
+
+      } catch ( error ) {
+
+        let err_msg = `Error occurred when ALKiln tried to go to "${ login_url }".`
+        if ( error.name === `TimeoutError` ) {
+          let non_reload_report_msg = `It took too long to load "${ login_url }"`;
+          await scope.handle_page_timeout_error( scope, { non_reload_report_msg, error });
+        } else {
+          // Throw any non-timeout error
+          scope.addToReport( scope, { type: `error`, value: err_msg });
+          throw error;
+        }  // ends if error is timeout error
+
+      }  // ends try/catch
 
       let email = process.env[ email_secret_name ];
       let password = process.env[ password_secret_name ];
@@ -2151,13 +2508,15 @@ module.exports = {
       if ( password === undefined ) {
         await scope.addToReport( scope, { type: `error`, value: password_msg })
       }
+
       expect( email, email_msg ).to.not.equal( undefined );
       expect( password, password_msg ).to.not.equal( undefined );
 
       // Try to log in
       await scope.page.type( `#email`, email );
       await scope.page.type( `#password`, password );
-      await scope.page.$eval( `button[name="submit"]`, (elem) => { return elem.click(); });
+      let elem = await scope.page.$( `button[name="submit"]` );
+      await scope.tapElement( scope, elem );
 
       // Wait to see the success message.
       // This is a bit of an assumption and needs success and failure testing
@@ -2170,10 +2529,234 @@ 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 tests 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()
+
 
   //#####################################
   //#####################################