@suffolklitlab/alkiln 5.2.0 → 5.3.0

package/lib/steps.js

@@ -21,6 +21,7 @@ const scope = require('./scope');
 const log = require('./utils/log');
 const session_vars = require('./utils/session_vars');
 const files = require('./utils/files' );
+const reports = require(`./utils/reports`);
 
 /* Of Note:
 - We're using `*=` for selectors because sometimes da text has funny characters in it that are hard to anticipate
@@ -125,7 +126,7 @@ Before(async (scenario) => {
   scope.expected_not_in_report = null;
   scope.server_reload_promise = null;
 
-  await scope.addReportHeading(scope, {scenario});
+  reports.addReportHeading(scope, {scenario});
   // Make folder for this Scenario in the all-tests artifacts folder
   scope.base_filename = await scope.getSafeScenarioBaseFilename(scope, {scenario});
   // Add a date for uniqueness in case dev has accidentally copied a Scenario description
@@ -203,6 +204,7 @@ Given(/I start the interview at "([^"]+)"/, {timeout: -1}, async (file_name) =>
     // at any one time since each step completes synchronously
 
     // If response has a file in it that matches the file we are downloading
+    // Sadly, 'content-disposition' isn't working. We're not sure what will.
     if ( response.headers()['content-disposition'] && (response.headers()['content-disposition']).includes(`attachment;filename=${scope.toDownload}`) ) {
       // We're choosing to avoid removing the event listener in case removal
       // would prevent downloading other files. The listener should get
@@ -352,7 +354,7 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
           resolve();
         } catch ( err ) {
           let err_msg = `Error occurred when tried to answer fields on question "${ id }".`
-          scope.addToReport( scope, { type: `error`, value: err_msg });
+          reports.addToReport( scope, { type: `error`, value: err_msg });
           // Throw error instead?
           reject( err );
         } finally {
@@ -371,7 +373,7 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
 
   // Add report strings from supported table, not an altered one
   for ( let row of supported_table ) {
-    row.report_str = `${ await scope.convertToOriginalStoryTableRow(scope, { row_data: row }) }`;
+    row.report_str = `${ reports.convertToOriginalStoryTableRow(scope, { row_data: row }) }`;
   }
   // Sort into alphabetical order, as is recommended for writing story tables
   let sorted_rows = supported_table.sort( function ( row1, row2 ) {
@@ -382,13 +384,13 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
 
   // Add full used table to report so it can be copied if needed.
   // TODO: Should we/How do we get this in the final scenario report instead of here?
-  await scope.addToReport( scope, { type: `note`, value: `\n${ ' '.repeat(2) }Rows that got set:` });
-  await scope.addToReport( scope, { type: `step`, value: `${ ' '.repeat(4) }And I get to the question id "${ target_id }" with this data:` });
-  await scope.addToReport(scope, { type: `row`, value: `${ ' '.repeat(6) }| var | value | trigger |`, });
+  reports.addToReport( scope, { type: `note`, value: `\n${ ' '.repeat(2) }Rows that got set:` });
+  reports.addToReport( scope, { type: `step`, value: `${ ' '.repeat(4) }And I get to the question id "${ target_id }" with this data:` });
+  reports.addToReport(scope, { type: `row`, value: `${ ' '.repeat(6) }| var | value | trigger |`, });
   let at_least_one_row_was_NOT_used = false;
   for ( let row of sorted_rows ) {
     if ( row.times_used > 0 ) {
-      await scope.addToReport(scope, { type: `row`, value: row.report_str, });
+      reports.addToReport(scope, { type: `row`, value: row.report_str, });
     } else {
       at_least_one_row_was_NOT_used = true;
     }
@@ -396,17 +398,17 @@ When(/^(?:the user gets)?(?:I get)? to ?(?:the)?(?: ?question)?(?: id)? "([^"]+)
 
   // Add unused rows if needed
   if ( at_least_one_row_was_NOT_used ) {
-    await scope.addToReport( scope, { type: `note`, value: `${ ' '.repeat(2) }Unused rows:` });
+    reports.addToReport( scope, { type: `note`, value: `${ ' '.repeat(2) }Unused rows:` });
     for ( let row of sorted_rows ) {
       if ( row.times_used === 0 ) {
-        await scope.addToReport(scope, { type: `row`, value: row.report_str, });
+        reports.addToReport(scope, { type: `row`, value: row.report_str, });
       }
     }
   } else {
-    await scope.addToReport(scope, { type: `note`, value: `${ ' '.repeat(2) }All rows were used` });
+    reports.addToReport(scope, { type: `note`, value: `${ ' '.repeat(2) }All rows were used` });
   }
 
-  await scope.addToReport(scope, { type: `note`, value: `` });
+  reports.addToReport(scope, { type: `note`, value: `` });
 });
 
 //#####################################
@@ -456,7 +458,7 @@ Then(/the (?:question|page|screen) id should be "([^"]+)"/i, { timeout: -1 }, as
   // No question id exists
   let no_id_msg = `Did not find any question id.`;
   if ( !question_has_id ) {
-    await scope.addToReport( scope, { type: `error`, value: no_id_msg });
+    reports.addToReport( scope, { type: `error`, value: no_id_msg });
   }
   expect( question_has_id , no_id_msg ).to.be.true;
 
@@ -464,7 +466,7 @@ Then(/the (?:question|page|screen) id should be "([^"]+)"/i, { timeout: -1 }, as
   let no_match_msg = `The question id was supposed to be "${ question_id }"`
     + `, but it's actually "${ id }".`;
   if ( !id_matches ) {
-    await scope.addToReport( scope, { type: `error`, value: no_match_msg });
+    reports.addToReport( scope, { type: `error`, value: no_match_msg });
   }
   expect( id_matches, no_match_msg ).to.be.true;
 
@@ -477,7 +479,7 @@ Then(/I ?(?:should)? see the phrase "([^"]+)"/i, async ( phrase ) => {  // √
   const bodyText = await scope.page.$eval('body', elem => elem.innerText);
 
   let msg = `The text "${ phrase }" SHOULD be on this page, but it's NOT.`;
-  if ( !bodyText.includes( phrase )) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !bodyText.includes( phrase )) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( bodyText, msg ).to.contain( phrase );
 
   await scope.afterStep(scope);
@@ -491,7 +493,7 @@ Then(/I should not see the phrase "([^"]+)"/i, async ( phrase ) => {  // √
   const bodyText = await scope.page.$eval('body', elem => elem.innerText);
 
   let msg = `The text "${ phrase }" should NOT be on this page, but it IS here.`;
-  if ( bodyText.includes( phrase )) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( bodyText.includes( phrase )) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( bodyText, msg ).not.to.contain( phrase );
 
   await scope.afterStep(scope);
@@ -501,7 +503,7 @@ Then('an element should have the id {string}', async ( id ) => {  // √
   const element = await scope.page.$('#' + id);
 
   let msg = `No element on this page has the ID "${ id }".`;
-  if ( !element ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !element ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( element, msg ).to.exist;
 
   await scope.afterStep(scope);
@@ -556,7 +558,7 @@ Then(/I (don't|can't|don’t|can’t|cannot|do not) continue/, async (unused) =>
   *    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 ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( scope.navigated ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( scope.navigated, msg ).to.be.false;
 
   await scope.afterStep(scope);
@@ -567,12 +569,12 @@ Then('I will be told an answer is invalid', async () => {  // √
   let { was_found, error_handlers } = await scope.checkForError( scope );
 
   let no_error_msg = `No error message was found on the page`;
-  if ( !was_found ) { await scope.addToReport(scope, { type: `error`, value: no_error_msg }); }
+  if ( !was_found ) { reports.addToReport(scope, { type: `error`, value: no_error_msg }); }
   expect( was_found, no_error_msg ).to.be.true;
 
   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 ) { await scope.addToReport(scope, { type: `error`, value: not_user_error_msg }); }
+  if ( !was_user_error ) { reports.addToReport(scope, { type: `error`, value: not_user_error_msg }); }
   expect( was_user_error, not_user_error_msg ).to.be.true;
 
   await scope.afterStep(scope);
@@ -583,7 +585,7 @@ Then('I arrive at the next page', async () => {  // √
   *    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 ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !scope.navigated ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( scope.navigated, msg ).to.be.true;
   await scope.afterStep(scope);
 });
@@ -594,7 +596,7 @@ Then('I should see the link {string}', async ( linkText ) => {  // √
   let [link] = await scope.page.$x(`//a[contains(text(), "${linkText}")]`);
 
   let msg = `Cannot find a link with the text "${ linkText }".`;
-  if ( !link ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !link ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( link, msg ).to.exist;
 
   await scope.afterStep(scope);
@@ -605,7 +607,7 @@ Then('I should see the link to {string}', async ( url ) => {  // √
   let link = await scope.page.$(`*[href="${ url }"]`);
 
   let msg = `Cannot find a link to "${ url }".`;
-  if ( !link ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !link ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect(link, msg ).to.exist;
   
   await scope.afterStep(scope);
@@ -621,7 +623,7 @@ Then(/the "([^"]+)" link leads to "([^"]+)"/, async (linkText, expected_url) =>
   let actual_url = await prop_obj.jsonValue();
 
   let msg = `Cannot find a link with the text "${ linkText }" leading to ${ expected_url }.`;
-  if ( actual_url !== expected_url ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( actual_url !== expected_url ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( actual_url ).to.equal( expected_url );
 
   await scope.afterStep(scope);
@@ -640,7 +642,7 @@ Then(/the "([^"]+)" link opens in (a new window|the same window)/, async (linkTe
     || ( !should_open_a_new_window && !opens_a_new_window );
 
   let msg = `The link "${ linkText }" does NOT open in ${ which_window }.`;
-  if ( !hasCorrectWindowTarget ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+  if ( !hasCorrectWindowTarget ) { reports.addToReport(scope, { type: `error`, value: msg }); }
   expect( hasCorrectWindowTarget, msg ).to.be.true;
 
   await scope.afterStep(scope);
@@ -673,7 +675,7 @@ Then(/(?:the )?text(?: in)?(?: the)?(?: JSON)?(?: var)?(?:iable)?(?: )?"([^"]+)"
 
   // Add warning to report if value is not as expected
   if ( actual_value !== expected_value ) {
-    await scope.addToReport( scope, {
+    reports.addToReport( scope, {
       type: `error`,
       value: `The variable "${ var_name }" was not equal to the expected `
         + `value on the "${ scope.page_id }" screen. Check `
@@ -780,7 +782,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
   let random_input_path = `${ scope.paths.scenario }/random${ timestamp }`
   scope.paths.random_screenshots = random_input_path;
   fs.mkdirSync( scope.paths.random_screenshots );
-  await scope.addToReport( scope, {
+  reports.addToReport( scope, {
     type: 'row',
     value: `Testing interview with random input (in ${ random_input_path })`
   });
@@ -815,7 +817,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
         let has_content = await scope.has_interview_content( scope );
 
         if ( !has_content ) {
-          await scope.addToReport( scope, {
+          reports.addToReport( scope, {
             type: `error`,
             value: no_content_err
           });
@@ -824,7 +826,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
         } else {
           let timeout_message = `The page with an id of "${ id }" took too long`
             + ` to fill with random answers (over ${ scope.timeout/1000/60 } min).`
-          await scope.addToReport( scope, { type: `error`, value: timeout_message });
+          reports.addToReport( scope, { type: `error`, value: timeout_message });
           reject( timeout_message );
         }
 
@@ -865,7 +867,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
             // Make sure to only throw once
             if ( !has_thrown ) {
               has_thrown = true;
-              await scope.addToReport( scope, {
+              reports.addToReport( scope, {
                 type: `error`,
                 value: no_content_err
               });
@@ -889,7 +891,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
           // Throw a specific error if there's no interview content
           let has_content = await scope.has_interview_content( scope );
           if ( !has_content ) {
-            await scope.addToReport( scope, {
+            reports.addToReport( scope, {
               type: `error`,
               value: no_content_err
             });
@@ -899,7 +901,7 @@ When(/I answer randomly for at most ([0-9]+) (?:page(?:s)?|screen(?:s)?)/, { tim
           } else {
             let err_msg = `The page with the question id "${ id }" errored when trying to fill`
               + ` it with random answers: ${ error.name }`
-            await scope.addToReport( scope, { type: `error`, value: err_msg });
+            reports.addToReport( scope, { type: `error`, value: err_msg });
             reject( error );
           }  // ends if !has_content
 
@@ -1097,24 +1099,29 @@ Given(/the final Scenario status should be "(passed|failed)"/i, async ( expected
 
 After(async function(scenario) {
 
+  let changeable_test_status = scenario.result.status;
   // The accessibility failures don't happen til the end, so the rest of the test can continue
   if ( scope.check_all_for_a11y && !scope.passed_all_for_a11y) {
     // The fact that the scenario failed has already been noted earlier in the report
-    scenario.result.status = `FAILED`;
+    changeable_test_status = `FAILED`;
+    scope.addToReport(scope, {
+      type: `error`,
+      value: `Accessibility standards weren't met. See information above.`
+    });
   }
 
   // Record status before internal report tests can interfere with values
-  await scope.setReportScenarioStatus( scope, { status: scenario.result.status });
+  reports.setReportScenarioStatus( scope, { status: changeable_test_status });
 
-  if (scenario.result.status !== `PASSED`) {
+  if (changeable_test_status !== `PASSED`) {
     if ( session_vars.get_debug() ) {
-      console.log( `Non-passed status occurred while running test:`, scenario.result.status );
+      console.log( `Non-passed status occurred while running test:`, changeable_test_status );
     }
 
     if ( scope.page ) {
 
       if ( !!scope.disable_error_screenshot ) {
-        scope.addToReport(scope, {
+        reports.addToReport(scope, {
           type: `row`,
           value: `For security, ALKiln will avoid creating a picture of the page for this error. It's possible a secret is being used on this screen.`
         });
@@ -1138,21 +1145,19 @@ After(async function(scenario) {
     }  // ends if scope.page exists
 
     // This has to come after the security message or security message doesn't print. Not sure why.
-    if (scenario.result.status === `FAILED`) {
-      await scope.addToReport(scope, { type: `outcome`, value: `**-- Scenario Failed --**` });
+    if (changeable_test_status === `FAILED`) {
+      reports.addToReport(scope, { type: `outcome`, value: `**-- Scenario Failed --**` });
     }
 
   }  // ends if not passed
 
-  let original_scenario_status = scenario.result.status;
-
   // Internal tests of this framework
   if ( scope.expected_status ) {
     let expected = scope.expected_status;
     scope.expected_status = null;  // reset for next Scenario
-    expect( scenario.result.status ).to.equal( expected );
+    expect( changeable_test_status ).to.equal( expected );
     // If the status was as expected, pass this criteria
-    scenario.result.status = `PASSED`;
+    changeable_test_status = `PASSED`;
   }
   
   if ( scope.expected_in_report && scope.expected_in_report.length > 0) {
@@ -1161,8 +1166,8 @@ After(async function(scenario) {
     scope.expected_in_report = null;
     let all_were_included = await scope.reportIncludesAllExpected( scope, { expected });
 
-    if ( all_were_included ) { scenario.result.status = `PASSED`; }
-    else { scenario.result.status = `FAILED`; }
+    if ( all_were_included ) { changeable_test_status = `PASSED`; }
+    else { changeable_test_status = `FAILED`; }
   }
   
   if (scope.expected_not_in_report && scope.expected_not_in_report.length > 0) {
@@ -1172,9 +1177,9 @@ After(async function(scenario) {
     let all_were_not_there = await scope.reportDoesNotInclude( scope, { not_expected });
 
     if ( all_were_not_there ) {
-      scenario.result.status = `PASSED`;
+      changeable_test_status = `PASSED`;
     } else { 
-      scenario.result.status = `FAILED`;
+      changeable_test_status = `FAILED`;
     }
 
   }
@@ -1198,7 +1203,7 @@ After(async function(scenario) {
       } else {
         // Throw any non-timeout error
         let err_msg = `Error occurred when ALKiln tried to sign out in preparation for the next test.`
-        scope.addToReport( scope, { type: `error`, value: err_msg });
+        reports.addToReport( scope, { type: `error`, value: err_msg });
         throw error;
       }  // ends if error is timeout error
 
@@ -1209,16 +1214,29 @@ After(async function(scenario) {
   // Add report text to Scenario folder after everything has been added to the report
   let current_report_obj = scope.report.get( scope.scenario_id );
   let scenario_report_obj = [ scope.scenario_id, current_report_obj ];  // Mimic how loop works with `Map`
-  let report = await scope.getPrintableScenario( scope, { scenario: scenario_report_obj });
+  let report = reports.getPrintableScenario( scenario_report_obj );
   // Save the report as in the Scenario folder
   fs.writeFileSync( scope.paths.scenario_report, report );
+
+  if ( changeable_test_status === `FAILED` ) {
+    // If the result object status wasn't failure and we still want
+    // the tests to fail, as with a11y tests, we can't mess with the
+    // cucumber result.status object because it will cause unwanted
+    // errors. We have to throw an error here instead.
+    if ( scenario.result.status !== `FAILED` ) {
+      throw new Error(`The test failed. See the report for more information.`);
+    }
+  } else {
+    // Other types of errors should be ok
+    scenario.result.status = changeable_test_status;
+  }
 });
 
 AfterAll(async function() {
   // Stop collecting server response statuses
   scope.stop_tracking_server_status = true;
   
-  let report = await scope.getPrintableReport( scope );
+  let report = reports.getPrintableReport( scope );
   // Log the report. Can't get this.attach() or this.log() to work in `After()` or here.
   // May need newest version of cucumberjs
   console.log( `\n\n${ report }` );

package/lib/utils/reports.js

@@ -0,0 +1,147 @@
+const fs = require(`fs`);
+
+// Ours
+const session_vars = require(`./session_vars`);
+const files = require(`./files` );
+
+
+module.exports = reports = {};
+
+reports.addReportHeading = function (scope, { scenario }) {
+  /** Return printable heading based on Scenario name and tags.
+  *    Allow characters from other languages.
+  */
+  if ( session_vars.get_debug() ) { console.log(`reports.addReportHeading(): ${scenario.pickle.name} \n`); }
+
+  // Collect all tag names
+  let tag_names = [];
+  for ( let tag of scenario.pickle.tags ) {
+    tag_names.push( tag.name );
+  }
+
+  let heading = `\n---------------\n`
+    + `Scenario: ${ scenario.pickle.name }`;
+
+  if ( tag_names.length > 0 ) {
+    heading += `\nTags: ${ tag_names.join(' ') }`;
+  }
+
+  heading += `\n---------------`;
+
+  reports.addToReport( scope, {
+    type: `heading`,
+    value: heading,
+  });
+};  // Ends reports.addReportHeading()
+
+reports.addToReport = 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 ( session_vars.get_debug() ) { console.log(`reports.addToReport():\ntype: ${ type }, value: ${ value }\n`) }
+  let scenario = makeSureReportPartsExist( scope );
+  scenario.lines.push({ type, value });
+
+  const MISC_ARTIFACTS_DIR = `_alkiln-misc_artifacts`;
+  // Ensure filepath for saving local unit test logs
+  if ( !scope.paths ) {
+    // TODO: would it be useful to put in existing artifacts folder if possible.
+    // Can this be usefully abstracted?
+    scope.paths = { debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_logs-${ files.readable_date() }.txt` };
+  }
+
+  try {
+    fs.appendFileSync(scope.paths.debug_log, `\nReport:\ntype: ${ type }, value: ${ value }`);
+  } catch (err) {
+    fs.mkdirSync( MISC_ARTIFACTS_DIR );
+    fs.appendFileSync(scope.paths.debug_log, `\nReport:\ntype: ${ type }, value: ${ value }`);
+  }
+
+  return scenario;
+};  // Ends reports.addToReport()
+
+let makeSureReportPartsExist = function( scope ) {
+  /** If a part of the report needs to exist right now, but doesn't exist,
+  * create it. */
+  if ( !scope.report ) { scope.report = new Map(); }
+  if ( !scope.scenario_id ) {
+    scope.scenario_id = `_report_${ Date.now() }`;
+  }
+  if ( !scope.report.get( scope.scenario_id )) {
+    scope.report.set( scope.scenario_id, {} )
+    scope.report.get( scope.scenario_id ).status = `in progress`;
+  }
+
+  let scenario = scope.report.get( scope.scenario_id );
+  if ( !scenario.lines ) { scenario.lines = []; }
+
+  return scenario;
+};  // Ends makeSureReportPartsExist()
+
+reports.setReportScenarioStatus = 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 reports.setReportScenarioStatus()
+
+reports.convertToOriginalStoryTableRow = function( scope, { row_data }) {
+  /** Returns the original data of row into a string formatted as a story table row.
+  * Should this show the actual row data that was used instead? That could
+  * be pretty confusing to most devs. */
+  let source_row = row_data.source || row_data;
+  let original = source_row.original;
+  let var_str = trimJSON( original.var );
+  let value_str = trimJSON( original.value );
+  let trigger_str = trimJSON( 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 reports.convertToOriginalStoryTableRows()
+
+let trimJSON = function( str=`` ) {
+  /** Turn into JSON string then trim quotes from the start and end. */
+  let json = JSON.stringify( str );
+  let trimmed = json.replace( /^"/, `` ).replace( /"$/, `` ).replace( /\\\\/g, `\\`);
+  return trimmed;
+};  // Ends trimJSON()
+
+reports.getPrintableReport = function( scope ) {
+  /** Return a string generated from test report data. */
+  let report = `Assembly Line Kiln Automated Testing Report - ${ (new Date()).toUTCString() }\n`;
+
+  // First list failed scenarios, then non-passed scenarios, then passed scenarios
+  let failed_reports = ``;
+  let passed_reports = ``;
+  let other_reports = ``;
+  for ( let scenario of scope.report ) {
+
+    let report = reports.getPrintableScenario( scenario );
+    let [ scenario_id, data ] = scenario;
+    if ( data.status === `FAILED` ) { failed_reports += report; }
+    else if ( data.status === `PASSED` ) { passed_reports += report; }
+    else { other_reports += report; }
+  };  // ends for every scenario
+
+  if ( failed_reports !== `` ) { report += `\n\n===============================\n===============================\nFailed scenarios:\n${ failed_reports }`; }
+  if ( other_reports !== `` ) { report += `\n\n===============================\n===============================\nScenarios that did not pass:\n${ other_reports }`; }
+  if ( passed_reports !== `` ) { report += `\n\n===============================\n===============================\nPassed scenarios:\n${ passed_reports }`; }
+
+  return report;
+};  // Ends reports.getPrintableReport()
+
+reports.getPrintableScenario = function( scenario ) {
+  /** Return a string generated from scenario list of report items. */
+  let [ scenario_id, data ] = scenario;
+  let report = ``;
+  for ( let line of data.lines ) {
+    if ( line.type === `page_id` ) { report += `screen id: `; }
+    else if ( line.type === `outcome` ) { report += `\n`; }
+    else if ( line.type === `warning` ) { report += `WARNING: `; }
+    else if ( line.type === `error` ) { report += `\nERROR: ` }
+    report += `${ line.value }\n`;
+  }
+  return report;
+};  // Ends reports.getPrintableScenario()

package/package.json

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