@suffolklitlab/alkiln 3.0.9

package/lib/utils/env_vars.js

@@ -0,0 +1,173 @@
+const fs = require('fs');
+
+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 are on their own.
+ */
+
+/* This file provides both `process.env` variables and other variables
+*    that are needed in a similar way, but are not `process.env` variables themselves,
+*    though they are based on the `process.env` variables.
+* 
+* The alternative seems to be some `process.env` type variables and some `foo`
+*    variables without great ways to differentiate between them. That or duplicate
+*    fiddly work in multiple files.
+* 
+* The need to get and set project name, etc. makes me wonder if we should create
+* a class with getters and setters, but general wisdom is that it's a bad idea and
+* maybe it comes to mind because I'm used to asking for `env_vars.CAPS_CASE`. Another
+* alternative is `env_vars.get( 'CAPS_CASE' )` and `env_vars.set( 'CAPS_CASE', 'value' )`
+*/
+
+// DEBUG is not required.
+
+const env_vars = {
+  PLAYGROUND_ID: process.env.PLAYGROUND_ID,
+  PLAYGROUND_EMAIL: process.env.PLAYGROUND_EMAIL,
+  PLAYGROUND_PASSWORD: process.env.PLAYGROUND_PASSWORD,
+  BASE_URL: process.env.BASE_URL,
+  REPO_URL: process.env.REPO_URL,
+  DEBUG: process.env.DEBUG,
+};
+
+/** 
+ * For each field in env_vars, check if the value is defined in an environment
+ * variable, and throw an exception if it is not.
+ * 
+ * @throws ReferenceError with a message for all missing variables. 
+ */
+ env_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.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.PLAYGROUND_EMAIL)
+  {
+    errorMessage += '\nThe PLAYGROUND_EMAIL GitHub secret must be defined.  The PLAYGROUND_EMAIL is the e-mail address of the test user to run the Docassemble suite.'
+  }
+  if (!process.env.PLAYGROUND_PASSWORD)
+  {
+    errorMessage += '\nThe PLAYGROUND_PASSWORD GitHub secret must be defined.  The PLAYGROUND_PASSWORD is your test user\'s password for the test suite.'
+  }
+  if (!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.`;
+  }
+
+  errorMessage = errorMessage.trim();
+
+  if (errorMessage !== '')
+    throw new ReferenceError(errorMessage);
+};
+  
+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 }`)
+  }
+};
+
+// 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.
+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`;
+};
+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 = [];
+}
+
+
+module.exports = env_vars;

package/lib/utils/langs.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+let _path = require('path');
+let fs = require('fs');
+let glob = require('glob');
+
+let env_vars = require('./env_vars');
+
+// Get the glob filepaths to find all the test files
+let dir_root = process.env.INIT_CWD;  // Path to root of project
+let test_glob = process.argv[2];  // String of glob (regex for filepaths)
+let filepaths = glob.sync( _path.resolve( dir_root, test_glob ) );
+let flag = '_lang_';
+
+let langs = env_vars.EXTRA_LANGUAGES;
+
+// Generate new language files
+for ( let full_path of filepaths ) {  // Handle old language files before creating new ones.
+  
+  // Don't apply this to the example test that this package always provides
+  if ( full_path.includes( 'example_test.feature' )) { continue; }
+
+  // Delete alredy existing non-default language files and skip the rest of this. For example,
+  // if 3 languages were tested previously and now only two are being tested.
+  if ( full_path.includes( flag )) {
+      fs.unlinkSync( full_path );
+      continue;
+  }
+
+  for ( let lang of langs ) {  // Create new language files
+    // Get and change the text from the file to add the language to it
+    let data = fs.readFileSync( full_path, 'utf8' );
+    let result = data.replace(/(Given I start the interview.*$)/gm, `$1 in lang "${ lang }"`);
+
+    // Unicode category for NOT language characters \P{L}
+    const lang_escaped = lang.replace(/(\P{L})+/gu, '_');
+
+    // append generated language tags to existing Feature tags if they exist
+    const tags_regex = /(?:(?<tags>@.*)\n)?(?=Feature:)/;
+    result = result.replace(tags_regex, (_, tags) =>  `${tags ? tags + ' ' : ''}@generated @lang @${ lang_escaped }\n`);
+
+    // Save the file to the same folder with a new name indicating the language
+    let test_dir = _path.dirname( full_path );
+    // Put it alphabetically next to its matching tests by starting with the same name (discuss)
+    let orig_filename = _path.basename( full_path ).replace('.feature', '');
+    let filename = `${ orig_filename }${ flag }${ lang_escaped }.feature`;
+    let fullPath = _path.resolve( test_dir, filename );
+    // Always overwrite previous versions of the file if they exist
+    fs.writeFileSync(fullPath, result, { encoding:'utf8', flag:'w' });
+  }
+}

package/lib/world.js

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@suffolklitlab/alkiln",
+  "version": "3.0.9",
+  "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
+  "main": "lib/index.js",
+  "scripts": {
+    "test": "npm run unit && npm run langs_setup && npm run cucumber -- $@",
+    "cucumber_base": "./node_modules/.bin/cucumber-js --require ./lib/index.js",
+    "cucumber": "run_cucumber(){ npm run cucumber_base -- \"$@\" tests/features/*.feature; }; run_cucumber",
+    "langs": "npm run langs_setup && ./node_modules/.bin/cucumber-js --require ./lib/index.js tests/features/*_lang*.feature",
+    "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",
+    "unit": "mocha tests/unit_tests/*.test.*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SuffolkLITLab/alkiln.git"
+  },
+  "keywords": [
+    "docassemble",
+    "cucumber",
+    "puppeteer",
+    "automated testing",
+    "integrated testing",
+    "chai"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/SuffolkLITLab/alkiln/issues"
+  },
+  "homepage": "https://github.com/SuffolkLITLab/alkiln#readme",
+  "dependencies": {
+    "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",
+    "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"
+  }
+}

package/tests/features/assembly_line.feature

@@ -0,0 +1,43 @@
+@assembly_line
+Feature: Assembly Line package-specific Steps
+
+# In tag names, 'al' is for 'assembly line'
+
+# Note: the first test for this suite is the first test in this file and we're having timeout issues, so we're trying to give the server longer to load.
+
+@fast @al1
+Scenario: I have two name parts
+  Given the max secs for each step is 120
+  Given I start the interview at "AL_tests"
+  And I set the name of "users[0]" to "Uli User"
+  And I tap to continue
+  And I set the address of "users[0]" to "120 Tremont Street, Unit 2, Boston, MA 02108"
+  And I tap to continue
+  And I set the name of "users[1]" to "Uli2 User2"
+  And I set the var "users[i].proxy_var" to "Mixed proxy var step test"
+  And I tap to continue
+  Then the question id should be "end"
+
+@fast @al2
+Scenario: I have three name parts
+  Given I start the interview at "AL_tests"
+  And I set the name of "users[0]" to "Uli Udo User"
+  And I tap to continue
+  And I set the address of "users[0]" to "120 Tremont Street, Unit 2, Boston, MA 02108"
+  And I tap to continue
+  And I set the name of "users[1]" to "Uli2 User2"
+  And I set the var "users[i].proxy_var" to "Mixed proxy var step test"
+  And I tap to continue
+  Then the question id should be "end"
+
+@fast @al3
+Scenario: I have four name parts
+  Given I start the interview at "AL_tests"
+  And I set the name of "users[0]" to "Uli Udo User Sr"
+  And I tap to continue
+  And I set the address of "users[0]" to "120 Tremont Street, Unit 2, Boston, MA 02108"
+  And I tap to continue
+  And I set the name of "users[1]" to "Uli2 User2"
+  And I set the var "users[i].proxy_var" to "Mixed proxy var step test"
+  And I tap to continue
+  Then the question id should be "end"

package/tests/features/establishing_steps.feature

@@ -0,0 +1,22 @@
+@establishing
+Feature: Establishing steps
+
+Steps that establish things about the state of the test
+# In tag names, 'e' is for 'establishing'
+
+@slow @e1
+Scenario: I am able to set a custom wait time that allows steps to run longer than the half minute default
+  Given I start the interview at "all_tests"
+  And the max seconds for each step in this scenario is 40
+  And I wait 35 seconds
+
+@slow @e2
+Scenario: I am able to set a custom wait time before an interview has been loaded
+  Given the max seconds for each step in this scenario is 40
+  And I start the interview at "all_tests"
+  And I wait 35 seconds
+
+@fast @e3 @urlargs
+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"

package/tests/features/example_test.feature

@@ -0,0 +1,11 @@
+@example_feature_tag
+Feature: An example test
+
+The tests in this file should cover
+- [x] Provide a template people can use to make their own tests.
+- [ ] Direct people to more documentation.
+- [ ] Find the ultimate question to life, the universe, and everything.
+
+@example_scenario_tag
+Scenario: Server finishes reloading
+  Given I start the interview at "test"

package/tests/features/interactive_steps.feature

@@ -0,0 +1,85 @@
+@interactive
+Feature: Interactive steps
+
+# In tag names, 'i' is for 'interactive'
+
+@slow @i1
+Scenario: I set text-type values
+  Given I start the interview at "all_tests"
+  Then the question id should be "upload files"
+  When I set the var "upload_files_visible" to "some_png_1.png, some_png_2.png"
+  And I set the var "show_upload" to "True"
+  And I upload "some_png_2.png,some_png_1.png" to "upload_files_hidden"
+  And I tap to continue
+  # Next page
+  Then the question id should be "group of complex fields"
+  And I set the var "double_quote_dict['double_quote_key']['dq_two']" to "true"
+  And I set the var "single_quote_dict['single_quote_key']['sq_two']" to "true"
+  And I tap to continue
+  Then the question id should be "direct standard fields"
+  # Next page
+  When I set the var "checkboxes_yesno" to "True"
+  And I set the var "checkboxes_other['checkbox_other_opt_1']" to "true"
+  And I set the var "dropdown_test" to "dropdown_opt_2"
+  And I set the var "radio_yesno" to "False"
+  And I set the var "radio_other" to "radio_other_opt_3"
+  And I set the var "text_input" to "Regular text input field value"
+  And I set the var "textarea" to "Multiline text\narea value"
+  And I set the var "date_input" to "today - 1"
+  When I set the var "direct_standard_fields" to "True"
+  # Next page
+  Then the question id should be "showifs"
+  When I set the var "show_2" to "True"
+  And I set the var "show_3" to "True"
+  And I set the var "showif_checkbox_yesno" to "true"
+  And I set the var "showif_checkboxes_other['showif_checkboxes_nota_2']" to "true"
+  And I set the var "showif_checkboxes_other['showif_checkboxes_nota_3']" to "true"
+  And I set the var "showif_yesnoradio" to "True"
+  And I set the var "showif_radio_other" to "showif_radio_multi_2"
+  And I set the var "showif_text_input" to "Show if text input value"
+  And I set the var "showif_textarea" to "Show if\nmultiline text\narea value"
+  And I set the var "showif_dropdown" to "showif_dropdown_1"
+  When I tap to continue
+  # Next page
+  Then the question id should be "buttons yesnomaybe"
+  When I set the var "buttons_yesnomaybe" to "None"
+  # Next page
+  Then the question id should be "buttons other"
+  When I set the var "buttons_other" to "button_3"
+  # Next page
+  Then the question id should be "button continue"
+  When I set the var "button_continue" to "True"
+  # Next page
+  Then the question id should be "screen features"
+  When I tap to continue
+  # Next page
+  Then the question id should be "proxy vars"
+  When I set the var "x[i].name.first" to "Proxyname1"
+  And I tap to continue
+  # Next page
+  Then the question id should be "is there another generic"
+  When I set the var "x.there_is_another" to "True"
+  # Next page
+  Then the question id should be "proxy vars"
+  When I set the var "x[i].name.first" to "Proxyname2"
+  And I tap to continue
+  # Next page
+  Then the question id should be "is there another generic"
+  When I set the var "x.there_is_another" to "False"
+  # Next page
+  Then the question id should be "first signature"
+  When I sign
+  And I tap to continue
+  # Next page
+  Then the question id should be "second signature"
+  When I sign
+  And I tap to continue
+  # Next page
+  Then the question id should be "simple doc"
+  When I download "simple-doc.pdf"
+  And I tap to continue
+  # Next page
+  Then the question id should be "button event action"
+  And I tap to continue
+  # Next page
+  Then the question id should be "the end"

package/tests/features/observation_steps.feature

@@ -0,0 +1,97 @@
+@observation
+Feature: Observational steps
+
+# In tag names, 'o' is for 'observational'
+
+@fast @o1
+Scenario: I observe things on a single page when I arrive
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  Then the question id should be "group of complex fields"
+  And I should see the phrase "Some complex fields"
+  And I SHOULD see the phrase "Some complex fields"
+  And I should not see the phrase "zzzzzzz"
+  And I should NOT see the phrase "zzzzzzz"
+  And an element should have the id "daform"
+
+@fast @o2
+Scenario: I see user errors.
+#  They're everywhere.  Some don't even know they are errors.
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  And I tap to continue
+  And I tap to continue
+  Then I can't continue
+  And I will be told an answer is invalid
+
+@fast @o3
+Scenario: I can include .yml in the filename
+  Given I start the interview at "all_tests.yml"
+
+@slow @o4
+Scenario: I check navigation
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  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 I arrive at the next page
+  Then I get to "screen features" with this data:
+    | var | value | trigger |
+    | button_continue | True |  |
+    | buttons_other | button_2 |  |
+    | buttons_yesnomaybe | True |  |
+  And I should see the link to "http://ecosia.org/"
+
+@fast @o4
+Scenario: Test "Then I don't continue" with a single quote
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  And I tap to continue
+  And I tap to continue
+  Then I don't continue
+  And I will be told an answer is invalid
+
+@fast @o5
+Scenario: Test "Then I cannot continue"
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  And I tap to continue
+  And I tap to continue
+  Then I cannot continue
+  And I will be told an answer is invalid
+
+@fast @o6
+Scenario: Test "Then I do not continue"
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  And I tap to continue
+  And I tap to continue
+  Then I do not continue
+  And I will be told an answer is invalid
+
+@fast @o7
+Scenario: Test "Then I can’t continue" with an apostrophe
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  And I tap to continue
+  And I tap to continue
+  Then I can’t continue
+  And I will be told an answer is invalid
+
+@fast @o8
+Scenario: Test "Then I don’t continue" with an apostrophe
+  Given I start the interview at "all_tests"
+  And I tap to continue
+  And I tap to continue
+  And I tap to continue
+  Then I don’t continue
+  And I will be told an answer is invalid