@suffolklitlab/alkiln 4.0.0-pre-api.7 → 4.0.0

package/CHANGELOG.md

@@ -38,12 +38,12 @@ Format:
 ### Security
 - 
 -->
-<!--2022-02-11 -->
+<!-- ## [Unreleased] -->
 
-## [Unreleased]
+## [4.0.0] - 2022-03-30
 ### Added
-- Add action.yml that runs most of what users' workflows run now, along with notes for a new user workflow that will take less maintainance. See #420. We need to add documentation on how to write a workflow file as it currently is if they want to take back control. Setup interview has not yet been updated with this workflow.
-- Add package.json creation/overwriting to action.yml. Simplify package.json.
+- BREAKING: Add package.json creation/overwriting to action.yml. Simplify package.json.
+- BREAKING: Add action.yml that runs most of what users' workflows run now, along with notes for a new user workflow that will take less maintainance. See #420. We need to add documentation on how to write a workflow file as it currently is if they want to take back control. Setup interview has not yet been updated with this workflow.
 - Step: `the text in the JSON variable "variable_with_text_value" should be`. Compare JSON variable with a text value to given text. See #470. Does not accept nested values, e.g. "child.name.first". Downloads all the JSON vars to a .json file in the "downloads" artifacts.
 - Step to log the page's JSON variables and values in the report. Future goal: save to file. See #454.
 - Step to log into the developer's docassemble server account using GitHub SECRETs. See #499.
@@ -51,12 +51,13 @@ Format:
 - Add control of alkiln npm version to the action.yml
 
 ### Changed
-- Update to v13 of puppeteer
-- Update to v7 of cucumber
-- Update action.yml node to v17
-- Use alkiln v4 package.json we create during the test run in `action.yml` (as discussed in #489)
+- BREAKING: NPM package is now suffolklitlab scoped package. Refer to @suffolklitlab/alkiln from now on.
+- BREAKING: Update to v13 of puppeteer
+- BREAKING: Update to v7 of cucumber
+- BREAKING: Update action.yml node to v17
+- BREAKING: Use alkiln v4 package.json we create during the test run in `action.yml` (as discussed in #489)
+- BREAKING: Use API key to access da server, create projects, pull code, delete projects, and check for server restart.
 - Remove and ignore package-lock.json so that our tests will behave more like our users' tests
-- Use API key to access da server, create projects, pull code, delete projects, and check for server restart.
 - Add warning in steps.js for name input with too many parts. Add test in reports.
 - fix typo in the report
 - Throw an error for uploading nonexistent file, changed to error instead of warning in reports. 
@@ -67,10 +68,63 @@ Format:
 - Peer dependencies and dev dependencies. Now `cucumber` is just a dependency. See https://github.com/SuffolkLITLab/ALKiln/issues/396 for discussion. Setup interview has not been updated to remove dependencies.
 
 ### Fixed
+- Proxy var story table row matches for any page containing the given variable name when there's only one row for the relevant variable. #464.
 - Fixed interview name not allowing url parameters. #449
 - Freeze colors npm package to before bug in both package.json and action.yml
 - Fix invalid project name allowed.
 - fix typo in the report.
+- session_vars branch path regex not removing start of branch path
+
+## [3.2.1] - 2022-02-09
+### Fixed
+- Typo in report that was messing up copy/paste of test table
+
+## [3.2.0] - 2022-02-09
+### Added
+- Add Step to log into server account using GitHub SECRETs (environment variables). See #499.
+
+## [3.1.11] - 2022-02-02
+### Changed
+- Handle an Assembly Line name Step value that has too many names, including a warning for the developer. Include the first three names and the last name to try to catch suffixes.
+
+## [3.0.11] - 2022-01-25
+### Added
+- Step: `the text in the JSON variable "variable_with_text_value" should be`. Compare JSON variable with a text value to given text. See #470. Does not accept nested values, e.g. "child.name.first". Downloads all the JSON vars to a .json file in the "downloads" artifacts.
+
+## [3.0.10] - 2022-01-24
+### Added
+- Step to log the page's JSON variables and values in the report. Future goal: save to file. See #454.
+
+## [3.0.9] - 2022-01-10
+### Security
+- Install the security fix in the action's package.json as well. Because dependents have to require cucumber itself, if they're not using our action (if they have their own package.json), they're going to have to implement this fix in their repo too. That's why our fix isn't working. We'll start the process of helping developers update. We also need to deprecate all previous versions of ALKiln. See #489.
+
+## [3.0.8] - 2022-01-10
+### Security
+- Fully publish the security fix in v3.0.7
+
+## [3.0.7] - 2022-01-10
+### Security
+- Pinned colors library to 1.4.0. See https://www.bleepingcomputer.com/news/security/dev-corrupts-npm-libs-colors-and-faker-breaking-thousands-of-apps/. We don't use faker, so we don't need to handle that.
+
+## [3.0.6] - 2022-01-07
+### Changed
+- See #371
+- Scenario heading tags are now on a second line
+- Artifact filenames use dashes more and are created separately from Scenario headings
+- Scenario ids are separated from filenames and Scenario headings
+
+## [3.0.5] - 2022-01-06
+### Added
+- Add action.yml that runs most of what users' workflows run now, along with notes for a new user workflow that will take less maintainance. See #420. We need to add documentation on how to write a workflow file as it currently is if they want to take back control. Setup interview has not yet been updated with this workflow.
+- Add package.json creation/overwriting to action.yml. Simplify package.json.
+
+<!-- ## [3.0.1-peer-deps.1] - 2021-12-07 -->
+### Removed
+- Peer dependencies and dev dependencies. Now `cucumber` is just a dependency. See https://github.com/SuffolkLITLab/ALKiln/issues/396 for discussion. Setup interview has not been updated to remove dependencies.
+
+### Fixed
+- Fixed interview name not allowing url parameters. #449
 
 ## [3.0.4] - 2021-12-11
 ### Fixed

package/README.md

@@ -1,5 +1,13 @@
-# docassemble-cucumber
-Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.
+# ALKiln
+Integrated automated end-to-end testing with docassemble, puppeteer, cucumber, and chai.
+
+Works well with https://github.com/suffolklitlab/docassemble-AssemblyLine but isn't
+dependent on it.
+
+Formerly named "docassemble-cucumber"
+
+## Documentation
+Read about how to use this framework at https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing/.
 
 ## Integration tests
 To setup for the integration tests, create the project on the server:

package/action.yml

@@ -32,6 +32,7 @@ inputs:
 runs:
   using: "composite"
   steps:
+    
     # Set environment variables
     - name: "ALKiln: Set environment variables"
       # If extra languages were set manually, override the repository
@@ -54,15 +55,19 @@ runs:
         echo "DOCASSEMBLE_DEVELOPER_API_KEY=${{ inputs.DOCASSEMBLE_DEVELOPER_API_KEY }}" >> $GITHUB_ENV
         echo "ALKILN_VERSION=${{ inputs.ALKILN_VERSION }}" >> $GITHUB_ENV
       shell: bash
+    - name: "ALKiln: confirm info"
+      run: echo -e "\nRepo is $REPO_URL\nBranch ref is $BRANCH_PATH\nManually added languages are $EXTRA_LANGUAGES\nAll other data is secret\n"
+      shell: bash
+
     # This doesn't use an already established package-lock.json and that
     # comes with some types of test breaking risks. Same problem as before.
-    - name: Overwrite or create package.json
+    - name: Temporarily overwrite or create package.json
       run: |
         cat << EOF > "package.json"
         {
           "scripts": {
             "test": "npm run langs_setup && npm run cucumber -- $@",
-            "cucumber_base": "./node_modules/.bin/cucumber-js --require ./node_modules/.bin/alkiln-cucumber",
+            "cucumber_base": "./node_modules/.bin/cucumber-js --require ./node_modules/@suffolklitlab/alkiln/lib/index.js",
             "cucumber": "run_cucumber(){ npm run cucumber_base -- \"$@\" docassemble/*/data/sources/*.feature; }; run_cucumber",
             "langs": "npm run langs_setup && ./node_modules/.bin/cucumber-js --require ./node_modules/.bin/alkiln-cucumber docassemble/*/data/sources/*_lang*.feature",
             "langs_setup": "node_modules/.bin/alkiln-langs 'docassemble/*/data/sources/*.feature'",
@@ -76,11 +81,8 @@ runs:
           }
         }
       shell: bash
-    - name: "ALKiln: confirm info"
-      run: echo -e "\nRepo is $REPO_URL\nBranch ref is $BRANCH_PATH\nManually added languages are $EXTRA_LANGUAGES\nAll other data is secret\n"
-      shell: bash
 
-    # Install node after package.json is created
+    # Install node
     - name: "ALKiln: Install node packages"
       uses: actions/setup-node@v1
       with:

package/lib/docassemble/docassemble_api_interface.js

@@ -124,7 +124,8 @@ da_i.get_dev_id = async function ( dev_id_options ) {
 
   // Default timeouts
   let { timeout } = dev_id_options ||  { timeout: 75 * 1000 };
-  return await _da_REST.get_dev_id( timeout );
+  let response = await _da_REST.get_dev_id( timeout );
+  return response.data.id;
 };  // Ends da_i.get_dev_id();
 
 

package/lib/docassemble/get_base_interview_url.js

@@ -0,0 +1,19 @@
+let session_vars = require(`../utils/session_vars`);
+let docassemble_api_interface = require('./docassemble_api_interface');
+
+let get_base_interview_url = async function () {
+  /** Return the part of the interview URL that comes before the filename.
+  *    Depends on the project name, which may get changed.
+  *    This also needs to ensure that variable values from previous tests aren't used.
+  *    That's not completely possible, but our tests try to do this in several ways.
+  *    This function uses `new_session=1` to try to ensure old session vars aren't used.
+  *    When finishing a test, we go to the sign out page (which is supposed to help even
+  *    when the user is not logged in.) We can't use `reset=2` because it caused an
+  *    'Unable to locate interview session' error. */
+  let server_url = session_vars.get_da_server_url();
+  let dev_id = await docassemble_api_interface.get_dev_id();
+  let project_name = session_vars.get_project_name();
+  return `${ server_url }/interview?new_session=1&i=docassemble.playground${ dev_id }${ project_name }%3A`;
+};
+
+module.exports = get_base_interview_url;

package/lib/index.js

@@ -1,4 +1,2 @@
-#!/usr/bin/env node
-
 require('./world');
 require('./steps.js');

package/lib/scope.js

@@ -5,8 +5,8 @@ const fs = require('fs');
 const safe_filename = require("sanitize-filename");
 
 // Ours
-const env_vars = require('./utils/env_vars');
 const session_vars = require('./utils/session_vars');
+const get_base_interview_url = require(`./docassemble/get_base_interview_url`);
 const time = require('./utils/time');
 
 
@@ -25,13 +25,14 @@ let escape_regex = function( to_escape ) {
 let proxies_regex = /(\bx\.)|(\bx\[)|(\[[ijklmn]\])/g;
 
 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.
     * 
     * The report has a key for each scenario and each of those
     * keys should correspond to a list containing the relevant data. */
-    if ( env_vars.DEBUG ) { console.log(`Report:\ntype: ${ type }, value: ${ value }`) }
+    if ( session_vars.get_debug() ) { console.log(`Report:\ntype: ${ type }, value: ${ value }`) }
     let scenario = await scope.makeSureReportPartsExist( scope );
     scenario.lines.push({ type, value });
 
@@ -70,6 +71,10 @@ module.exports = {
     let var_str = await scope.toTrimmedJSON( scope, { str: original.var });
     let value_str = await scope.toTrimmedJSON( scope, { str: original.value });
     let trigger_str = await scope.toTrimmedJSON( scope, { str: original.trigger });
+    if ( trigger_str === scope.trigger_not_needed_flag ) {
+      // This text was added by ALKiln itself. It's not part of the user's data
+      trigger_str = ``;
+    }
     return `${ ' '.repeat(6) }| ${ var_str } | ${ value_str } | ${ trigger_str } |`;
   },  // Ends scope.convertToOriginalStoryTableRows()
 
@@ -84,7 +89,7 @@ module.exports = {
     /** Return printable heading based on Scenario name and tags.
     *    Allow characters from other languages.
     */
-    if ( env_vars.DEBUG ) { console.log( scenario.pickle.name ); }
+    if ( session_vars.get_debug() ) { console.log( scenario.pickle.name ); }
 
     // Collect all tag names
     let tag_names = [];
@@ -397,13 +402,14 @@ module.exports = {
 
     // If there is no browser open, start a new one
     if (!scope.browser) {
-      scope.browser = await scope.driver.launch({ headless: !env_vars.DEBUG });
+      scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug() });
     }
     if ( !scope.page ) { scope.page = await scope.browser.newPage(); }
 
     if ( !file_name.includes('.yml') ) { file_name = `${ file_name }.yml` }
-    let interview_url = `${ env_vars.getBaseInterviewURL() }${ file_name }`;
-    if ( env_vars.DEBUG ) { console.log( interview_url ); }
+    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 })
 
@@ -481,7 +487,7 @@ module.exports = {
       supported_table.push( result );
     }
 
-    if ( env_vars.DEBUG ) { console.log( 'scope.normalizedTable():\n', JSON.stringify( supported_table )); }
+    if ( session_vars.get_debug() ) { console.log( 'scope.normalizedTable():\n', JSON.stringify( supported_table )); }
 
     return supported_table;
   },  // Ends scope.normalizeTable()
@@ -506,7 +512,7 @@ module.exports = {
     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.
-      await scope.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. Talk to the folks at the AssemblyLine project to learn more or see an example here: https://github.com/plocket/docassemble-ALAutomatedTestingTests/blob/ad1232049d7ca7a9b97b22f8ca3915dd3dae8114/docassemble/ALAutomatedTestingTests/data/questions/all_tests.yml#L6-L10.` });
+      await scope.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 = await scope.toBase64( scope, { utf8_str: `None` });
     }
     let trigger = await scope.fromBase64( scope, { base64_str: encoded_trigger_var });
@@ -598,7 +604,7 @@ module.exports = {
       fields.push( field_data );
     }  // ends for every node
 
-    if ( env_vars.DEBUG ) { console.log( `page fields:\n${ JSON.stringify( fields )}`); }
+    if ( session_vars.get_debug() ) { console.log( `page fields:\n${ JSON.stringify( fields )}`); }
     return fields;
   },  // Ends scope.getAllFields()
 
@@ -828,6 +834,8 @@ module.exports = {
     /* 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
     * 
     * @param var_data {arr} - fields and the values they can be set to
     * @param var_data[n].var {str} - name of variable to set
@@ -840,24 +848,26 @@ module.exports = {
     * @param field[n].tag {str} - HTML tag of node
     * @param field[n].type {str} - HTML type of node if it has one
     * @param field[n].guesses {arr} - arr of objects that could
-    *    possibly match a table row
+    *    possibly match a table row's `var` column
     * @param field[n].guesses[n].var {str} - name of variable
     * @param field[n].guesses[n].value {str} - value of a choice
     * @param <field[n].guesses[n].trigger> {str} - var name that triggered this page
     * 
     * @returns [ var_data[n] ]
     */
-    let matches = [];
-    let uses_proxies = false;
 
-    // There are mutliple guesses because field names are encoded
+    let rows_that_match_field_names = [];
+    let uses_proxies = false;  // See "proxies" notes further down
+    let trigger_might_be_needed = true;
+
+    // There are mutliple guesses because field names are sometimes encoded
     for ( let guess of field.guesses ) {
-      for ( let var_datum of var_data ) {
-        let row_matches = false;
+      for ( let table_row of var_data ) {
+        let this_row_matches_this_field = false;
 
         // If the dev uses single instead of double quotes, etc, allow that
-        let names_match = await scope.matchNeutralizedQuotes( scope, { value1: guess.var, value2: var_datum.var });
-        let values_match = await scope.matchNeutralizedQuotes( scope, { value1: guess.value, value2: var_datum.value });
+        let names_match = await scope.matchNeutralizedQuotes( scope, { value1: guess.var, value2: table_row.var });
+        let values_match = await scope.matchNeutralizedQuotes( scope, { value1: guess.value, value2: table_row.value });
 
         // Check different things for different fields. An input box won't
         // be expected to have the same value as the var you want to set while
@@ -865,91 +875,152 @@ module.exports = {
         switch ( field.tag ) {
           case 'button':
           case 'select':
-            if ( names_match && values_match ) { row_matches = true; }
+            if ( names_match && values_match ) { this_row_matches_this_field = true; }
             break;
 
           case 'canvas':
           case 'textarea':
           case 'a':
-            if ( names_match ) { row_matches = true; }
+            if ( names_match ) { this_row_matches_this_field = true; }
             break;
 
           case 'input':
             if ( field.type === 'radio' ) {
-              if ( names_match && values_match ) { row_matches = true; }
+              if ( names_match && values_match ) { this_row_matches_this_field = true; }
             } else {  // Some kind of text input
-              if ( names_match ) { row_matches = true; }
+              if ( names_match ) { this_row_matches_this_field = true; }
             }
             break;
         }
 
-        if ( row_matches ) {
-          matches.push( var_datum );  // Collect all matches to start with.
-          if ( !uses_proxies ) {  // If this gets set to `true` once, leave it alone
-            // x, i, j, etc. See notes below about the reasoning
-            // AVOID `.test()` - it advances through a string each time you call it on the
-            // string, so you can have unexpected results.
-            uses_proxies = guess.var.match( proxies_regex );  // 
+        if ( this_row_matches_this_field ) {
+          rows_that_match_field_names.push( table_row );
+          // Check this until the value is set to `true` (if it ever is)
+          // If the field uses proxy variables - x, i, j, etc, flag it. See "proxies" note.
+          uses_proxies = uses_proxies || guess.var.match( proxies_regex );
+
+          if ( table_row.trigger === scope.trigger_not_needed_flag ) {
+            trigger_might_be_needed = false;
           }
-          continue;
-        }
+        } // end if this_row_matches_this_field
 
       }  // ends for each table row
     }  // ends for each field row possibility
 
-    // Some fields will have multiple matches from the story table.
-    // The only reason we would care about multiple story table row
-    // matches is if there is a possible proxy var conflict.
-    // When a dev has a loop with an index var or generic object,
-    // the same variable name will be used over and over, e.g. `users[i]`.
-    // That's what will be in the story table, so there will be multiple
-    // matches for a field setting `users[i]`. For this program to
-    // know which table row to use on which page, we need the one unique var that
-    // will appear on the page - the trigger var. When a row with `users[i]`
-    // has a trigger var that matches the page trigger var, the
-    // program knows to use that row to set the value for that page.
-
-    // If needed, only get the matches that also match the trigger var
-    // For now, we're being flexible about it - if we don't think we
-    // need that trigger var, we don't prevent data getting through.
-    // e.g. If an interview has a list of `users`, but they only set
-    // data for `users[0]`, there's no need to check the trigger var.
-    // That way devs with simple cases can ignore the trigger var column.
-
-    // If field uses proxies and there has been more than one match
-    // we now use the trigger var to narrow down the matches.
-    if ( uses_proxies && matches.length > 1 ) {
-      // Multiple matches means this came from a story
-
-      // Feedback for devs - we need the trigger var but we don't have it (field data)
-      // TODO: Add docs and link to docs on how to add the trigger var
-      if ( field.trigger === undefined ) { await scope.addToReport(scope, { type: `warning`, value: `A field on this page uses an index variable or a generic object, but the page does not contain an element with the trigger variable's name. Tell the developer to add an element to the page with the id "trigger"` }); }
-
-      let original_matches = matches;
-      matches = [];
-      for ( let match of original_matches ) {
-        // Feedback for devs - we need the trigger var but we don't have it (var data)
-        if ( match.trigger === undefined ) { await scope.addToReport(scope, { type: `warning`, value: `A field on this page uses an index variable or a generic object. The test gave story data for setting the field, but that data is missing the trigger. Add a trigger variable to the story table \`trigger\` column. For now, the test may end up ignoring this field. The row's data is\n${ JSON.stringify( match.original )}.\nThe field's data is\n${ JSON.stringify( field )}` }); }
-          // TODO: Add a warning if they're both `undefined`?
-        else {
-
-          let triggers_match = await scope.matchNeutralizedQuotes( scope, { value1: field.trigger, value2: match.trigger });
+    // Proxies:
+    // When a dev has a loop with an index var or generic object, the
+    // same variable name will be used over and over, e.g.`users[i].name.first`.
+    // In a regular Step, there's no ambiguity about the value to set.
+    // In a dev's story table, though, there could be multiple rows that match
+    // a field named `users[i]`. For kiln to know which row to use on which
+    // page, we need the one unique HTML string that will appear on the page -
+    // the trigger var name. When a row with `users[i]` has a "trigger" column
+    // value that matches the page HTML's trigger var name, kiln will know to
+    // use the value from that row. We need to find the matching row.
+    let final_matching_rows = [];
+    if ( trigger_might_be_needed && uses_proxies && rows_that_match_field_names.length > 0 ) {
+
+      let rows_that_also_match_trigger_name = [];
+      let rows_without_a_trigger_name = [];
+      let rows_with_conflicting_trigger_names = [];
+
+      let page_trigger_name = field.trigger;
+
+      // 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.`;
+        await scope.addToReport(scope, { type: `warning`, value: page_trigger_warning });
+      }
+
+      for ( let row_that_matches_this_field of rows_that_match_field_names ) {
+
+        let table_row_trigger_name = row_that_matches_this_field.trigger;
+
+        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.
+
+          // First, make the row data more readable to humans.
+          let row_as_story_table = await scope.convertToOriginalStoryTableRow( scope, { row_data: row_that_matches_this_field });
+          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 )}`;
+          await scope.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 });
           if ( triggers_match ) {
-            matches.push( match );
+            rows_that_also_match_trigger_name.push( row_that_matches_this_field );
+          } else {
+            rows_with_conflicting_trigger_names.push( row_that_matches_this_field );
           }
         }
+      }  // ends for each row_that_matches_this_field
+
+      // Be very permissive, based on feedback. See https://github.com/SuffolkLITLab/ALKiln/issues/464#issuecomment-1005166616
+      if ( rows_that_also_match_trigger_name.length > 0 ) {
+        final_matching_rows = rows_that_also_match_trigger_name;
+      } else {
+        final_matching_rows = rows_without_a_trigger_name;
       }
-      // Feedback for devs - we are missing the matching triggers we need
-      if ( matches.length === 0 ) { await scope.addToReport(scope, { type: `warning`, value: `A field on this page uses an index variable or a generic object. The test gave multiple matches for the story data for the field, but none match the trigger variable. Is the story table missing a row? For now, the test will have to ignore this field. The rows' data is\n${ JSON.stringify( original_matches )}.\nThe field's data is\n${ JSON.stringify( field )}` }); }
-    }
 
-    // Dev may have accidentally included a row more than once. Give them feedback
-    if ( matches.length > 1 ) {
-      await scope.addToReport(scope, { type: `warning`, value: `there are multiple story data matches for this field. The story table data that appears last will be used. The field's data is\n${JSON.stringify( field )}` });
+      // Warn the user if all matching rows had trigger names that conflicted.
+      // Missing trigger names don't count as conflicting.
+      if ( final_matching_rows.length === 0 ) {
+
+        // First, make the row data more readable to humans.
+        let conflicts_as_story_table_rows = [];
+        for ( let row of rows_with_conflicting_trigger_names ) {
+          let table_str = await scope.convertToOriginalStoryTableRow( scope, { row_data: row });
+          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` )}`
+          + `\nThis field's data:\n${ JSON.stringify( field )}`;
+        await scope.addToReport(scope, {
+          type: `warning`,
+          value: all_trigger_names_conflict_msg
+        });
+      }
+
+    } else {
+      // These should be used if NO trigger name was needed
+      final_matching_rows = rows_that_match_field_names;
+    }  // ends if need trigger name to match
+
+    // Dev may have accidentally included a row more than once.
+    if ( final_matching_rows.length > 1 ) {
+
+      // First, make the row data more readable to humans.
+      let rows_as_story_table = [];
+      for ( let row of final_matching_rows ) {
+        let table_str = await scope.convertToOriginalStoryTableRow( scope, { row_data: row });
+        rows_as_story_table.push( table_str );
+      }
+
+      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`) }`
+        + `\nThis field's data:\n${ JSON.stringify( field )}`;
+      await scope.addToReport(scope, { type: `warning`, value: multiple_matches_msg });
     }
 
-    if ( env_vars.DEBUG ) { console.log( `matches:\n`, JSON.stringify( matches )); }
-    return matches;
+    if ( session_vars.get_debug() ) { console.log( `final_matching_rows:\n`, JSON.stringify( final_matching_rows )); }
+    return final_matching_rows;
   },  // Ends scope.getMatchingRows()
 
 
@@ -963,7 +1034,6 @@ module.exports = {
     return val_2_str.match( val_1_regex );
   },  // Ends scope.matchNeutralizedQuotes()
 
-
   setVariable: async function ( scope, { field, var_data }) {
     /* Returns true if the field was set.
     *
@@ -1004,7 +1074,7 @@ module.exports = {
     // If field is disabled, don't set it yet
     if ( disabled ) { return row_used; }
 
-    if ( env_vars.DEBUG ) {
+    if ( session_vars.get_debug() ) {
       let name = await handle.evaluate(( elem ) => {  // Not using this right now
         try { elem.nextSibling.style.background = 'Khaki'; }
         catch(err){ elem.style.background = 'Khaki'; }
@@ -1066,7 +1136,7 @@ module.exports = {
       for ( let field_i = 0; field_i < fields.length; field_i++ ) {
         let field = fields[ field_i ];
 
-        if ( env_vars.DEBUG ) {
+        if ( session_vars.get_debug() ) {
           await field.evaluate( elem => { elem.style.background = `Khaki`; });
         }
 
@@ -1130,7 +1200,7 @@ module.exports = {
 
         let [label] = await handle.$x(`following-sibling::label`);
         
-        if ( env_vars.DEBUG ) {
+        if ( session_vars.get_debug() ) {
           if ( set_to.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'); });
@@ -1179,7 +1249,7 @@ module.exports = {
     
     // 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
-    let dir_source = `${ process.cwd() }/docassemble/${ env_vars.REPO_URL.match(/docassemble-(.*)/)[1] }/data/sources`;
+    let dir_source = `${ process.cwd() }/docassemble/${ session_vars.get_repo_url().match(/docassemble-(.*)/)[1] }/data/sources`;
     let dir_features = `${ process.cwd() }/tests/features`;
     let dir = null;
 
@@ -1334,7 +1404,7 @@ module.exports = {
     * @param ensure_all_vars_used {bool} [false] = Default false. If true, errors if any
     *     object in var_data is not used during running of this function.
     */
-    if ( env_vars.DEBUG ) { console.log( `~~~~~~~~~~~~~~ scope.setFields() ~~~~~~~~~~~~~~` ); }
+    if ( session_vars.get_debug() ) { console.log( `~~~~~~~~~~~~~~ scope.setFields() ~~~~~~~~~~~~~~` ); }
 
     // Only record the page id once for each page to which we navigate
     let { id } = await scope.examinePageID( scope, 'none to match' );
@@ -1621,7 +1691,7 @@ module.exports = {
       if ( possible_errors[ error_key ][0] ) {
         // If you're debugging and you close the window early, the process will still
         // take this long to exit after the tests finish. Not sure how to account for that.
-        if ( env_vars.DEBUG ) { await scope.page.waitForTimeout( 60 * 1000 ); }
+        if ( session_vars.get_debug() ) { await scope.page.waitForTimeout( 60 * 1000 ); }
         was_found = true;
         error_handlers[ error_key ] = possible_errors[ error_key ][0];
       }
@@ -1705,7 +1775,7 @@ module.exports = {
     },  // Ends link_works()
 
     set_regular_var: async ( scope, var_name, set_to ) => {
-      /** Set any variable (with or without a choice associated with it) to a value. Set:
+      /** Set a non-story table variable (with or without a choice associated with it) to a value. Set:
       *  - Buttons associated with variables
       *  - Dropdowns
       *  - Checkboxes (multiple choice checkboxes must be set to "true" or "false")
@@ -1713,11 +1783,12 @@ module.exports = {
       *  - Text inputs
       *  - Textareas
       */
+      // 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: '' }],
+        var_data: [{ var: var_name, value: set_to, trigger: scope.trigger_not_needed_flag }],
       });
-      // Don't continue if the variable doesn't navigate and if this variable
-      // cannot be seton this page, trigger an error
+      // 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()