@suffolklitlab/alkiln 4.11.5 → 5.0.0-experimental1

package/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+In this PR, I have:
+
+* [ ] Added tests for any new features or bug fixes (if relevant)
+* [ ] Added my changes to the CHANGELOG.md at the top, under the "Unreleased" section
+* [ ] Ensured issues that this PR closes will be [automatically closed](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
+
+### Reason for this PR
+
+<Insert reasons for this PR>
+
+### Links to any solved or related issues
+
+<Insert links>
+
+### Any manual testing I have done to ensure my PR is working
+
+<Insert description>

package/.github/workflows/test_tests.yml

@@ -20,7 +20,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [17.x]
+        node-version: [18.x]
 
     env:
       BASE_URL: ${{ secrets.SERVER_URL }}
@@ -34,6 +34,7 @@ jobs:
       SECRET_VAR1: secret-var1-value
       SECRET_VAR2: secret-var2-value
       SECRET_FOR_MISSING_FIELD: secret for missing field
+      _ORIGIN: github
 
     name: Run Puppeteer tests
     steps:
@@ -52,24 +53,24 @@ jobs:
       # For the testing repo, the `REPO_URL` is that of a different repo and is created in `env:`
       - run: echo "Repo address is $REPO_URL"
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Setup environment
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm install
       - run: npm run setup
-      - run: npm run test -- ${{ github.event.inputs.tags && format('"--tags" "{0}"', github.event.inputs.tags) }}
+      - run: npm run test ${{ github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
       # Artifacts
       - name: upload unit tests artifacts folder
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         # This will upload even if a previous step has failed
         if: ${{ always() }}
         with:
           name: ${{ env.UNIT_TESTS_ARTIFACT_NAME }}
           path: ./_alkiln-*
       - name: upload integration tests artifacts folder
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         if: ${{ always() }}
         with:
           name: ${{ env.ARTIFACT_NAME }}

package/CHANGELOG.md

@@ -38,26 +38,36 @@ Format:
 ### Security
 - 
 -->
-<!-- ## [Unreleased] -->
-
-## [4.11.4] - 2023-04-19
-### Fixed
-- Shorten path names to try to accommodate limitations of windows systems while still keeping enough useful information to help devs identify the test outputs. https://github.com/SuffolkLITLab/ALKiln/issues/618
+## [Unreleased]
+### Added
+- added additional functionality to the sign method to allow developers to take a name argument to sign on canvas: issue #596
+- A new script: `alkiln-run`, which acts like `npm run cucumber`, but can
+  be run in any directory, not just in an npm package.
+- Additional environment variables and their validation to allow for tests that run on a developer's server/Playground instead of through GitHub. Also, other functionality for that purpose. [Issue #661](https://github.com/SuffolkLITLab/ALKiln/issues/661)
+- Tests for new session_vars behavior and improve previous tests.
+- Adds `npm-shrinkwrap.json`, so installs from npm will have fixed version dependencies
 
-## [4.11.3] - 2023-04-06
 ### Changed
-- Project name prefix now includes ALKiln in it for clarity
+- BREAKING: the github action no longer runs `npm run XYZ`; it directly calls scripts,
+    e.g. `alkiln-setup`, `alkiln-run`, `alkiln-takedown`
+- upgraded cucumber v8.6.0
+- using cucumber's JS API to run tests. For more details on how it works,
+    see [the cucumber-js docs](https://github.com/cucumber/cucumber-js/blob/main/docs/javascript_api.md).
+- don't print the ["publish this cucumber report" message](https://github.com/cucumber/cucumber-js/blob/main/docs/configuration.md#options)
+- Adjusted validation of some environment variables to account for Playground vs. GitHub or local test runs. [Issue #661](https://github.com/SuffolkLITLab/ALKiln/issues/661)
+- Docassemble Project name prefix now includes ALKiln in it for clarity
 
 ### Fixed
 - Projects created in da each have a unique name. https://github.com/SuffolkLITLab/ALKiln/issues/663
+- Shorten path names to try to accommodate limitations of windows systems while still keeping enough useful information to help devs identify the test outputs. https://github.com/SuffolkLITLab/ALKiln/issues/618
+- Updated field decoding to handle new object field encoding. See [#711](https://github.com/SuffolkLITLab/ALKiln/issues/711)
+- Allows ALKilnInThePlayground to upload files. See https://github.com/SuffolkLITLab/docassemble-ALKilnInThePlayground/issues/18.
 
-## [4.11.2] - 2023-03-22
 ### Security
 - Pass docassemble API keys through HTTP headers instead of as parameters.
-  - ACTION: all users should delete any uWSGI logs that show their API keys.
   - Parameters to certain HTTP requests are printed directly in docassemble's
     uWSGI log, leaking API keys to actors with log access on your docassemble
-    server.
+    server
 
 ## [4.11.1] - 2023-03-21
 ### Changed
@@ -595,4 +605,4 @@ Format:
 - `example.feature` - an example test to get a project started
 - `github/workflows/run_form_tests.yml` - Automated github workflow to run tests when code is pushed and a manual trigger for testing without needing to push
 - `.gitignore` - ignores files that are generated by the tests and shouldn't be added to the repo
-- `package.json` - keep up-to-date version of this test repository and hold scripts that the automated tests run
+- `package.json` - keep up-to-date version of this test repository and hold scripts that the automated tests run

package/CONTRIBUTING.md

@@ -112,6 +112,12 @@ Our tests require the user/developer to have a docassemble server on which they
 
 When the developer commits code to GitHub, their account triggers our code, passing along variables that our code needs, like their GitHub secret of the API key for their docassemble server developer account.
 
+## Updating dependencies
+
+Sometimes you will have to add dependencies to ALKiln. You can do so by adding the dependency in the `package.json` "dependencies" section, specifying an exact version. Then, run `npm install` to update `npm-shrinkwrap.json` to have the new dependency.
+
+If you have to update an existing dependency, you can change the version in `package.json`, and run `npm install` to update `npm-shrankwrap.json`.
+
 ## Very general architecture of files and folders
 
 An honest look at our current project architecture—some of our files and folders, what they do, and how they interact.

package/action.yml

@@ -61,6 +61,7 @@ runs:
         echo "DOCASSEMBLE_DEVELOPER_API_KEY=${{ inputs.DOCASSEMBLE_DEVELOPER_API_KEY }}" >> $GITHUB_ENV
         echo "ALKILN_VERSION=${{ inputs.ALKILN_VERSION }}" >> $GITHUB_ENV
         echo "MAX_SECONDS_FOR_SETUP=${{ inputs.MAX_SECONDS_FOR_SETUP }}" >> $GITHUB_ENV
+        echo "_ORIGIN=github" >> $GITHUB_ENV
       shell: bash
     - name: "ALKiln: confirm info"
       run: |
@@ -68,64 +69,36 @@ runs:
         echo -e "\nALKiln version is $ALKILN_VERSION\nRepo is $REPO_URL\nBranch ref is $BRANCH_PATH\nMAX_SECONDS_FOR_SETUP is $MAX_SECONDS_FOR_SETUP\nManually added languages are $EXTRA_LANGUAGES\n"
       shell: bash
 
-    # This doesn't use an already established package-lock.json and that
-    # comes with some types of test breaking risks. Same problem as before.
-    - name: Temporarily overwrite or create package.json
-      run: |
-        cat << EOF > "package.json"
-        {
-          "scripts": {
-            "test": "npm run langs_setup && npm run cucumber -- $@",
-            "cucumber_base": "./node_modules/.bin/cucumber-js --require ./node_modules/@suffolklitlab/alkiln/lib/index.js",
-            "cucumber": "run_cucumber(){ npm run cucumber_base -- \"$@\" docassemble/*/data/sources/*.feature --retry 1; }; run_cucumber",
-            "langs": "npm run langs_setup && ./node_modules/.bin/cucumber-js --require ./node_modules/.bin/alkiln-cucumber docassemble/*/data/sources/*_lang*.feature",
-            "langs_setup": "node_modules/.bin/alkiln-langs 'docassemble/*/data/sources/*.feature'",
-            "setup": "node_modules/.bin/alkiln-setup",
-            "takedown": "node_modules/.bin/alkiln-takedown"
-          },
-          "dependencies": {
-            "colors": "1.4.0",
-            "@cucumber/cucumber": "7.3.2",
-            "@suffolklitlab/alkiln": "$ALKILN_VERSION"
-          }
-        }
-        EOF
-        # Keep in sync with the cucumber.js in root
-        cat << EOF > "cucumber.js"
-        module.exports = {
-          default: "--require ./lib/index.js --format progress --format summary:cucumber-report.txt"
-        }
-        EOF
-      shell: bash
-
     # Install node
     - name: "ALKiln: Install node packages"
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
-        node-version: "17"
-    - run: npm install
+        node-version: "18"
+    - name: Install ALKiln directly from npm
+      run: |
+        npm install -g github:SuffolkLITLab/ALKiln#v5
       shell: bash
 
     # Run tests
     - name: "ALKiln: Create a Project and pull the package from GitHub"
-      run: npm run setup
+      run: alkiln-setup
       shell: bash
     - name: "ALKiln: Run tests"
       if: ${{ success() }}
-      run: npm run test -- ${{ github.event.inputs.tags && format('"--tags" "{0}"', github.event.inputs.tags) }}
+      run: alkiln-run ${{ github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
       shell: bash
     - run: echo -e "\n\n====ALKiln could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
       if: ${{ failure() }}
       shell: bash
     - name: "ALKiln: Delete project from docassemble test account"
       if: ${{ always() }}
-      run: npm run takedown
+      run: alkiln-takedown
       shell: bash
     
     # Upload artifacts that subscribers can download on the Actions summary page
     - name: "ALKiln: Upload artifacts folder"
       if: ${{ always() }}
-      uses: actions/upload-artifact@v2
+      uses: actions/upload-artifact@v3
       with:
         name: ${{ env.ARTIFACT_NAME }}
         path: ./alkiln-*

package/lib/docassemble/docassemble_api_REST.js

@@ -27,7 +27,8 @@ da.get_dev_id = async function ( timeout ) {
   try {
     return await axios.request( options );
   } catch (error) {
-    throw {...error.toJSON(), data: error.response?.data};
+    let response = error.response || {data: null}
+    throw {...error.toJSON(), data: response.data};
   }
 };  // Ends da.get_dev_id()
 
@@ -48,7 +49,8 @@ da.create_project = async function ( project_name, timeout ) {
   try {
     return await axios.request( options );
   } catch (error) {
-    throw {...error.toJSON(), data: error.response?.data};
+    let response = error.response || {data: null}
+    throw {...error.toJSON(), data: response.data};
   }
 };  // Ends da.create_project()
 
@@ -71,7 +73,8 @@ da.pull = async function ( timeout ) {
   try {
     return await axios.request( options );
   } catch (error) {
-    throw {...error.toJSON(), data: error.response?.data};
+    let response = error.response || {data: null}
+    throw {...error.toJSON(), data: response.data};
   }
 };  // Ends da.pull()
 
@@ -92,7 +95,8 @@ da.has_task_finished = async function ( task_id, timeout ) {
   try {
     return await axios.request( options );
   } catch (error) {
-    throw {...error.toJSON(), data: error.response?.data};
+    let response = error.response || {data: null}
+    throw {...error.toJSON(), data: response.data};
   }
 };  // Ends da.has_task_finished()
 
@@ -113,7 +117,8 @@ da.delete_project = async function ( timeout ) {
   try {
     return await axios.request( options );
   } catch (error) {
-    throw {...error.toJSON(), data: error.response?.data};
+    let response = error.response || {data: null}
+    throw {...error.toJSON(), data: response.data};
   }
 };  // Ends da.delete_project()
 
@@ -142,7 +147,8 @@ da.__delete_projects_starting_with = async function ( base_name, starting_num=1,
 
       await axios.request( options );
     } catch ( error ) {
-      console.log( {...error.toJSON(), data: error.response?.data});
+      let response = error.response || {data: null}
+      console.log( {...error.toJSON(), data: response.data});
     }
     name_incrementor++;
   }

package/lib/docassemble/docassemble_api_interface.js

@@ -122,9 +122,15 @@ da_i.throw_an_error_if_server_is_not_responding = async function ( options ) {
 
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").is_server_responding()'
 da_i.is_server_responding = async function ( dev_id_options ) {
-  /** Use _da_REST.get_dev_id() to test if server is up.
+  /** For non-playground interviews, use _da_REST.get_dev_id() to
+  *    return if server is up. Otherwise, return true.
   *    See https://docassemble.org/docs/api.html#user. */
 
+  // Playground interview will itself timeout. No way to detect that.
+  if ( session_vars.get_origin() === 'playground' ) {
+    return true;
+  }
+
   // Default timeouts
   let { timeout } = dev_id_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
   try {
@@ -141,13 +147,28 @@ da_i.is_server_responding = async function ( dev_id_options ) {
 
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").get_dev_id()'
 da_i.get_dev_id = async function ( dev_id_options ) {
-  /** For consistency, wrap _da_REST.get_dev_id().
-  *    See https://docassemble.org/docs/api.html#user. */
+  /** Get user id, either from the server or from env vars (for Playground runs).
+  *    See https://docassemble.org/docs/api.html#user.
+  * 
+  * @param dev_id_options {obj} Options for getting dev_id
+  * @param dev_id_options.timeout {int} Required if options is defined. Max MS
+  *    to allow for server request.
+  */
 
-  // Default timeouts
-  let { timeout } = dev_id_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
-  let response = await _da_REST.get_dev_id( timeout );
-  return response.data.id;
+  let dev_id = null;
+
+  // For tests running in the dev Playground, use the appropriate env var
+  if ( session_vars.get_origin() === 'playground' ) {
+    dev_id = session_vars.get_user_id();
+
+  } else {
+    // Default timeouts
+    let { timeout } = dev_id_options ||  { timeout: DEFAULT_MAX_REQUEST_MS };
+    let response = await _da_REST.get_dev_id( timeout );
+    dev_id = response.data.id;
+  }
+  
+  return dev_id;
 };  // Ends da_i.get_dev_id();
 
 

package/lib/run_cucumber.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const log = require('./utils/log');
+const session_vars = require('./utils/session_vars');
+
+const cucumber_api = require('@cucumber/cucumber/api');
+
+(async function main() {
+  let argv = process.argv;
+
+  const environment = { cwd: process.cwd() };
+  console.log("alkiln-run: environment: %o", environment);
+  const provided_config = {
+    "publishQuiet": true,
+    "require": "./lib/index.js",
+    "format": ["progress", "summary:cucumber-report.txt"],
+    "paths": ["docassemble/*/data/sources/*.feature"],
+    "retry": 1,
+  }
+
+
+  // If they're running it from an interview on their server instead of from GitHub
+  if ( session_vars.get_origin() === `playground` ) {
+    provided_config.paths.push(`/usr/share/docassemble/files/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}/*.feature`);
+    // For S3
+    provided_config.paths.push(`/tmp/playgroundsources/${session_vars.get_user_id()}/${session_vars.get_user_project_name()}/*.feature`);
+  }
+
+  let tags = argv.slice(2);
+  if ( session_vars.get_origin() === `playground` ) {
+    tags = session_vars.get_tags();
+  }
+
+  if (tags.length > 0) {
+    // Cucumber expects tags in boolean expressions, like (@a0 or @a1) and @random.
+    // If we get a list of only tags, then "or" them all together
+    if (tags.every((val) => val.startsWith("@"))) {
+      provided_config.tags = tags.join(' or ');
+    }
+    // If we get a list of seemingly no tags, assume they meant to use tags
+    else if (tags.every((val) => !val.startsWith("@"))) {
+      provided_config.tags = tags.map((val) => "@" + val).join(' or ');
+    }
+    // If it's a mix of tags and no tags, it's probably a boolean expression!
+    else {
+      provided_config.tags = tags.join(' ');
+    }
+  }
+
+  const { runConfiguration } = await cucumber_api.loadConfiguration({
+    provided: provided_config
+  }, environment);
+  console.log("alkiln-run: runConfiguration: %o", runConfiguration);
+  var path = require('path');
+  var codeDir = path.dirname(require.main.filename);
+  const support = await cucumber_api.loadSupport({ support: {
+    requireModules: [`${ codeDir }/index.js`],
+    requirePaths: [ `${ codeDir }/index.js`],
+    importPaths: [],
+  }, sources: {paths: []}}, environment);
+
+  console.log("alkiln-run: working directory: %o", codeDir);
+  console.log(`\n\n`);
+
+  const { success } = await cucumber_api.runCucumber({...runConfiguration, support});
+  console.log("alkiln-run: success: %b", success);
+  const exitCode = success ? 0 : 1;
+  process.exitCode = exitCode;
+
+  // This is hardcoded information from `provide_config` above.
+  // This code isn't used for anything other than detecting and removing color codes.
+  let summary_file_name = 'cucumber-report.txt';
+  fs.readFile(summary_file_name, 'utf8', (err, data) => {
+    if (err) {
+      console.error(err);
+      return;
+    }
+
+    // Replace terminal color codes, if present
+    // https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797#colors--graphics-mode
+    data = data.replace(/\x1b\[[0-9][0-9]?[0-9]?m/g, '');
+
+    // Put it in the correct file in the correct folder
+    let artifacts_path = session_vars.get_artifacts_path_name();
+    fs.appendFileSync( `${ artifacts_path}/${ log.debug_log_file }`, data);
+  });
+})();

package/lib/scope.js

@@ -1212,7 +1212,7 @@ module.exports = {
     // Some fields have a key hidden inside them.
     // This gets the variable name before the final brackets, and the likely
     // still base64 encoded string inside the brackets
-    let before_and_in_brackets = expr_str.match( /^(.*)\[[BR]'(.*)'\]/ );
+    let before_and_in_brackets = expr_str.match( /^(.*)\[[BRO]'(.*)'\]/ );
 
     // Of the format `foo[B'encoded']` or `foo[R'encoded']`
     // The B means internal to docassemble, the encoded portion is a string,
@@ -1877,16 +1877,26 @@ module.exports = {
     }, 500)
   },
 
-  draw_signature: async function ( scope ) {
+  draw_signature: async function ( scope, name ) {
     /* On a signature page, there should only be a single signature canvas
     * and a continue button. Draw in the #dasigcanvas element. `<canvas>`
     * takes a while to load. */
-    let handle = await scope.page.waitForSelector( `#dasigcanvas` );
+    let canvas = await scope.page.waitForSelector( `#dasigcanvas` );
     let msg = `Could not find a signature field.`;
-    if ( !handle ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
-    expect( handle, msg ).to.exist;
-
-    let bounding_box = await handle.boundingBox();
+    if ( !canvas ) { await scope.addToReport(scope, { type: `error`, value: msg }); }
+    expect( canvas, msg ).to.exist;
+
+    // Provides functionality to draw name arg on canvas
+    if (name !== undefined) {
+      await scope.page.$eval(`#dasigcanvas`, (canvas, name) => {
+        const ctx = canvas.getContext("2d");
+        ctx.font = "24px serif";
+        ctx.fillText(name, 10, 50);
+      }, name);
+    }
+    let bounding_box = await canvas.boundingBox();
+    // We draw the dot because it allows the developer to tap continue
+    // Docassemble does not allow to tap continue unless the user interacts with the canvas
     await scope.page.mouse.move(bounding_box.x + bounding_box.width / 2, bounding_box.y + bounding_box.height / 2);
     await scope.page.mouse.down();
     // await scope.page.mouse.move(1, 1);  // Too big? Wait a while before drawing?
@@ -2415,9 +2425,9 @@ module.exports = {
       await scope.afterStep(scope, {waitForShowIf: true});
     },  // Ends scope.steps.tap_term()
 
-    sign: async ( scope ) => {
+    sign: async ( scope, name ) => {
       /** Sign on a signature page. */
-      await scope.draw_signature( scope );
+      await scope.draw_signature( scope, name );
       await scope.afterStep(scope);
     },  // Ends scope.steps.sign()
 

package/lib/steps.js

@@ -92,7 +92,7 @@ BeforeAll(async () => {
   // Make the folder to store all the files for this run of the tests
   scope.paths.artifacts = files.make_artifacts_folder();
   // Save its name in a file. `session_vars` can get it back later.
-  // This is used by at least clean_reports.js.
+  // The value we are saving is used by at least run_cucumber.js.
   session_vars.save_artifacts_path_name( scope.paths.artifacts );
 
   scope.paths.report = `${ scope.paths.artifacts }/report.txt`;
@@ -103,7 +103,14 @@ BeforeAll(async () => {
 Before(async (scenario) => {
   // Create browser, which can't be created in BeforeAll() where .driver doesn't exist for some reason
   if (!scope.browser) {
-    scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug(), devtools: session_vars.get_debug() });
+    if (session_vars.get_origin() === 'playground') {
+      // Will only run in the Playground outside of a sandbox. TODO: There's a
+      // better way to do this, though it's more complicated. See comments in
+      // https://github.com/SuffolkLITLab/ALKiln/issues/661
+      scope.browser = await scope.driver.launch({ args: ['--no-sandbox'] });
+    } else {
+      scope.browser = await scope.driver.launch({ headless: !session_vars.get_debug(), devtools: session_vars.get_debug() });
+    }
   }
   // Clean up all previously existing pages
   for (const page of await scope.browser.pages()) { 
@@ -973,13 +980,21 @@ When('I tap the defined text link {string}', { timeout: -1 }, async ( phrase ) =
   await scope.steps.tap_term( scope, phrase );
 });
 
-Then('I sign', { timeout: -1 }, async () => {
+Then(/^I sign$/, { timeout: -1 }, async () => {
   return wrapPromiseWithTimeout(
     scope.steps.sign( scope ),
     scope.timeout
   );
 });
 
+Then('I sign with the name {string}', { timeout: -1 }, async ( name ) => {
+  /* Signs with the string argument */
+  return wrapPromiseWithTimeout(
+    scope.steps.sign( scope, name ),
+    scope.timeout
+  );
+});
+
 When(/I download "([^"]+)"$/, { timeout: -1 }, async ( 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.