@suffolklitlab/alkiln 5.8.1 → 5.9.0

package/lib/scope.js

@@ -292,6 +292,9 @@ module.exports = {
     if ( !elem ) { reports.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();
+
     click_promise = click_promise || elem.click();
     
     // TODO: implement and use scope.handle_possible_timeout()
@@ -308,14 +311,11 @@ module.exports = {
     } catch ( error ) {
 
       if ( error.name === `TimeoutError` ) {
-        let non_reload_report_msg = `ALKiln tapped "${ tapperText }", but the interview took to long to finish.`;
+        let non_reload_report_msg = `After ALKiln tapped "${ tapperText }" it took too long to load the next page.`;
         await scope.handle_page_timeout_error( scope, { non_reload_report_msg, error });
       } else {
-
-        // Get the text on the button or link for a potential error message later
-        let tapperText = await (await elem.getProperty('textContent')).jsonValue();
         // Throw any non-timeout error
-        let err_msg = `Error occurred when ALKiln tried to tap "${ tapperText }".`
+        let err_msg = `An error occurred when ALKiln tried to tap "${ tapperText }".`
         reports.addToReport( scope, { type: `error`, value: err_msg });
         throw error;
       }  // ends if error is timeout error
@@ -464,9 +464,9 @@ module.exports = {
 
   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.`;
+    let reload_failure_msg = `The test was unable to continue because it `
+      + `took too long to reach the server. ALKiln will try this Scenario a total of `
+      + `2 times. A full error will be printed for the second attempt.`;
     reports.addToReport( scope, { type: `error`, value: reload_failure_msg });
     // reports.addToReport( scope, { type: `error`, value: timeout_message });
     // clearTimeout( server_timeout_id );
@@ -573,10 +573,7 @@ module.exports = {
       axe_path = await scope.getA11yPath( scope );
       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 }.`;
-      reports.addToReport( scope, {
-        type: `error`,
-        value: msg
-      });
+      reports.addToReport( scope, { type: `error`, value: msg });
     } else {
       reports.addToReport(scope, { type: `info`, value: `Accessibility on ${ scope.page_id } passed!`})
     }
@@ -730,7 +727,7 @@ module.exports = {
      * normalizeTable internally.
      */
 
-    if (!var_data && ! raw_var_data) {
+    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!`;
       reports.addToReport( scope, { type: `error`, value: no_data_msg });
@@ -739,39 +736,52 @@ module.exports = {
 
     // 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])) {
+      // If this table doesn't have headers
+      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] }"`;
+
+          // Wrong number of columns error
+          if (row_raw.length < 2 || row_raw.length > 3) {
+            let more_or_less = `more`;
+            if ( row_raw.length > 3 ) { more_or_less = `less`; }
+            let bad_table_msg = `Your Story Table should have ${ more_or_less } than`
+              + ` ${ row_raw.length } columns. Take another look at Story Table documentation at`
+              + ` https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#story-tables.`
             reports.addToReport( scope, { type: `error`, value: bad_table_msg})
             throw Error(bad_table_msg);
-          } else if (row_raw.length == 2) {
+          }
+
+          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]});
           }
-        }
-      }
-    }
+        }  // ends for every row in table
+      }  // ends if this table doesn't have headers
+
+    }  // ends if we have access to the full raw data
 
     // Support tables with no 'trigger' column
     let supported_table = [];
+
     for ( let row of var_data ) {
       // See tests > unit_tests > tables.fixtures.js > tables.old_to_current_formatting
       let actual_var_value = row.value;
       if (is_secret_var(row)) {
-        actual_var_value = process.env[row.flags.secret_name];
+        actual_var_value = process.env[ row.flags.secret_name ];
         if ( actual_var_value === undefined ) {
-          let not_in_env_msg = `The GitHub SECRET "${ row.flags.secret_name }" doesn't exist. Check for a typo and check your workflow file.`;
-          reports.addToReport( scope, { type: `error`, value: not_in_env_msg })
-          throw ReferenceError(`Could not find "${row.flags.secret_name }": ${not_in_env_msg}.`)
+          let not_in_env_msg = `ALKiln could not find the GitHub secret "${ row.flags.secret_name }".`
+            + ` Check for a typo and check your workflow file.`
+            + ` Read more about using GitHub secrets in your workflow file at`
+            + ` https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#github-secrets.`
+          reports.addToReport( scope, { type: `error`, value: not_in_env_msg });
+          throw ReferenceError(not_in_env_msg);
         }
-      }
+      }  // ends if is secret var
 
       let result = {
         // NOTE: mutating frozen objects will fail silently, so don't mutate this attribute
@@ -780,9 +790,9 @@ module.exports = {
         // Give fake data if needed to prevent some kind of hidden input field from being found
         // See bug at https://github.com/plocket/docassemble-cucumber/issues/79
         // May be able to remove this once converted to `getAllFields`
-        var: row.var || 'al_no_var_name',
+        var: row.var || `alkiln_no_var_name`,
         value: actual_var_value,
-        trigger: row.trigger || '',
+        trigger: row.trigger || ``,
         // This will track how many times total the row or its connected
         // artificial rows are used. Artificial rows are only added for some rows.
         times_used: 0,
@@ -791,11 +801,12 @@ module.exports = {
       result.used_for[ result.var ] = 0;
 
       supported_table.push( result );
-    }
+    }  // ends for every row
 
-    if ( session_vars.get_debug() ) { 
-      console.log( 'scope.normalizedTable():\n', JSON.stringify( supported_table )); 
-    }
+    log.debug({
+      type: `info`,
+      pre: `scope.normalizedTable():\n ${JSON.stringify( supported_table )}`
+    })
 
     return supported_table;
   },  // Ends scope.normalizeTable()
@@ -815,17 +826,22 @@ module.exports = {
     // This is the new trigger var element that developers will have to add to their interviews.
     // AssemblyLine will add it automatically unless someone overrides the values in their own interview.
     // See the report message to the dev below for a link to an example.
-    let trigger_elem = $( `#trigger` );
-    if ( !trigger_elem.length ) { trigger_elem = $( `#sought_variable` ); }  // Backwards compatibility
-    let encoded_trigger_var = $( trigger_elem ).data( `variable` );  // This should come out to 'None' at the very least
-    if ( !encoded_trigger_var ) {
-      // TODO: Add documentation and then link to it in this message.
-      reports.addToReport(scope, { type: `warning`, value: `You are missing an element containing the data for the page's trigger variable. Some fields, like loops with index variables, may not work correctly in these tests. See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#a-missing-trigger-variable.` });
-      encoded_trigger_var = toBase64( `None` );
-    }
+    let $trigger_elem = $( `#trigger` );
+    if ( !$trigger_elem.length ) { $trigger_elem = $( `#sought_variable` ); }  // Backwards compatibility
+    let encoded_trigger_var = $( $trigger_elem ).data( `variable` ) || ``;
     let trigger = fromBase64( encoded_trigger_var );
 
-    
+    let $proxies_node = $( `#alkiln_proxy_var_values` );
+    let proxies = {};
+    // If possible, get values of `x` and `i` that the dev put on the page
+    if ( $proxies_node.length ) {
+      // Empty strings are fine since that means that proxy is absent and won't come into play.
+      proxies.x = fromBase64( $proxies_node.data( `generic_object` ) );
+      for ( let index_var of `ijklmn`.split(``) ) {
+        proxies[index_var] = fromBase64( $proxies_node.data( `index_var_${ index_var }` ) );
+      }
+    }
+
     // Some `show if` fields have `names` like '_field_n' instead of their var name. Ex: _field_1
     let field_like_names = await scope.getFieldNamesDict( scope, { $: $ });
 
@@ -845,62 +861,62 @@ module.exports = {
       };
       if ( node.attribs.type ) { field_data.type = node.attribs.type; }
 
+      // Often used for the variable name
+      let not_decoded_name = $node.attr( `name` );
+
+      // `<input type="hidden" name="_save_as" value="c2lnbmF0dXJlXzE">`
       // canvas elements are the only field on a signature page
       if ( $(`#dasigpage`).length > 0 && $(`#dasigpage`)[0].name ) {
         field_data.selector = `#daquestion canvas`;
         field_data.tag = `canvas`;
-        field_data.guesses = [{
-          var: trigger,
-          value: '/sign',
-        }];
-        fields.push( field_data );
-        continue;
+        not_decoded_name = $( `input[name="_save_as"]` ).attr( `value` );
       }
       
       // The selector we'll use to set the DOM node's value later
-      field_data.selector = await scope.getFieldSelector( scope, { $, node });
+      if ( !field_data.selector ) {
+        field_data.selector = await scope.getFieldSelector( scope, { $, node });
+      }
 
-      // Often used in the variable name
-      let encoded_name = $node.attr( `name` );
       // Action buttons keep their var name in a unique place
+      // TODO: add examples of the hrefs
       if ( $( node ).hasClass( 'daquestionactionbutton' )) {
         let href = node.attribs.href;
         let match = href.match( /action=([^&]*)/ );
         if ( match ) {
-          encoded_name = match[1];
+          not_decoded_name = match[1];
         } else {
           // Some action buttons just use urls instead of da actions
-          // TODO: Does this `replace` need the `g` flag?
-          // TODO: This only replaces the chars at the start of the string. Is that intentional?
-          encoded_name = href.replace(/^[A-Za-z0-9]*/, '_');
+          // This means the first guess of the name should be the not_decoded_name
+          // TODO: This only replaces the chars at the start of the string. Is that
+          // intentional? Does this `.replace()` need the `g` flag?
+          not_decoded_name = href.replace(/^[A-Za-z0-9]*/, '_');
         }
       }
 
-      if ( !encoded_name ) {
+      if ( !not_decoded_name ) {
         // Some fields, like comboboxes, have a weird var name setup
-        encoded_name = $node.attr( `id` );
+        not_decoded_name = $node.attr( `id` );
       }
 
       // ====================
       // Table rows
       // ====================
-      // Default values
-      let var_names = await scope.getPossibleVarNames( scope, {
-        encoded: encoded_name,
-        field_like_names,
-        nota: false,  // none of the above (detected and overwritten later)
-      });
-      
+      // "None of the above" checkbox/object radio options don't contain their variable's name
+      let is_none_of_the_above = false;
       if ( $node.hasClass('danota-checkbox') || $node.parents(`.da-field-container-datatype-object_radio`).name ) {
-        // 'None of the above' fields must find var name info from siblings' attributes
+        is_none_of_the_above = true;
         let first_sib = $(node.parent).find( 'input' )[0];
-        var_names = await scope.getPossibleVarNames( scope, {
-          encoded: first_sib.attribs.name,
-          field_like_names,
-          nota: true,  // none of the above
-        });
+        not_decoded_name = first_sib.attribs.name;
+        // TODO: Do we need daaota as well? ("all of the above")
       }
 
+      let var_names = await scope.getPossibleDecodedNames( scope, {
+        not_decoded: not_decoded_name,
+        field_like_names,
+        is_none_of_the_above: is_none_of_the_above,
+        proxies,
+      });
+
       // button, radio, checkbox yesno, and maybe others need the value of the `value` attribute
       let values = [];
       if ( node.name === `select` ) {
@@ -926,8 +942,6 @@ module.exports = {
     return await scope.page.evaluate(async function ( elem ) {
       return await get_interview_variables();
     });
-
-    // return data;
   },  // Ends scope.getPageJSON()
 
   getFieldSelector: async function ( scope, { $, node }) {
@@ -978,10 +992,11 @@ module.exports = {
           // Ignore blanks, and values that certainly aren't base64 encoded like True and False
           // Modified from https://stackoverflow.com/a/8571649/11416267
           // DA doesn't use `==` to pad base 64
+          // TODO: How are 'None', 'True', and 'False' being handled?
           if (value !== 'None' && value !== 'True' && value !== 'False'
               && value.match(da_base64_regex)) {
             let value_decoded = fromBase64(value);
-            let values_decoded = scope.decodeFully( scope, {expr_str: value_decoded });
+            let values_decoded = scope.decodeFully( scope, { expr_str: value_decoded });
             for (let possible_val of values_decoded) {
               possible_table_rows.push({var: var_name, value: possible_val, });
             }
@@ -1008,12 +1023,20 @@ module.exports = {
     */
     if ( !$('input[name="_varnames"]')[0] ) { return {}; }
 
+    // TODO: Why are we docoding the field names here? We could decode them later, right?
+    // In `getPossibleDecodedNames` we could do:
+    // if ( field_like_original_names[ not_decoded ] ) {
+    //   still_encoded = field_like_names[ not_decoded ];
+    //   decode( still_encoded )
+    // }
+
     let field_like_names = {};
     let field_like_names_encoded = $('input[name="_varnames"]')[0].attribs.value;
     let field_like_names_str = fromBase64( field_like_names_encoded );
     let field_like_names_json = JSON.parse( field_like_names_str );
     for ( let field_like_key in field_like_names_json ) {
       let field_like_DOM_name = fromBase64( field_like_key );
+      // Even with `multiselect`, field names are only encoded once
       let field_like_var_name = fromBase64( field_like_names_json[ field_like_key ] );
       field_like_names[ field_like_DOM_name ] = field_like_var_name;
     }
@@ -1021,8 +1044,13 @@ module.exports = {
     return field_like_names;
   },  // Ends scope.getFieldNamesDict()
 
-  getPossibleVarNames: async function ( scope, { encoded, field_like_names, nota }) {
-    /* Given a base64 encoded string and a map of `_field_n` to var names, return
+  getPossibleDecodedNames: async function ( scope, {
+    not_decoded,
+    field_like_names={},
+    is_none_of_the_above=false,
+    proxies={}
+  }) {
+    /** Given a potentially base64 encoded string and a map of `_field_n` to var names, return
     * the decoded possible var names and, sometimes, values that the
     * encoded string could be. Only some node names actually use `_field_n`.
     * 
@@ -1040,41 +1068,69 @@ module.exports = {
     * TODO: We'll probably eventually have to search for `[B'encoded']` and such
     * iteratively to get all of them. Hasn't cropped up yet, though.
     *  
-    *  @param encoded {str} - base64 encoded string of the node
+    *  @param not_decoded {str} - potentially base64 encoded string from the node
     *  @param field_like_names {obj} - e.g. `{ _field_0: 'some_checkbox_var_name' }`
-    *  @param nota {bool} - is the field a 'none of the above' field? */
+    *  @param is_none_of_the_above {bool} - is the field a 'none of the above' field?
+    *  @param proxies {obj} - e.g. `{ x: str, i: str, j: str, ... n: str }`. Empty strings
+    *     are fine since that means that proxy is absent and won't come into play.
+    */
+
     // E.g. continue buttons that don't set a variable
-    if ( encoded === undefined ) { return []; }
+    if ( not_decoded === undefined ) { return []; }
+    // Not sure it's necessary to have both with and without proxies here
+    let guesses = scope.with_and_without_proxies( scope, {
+      var_name: `${ not_decoded }`,
+      proxies,
+    });
 
     // Names can be encoded multiple times, so start peeling the layers
-    let layer_1_decoded = fromBase64( encoded );
-    // If this is of the format `_field_n`, we need to get the actual matching var name.
-    if ( field_like_names[ layer_1_decoded ] ) {
-      layer_1_decoded = field_like_names[ layer_1_decoded ];
+    let decoded_once = fromBase64( not_decoded );
+    // If this is of the format `_field_n`, we need to get the actual matching var name
+    if ( field_like_names[ decoded_once ] ) {
+      decoded_once = field_like_names[ decoded_once ];
     }
 
     try {
-      let action_button_json = JSON.parse( layer_1_decoded );
-      if ( action_button_json.action ) { layer_1_decoded = action_button_json.action }
+      // We think this never has proxy vars
+      let action_button_json = JSON.parse( decoded_once );
+      if ( action_button_json.action ) { decoded_once = action_button_json.action }
     } catch ( error ) {
       // Things that are not action buttons can't be parsed this way.
       // A special error for action buttons requires passing the node in here too, which is a lot to pass in.
       // TODO: Should we move this back into `getAllFields()`?
     }
 
-    return scope.decodeFully(scope, { expr_str: layer_1_decoded, field_like_names, nota });
-  },  // Ends scope.getPossibleVarNames()
-
-  decodeFully: function ( scope, { expr_str, field_like_names = {}, nota} ) {
-    /*
+    // Include `not_decoded` since the name might not be encoded
+    // TODO: Should we try to replace proxies in `not_decoded`. I can't
+    // think of an occasion where that would be necessary.
+    guesses = guesses.concat( scope.decodeFully( scope, {
+        expr_str: decoded_once,
+        field_like_names,
+        is_none_of_the_above,
+        proxies
+      })
+    );
+
+    return guesses;
+  },  // Ends scope.getPossibleDecodedNames()
+
+  decodeFully: function ( scope, {
+    expr_str,
+    field_like_names = {},
+    is_none_of_the_above=false,
+    proxies={}
+  }) {
+    /**
     * Given a DA variable or value name, make sure it's fully decoded from base64.
-    *  @param variable_str {str} - a python variable string, potentially partially base64 encoded
+    *  @param expr_str {str} - a python variable string, potentially partially base64 encoded
     *    Some examples:
     *    - my_variable
     *    - checkboxes_choices[B'Y2hlY2tib3hfb3RoZXJfb3B0XzI']
     *    - foo[bar][B'Y2hlY2tib3hfb3RoZXJfb3B0XzI']
     *  @param field_like_names {obj} - e.g. `{ _field_0: 'some_checkbox_var_name' }`
-    *  @param nota {bool} - is the field a 'none of the above' field?
+    *  @param is_none_of_the_above {bool} - is the field a 'none of the above' field?
+    *  @param proxies {obj} - e.g. `{ x: str, i: str, j: str, ... n: str }`. Empty strings
+    *     are fine since that means that proxy is absent and won't come into play.
     */
     // Some fields have a key hidden inside them.
     // This gets the variable name before the final brackets, and the likely
@@ -1094,22 +1150,37 @@ module.exports = {
     if ( before_and_in_brackets ) {
       let key_or_name = before_and_in_brackets[1];
       // If this is of the format `_field_n`, we need to get the actual matching var name.
-      let var_name = field_like_names [ key_or_name ] || key_or_name;
+      let var_name = field_like_names[ key_or_name ] || key_or_name;
 
       let dictionary_key = before_and_in_brackets[2];
 
       // Our own marker for a 'none of the above' checkbox choice
-      if ( nota ) { 
-        possible.push( `${ var_name }['None']` ); 
+      if ( is_none_of_the_above ) {
+        // possible.push( `${ var_name }['None']` );
+        possible = possible.concat( scope.with_and_without_proxies( scope, {
+          var_name: `${ var_name }['None']`,
+          proxies,
+        }));
       } else {
+
+        // TODO: Just use try/catches?
+
         if (dictionary_key.match(da_base64_regex)) {
           // Get the choice name. E.g. option_1, option_2
           let dictionary_key_decoded = fromBase64( dictionary_key );
-          possible.push( `${ var_name }['${ dictionary_key_decoded }']` );
+          // possible.push( `${ var_name }['${ dictionary_key_decoded }']` );
+          possible = possible.concat( scope.with_and_without_proxies( scope, {
+            var_name: `${ var_name }['${ dictionary_key_decoded }']`,
+            proxies,
+          }));
           if (dictionary_key_decoded.match(da_base64_regex)) {
             try {
-              // The part inside `[B'encoded']` could need one more decoding.
-              possible.push(`${ var_name }['${ fromBase64( dictionary_key_decoded ) }']`);
+              // The part inside `[B|R|O'encoded']` could need one more decoding.
+              // possible.push(`${ var_name }['${ fromBase64( dictionary_key_decoded ) }']`);
+              possible = possible.concat( scope.with_and_without_proxies( scope, {
+                var_name: `${ var_name }['${ fromBase64( dictionary_key_decoded ) }']`,
+                proxies,
+              }));
             } catch ( err ) {}  // It wasn't double encoded. Do nothing.
           }
         }
@@ -1118,18 +1189,65 @@ module.exports = {
     // =====================
     // If bracket regex didn't match, just use var name
     } else {
-      possible.push(`${ expr_str }`);
+      possible = possible.concat( scope.with_and_without_proxies( scope, {
+        var_name: `${ expr_str }`,
+        proxies,
+      }) );
     }
     return possible;
   },
 
+  with_and_without_proxies: function ( scope, { var_name, proxies={} }) {
+    /** Given a variable or value's possible name and a map of values for
+     *    each proxy variable, return a list of either one or two strings.
+     *    It always includes the given variable name. If proxies were found
+     *    and replaced, the list also includes a version of the variable
+     *    name in which the proxies have been replaced by their values.
+     *
+     * Proxies are generic objects (x) or index variables (i, j, k, l, m, n).
+     *
+     * @param { string } var_name - The possible name of a variable or value
+     * @param { Object } proxies - A map of proxy variables to their values on
+     *    the HTML page, if they're there.
+     *
+     * @returns {Array<string>} - An array of at least one string - var_name
+     *    itself. Possibly a second value where proxy variables in var_name
+     *    are replaced with their values (if the proxy variables are present
+     *    and if their values are passed in).
+     * */
+    // We could combine these regexes, but this may be easier to read
+    let generic_obj_regex = /^(x)\b/;
+    let index_var_regex = /(?<=\[)([ijklmn])(?=\])/g;
+    // If proxies exist in the HTML, replace any proxies in the variables
+    // with those values.
+    let new_name = var_name;
+    if ( proxies.x !== '' && proxies.x !== undefined ) {
+      new_name = new_name.replace( generic_obj_regex, proxies.x );
+    }
+    new_name = new_name.replace( index_var_regex, function(match) {
+      if ( proxies[ match ] === '' || proxies[ match ] === undefined ) {
+        return match;
+      } else {
+        return proxies[ match ];
+      }
+    });
+
+    // The older versions of Story Table need to see "x", "i", etc.,
+    // so keep that old name around.
+    let unique_names = [ var_name ];
+    // If there were proxies, add the new version of the name
+    if ( new_name !== var_name ) { unique_names.push( new_name ); }
+
+    return unique_names;
+  },  // Ends scope.with_and_without_proxies()
+
   getOptionValues: async function ( scope, { $select }) {
     /* Returns all the option node values of the select node. */
     let options = [];
     let option_nodes = $select.find( `option` );
     for ( let opt of option_nodes ) {
       options.push( opt.attribs.value );
-      // Dropdowns created w/ objects are base64 encoded; but it's handled in getPossibleTableRowMatches
+      // Dropdowns created w/ objects are base64 encoded; but it's handled in getPossibleTableRowMatchers
     }
     return options;
   },  // Ends scope.getOptionValues()
@@ -1137,11 +1255,11 @@ module.exports = {
 
   // TODO: Maybe add `from_story_table` to the var data table (array...)
   getMatchingRows: async function ( scope, { field, var_data }) {
-    /* Given var_data, a list of objects with variable data for
+    /** Given var_data, a list of objects with variable data for
     * setting fields, and an object for a DOM field, returns list of the
     * rows that match the DOM field. That list of story table rows may be empty.
     *
-    * For notes on trigger var, see https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger
+    * For notes on trigger var, see https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#trigger
     * 
     * @param var_data {arr} - fields and the values they can be set to
     * @param var_data[n].var {str} - name of variable to set
@@ -1205,6 +1323,7 @@ module.exports = {
           // If the field uses proxy variables - x, i, j, etc, flag it. See "proxies" note.
           uses_proxies = uses_proxies || guess.var.match( proxies_regex );
 
+          // TODO: can we just use `uses_proxies` in here?
           if ( table_row.trigger === scope.trigger_not_needed_flag ) {
             trigger_might_be_needed = false;
           }
@@ -1235,9 +1354,9 @@ module.exports = {
       // field/page trigger name is needed but is missing.
       if ( !page_trigger_name ) {
         let page_trigger_warning = `A field on this page uses an index `
-          + `variable or a generic object, but the page does not `
-          + `contain the trigger variable's name in its HTML. See `
-          + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#a-missing-trigger-variable.`;
+          + `variable or a generic object, but the page is missing `
+          + `the ALKiln "trigger" variable's name. See `
+          + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#a-missing-trigger-variable.`;
         reports.addToReport(scope, { type: `warning`, value: page_trigger_warning });
       }
 
@@ -1247,18 +1366,18 @@ module.exports = {
 
         if ( !table_row_trigger_name ) {
           // var/row trigger name is (probably) needed but is missing. Caveat: If there's
-          // only one page in the proxy var loop and there's only one row, trigger name is
-          // not needed, but I'm not sure how we figure out all those things here and log
-          // a useful message.
+          // only one page in the proxy var loop and there's only one row (like the "I set the var"
+          // Step), trigger name is not needed, but I'm not sure how we figure out all those
+          // things here and log a useful message.
 
           // First, make the row data more readable to humans.
           let row_as_story_table = reports.convertToOriginalStoryTableRow( scope, { row_data: row_that_matches_this_field });
-          let row_trigger_warning = `This story table row needs a value in the "trigger" `
+          let row_trigger_warning = `This Story Table row needs a value in the "trigger" `
             + `column, but it is empty. The test might get unexpected results. See `
-            + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger.`
-            + `\nThe row's data:\n${ row_as_story_table }`
-            + `\nThis field's data:\n${ JSON.stringify( field.guesses )}`;
+            + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#trigger.`
+            + `\nThe rows:\n${ row_as_story_table }`;
           reports.addToReport(scope, { type: `warning`, value: row_trigger_warning });
+
           rows_without_a_trigger_name.push( row_that_matches_this_field );
         } else {
           let triggers_match = await scope.matchNeutralizedQuotes( scope, { value1: page_trigger_name, value2: table_row_trigger_name });
@@ -1278,7 +1397,7 @@ module.exports = {
       }
 
       // Warn the user if all matching rows had trigger names that conflicted.
-      // Missing trigger names don't count as conflicting.
+      // Missing trigger names don't count as conflicting. [Did this mean missing in the table or in the page?]
       if ( final_matching_rows.length === 0 ) {
 
         // First, make the row data more readable to humans.
@@ -1288,12 +1407,12 @@ module.exports = {
           conflicts_as_story_table_rows.push( table_str );
         }
 
-        let all_trigger_names_conflict_msg = `Is this story table missing a row? `
-          + `${ rows_that_match_field_names.length } story table row(s) matched a field name, `
-          + `but none of their trigger variable name(s) matched the trigger variable `
-          + `name in the screen's HTML. The test will have to ignore this field. See `
-          + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger.`
-          + `\nThe data of row(s) with conflicting trigger name(s):\n${ conflicts_as_story_table_rows.join( `\n` )}`
+        let all_trigger_names_conflict_msg = `${ rows_that_match_field_names.length } `
+          + `Story Table row(s) matched a field name, but didn't match a trigger `
+          + `variable. The Story Table might be missng a row or a trigger variable. `
+          + `The test will have to ignore this field. See `
+          + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#trigger.`
+          + `\nThe row(s) data:\n${ conflicts_as_story_table_rows.join( `\n` )}`
           + `\nThis field's data:\n${ JSON.stringify( field )}`;
         reports.addToReport(scope, {
           type: `warning`,
@@ -1318,9 +1437,12 @@ module.exports = {
 
       let multiple_matches_msg = `Do you have a duplicate story table row? `
         + `Multiple story table rows match this field's variable name. `
-        + `The test will use the last row that matched. See `
-        + `https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/#trigger.`
-        + `\nThe matching rows:\n${ rows_as_story_table.join(`\n`) }`
+        + `The test will use the last row that matched.`
+
+      if ( trigger_might_be_needed ) {
+        multiple_matches_msg += ` See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/#trigger.`
+      }
+      multiple_matches_msg += `\nThe matching rows:\n${ rows_as_story_table.join(`\n`) }`
         + `\nThis field's data:\n${ JSON.stringify( field )}`;
       reports.addToReport(scope, { type: `warning`, value: multiple_matches_msg });
     }
@@ -1374,7 +1496,9 @@ module.exports = {
     let disabled = await handle.evaluate(( elem )=> {
       // da's header covers the top of the section containing the fields which means
       // sometimes it blocks nodes from clicks. Scroll item to the bottom instead.
-      if ( !elem.disabled ) { elem.scrollIntoView(false); }
+      // Note: I'm not sure how we'd get in here if `elem` didn't exist, but
+      // I once got an error here that I couldn't read `.disabled` of `null`.
+      if ( elem && !elem.disabled ) { elem.scrollIntoView(false); }
       return elem.disabled;
     });
 
@@ -1982,24 +2106,21 @@ module.exports = {
 
     // If all table rows must be used and any table row was not, error
     if ( ensure_all_vars_used ) {
-      let num_unused_rows = 0;
       for ( let row of var_data ) {
         if ( row.times_used === 0 ) {
-          num_unused_rows += 1;
+          let values_used_status = 'The page is missing a value';
           let source_row = row;
           // TODO: Make the row object flatter so we don't need to dig in this way
           if ( row.source ) { source_row = row.source; }
           let original_row = source_row.original;
-          let msg = `Did not find a field on this page for the variable "${ original_row.var }" that could be set to "${ original_row.value }"`;
-          reports.addToReport(scope, { type: `warning`, value: msg });
+          let { id } = await scope.examinePageID( scope, 'none to match' );
+          let msg = `In a linear Step all the values you give MUST be filled in, but ALKiln was unable `
+            + `to find a field on the page "${id}" for the variable "${ original_row.var }" that `
+            + `could be set to "${ original_row.value }". See this Scenario's HTML file for details.`;
+          reports.addToReport(scope, { type: `error`, value: msg });
+          expect( values_used_status, msg ).to.equal( '' );
         }
       }
-      if ( num_unused_rows > 0 ) {
-        let { id } = await scope.examinePageID( scope, 'none to match' );
-        let msg = `Error on page "${id}". See screenshot and see text above for more details.`;
-        reports.addToReport(scope, { type: `error`, value: msg });
-        expect( num_unused_rows, msg ).to.equal( 0 );
-      }
     }
 
     // If didn't already press a continue button, press one now.
@@ -2191,7 +2312,7 @@ module.exports = {
             value: 'The attribute `.there_is_another` is invalid in story table tests. Replace it with '
               + '`.target_number` in your `var` and `trigger` columns. Set the `value` to the number of items in '
               + `that list. This test will now set this row's \`value\` to \`False\`. See `
-              + `https://suffolklitlab.github.io/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing#there_is_another. `
+              + `https://suffolklitlab.github.io/docassemble-AssemblyLine-documentation/docs/alkiln#there_is_another. `
               + `The row data is\n${ JSON.stringify( var_datum.original )}` });
       }  // ends if it's a `target_number` row
     }  // ends for each row
@@ -2221,7 +2342,7 @@ module.exports = {
     } else if ( value.match( /(true|yes|checked|check|selected|select)/i )) {
       if ( from_story_table && !row.artificial ) {
         if ( row.var.match( /\.there_is_another$/ ) ) {
-          reports.addToReport( scope, { type: `warning`, value: `The attribute \`.there_is_another\` is invalid in story table tests. Replace it with \`.target_number\` in your \`var\` column. Set the \`value\` to the number of items in that list. This test will now set this row's \`value\` to \`False\`. See https://suffolklitlab.github.io/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing#there_is_another-loop. The row data is\n${ JSON.stringify( row.original )}` });
+          reports.addToReport( scope, { type: `warning`, value: `The attribute \`.there_is_another\` is invalid in story table tests. Replace it with \`.target_number\` in your \`var\` column. Set the \`value\` to the number of items in that list. This test will now set this row's \`value\` to \`False\`. See https://suffolklitlab.github.io/docassemble-AssemblyLine-documentation/docs/alkiln#there_is_another-loop. The row data is\n${ JSON.stringify( row.original )}` });
         } else {
           // If `target_number` is set to True instead of a number
           reports.addToReport( scope, { type: `warning`, value: `${ val_to_print } value is not a valid value for ${ row.var } here. This test will default to \`False\` to avoid problems.` });
@@ -2583,6 +2704,7 @@ module.exports = {
       *       1. Four words - a first, middle, last, and suffix (ex: "Tal Tay Taylor III")
       *
       * The string 'the var'/'the variable' part of the step is optional, as you can see below.
+      * This is a linear step, so no trigger var is needed.
       */
       let name_patterns = [
         [ `text` ],
@@ -2628,6 +2750,7 @@ module.exports = {
       *
       * The string 'the var'/'the variable' part of the step is optional,
       *    as you can see below.
+      * This is a linear step only, so it doesn't need to have a trigger var.
       */
       
       // Get all the parts of the address properly separated