@suffolklitlab/alkiln 4.11.6 → 5.0.0-experimental2

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,30 +38,37 @@ Format:
 ### Security
 - 
 -->
-<!-- ## [Unreleased] -->
-
-## [4.11.5] - 2023-06-12
-### Fixed
-- Updated field decoding to handle new object field encoding. See [#711](https://github.com/SuffolkLITLab/ALKiln/issues/711)
-
-## [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.
+- Conform upload file behavior to that of other Story Table rows - avoid erroring when field isn't set properly unless using all variables is required.
 
-## [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
@@ -599,4 +606,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);
+  });
+})();