@suffolklitlab/alkiln 3.0.9 → 4.0.0-pre-api.4

package/lib/scope.js

@@ -2,9 +2,12 @@ const { expect } = require('chai');
 const cheerio = require('cheerio');
 const path = require('path');
 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 time = require('./utils/time');
 
 
 let ordinal_to_integer = {
@@ -28,11 +31,13 @@ module.exports = {
     * 
     * 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:\n type: ${ type }, value: ${ value }`) }
+    if ( env_vars.DEBUG ) { console.log(`Report:\ntype: ${ type }, value: ${ value }`) }
     let scenario = await scope.makeSureReportPartsExist( scope );
     scenario.lines.push({ type, value });
 
+    fs.appendFileSync('log.txt', `Report:\ntype: ${ type }, value: ${ value }`);
     return scenario;
+    
   },  // Ends scope.addToReport()
 
   makeSureReportPartsExist: async function( scope ) {
@@ -51,7 +56,7 @@ module.exports = {
     return scenario;
   },  // Ends scope.makeSureReportPartsExist()
 
-  setReportScenarioStatus: async function( scope, { status=`passed` }) {
+  setReportScenarioStatus: async function( scope, { status=`PASSED` }) {
     /* Add final status of scenario to scenario report object - passed, failed, etc. */
     scope.report.get( scope.scenario_id ).status = status;
   },  // Ends scope.setReportScenarioStatus()
@@ -114,8 +119,8 @@ module.exports = {
 
       let report = await scope.getPrintableScenario( scope, { scenario });
       let [ scenario_id, data ] = scenario;
-      if ( data.status === `failed` ) { failed_reports += report; }
-      else if ( data.status === `passed` ) { passed_reports += report; }
+      if ( data.status === `FAILED` ) { failed_reports += report; }
+      else if ( data.status === `PASSED` ) { passed_reports += report; }
       else { other_reports += report; }
     }  // ends for every scenario
 
@@ -179,11 +184,35 @@ module.exports = {
     return safer_name;
   },  // Ends scope.getSafeScenarioFilename()
 
+  getJSONFilename: async function( scope ) {
+    let filename = await scope.getSafeScenarioFilename( scope, {
+      prefix: `downloads_${ scope.page_id }_JSON`
+    });
+    filename += `.json`;
+    return filename;
+  },
+
+  savePageJSONData: async function( scope ) {
+    /** Save the JSON variables of the current page to a json file.
+    *
+    * @returns {Object} info Info about the result.
+    * @returns {string} info.filename The name of the file that was saved.
+    * @returns {Object} info.json The variables object.
+    */
+    // Get a unique json file filename
+    let filename = await scope.getJSONFilename( scope );
+    // Get the data
+    let json = await scope.getPageJSON( scope );
+    // Save the data
+    fs.writeFileSync( filename, JSON.stringify( json, null, 2 ));
+    return { filename, json };
+  },  // Ends scope.savePageJSONData()
+
   waitForShowIf: async function waitForShowIf(scope) {
     // If something might be hidden or shown, wait extra time to let it hide or show
     // I think `.$()` does not use a timeout
     let showif = await scope.page.$('.dashowif');
-    if ( showif ) { await scope.page.waitFor( scope.showif_timeout ); }
+    if ( showif ) { await scope.page.waitForTimeout( scope.showif_timeout ); }
   },
 
   afterStep: async function afterStep(scope, options = {waitForShowIf: false, navigated: false, waitForTimeout: 0}) {
@@ -191,37 +220,39 @@ module.exports = {
     *    TODO: discuss splitting into `afterField` and `afterStep` or something. Or just change name
     *    TODO: Update to latest cucumberjs, which as `AfterStep` */
 
-    // Use a while loop until the below does not error with `Error: Execution context was destroyed`
-    // Temporary fix for race condition. See https://github.com/plocket/docassemble-cucumber/issues/190
-    let error_id_elem;
-    while ( true ) {
-      try {
-        // Waiting for `page` to exist. '#da-retry' does not need to exist, it's incidental at this point.
-        // If this doesn't throw an error, then the page exists and the result is valid.
-        error_id_elem = await scope.page.$('#da-retry');
-        break;
-      } catch ( err ) {}
-    }
+    if ( scope.page ) {
+      // Use a while loop until the below does not error with `Error: Execution context was destroyed`
+      // Temporary fix for race condition. See https://github.com/plocket/docassemble-cucumber/issues/190
+      let error_id_elem;
+      while ( true ) {
+        try {
+          // Waiting for `page` to exist. '#da-retry' does not need to exist, it's incidental at this point.
+          // If this doesn't throw an error, then the page exists and the result is valid.
+          error_id_elem = await scope.page.$('#da-retry');
+          break;
+        } catch ( err ) {}
+      }
 
-    // If there's a system error, throw it
-    if ( error_id_elem ) {
-      let error_elem = await scope.page.$('blockquote')
-      let error_text_prop = await error_elem.getProperty( 'textContent' );
-      let system_error_text = await error_text_prop.jsonValue();
+      // If there's a system error, throw it
+      if ( error_id_elem ) {
+        let error_elem = await scope.page.$('blockquote')
+        let error_text_prop = await error_elem.getProperty( 'textContent' );
+        let system_error_text = await error_text_prop.jsonValue();
 
-      await scope.addToReport(scope, { type: `error`, value: system_error_text });
-      throw system_error_text;
-    };
+        await scope.addToReport(scope, { type: `error`, value: system_error_text });
+        throw system_error_text;
+      };
+
+      // Wait for elements that might get revealed
+      if ( options.waitForShowIf ) { await scope.waitForShowIf( scope ); }
+    }  // ends if scope.page
 
-    // RESET
+    // Reset navigation (TODO: discuss use for observational steps)
     if ( options.navigated ) { scope.navigated = true; }  // Consider `daPageLoad` event
     else { scope.navigated = false; }
-
-    // WAITING
-    if ( options.waitForShowIf ) { await scope.waitForShowIf(scope); }
-    // Plain old waiting. Yeah, I abstracted it into here so only
-    // one thing was being called at the end
-    if ( options.waitForTimeout ) { await scope.page.waitFor( options.waitForTimeout ); }
+    
+    // Plain old waiting. Here to avoid doing this in each individual place
+    if ( options.waitForTimeout ) { await time.waitForTimeout( options.waitForTimeout ); }
   },  // Ends afterStep
 
   tapElement: async function tapElement(scope, elem) {
@@ -293,7 +324,7 @@ module.exports = {
       return true;
     } else {
       // Otherwise wait and then check again
-      await scope.page.waitFor( 100 );
+      await scope.page.waitForTimeout( 100 );
       await scope.detectDownloadComplete(scope, endTime);
     }
 
@@ -525,6 +556,8 @@ module.exports = {
           encoded_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]*/, '_');
         }
       }
@@ -569,6 +602,15 @@ module.exports = {
     return fields;
   },  // Ends scope.getAllFields()
 
+  getPageJSON: async function ( scope ) {
+    /* Get the JSON data of the current page. */
+    return await scope.page.evaluate(async function ( elem ) {
+      return await get_interview_variables();
+    });
+
+    // return data;
+  },  // Ends scope.getPageJSON()
+
   getFieldSelector: async function ( scope, { $, node }) {
     /* Given the page object and the node object, return the selector
     * we'll use to set the field's value later. Excludes `canvas`.
@@ -968,7 +1010,7 @@ module.exports = {
         catch(err){ elem.style.background = 'Khaki'; }
         return elem.getAttribute('for') || elem.getAttribute('name'); 
       });
-      await scope.page.waitFor( 400 );
+      await scope.page.waitForTimeout( 400 );
     }
 
     let { tag, type } = field;
@@ -1186,30 +1228,30 @@ module.exports = {
       }
     }
 
-    if ( !paths ) {
-      // TODO: Should this throw an error?
-      await scope.addToReport( scope, { type: `warning`, value: `Could not find any files to upload at "${ dir }".` });
-    } else {
-      // Prepare to wait for upload to complete
-      let name = await handle.evaluate( elem => { return elem.getAttribute(`name`); });
-      let selector = `*[name="${ name }"]`
-      let disabled_selector = `${ selector }[disabled]`;
-      let enabled_selector = `${ selector }:not([disabled])`;
-
-      // This comes before the upload starts
-      // Notice `await` is absent. Don't actually wait here.
-      // Just start looking for it now. That way we'll catch it before it's gone
-      let wait_for_disable = scope.page.waitForSelector( disabled_selector );
-      
-      // Upload
-      await handle.uploadFile(...paths);
-
-      // Halt progress to wait for the input to be disabled. If it already is, then this
-      // will have resolved already and will keep going.
-      await wait_for_disable;
-      // When it's again enabled, the files have finished loading. Or so I have observed.
-      await scope.page.waitForSelector( enabled_selector );
-    }
+    if ( paths.length === 0 ) {
+      await scope.addToReport( scope, { type: `error`, value: `Could not find "${set_to}".` });
+      throw ReferenceError(`Could not find "${set_to}".`)
+    } 
+    // Prepare to wait for upload to complete
+    let name = await handle.evaluate( elem => { return elem.getAttribute(`name`); });
+    let selector = `*[name="${ name }"]`
+    let disabled_selector = `${ selector }[disabled]`;
+    let enabled_selector = `${ selector }:not([disabled])`;
+
+    // This comes before the upload starts
+    // Notice `await` is absent. Don't actually wait here.
+    // Just start looking for it now. That way we'll catch it before it's gone
+    let wait_for_disable = scope.page.waitForSelector( disabled_selector );
+    
+    // Upload
+    await handle.uploadFile(...paths);
+
+    // Halt progress to wait for the input to be disabled. If it already is, then this
+    // will have resolved already and will keep going.
+    await wait_for_disable;
+    // When it's again enabled, the files have finished loading. Or so I have observed.
+    await scope.page.waitForSelector( enabled_selector );
+  
 
   },  // Ends scope.uploadFiles()
 
@@ -1546,7 +1588,7 @@ module.exports = {
 
     // Attempt to solve weird race condition issues where page has not properly continued
     while ( curr_url === prev_url && !error.was_found && !timedOut ) {
-      await scope.page.waitFor( 50 );
+      await scope.page.waitForTimeout( 50 );
       curr_url = await scope.page.url();
       error = await scope.checkForError( scope );
     }
@@ -1579,7 +1621,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.waitFor( 60 * 1000 ); }
+        if ( env_vars.DEBUG ) { await scope.page.waitForTimeout( 60 * 1000 ); }
         was_found = true;
         error_handlers[ error_key ] = possible_errors[ error_key ][0];
       }
@@ -1605,6 +1647,241 @@ module.exports = {
     return scope;
   },  // Ends scope.throwPageError()
 
+
+  //#####################################
+  //#####################################
+  // Custom timeouts for **a bunch of stuff** for v7+ of cucumber
+  //#####################################
+  //#####################################
+  steps: {
+
+    screenshot: async ( scope, name ) => {
+      /* Download and save a screenshot. `name` does not have to be
+      * unique as the filename will be made unique. */
+      name = name || '';
+      let safe_path = await scope.getSafeScenarioFilename(
+        scope, { prefix: `screenshot_${ name }` }
+      );
+
+      await scope.page.screenshot({
+        path: `./${ safe_path }.jpg`,
+        type: 'jpeg',
+        fullPage: true
+      });
+
+      await scope.afterStep( scope );
+    },  // Ends screenshot()
+
+    add_json_vars_to_report: async ( scope ) => {
+      /** Uses  https://docassemble.org/docs/functions.html#js_get_interview_variables
+      *    to get the variable values on the page of the interview and add
+      *    them to the report. */
+      let data = await scope.page.evaluate(async function ( elem ) {
+        return await get_interview_variables();
+      });
+
+      // In future, may be saved to artifact file
+      await scope.addToReport( scope, {
+        type: `json`,
+        value: JSON.stringify( data, null, 2 )
+      });
+    },  // Ends add_json_vars_to_report()
+
+    link_works: async ( scope, linkText ) => {
+      let [link] = await scope.page.$x(`//a[contains(text(), "${ linkText }")]`);
+      let prop_obj = await link.getProperty( 'href' );
+      let actual_url = await prop_obj.jsonValue();
+
+      let linkPage = await scope.browser.newPage();
+      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;
+
+      linkPage.close()
+
+      await scope.afterStep(scope);
+    },  // 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:
+      *  - Buttons associated with variables
+      *  - Dropdowns
+      *  - Checkboxes (multiple choice checkboxes must be set to "true" or "false")
+      *  - Radio buttons
+      *  - Text inputs
+      *  - Textareas
+      */
+      let var_data = await scope.normalizeTable( scope, {
+        var_data: [{ var: var_name, value: set_to, trigger: '' }],
+      });
+      // Don't continue if the variable doesn't navigate and if this variable
+      // cannot be seton this page, trigger an error
+      await scope.setFields( scope, { var_data, ensure_navigation: false, ensure_all_vars_used: true });
+    },  // Ends set_regular_var()
+
+    tap_term: async ( scope, phrase ) => {
+      /** Tap a link that doesn't navigate. Depends on the language of the text. */
+      const [link] = await scope.page.$x(`//a[contains(text(), "${phrase}")]`);
+
+      let msg = `The term "${ phrase }" seems to be missing.`;
+      if ( !link ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+      expect( link, msg ).to.exist;
+
+      await link.evaluate( elem => { return elem.click(); });
+
+      await scope.afterStep(scope, {waitForShowIf: true});
+    },  // Ends tap_term()
+
+    sign: async ( scope ) => {
+      /** Sign on a signature page. */
+      await scope.sign( scope );
+      await scope.afterStep(scope);
+    },  // Ends sign()
+
+    download: async ( scope, filename ) => {
+      /* Taps the link that leads to the given filename to trigger downloading.
+      *    and waits till the file has been downloaded before allowing the tests to continue.
+      *    WARNING: Cannot download the same file twice in a single scenario.
+      *    WARNING: Must not have any characters that are totally unique to that
+      *    page load. It's usually just the name of the file.
+      */
+      let [elem] = await scope.page.$x(`//a[contains(@href, "${ filename }")]`);
+
+      let msg = `"${ filename }" seems to be missing. Cannot find a link to that document.`;
+      if ( !elem ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+      expect( elem, msg ).to.exist;
+
+      scope.toDownload = filename;
+      await elem.evaluate( elem => { return elem.click(); });
+      await scope.detectDownloadComplete( scope );
+    },  // Ends download()
+
+    set_al_name: async ( scope, var_base, name_str ) => {
+      /** Given a variable name and a space-separated string, fills the
+      *    appropriate fields on an Assembly Line name question.
+      *    It handles any of:
+      *    1. A one-word value to set name.text (ex: 'LandlordEtAl')
+      *    1. An Individual's name that it will set based on the number of words:
+      *       1. Two words - a first and last name (ex: "Tal Taylor")
+      *       1. Three words - a first, middle, and last name (ex: "Tal Tay Taylor")
+      *       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.
+      */
+      let name_patterns = [
+        [ `text` ],
+        [ `first`, `last` ],
+        [ `first`, `middle`, `last` ],
+        [ `first`, `middle`, `last`, `suffix` ],
+      ];
+
+      let name_parts = name_str.split(' ');
+
+      if (name_parts.length > 4) {
+        let name_parts_last = name_parts[name_parts.length - 1];
+        let name_parts_slice = name_parts.slice(0, 3);
+        name_parts_slice.push(name_parts_last);
+        name_parts = name_parts_slice;
+      
+        await scope.addToReport(scope, {
+          type: `warning`,
+          value: `The name "${name_str}" has more than 4 parts, but 4 is the maximum allowed. The test will set the name to "${name_parts.join(" ")}".`
+        });
+      }
+
+      let desired_pattern = name_patterns[( name_parts.length - 1 )];
+
+      for ( let parti = 0; parti < name_parts.length; parti++ ) {
+        let var_name = `${ var_base }.name.${ desired_pattern[ parti ] }`
+        let value = name_parts[ parti ];
+        await scope.setVar( scope, var_name, value );
+      }
+
+      // Continue to next page...?
+      await scope.afterStep(scope, {waitForShowIf: true});
+    },  // Ends set_al_name()
+
+    set_al_address: async ( scope, var_base, address_str ) => {
+      /** Given a variable name and a four-part address formatted as below,
+      *    sets the appropriate Assembly Line address fields.
+      *
+      * The string 'the var'/'the variable' part of the step is optional,
+      *    as you can see below.
+      */
+      
+      // Get all the parts of the address properly separated
+      // First, split apart each line of the address to [address line 1, address line 2, city, state zip]...
+      let split = address_str.split(/,\s*/);
+      // ...then, separate the state and the zip code...
+      let last_parts = (split.pop()).split(/\s+/);
+      // ...and add them back in, to end up with [address line 1, address line 2, city, state, zip].
+      let address_parts = split.concat( last_parts );
+      let start = `${ var_base }.address.`;
+
+      let index = 0;
+      await scope.setVar( scope, `${start}address`, address_parts[0] );
+      // Ensure it's without 'Unit '/'unit '
+      await scope.setVar( scope, `${start}unit`, (address_parts[1].toLowerCase()).replace(/unit\s*/, '') );
+      await scope.setVar( scope, `${start}city`, address_parts[2] );
+      await scope.setVar( scope, `${start}state`, address_parts[3] );
+      await scope.setVar( scope, `${start}zip`, address_parts[4] );
+
+      await scope.afterStep(scope, {waitForShowIf: true});
+    },  // Ends set_al_address()
+
+    sign_in: async function ( scope, { email_secret_name, password_secret_name }) {
+      /** Allow the developer to log a user into their server using GitHub
+      * secrets to authenticate.
+      */
+      // If there is no browser open, start a new one
+      if (!scope.browser) {
+        scope.browser = await scope.driver.launch({ headless: !session_vars.DEBUG });
+      }
+      if ( !scope.page ) { scope.page = await scope.browser.newPage(); }
+
+      // 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` );
+
+      let email = process.env[ email_secret_name ];
+      let password = process.env[ password_secret_name ];
+
+      // Give as many useful messages to the user as possible if the env vars
+      // aren't defined. Eventually, just provide a link to the docs because
+      // this is complex
+      let email_msg = `The email address GitHub SECRET "${ email_secret_name }" doesn't exist. Check for a typo and check your workflow file.`
+      if ( email === undefined ) {
+        await scope.addToReport( scope, { type: `error`, value: email_msg })
+      }
+      let password_msg = `The password GitHub SECRET "${ password_secret_name }" doesn't exist. Check for a typo and check your workflow file.`
+      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(); });
+
+      // Wait to see the success message.
+      // This is a bit of an assumption and needs success and failure testing
+      // TODO: use a Promise.race to fail faster.
+      await scope.page.waitForSelector( `.datopcenter .alert-success` );
+
+      await scope.addToReport( scope, {
+        type: `row`,
+        value: `Logged into ${ session_vars.get_da_server_url() }/user/sign-in as a ${ email } with ${ password }.`
+      });
+    },  // Ends sign_in
+
+  },  // ends scope.steps
+
+
   //#####################################
   //#####################################
   // Framework Development