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

package/lib/utils/env_vars.js

@@ -2,6 +2,8 @@ const fs = require('fs');
 
 require('dotenv').config();
 
+const session_vars = require( './session_vars' );
+
 /**
  * This code assumes that this module is run as part of a GitHub Action.  If the
  * customer is running it as a CLI tool, then they are on their own.
@@ -76,66 +78,66 @@ const env_vars = {
   
 env_vars.validateEnvironment();
   
-// Path could be 'refs/branch_name' or 'refs/head/branch_name' and maybe other things
-// Assume branch name is last part of branch path
-if ( process.env.BRANCH_PATH ) {
-  let split = process.env.BRANCH_PATH.split('/');
-  env_vars.BRANCH_NAME = split[ split.length - 1 ];
-} else {
-  env_vars.BRANCH_NAME = 'test'
-}
-
-// ---- Project name ----
-let no_starting_digit = ( 'testing' + env_vars.BRANCH_NAME ).replace( /^[0-9]+/i, '' );
-env_vars.PROJECT_BASE_NAME = no_starting_digit.replace( /[^A-Za-z0-9]+/gi, '' );
-
-const project_name_file_path = '_al_test_project_name.json';
-env_vars.setProjectName = function ( value ) {
-  // As long as it's a string, it can be made safe for a project name
-  if ( typeof value !== 'string' ) { throw new TypeError(`The project's name must start as a string. It was ${ value }.`); }
-  // Make the name safe for a project name
-  let no_starting_digit = value.replace( /^[0-9]+/i, '' );
-  let alphanumeric = no_starting_digit.replace( /[^A-Za-z0-9]+/gi, '' );
-  // Create or modify a file to store the actual name of the project
-  // for later deletion as internal values and context get destroyed before
-  // the takedown command that comes later. It's a string, not a list, to avoid
-  // the list getting out of date and deleting another test's project.
-  fs.writeFileSync( project_name_file_path, JSON.stringify( alphanumeric ));
-  console.log( `Saved new project name: ${ alphanumeric }` );
-
-  return alphanumeric;
-}
-
-env_vars.getProjectName = function () {
-  /* Get the stored name of the project that was created on the
-  * server - the base project name might have been adjusted to
-  * avoid overwriting existing project. */
-  if ( env_vars.DEBUG ) { console.trace( `Getting project name` ); }
-  let actual_proj_name = null;
-  // Avoid race coditions possibly caused by checking for existence first
-  try {
-    actual_proj_name = JSON.parse( fs.readFileSync( project_name_file_path ));
-    if ( env_vars.DEBUG ) { console.log( `Project name from file is ${ actual_proj_name }.` ); }
-  } catch ( error ) {}  // Do nothing
-
-  // If no such file existed or value was invalid, set up the file with a basic name
-  if ( !actual_proj_name ) {
-    actual_proj_name = env_vars.setProjectName( env_vars.PROJECT_BASE_NAME );
-  }
-
-  if ( env_vars.DEBUG ) { console.log( `Processed project name is "${ actual_proj_name }"` ); }
-  return actual_proj_name;
-};
-
-env_vars.cleanUpProjectName = function () {
-  /* Delete stored name of project */
-  // Avoid race coditions possibly caused by checking for existence first
-  // Delete file if possible
-  try { fs.unlinkSync( project_name_file_path ); }
-  catch ( error ) {
-    console.warn(`After trying to delete the project created for the test, the file containing the name of project did not exist. ${ error }`)
-  }
-};
+// // Path could be 'refs/branch_name' or 'refs/head/branch_name' and maybe other things
+// // Assume branch name is last part of branch path
+// if ( process.env.BRANCH_PATH ) {
+//   let split = process.env.BRANCH_PATH.split('/');
+//   env_vars.BRANCH_NAME = split[ split.length - 1 ];
+// } else {
+//   env_vars.BRANCH_NAME = 'test'
+// }
+
+// // ---- Project name ----
+// let no_starting_digit = ( 'testing' + env_vars.BRANCH_NAME ).replace( /^[0-9]+/i, '' );
+// env_vars.PROJECT_BASE_NAME = no_starting_digit.replace( /[^A-Za-z0-9]+/gi, '' );
+
+// const project_name_file_path = '_al_test_project_name.json';
+// env_vars.setProjectName = function ( value ) {
+//   // As long as it's a string, it can be made safe for a project name
+//   if ( typeof value !== 'string' ) { throw new TypeError(`The project's name must start as a string. It was ${ value }.`); }
+//   // Make the name safe for a project name
+//   let no_starting_digit = value.replace( /^[0-9]+/i, '' );
+//   let alphanumeric = no_starting_digit.replace( /[^A-Za-z0-9]+/gi, '' );
+//   // Create or modify a file to store the actual name of the project
+//   // for later deletion as internal values and context get destroyed before
+//   // the takedown command that comes later. It's a string, not a list, to avoid
+//   // the list getting out of date and deleting another test's project.
+//   fs.writeFileSync( project_name_file_path, JSON.stringify( alphanumeric ));
+//   console.log( `Saved new project name: ${ alphanumeric }` );
+
+//   return alphanumeric;
+// }
+
+// env_vars.getProjectName = function () {
+//   /* Get the stored name of the project that was created on the
+//   * server - the base project name might have been adjusted to
+//   * avoid overwriting existing project. */
+//   if ( env_vars.DEBUG ) { console.trace( `Getting project name` ); }
+//   let actual_proj_name = null;
+//   // Avoid race coditions possibly caused by checking for existence first
+//   try {
+//     actual_proj_name = JSON.parse( fs.readFileSync( project_name_file_path ));
+//     if ( env_vars.DEBUG ) { console.log( `Project name from file is ${ actual_proj_name }.` ); }
+//   } catch ( error ) {}  // Do nothing
+
+//   // If no such file existed or value was invalid, set up the file with a basic name
+//   if ( !actual_proj_name ) {
+//     actual_proj_name = env_vars.setProjectName( env_vars.PROJECT_BASE_NAME );
+//   }
+
+//   if ( env_vars.DEBUG ) { console.log( `Processed project name is "${ actual_proj_name }"` ); }
+//   return actual_proj_name;
+// };
+
+// env_vars.cleanUpProjectName = function () {
+//   /* Delete stored name of project */
+//   // Avoid race coditions possibly caused by checking for existence first
+//   // Delete file if possible
+//   try { fs.unlinkSync( project_name_file_path ); }
+//   catch ( error ) {
+//     console.warn(`After trying to delete the project created for the test, the file containing the name of project did not exist. ${ error }`)
+//   }
+// };
 
 // Notes: We were using `new_session=1` in the url args, but it wasn't
 // always working. The idea was to save each session so we could look
@@ -155,19 +157,21 @@ env_vars.getBaseInterviewURL = function () {
   /* Return the part of the interview URL that comes before the filename.
   * Depends on the project name, which may have been changed. */
   let new_session = `/interview?new_session=1&i=docassemble.playground`;
-  return `${ env_vars.BASE_URL }${ new_session }${ env_vars.PLAYGROUND_ID }${ env_vars.getProjectName() }%3A`;
+  return `${ session_vars.get_da_server_url() }${ new_session }${ env_vars.PLAYGROUND_ID }${ session_vars.get_project_name() }%3A`;
 };
 env_vars.BASE_INTERVIEW_URL = env_vars.getBaseInterviewURL();
 
 
-// These are actually the words that are on the buttons or links
-// that change the language of the interview. Have not yet detected
-// another distinguishing feature
-if ( process.env.EXTRA_LANGUAGES && process.env.EXTRA_LANGUAGES !== 'default' ) {
-  env_vars.EXTRA_LANGUAGES = process.env.EXTRA_LANGUAGES.split(', ');
-} else {
-  env_vars.EXTRA_LANGUAGES = [];
-}
+// // These are actually the words that are on the buttons or links
+// // that change the language of the interview. Have not yet detected
+// // another distinguishing feature
+// if ( process.env.EXTRA_LANGUAGES && process.env.EXTRA_LANGUAGES !== 'default' ) {
+//   env_vars.EXTRA_LANGUAGES = process.env.EXTRA_LANGUAGES.split(', ');
+// } else {
+//   env_vars.EXTRA_LANGUAGES = [];
+// }
+
+env_vars.EXTRA_LANGUAGES = session_vars.get_languages();
 
 
 module.exports = env_vars;

package/lib/utils/log.js

@@ -0,0 +1,51 @@
+const session_vars = require( './session_vars' );
+
+let log = {};
+module.exports = log;
+
+let create_msg_start = function ( types, pre='' ) {
+  let parts = [ `ALKiln`, ...types ];
+  let start = parts.join(` `);
+  return `${ start }: ${ pre }`;
+};
+
+log.info = function ({ type='', pre='', data='', post='' }) {
+  /* Log info msg with the given information and strings, prepended with `ALKiln`.
+  *    `type` is often something like 'setup', 'takedown', etc. */
+  let start = create_msg_start([ type ], pre );
+  // Log them each on a separate line
+  console.info( `${ start }` );
+  if ( data ) { console.info( data ); }
+  if ( post ) { console.info( post ); }
+};
+
+log.warn = function ({ type='', pre='', data='', post='' }) {
+  /* Log warning msg with the given information and strings, prepended with `ALKiln`.
+  *    `type` is often something like 'setup', 'takedown', etc. */
+  let start = create_msg_start([ type, `WARNING` ], pre );
+  // Log them each on a separate line
+  console.warn( `${ start }` );
+  if ( data ) { console.warn( data ); }
+  if ( post ) { console.warn( post ); }
+};
+
+log.error = function ({ type='', pre='', data='', post='' }) {
+  /* Log error msg with the given information and strings, prepended with `ALKiln`.
+  *    `type` is often something like 'setup', 'takedown', etc. */
+  let start = create_msg_start([ type, `ERROR` ], pre );
+  // Log them each on a separate line with extra new lines around the whole thing
+  console.error( `\n${ start }` );
+  if ( data ) { console.error( data ); }
+  if ( post ) { console.error( post, `\n` ); }
+};
+
+log.debug = function ({ type='', pre='', data='', post='' }) {
+  /* If debugging is turned on, log a message that includes `ALKiln` and `debug` */
+  if ( session_vars.get_debug() ) {
+    let start = create_msg_start([ type, 'debug' ], pre );
+    // Log them each on a separate line
+    console.log( `ALKiln ${ type } debug: ${ pre }` );
+    if ( data ) { console.log( data ); }
+    if ( post ) { console.log( post ); }
+  }
+};

package/lib/utils/session_vars.js

@@ -0,0 +1,188 @@
+const fs = require('fs');
+const path = require('path'); 
+require('dotenv').config();
+
+/**
+ * This code assumes that this module is run as part of a GitHub Action.  If the
+ * customer is running it as a CLI tool, then they won't get useful messages yet.
+ */
+
+/* This file provides user info variables. E.g. server address. They're either
+*    `process.env` vars or vars that have been built from `process.env` vars.
+*    It is meant to avoid duplication, make testing easier, and leave room for
+*    future maninpulation. No other file should need to use `process.env`.
+*
+* We have a bunch of `.get_foo()` functions partly because it makes the code
+*    much easier to test.
+*/
+
+const session_vars = {
+  PLAYGROUND_ID: process.env.PLAYGROUND_ID,  // Need to get rid of this in favor of API
+};
+
+module.exports = session_vars;
+
+/**
+ * Ensure all required environment variables exist. Add each missing variable
+ *    to an error that will be thrown at the end.
+ * 
+ * @throws ReferenceError with a message for all missing variables. 
+ */
+ session_vars.validateEnvironment = function() {
+
+  // We are checking for BASE_URL, but we are referring it as SERVER_URL as that
+  // is the name used in GitHub secrets, which is what most devs will be using.
+
+  let errorMessage = '';
+
+  // Since this code will most often be run in GitHub, I'm going to build a single error message that outlines all missing variables.  Otherwise, a developer
+  // will have to run their pipeline an incredible number of times to discover all the missing variables.
+  if (!process.env.DOCASSEMBLE_DEVELOPER_API_KEY)
+  {
+    errorMessage += `\nThe DOCASSEMBLE_DEVELOPER_API_KEY GitHub secret must be defined. The DOCASSEMBLE_DEVELOPER_API_KEY is a docassemble API key you created for your server's testing account. It should have developer permissions.`
+  }
+  if (!process.env.PLAYGROUND_ID)
+  {
+    errorMessage += '\nThe PLAYGROUND_ID GitHub secret must be defined.  The PLAYGROUND_ID is the ID of the Docassemble suite to run.'
+  }
+  if (!process.env.SERVER_URL && !process.env.BASE_URL)
+  {
+    errorMessage += `\nThe SERVER_URL GitHub secret must be defined. The SERVER_URL is the URL of the Docassemble Server where the tests should be run.`;
+  }
+  if (!process.env.REPO_URL)
+  {
+    errorMessage += `\nThe REPO_URL GitHub secret must be defined. The REPO_URL is the URL to the Git repo whose Actions are being run.`;
+  }
+  if (!process.env.BRANCH_PATH && !process.env.BRANCH_NAME)
+  {
+    errorMessage += `\nThe BRANCH_NAME environment variable must be defined. The BRANCH_NAME is the name of the repository branch that should be pulled into the docassemble project.`;
+  }
+
+  errorMessage = errorMessage.trim();
+
+  if (errorMessage !== '') {
+    throw new ReferenceError(errorMessage);
+  }
+};
+  
+session_vars.validateEnvironment();
+
+session_vars.get_dev_api_key = function () { return process.env.DOCASSEMBLE_DEVELOPER_API_KEY; };
+session_vars.get_da_server_url = function () {
+  let url = process.env.SERVER_URL || process.env.BASE_URL;
+  return url.replace(/\/$/g, '');  // Remove any trailing slash for safety
+};
+session_vars.get_debug = function () { return process.env.DEBUG; };
+session_vars.get_repo_url = function () { return process.env.REPO_URL; };
+// missing/moving functionality:
+// getBaseInterviewURL
+// Project name setting/getting
+// Playground id functionality needs to be transfered to api requests
+
+
+session_vars.get_branch_name = function () {
+  /* Get the name of the repository's branch that is being tested */
+  let branch_name = null;
+  if ( process.env.BRANCH_PATH ) {
+      branch_name = process.env.BRANCH_PATH.replace( `refs/head/`, '' );
+  } else if ( process.env.BRANCH_NAME ) {
+    branch_name = process.env.BRANCH_NAME;
+  }
+  return branch_name;
+};
+
+session_vars.get_project_base_name = function () {
+  /* Make an un-incremented project name based on the repo name and branch name. */
+  let repo_url_without_trailing_slash = session_vars.get_repo_url().replace(/\/$/, '');
+  let repo_name_parts = repo_url_without_trailing_slash.split('/');
+  let package_name = repo_name_parts[ repo_name_parts.length - 1 ];
+
+  let name = `testing${ package_name }${ session_vars.get_branch_name() }`;
+  let sanitized_name = name.replace( /[^A-Za-z0-9]/g, '' );
+  return sanitized_name;
+};
+
+// // Notes: We were using `new_session=1` in the url args, but it wasn't
+// // always working. The idea was to save each session so we could look
+// // back on it if needed. Aside from the fact that you usually need to log in
+// // to make the sessions retrievable (though if you're using `interview_list()`
+// // you can get them anyway), it also has inconsistent behavior when
+// // `sessions are unique`` or `temporary session` or use `interview_list()`
+// // and/or respond immediately with a `command()`. Three ways to avoid this:
+// // 1. x Start a new browser instead of just a new page each time. Lengthens the tests.
+// // 1. √ Visit `/user/sign-out` (needed even if the user is not logged in)
+// // 1. x (seems to be causing a 'Unable to locate interview session' error
+// // instead) Use `reset=2` instead , which will not save the previous session at all. It
+// // Will not just restart any existing interview sessions, it will also
+// // clear out the browser session's memory of what other interviews the user has
+// // visited in the same browser session_vars.
+// session_vars.getBaseInterviewURL = function () {
+//   /* Return the part of the interview URL that comes before the filename.
+//   * Depends on the project name, which may have been changed. */
+//   let new_session = `/interview?new_session=1&i=docassemble.playground`;
+//   return `${ session_vars.BASE_URL }${ new_session }${ session_vars.PLAYGROUND_ID }${ session_vars.getProjectName() }%3A`;
+// };
+// // session_vars.BASE_INTERVIEW_URL = session_vars.getBaseInterviewURL();
+
+
+session_vars.get_languages = function () {
+  /* Returns an array of strings, names of languages that should be tested. */
+
+  // These are assumed to be the words that are on the buttons or links
+  // that change the language of the interview. Have not yet detected
+  // another distinguishing feature
+  // Need to research using the language url param instead.
+  let langs = [];
+  if ( process.env.EXTRA_LANGUAGES && process.env.EXTRA_LANGUAGES !== 'default' ) {
+    langs = process.env.EXTRA_LANGUAGES.split(', ');
+  }
+  return langs;
+};  // Ends session_vars.get_languages()
+
+
+const project_name_file_path = `_al_test_project_name.json`;
+session_vars.save_project_name = function ( project_name ) {
+  /* Saves the name of the project to a file 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 */
+
+  // Warn local developers if file already exists
+  if ( fs.existsSync( project_name_file_path ) ) {
+    let old_project_name = session_vars.get_project_name();
+    let session_project_already_exists_msg = `ALKiln WARNING: `
+      + `This session had a project name already: ${ old_project_name }. `
+      + `A new project has now been created called ${ project_name }. `
+      + `Remember to delete ${ old_project_name }`;
+    console.warn( session_project_already_exists_msg );
+  }
+
+  let file = fs.writeFileSync( project_name_file_path, JSON.stringify( project_name ) );
+  if ( session_vars.get_debug() ) {
+    console.log( `ALKiln debug: Stored name of Project "${ project_name }" locally.` );
+  }
+  return file;
+};  // Ends save_project_name()
+
+session_vars.get_project_name = function () {
+  /* Get the name of the current project  */
+  let project_name =  JSON.parse( fs.readFileSync( project_name_file_path ));
+  if ( session_vars.get_debug() ) { console.log( `Project name from file is "${ project_name }".` ); }
+  return project_name;
+};  // Ends get_project_name()
+
+session_vars.delete_project_name = function () {
+  /* Delete the file storing the name of the docassemble project */
+  // Avoid race coditions possibly caused by checking for existence first
+  // Delete file if possible
+  try {
+    fs.unlinkSync( project_name_file_path );
+    console.log( `ALKiln: Deleted the file that stored the name of the Project.` );
+    return true;
+  } catch ( error ) {
+    console.warn( `ALKiln WARNING: Could not delete the Project name file. Error: ${ error }.` );
+    return false;
+  }
+};

package/lib/utils/time.js

@@ -0,0 +1,26 @@
+
+// We'll use a library if we need anything more complicated
+let time = {};
+module.exports = time;
+
+/**
+ * Causes your script to wait for the given number of milliseconds.
+ *
+ * @remarks
+ * From https://github.com/puppeteer/puppeteer/pull/6268/files#diff-94b4e5903a98ebf8e5f178eb3354b806fd2aed9c74a5022d88dcd24bc477a5aaR1096-R1100
+ *
+ * @example
+ *
+ * Wait for 1 second:
+ *
+ * ```
+ * await time.waitForTimeout( 1000 );
+ * ```
+ *
+ * @param milliseconds - the number of milliseconds to wait.
+ */
+time.waitForTimeout = function( milliseconds ) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+  });
+};

package/lib/world.js

@@ -1,4 +1,4 @@
-const { setWorldConstructor } = require('cucumber');
+const { setWorldConstructor } = require('@cucumber/cucumber');
 const puppeteer = require('puppeteer');
 const scope = require('./scope');
 
@@ -7,4 +7,4 @@ const World = function() {
   scope.context = {};
 };
 
-setWorldConstructor(World);
+setWorldConstructor( World );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "3.0.9",
+  "version": "4.0.0-pre-api.4",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {
@@ -11,8 +11,8 @@
     "langs_setup": "./lib/utils/langs.js 'tests/features/*.feature'",
     "langs_local": "npm run langs_setup && npm run local",
     "local": "npm run setup && npm run cucumber; npm run takedown",
-    "setup": "./lib/github_integration/setup.js",
-    "takedown": "./lib/github_integration/takedown.js",
+    "setup": "./lib/docassemble/setup.js",
+    "takedown": "./lib/docassemble/takedown.js",
     "unit": "mocha tests/unit_tests/*.test.*"
   },
   "repository": {
@@ -32,22 +32,23 @@
   "bugs": {
     "url": "https://github.com/SuffolkLITLab/alkiln/issues"
   },
-  "homepage": "https://github.com/SuffolkLITLab/alkiln#readme",
+  "homepage": "https://suffolklitlab.github.io/docassemble-AssemblyLine-documentation/docs/automated_integrated_testing",
   "dependencies": {
+    "@cucumber/cucumber": "^7.3.2",
+    "axios": "^0.24.0",
     "chai": "^4.2.0",
     "cheerio": "^1.0.0-rc.5",
-    "colors": "1.4.0",
-    "cucumber": "^6.0.5",
     "dotenv": "^8.2.0",
-    "mocha": "^7.2.0",
-    "puppeteer": "^3.1.0",
+    "mocha": "^9.2.0",
+    "puppeteer": "^13.1.3",
+    "qs": "^6.10.2",
     "sanitize-filename": "^1.6.3",
     "uuid": "^8.3.2"
   },
   "bin": {
-    "da-setup": "./lib/github_integration/setup.js",
-    "da-takedown": "./lib/github_integration/takedown.js",
-    "da-cucumber": "./lib/index.js",
-    "da-langs": "./lib/utils/langs.js"
+    "alkiln-setup": "./lib/docassemble/setup.js",
+    "alkiln-takedown": "./lib/docassemble/takedown.js",
+    "alkiln-cucumber": "./lib/index.js",
+    "alkiln-langs": "./lib/utils/langs.js"
   }
 }

package/tests/features/establishing_steps.feature

@@ -20,3 +20,18 @@ Scenario: I am able to set a custom wait time before an interview has been loade
 Scenario: Interview name includes url args
   Given I start the interview at "url_args.yml&from=theinternets&random=zoo"
   Then I should see the phrase "zoo"
+
+@slow @e4 @wait_first
+Scenario: I can wait as a first step in a test
+  Given I wait 1 second
+  
+@slow @e5 @wait_first
+Scenario: Interview name includes url args with a wait
+  Given I wait 1 second
+  Then I start the interview at "url_args.yml&from=theinternets&random=zoo"
+  Then I should see the phrase "zoo"
+
+@fast @e6 @signin
+Scenario: I sign in
+  Given I sign in with the email "USER1_EMAIL" and the password "USER1_PASSWORD"
+  And I start the interview at "all_tests"

package/tests/features/observation_steps.feature

@@ -95,3 +95,34 @@ Scenario: Test "Then I don’t continue" with an apostrophe
   And I tap to continue
   Then I don’t continue
   And I will be told an answer is invalid
+
+@fast @o9
+Scenario: I can match JSON page var to str
+  Given I start the interview at "all_tests.yml"
+  And I get to "showifs" with this data:
+    | var | value | trigger |
+    | double_quote_dict["double_quote_key"]['dq_two'] | true |  |
+    | checkboxes_other['checkbox_other_opt_1'] | true |  |
+    | dropdown_test | dropdown_opt_2 | |
+    | radio_yesno | False | false |
+    | radio_other | radio_other_opt_3 | |
+    | single_quote_dict['single_quote_key']['sq_two'] | true |  |
+    | text_input | Regular text input field value | |
+    | textarea | Multiline text\narea value | |
+    | date_input | today | |
+  Then the text in the JSON variable "dropdown_test" should be
+  """
+  dropdown_opt_2
+  """
+
+# Maybe this one should be in the report tests (as well?)
+@fast @o10 @json
+Scenario: I get the page's JSON
+  Given I start the interview at "all_tests"
+  Then I get the page's JSON variables and values
+
+@fast @o9
+Scenario: I take a screenshot
+  Given I start the interview at "all_tests"
+  Then I take a screenshot
+  Then I take a screenshot named "some-screenshot"