@suffolklitlab/alkiln 5.17.0 → 5.17.1

package/lib/steps.js

@@ -383,7 +383,7 @@ When(/I? ?gets? to ?.*?(".*").*?with.*?(?:this data:)?/i, {timeout: -1}, async (
 
       // Set up the timeout that avoids infinite loops
       let on_page_timeout = async function() {
-
+        // Will throw
         let non_reload_report_msg = `The target id or ids were ${ target_ids }, but it took `
         + `too long to try to reach a valid id (over ${ scope.timeout/1000/60 } min). The `
         + `test got stuck on "${ id }".`
@@ -418,10 +418,13 @@ When(/I? ?gets? to ?.*?(".*").*?with.*?(?:this data:)?/i, {timeout: -1}, async (
 
           // THIS FUNCTION ACTUALLY MATTERS
           // Some errors happen in there to be closer to the relevant code. We'd have to try/catch anyway.
-          let error = await scope.setFields(scope, { var_data: ensured_var_data, id, ensure_navigation: true });
+          let error_data = await scope.setFields(scope, { var_data: ensured_var_data, id, ensure_navigation: true });
 
-          // Discuss: use Log class to throw this error?
-          if ( error.was_found ) { await scope.throwPageError( scope, { id: id }); }
+          // Story Table assumes we require navigation while other Steps don't.
+          // Throw here in case something sneaks through.
+          if ( error_data?.was_found ) { await scope.throw_system_error( scope, {
+            error_handlers: error_data.handlers, id: id
+          }); }
           resolve();
         } catch ( err ) {
           let err_msg = `ALKiln ran into an error when it tried to answer fields on the page with the question id "${ id }". The text above might have more information.`
@@ -498,12 +501,9 @@ When(/I wait ?(?:for)? (\d*\.?\d+) seconds?/, { timeout: -1 }, async ( seconds )
   * - I wait 1 second
   * - I wait .5 seconds
   *
-  * Questions:
-  * - Should this really reset the 'navigated' flag? Should the below
-  *     return succeed or fail? e.g:
-  *     I tap to continue; I wait 10 seconds; I arrive at the next page;
-  *     Maybe the 'navigated' flag should only be reset just before trying to
-  *     navigate (after pressing a button)
+  * Discuss: Should this reset the 'navigated' flag? Maybe the 'navigated' flag
+  *     should only be reset just before trying to navigate (after pressing a
+  *     button.)
   */
   return wrapPromiseWithTimeout(
     scope.afterStep(scope, {waitForTimeout: (parseFloat( seconds ) * 1000)}),
@@ -627,39 +627,45 @@ Then('an element should have the id {string}', async ( id ) => {  // √
 
 // This phrase is confusing. It sounds like it's going to at least try to continue.
 Then(/I (don't|can't|don’t|can’t|cannot|do not) continue/, async (unused) => {  // √
-  /* Tests for detection of url change from button or link tap.
-  *    Can other things trigger navigation? Re: other inputs things
-  *    like 'Enter' acting like a click is a test for docassemble */
-  let msg = `The page should have stopped the user from continuing, but the user was able to continue.`;
-  if ( scope.navigated ) { reports.addToReport(scope, { type: `error`, code: `ALK0075`, value: msg }); }
-  expect( scope.navigated, msg ).to.be.false;
+  /** Press to continue. Succeeds when navigation then fails. */
+
+  // Must catch "failure to navigate"-type error.
+  // TODO: Explore using .continue + .checkForError (see "invalid answer" Step)
+  try {
+    let error_data = await scope.setFields( scope, { var_data: [], ensure_navigation: true });
+    // TODO: Add test for excluding AL..075 msg when Step succeeds
+    if ( scope.navigated ) {
+      let report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0075`,
+        value: `The page should have stopped the user from continuing, but the user was able to continue.`
+      });
+      expect( scope.navigated, report_msg ).to.be.false;
+    }
+
+  } catch ( continue_attempt_error ) {
+    // Discuss: Too deeply coupled? Alternatives?
+    if ( !continue_attempt_error.message?.includes(`ALK0148`) ) {
+      throw continue_attempt_error;
+    }
+  }
 
   await scope.afterStep(scope);
 });
 
 Then('I will be told an answer is invalid', async () => {  // √
 
-  let { was_found, error_handlers } = await scope.checkForError( scope );
+  let { ok, type, error_handlers } = await scope.checkForError( scope );
 
-  let no_error_msg = `No error message was found on the page`;
-  if ( !was_found ) { reports.addToReport(scope, { type: `error`, code: `ALK0076`, value: no_error_msg }); }
-  expect( was_found, no_error_msg ).to.be.true;
+  let report_msg = null;
+  if ( ok ) { report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0076`, value: `Sorry, you expected at least one invalid answer, but all answers were valid` }); }
+  expect( ok, report_msg ).to.be.false;
 
-  let was_user_error = error_handlers.complex_user_error !== undefined || error_handlers.simple_user_error !== undefined;
-  let not_user_error_msg = `The error was a system error, not an invalid user answer. Check for the picture of the page's error if the Step did not use any secret variables.`;
-  if ( !was_user_error ) { reports.addToReport(scope, { type: `error`, code: `ALK0077`, value: not_user_error_msg }); }
-  expect( was_user_error, not_user_error_msg ).to.be.true;
-
-  await scope.afterStep(scope);
-});
+  if ( type !== `user` ) {
+    report_msg = reports.addToReport(scope, { type: `error`, code: `ALK0077`,
+      value: `The error was a system error, not an invalid user answer. Check for the picture of the page's error if the Step did not use any secret variables.`
+    });
+  }
+  expect( type, report_msg ).to.equal( `user` );
 
-Then('I arrive at the next page', async () => {  // √
-  /* Tests for detection of url change from button or link tap.
-  *    Can other things trigger navigation? Re: other inputs things
-  *    like 'Enter' acting like a click is a test for docassemble */
-  let msg = `User did not arrive at the next page.`
-  if ( !scope.navigated ) { reports.addToReport(scope, { type: `error`, code: `ALK0078`, value: msg }); }
-  expect( scope.navigated, msg ).to.be.true;
   await scope.afterStep(scope);
 });
 

package/lib/utils/Log.js

@@ -284,8 +284,9 @@ class Log {
    *
    * @param { Object } console_opts - Required. Metadata and functional flags
    *     and data.
-   * @param { "success"|"info"|"warn"|"error" } console_opts.level - Required.
-   *     The log level. Functional and metadata. Defined by the internal caller.
+   * @param { "success"|"info"|"warn"|"error"|"throw" } console_opts.level -
+   *     Required. The log level. Functional and metadata. Defined by the
+   *     internal caller.
    * @param { string } console_opts.before - Optional. Text to add before the
    *     metadata of the log. Metadata. Default "".
    * @param { string } console_opts.icon - Required. Unicode char put at the
@@ -426,9 +427,9 @@ class Log {
      *
      * @param { Object } console_opts - Required. Metadata and functional flags
      *     and data.
-     * @param { "success"|"info"|"warn"|"error" } console_opts.level - Required.
-     *     The log level. Functional and metadata. Defined by the internal
-     *     caller.
+     * @param { "success"|"info"|"warn"|"error"|"throw" } console_opts.level -
+     *     Required. The log level. Functional and metadata. Defined by the
+     *     internal caller.
      * @param { string } console_opts.before - Optional. Text to add before the
      *     metadata of the log. Metadata. Default "".
      * @param { string } console_opts.icon - Required. Unicode char put at the
@@ -459,6 +460,7 @@ class Log {
      *
      * @example
      * log.debug()
+     * // In debug_log.txt, not in the console:
      * // 🐛 ALK000d DEBUG [2024-08-16 00:38:49UTC]:
      * */
 
@@ -809,7 +811,7 @@ class Log {
      * @returns { string } Formatted metadata and logs.
      *
      * @example
-     * log.warn({
+     * log.success({
      *   before: "~~~",
      *   code: "ALK00d3",
      *   context: "demo",
@@ -843,7 +845,7 @@ class Log {
      * @returns { string } Formatted metadata and logs.
      *
      * @example
-     * log.warn({
+     * log.info({
      *   before: "~~~",
      *   code: "ALK00d4",
      *   context: "demo",
@@ -910,7 +912,7 @@ class Log {
      * @returns { string } Formatted metadata, logs, and, if given, the error.
      *
      * @example
-     * log.warn({
+     * log.error({
      *   before: "~~~",
      *   code: "ALK00d5",
      *   context: "demo",

package/lib/utils/session_vars.js

@@ -90,6 +90,9 @@ session_vars.get_max_tests_per_template_scenario = function() {
 }
 
 session_vars.get_da_server_url = function () {
+  /** 
+   * @returns { string } - the server url. Example: https://awesome_law.example
+   * */
   try {
     let url = process.env.SERVER_URL || process.env.BASE_URL;
     return url.replace(/\/$/g, '');  // Remove any trailing slash for safety
@@ -99,7 +102,10 @@ session_vars.get_da_server_url = function () {
 };
 
 session_vars.get_branch_name = function () {
-  /* Get the name of the repository's branch that is being tested */
+  /**
+   * @returns {string} - the name of the branch that is being tested. Example:
+   *   the_branch
+   * */
   let branch_name = null;
   if ( process.env.BRANCH_PATH ) {
       branch_name = process.env.BRANCH_PATH.replace( `refs/heads/`, '' );
@@ -110,13 +116,21 @@ session_vars.get_branch_name = function () {
 };
 
 session_vars.get_package_name = function () {
-  /* Make an un-incremented project name based on the repo name and branch name. */
+  /**
+   * @returns {string} - an un-incremented package name based on the repo
+   *   name. Example: ThePackage
+   * 
+   * */
   let repo_url_without_trailing_slash = session_vars.get_repo_url().replace(/\/$/, '');
   let repo_name_parts = repo_url_without_trailing_slash.split('/');
   return repo_name_parts[ repo_name_parts.length - 1 ];
 };
 
 session_vars.get_project_base_name = function () {
+  /**
+   * @returns {string} - a valid docassemble Playground Project name, without
+   *   any attempt to make it unique. Example: ALKilnTestThePackagethebranch
+   * */
   let name = `ALKilnTest${ session_vars.get_package_name() }${ session_vars.get_branch_name() }`;
   let sanitized_name = name.replace( /[^A-Za-z0-9]/g, '' );
   return sanitized_name;
@@ -139,12 +153,15 @@ session_vars.get_languages = function () {
 
 const project_name_key = `da_project_name`;
 session_vars.save_project_name = function ( project_name ) {
-  /* Saves the name of the project to a json obj so deletion can use it later.
-  *    Built for local as well as remote testing. Assumes a kosher string.
-  *    We avoided a list because of concerns over getting out of date.
-  *    Should we try to prevent someone overwriting a previous project name?
-  * 
-  * @param project_name { string } - purely alphanumeric string */
+  /**
+   * Saves the name of the project to a json obj so deletion can use it later.
+   *   Built for local as well as remote testing. Assumes a kosher string.
+   *   We avoided a list because of concerns over getting out of date.
+   *   Should we try to prevent someone overwriting a previous project name?
+   * 
+   * @param project_name { string } - purely alphanumeric string
+   * @returns {Object} - node fs file
+   * */
   const runtime_config_path = session_vars.get_runtime_config_path();
 
   // Warn local developers if file already exists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.17.0",
+  "version": "5.17.1",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {

package/tests/log_codes/log_code_expected_instances.txt

@@ -10,6 +10,7 @@ Reasons for deletion:
 0173 - redundant
 0181 - unknown
 0223 - changed Log behavior ("Only logs that throw should give a value to `error`.")
+0078 - removed unsupported Step "I arrive at the next page" and moved responsibility to Steps that navigate
 
 ALK0000:0
 ALK0001:1
@@ -89,7 +90,7 @@ ALK0074:1
 ALK0075:1
 ALK0076:1
 ALK0077:1
-ALK0078:1
+ALK0078:0
 ALK0079:1
 ALK0080:1
 ALK0081:1
@@ -159,7 +160,7 @@ ALK0144:1
 ALK0145:1
 ALK0146:1
 ALK0147:1
-ALK0148:1
+ALK0148:2
 ALK0149:1
 ALK0150:1
 ALK0151:1
@@ -291,3 +292,12 @@ ALK0276:1
 ALK0277:1
 ALK0278:1
 ALK0279:1
+ALK0280:1
+ALK0281:1
+ALK0282:1
+ALK0283:1
+ALK0284:1
+ALK0285:1
+ALK0286:1
+ALK0287:1
+ALK0288:1

package/tests/unit_tests/constrained_random_answers/valid.fixtures.js

@@ -573,7 +573,9 @@ Scenario: Keeps comment after table
   Given I start the interview at "file.yml"
   And ALKiln will get to "end" with:
     | var | possible_values |
-    | user_choice | correct;; wrong |
+    | choice_1 | correct;; wrong |
+    | choice_2 | a;; b;; c |
+    | choice_3 | 1;; 2;; 3 |
     # Comment 1 keep and repeat
 
 # Comment 2 keep and repeat`;

package/tests/unit_tests/fields.fixtures.js

@@ -3,6 +3,8 @@ let fields =  {};
 /** The fixtures in here are used in at least 2 types of tests:
  * - getAllFields
  * - getMatchignRows
+ * 
+ * ✏️ Fixtures are using HTML from docassemble versions <= 1.9.n
  * */
 
 // ============================
@@ -885,20 +887,22 @@ fields.proxy_substitution_i_is_1 = [
 // ============================
 // Signature
 // ============================
-// Signature page continue buttons are contained in a different DOM structure than regular ones
-// Also, there's an additional hidden continue button on the page with similar selectors
+// Signature page continue buttons are contained in a different DOM structure
+//   than other pages. Also, there's an additional continue button on the page
+//   with similar selectors. One continue button is hidden on wide screens while
+//   the other is hidden on narrow screens.
 fields.signature = [
   {
-    "selector": "#daquestion canvas",
+    "selector": "#daquestion canvas[id=\"dasigcanvas\"]",
     "tag": "canvas",
     "guesses": [
       {
-        "var": "c2lnbmF0dXJlXzE",
-        "value": ""
+        "value": "",
+        "var": "c2lnbmF0dXJlXzE"
       },
       {
-        "var": "signature_1",
-        "value": ""
+        "value": "",
+        "var": "signature_1"
       }
     ],
     "type": "",
@@ -1129,7 +1133,7 @@ fields.ajax = [
     "trigger": ""
   },
   {
-    "selector": "#daquestion input[id=\"ZmF2b3JpdGVfd29yZA\"][class=\"form-control da-ajax-combobox\"]",
+    "selector": "#daquestion input[id=\"ZmF2b3JpdGVfd29yZA\"][class=\"form-control da-ajax-combobox\"][role=\"combobox\"]",
     "tag": "input",
     "guesses": [
       {
@@ -1160,6 +1164,13 @@ fields.ajax = [
     "type": "",
     "trigger": ""
   },
+  {
+    "selector": "#daquestion button[class=\"btn btn-outline-secondary dacomboboxtoggle\"]",
+    "tag": "button",
+    "guesses": [],
+    "type": "button",
+    "trigger": ""
+  },
   {
     "selector": "#daquestion button[id=\"da-continue-button\"][class=\"btn btn-da btn-primary\"]",
     "tag": "button",

package/tests/unit_tests/getAllFields.test.js

@@ -2,7 +2,7 @@ const chai = require('chai');
 const expect = chai.expect;
 const deepEqualInAnyOrder = require('deep-equal-in-any-order');
 chai.use(deepEqualInAnyOrder);
-// We need jest or something, right? To do fancy stuff.
+// jest may let us store and update snapshots, but may discourage hand-checking
 
 const html = require('./html.fixtures.js');
 const fields = require('./fields.fixtures.js');

package/tests/unit_tests/html.fixtures.js

@@ -4,6 +4,8 @@
 * #trigger element is added into #daquestion, though it's not at
 * that location on the actual page. Otherwise, we'd have a lot more
 * html in here. In scope.js, it's found just using its id selector.
+* 
+* ✏️ Fixtures are using HTML from docassemble versions <= 1.9.n
 */
 
 let html = {};
@@ -586,7 +588,7 @@ html.proxy_substitution_i_is_0 = `
       <legend class="visually-hidden">Press one of the following buttons:</legend>
       <button class="btn btn-da btn-primary" id="da-continue-button" type="submit">Continue</button>
     </fieldset>
-    <input type="hidden" name="csrf_toke" value="ImNlMGRmOWY5NmQ4MGRjMjI0ZDQyNGFjMWRiYjdiODAzOTk2ZThhY2Ui.Zb7dOA.Fvil0jDP4mebaBoPmtM7sXv6wSQ"/>
+    <input type="hidden" name="csrf_token" value="ImNlMGRmOWY5NmQ4MGRjMjI0ZDQyNGFjMWRiYjdiODAzOTk2ZThhY2Ui.Zb7dOA.Fvil0jDP4mebaBoPmtM7sXv6wSQ"/>
     <input type="hidden" name="_event" value="WyJwcm94eV9saXN0WzBdLm5hbWUuZmlyc3QiXQ"/>
     <input type="hidden" name="_question_name" value="ID proxy vars"/>
     <input type="hidden" name="_tracker" value="3"/>