@suffolklitlab/alkiln 5.17.1 → 5.17.2-deps

package/.github/workflows/al_da_image_latest.yml

@@ -36,6 +36,17 @@ jobs:
           && github.event.pull_request.head.repo.fork
         )
     runs-on: ubuntu-latest
+
+    env:
+      NORMAL_USER_EMAIL: "alkiln@example.com"
+      NORMAL_USER_PASSWORD: "User123^"
+      WRONG_EMAIL: "wrong_email@example.com"
+      WRONG_PASSWORD: "wrong_password"
+      INVALID_API_KEY: "invalidAPIkey"
+      EMPTY_STRING: ""
+      SECRET_VAR1: "secret-var1-value"
+      SECRET_VAR2: "secret-var2-value"
+      SECRET_FOR_MISSING_FIELD: "secret for missing field"
       
     steps:
       # Place the root directory in this branch to access relative paths to
@@ -51,20 +62,70 @@ jobs:
       - run: echo "ALKiln finished starting the isolated GitHub docassemble server"
         shell: bash
 
+      - name: "Add a low-level user and their API key (in an env var)"
+        env:
+          SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
+          KEY: ${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}
+        run: |
+          # Create user and their API key
+
+          # Install json processor
+          sudo apt-get install jq
+
+          # https://docassemble.org/docs/api.html#user_new
+          user_data=$(curl -X POST \
+            ${{ env.SERVER_URL }}/api/user/new \
+            -H 'Content-Type: application/json' \
+            -d '{
+              "key": "${{ env.KEY }}",
+              "username": "${{ env.NORMAL_USER_EMAIL }}",
+              "password": "${{ env.NORMAL_USER_PASSWORD }}"
+            }')
+          echo "User data:"
+          echo "$user_data"
+
+          user_id=$(echo "$user_data" | jq '.user_id' -r)
+
+          # https://docassemble.org/docs/api.html#api_user_user_id_api_post
+          new_key_with_quotes=$(curl -X POST \
+            ${{ env.SERVER_URL }}/api/user/"$user_id"/api \
+            -H 'Content-Type: application/json' \
+            -d '{
+              "key": "${{ env.KEY }}",
+              "name": "alkiln_key",
+              "method": "none"
+            }')
+          echo "new key (watch out, this contains actual quotation marks): $new_key_with_quotes"
+          no_end_quote="${new_key_with_quotes%\"}"
+          unquoted="${no_end_quote#\"}"
+          echo "unquoted: $unquoted"
+
+          echo "NORMAL_USER_API_KEY=$unquoted" >> "$GITHUB_ENV"
+
       ## Optional debugging to explore things like docker issues
       #- name: Docker debug tmate session
       #  #if: ${{ failure() && github.event.inputs.enable_tmate == 'true' }}
       #  uses: mxschmitt/action-tmate@v3
 
-      - name: "ALKiln - Confirm docassemble packages get installed correctly"
+      - name: "Create other env vars for our own tests from server output"
+        run: |
+          echo "USER1_EMAIL=${{ steps.github_server.outputs.DA_ADMIN_EMAIL }}" >> $GITHUB_ENV
+          echo "USER1_PASSWORD=${{ steps.github_server.outputs.DA_ADMIN_PASSWORD }}" >> $GITHUB_ENV
+
+      - name: "ALKiln - Run if docassemble packages get installed correctly"
         if: ${{ success() }}
         id: alkiln
         uses: ./
+        env:
+          # Internal: docassemble changes sometimes break @a11y tests. That is
+          # a da problem, not ours. We will trigger these tests manually when we
+          # want to check up on this.
+          ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || '(not @error) and (not @temp_error)' }}"
         with:
           # Required inputs. See
           # https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#sandbox-inputs
           SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}"
           INSTALL_METHOD: "server"
-          ALKILN_TAG_EXPRESSION: "@e3"  # One very simple test
-          # ALKILN_VERSION: 
+          ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
+          # ALKIlN_VERSION:

package/.github/workflows/github_server.yml

@@ -159,7 +159,7 @@ jobs:
           #### Developer note: You can probably leave the rest out
           #### To learn more, see https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#optional-inputs
           ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
-          # ALKILN_VERSION:
+          # ALKIlN_VERSION:
 
       #### Developer note: Example of making an issue when tests fail
       #### that includes the text of the failure output file

package/.github/workflows/playground.yml

@@ -80,4 +80,4 @@ jobs:
           # want to check up on this.
           ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
           #### Developer note: You can probably leave this out
-          # ALKILN_VERSION:
+          # ALKIlN_VERSION:

package/CHANGELOG.md

@@ -21,6 +21,7 @@ Format:
 - 
 
 ## [1.0.0] - 2021-01-16
+
 ### Added
 - 
 
@@ -43,10 +44,49 @@ Format:
 - 
 -->
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Changed
+
+- Updated many dependencies
+- Updated nodejs version
+
+## [5.17.2] - 2026-10-29
+
+### Added
+
+- Step `I continue` which taps the continue button expecting to navigate to a new page in the interview. `I continue` and `I can't continue` should together replace the behaviors of `I tap to continue`.
+- Step `I can't continue` which taps the continue button expecting to fail to navigate. It passes when there are invalid answers or when a continue button is missing. It fails on other errors, like system errors (including Assembly Line custom errors) and timeout errors. Those types of errors should always fail across the whole framework. An author could use `I can't continue` to check that the interview correctly indicated one or more invalid answers. This replaces the practice of using `I tap to continue` twice.
+
+### Changed
+
+- Part 2 of detecting custom AL error screen (final part): Though `I tap to continue` allows invalid answers again, it throws on other errors, like system errors (including Assembly Line custom errors) and timeout errors. Those types of errors should always fail across the whole framework. It also throws if the continue button is missing. See [#656](https://github.com/SuffolkLITLab/ALKiln/issues/656).
+- Extended error message when the test causes a docassemble system error page (like syntax errors, etc.) It now should contain some of the relevant contents of the page.
+- Tweaked other log messages.
+
+### Fixed
+
+- Restored the documented behavior of `I tap to continue`. Specifically, the documentation describes using `I tap to continue` to potentially trigger invalid answers. To do this, these commits re-implement old behavior - `I tap to continue` never fails with invalid answers or missing continue-type buttons. Does add a small change - `I tap to continue` now throws on other errors, like system errors and timeout errors. Those types of errors should always fail across the whole framework. Note: A different behavior was proposed where an author could tap to continue once and be guaranteed no failures and then fail on a second tap to the same page. There are situations in which this would break potentially live tests. For example, an author could test multiple invalid answers in a row for the same field by cycling through `I tap to continue` and `I should see the phrase`. The proposed change would break those tests. The `I tap to continue` Step does now log its deprecation, as well as copious warnings with invalid answers or ambiguous lack of navigation. See [#1125](https://github.com/SuffolkLITLab/ALKiln/issues/1125).
+- Ensured new file upload buttons don't warn about duplicates since they have the same selectors.
+- Restored wait for file upload completion signals. See [#1125](https://github.com/SuffolkLITLab/ALKiln/issues/1125).
+
+### Internal
+
+- Fixed confusing error message when tests expected to fail actually pass.
+- Started refactoring navigation functions to start untangling that rat's nest formed by overlapping motivations.
+- Refactored getting different types of page errors (system error pages vs. user errors.)
+- Started refactoring out `scope.examinePageID()` which is currently doing too many things.
+- Added tests
+- Fixed check for previous filenames on file uploads. See [#1125](https://github.com/SuffolkLITLab/ALKiln/issues/1125).
+- Removed `shared_names` from global scope. See [#1125](https://github.com/SuffolkLITLab/ALKiln/issues/1125).
+- Use latest AL docassemble image to run all tests instead of just one.
 
 ## [5.17.1] - 2026-10-13
 
+### Added
+
+- Added the `I can't continue` Step to assert that pressing the continue button fails to continue. That press should allow the author to then check for invalid answers. Using `I can't continue` once should replace the practice of using `I tap to continue` twice.
+
 ### Changed
 
 - Updated to work with docassemble v1.10.n while being backwards compatible. See [issue #1117](https://github.com/SuffolkLITLab/ALKiln/issues/1117)
@@ -57,13 +97,13 @@ Format:
   - Unable to sign with a name
   - Unable to upload files
   - Created infinite loop with 'Restart' button
-- Changed the internal behavior of the experimental Step "I can't continue" from testing for errors after the previous Step (whatever it happened to be) to attempting to continue. Failure to continue causes success of the Step.
+- Changed the internal behavior of the experimental Step `I can't continue` from testing for errors after the previous Step (whatever it happened to be) to attempting to continue. Failure to continue causes success of the Step.
 
 ### Internal
 
 - Added a workflow to test using an Assembly Line docker image
 - Test using a cron job to catch failures more regularly
-- Remove unsupported Step "Then I arrive at the next page" and moved responsibility to Steps that imply they navigate
+- Remove unsupported Step `Then I arrive at the next page` and moved responsibility to Steps that imply they navigate
 - Fixed typo in fixture
 
 ## [5.17.0] - 2026-09-10
@@ -75,7 +115,7 @@ Format:
 ### Fixed
 
 - Fixed GitHub+You action outdated docassemble cli version causing Scenario timeouts.
-- Part 1 of detecting custom AL error screen: Story Table now catches `al_custom_error_screen` error. Previously, Story Tables that ran into this screen would get stuck on the AL error page infinitely. Next steps: Linear Steps may need additional development. Currently linear Steps succeed even when they run into AL's error page. That bears additional discussion. See [issue #656](https://github.com/SuffolkLITLab/ALKiln/issues/656) and [PR #1116](https://github.com/SuffolkLITLab/ALKiln/pull/1116).
+- Part 1 of detecting custom AL error screen: Story Table now catches `al_custom_error_action` error. Previously, Story Tables that ran into this screen would get stuck on the AL error page infinitely. Next steps: Linear Steps may need additional development. Currently linear Steps succeed even when they run into AL's error page. That bears additional discussion. See [issue #656](https://github.com/SuffolkLITLab/ALKiln/issues/656) and [PR #1116](https://github.com/SuffolkLITLab/ALKiln/pull/1116).
 
 ### Internal
 

package/action.yml

@@ -113,7 +113,7 @@ runs:
     - name: "💡 ALK0025 INFO: Set up node"
       uses: actions/setup-node@v6
       with:
-        node-version: "24.x"
+        node-version: "26.x"
         package-manager-cache: false
 
     - name: "💡 ALK0026 INFO: Install ALKiln directly from npm"

package/docs/decisions/017_post_navigation_custom_behavior_2026_10_26.md

@@ -0,0 +1,136 @@
+# Post navigation custom behavior
+
+## Context and Problem Statement
+
+What architecture should we use to abstract custom behavior after navigation, like for invalid answers?
+
+At this time, we need to test for navigation failures in several different ways and in this specific order:
+
+1. A visible system error page, a **critical error**, trumps all other errors. Must always run.
+2. Invalid answers will offer more specific information than the handlers to come after. Optional and must allow custom handling (e.g. warning, failure.)
+3. A timeout with failed navigation is an otherwise invisible **critical error**, but doesn't have much information. Must always run.
+4. A final catchall navigation failure must allow custom handling (warning, failure, other) and has the least amount of information. Optional and must allow custom handling (e.g. warning, failure.)
+
+Requirements:
+
+- We must enforce test failure for all critical errors
+- We must allow custom behavior for other situations
+- Visible system errors must come first
+- The custom catchall failure must come last if the caller wants it
+
+```
+Navigation attempt
+    |
+Visible system error page – critical error, required
+    |
+Invalid answers? – optional
+    |
+Nav timeout – critical error, required
+    |
+Catch‑all? – optional
+```
+
+We currently have only 1 need for custom behavior - the "I tap to continue" Step. That Step must avoid a test failure for invalid answers or other non-critical non-navigation.
+
+Note that the default post-navigation functions are most strict and handle any kind of irregularity by throwing errors. They don't warn or skip checks.
+
+## Considered Options
+
+For each of these options, I'm assuming the caller passes in its desired post-navigation-attempt behavior as handler functions. Those post-navigation-attempt handlers will be called one after the other until finished. An error in one of the handlers will stop the execution of any further handlers. The handler arguments can be:
+
+1. A list of handlers that the deepest function calls after the navigation attempt is complete.
+2. Two individual handlers, one called after the page error handler, and the other called after the "timeout before navigation" error handler.
+3. Option 2, but each argument would be a list of handlers.
+4. Three lists of handlers with the error handlers running between them.
+
+Also considered, but dismissed on the spot:
+
+- Global state flags
+- Caller passes in flags instead of functions
+- The caller has a choice of top-level functions to call, each of which duplicates the initial required navigation behavior followed by a different variation on the post-navigation-attempt behavior 🤪
+
+## Decision Outcome
+
+We will use option 1, the caller passes a list of all the functions to run after attempted navigation. I'm most compelled by the second "pro" for option 1. That is, this option keeps the flow of the logic visible in one place at the highest level possible.
+
+## Implementation
+
+The deepest navigation logic is in `scope.wait_until_continued()`, which will accept, among other arguments, the list of handlers described in option 1. For the purposes of the rest of this documentation, I will use the name `post_navigation_handlers` as the name for the parameter containing the list of handlers from option 1.
+
+Pseudo-code for one possible simplified implementation where most names are examples:
+
+```js
+function top_caller() {
+  const post_navigation_handlers = [
+    throw_on_page_system_error,
+    warn_on_invalid_answers,
+    throw_on_nav_timeout,
+    warn_on_unspecified_non_navigation,
+  ];
+  await scope.first_chain_method( post_navigation_handlers );
+};
+
+// In `scope.js`
+
+const scope = {
+  first_chain_method: async ( post_navigation_handlers=null ) => {
+    await scope.wait_until_continued( post_navigation_handlers );
+  },
+  wait_until_continued: async ( post_navigation_handlers=null ) => {
+    post_navigation_handlers ??= [
+      throw_on_page_system_error,
+      throw_on_invalid_answers,
+      throw_on_nav_timeout,
+      throw_on_unspecified_non_navigation,
+    ];
+    // Other logic
+    for ( const handler of post_navigation_handlers ) {
+      await handler( shared_arguments );
+    }
+  },
+}
+```
+
+As shown in the example, when the navigation attempt is finished, `scope.wait_until_continued()` will loop through `post_navigation_handlers`, calling each one in succession until one triggers an error or until it has called all the handlers. We will not handle catching any errors to let failing tests fail properly.
+
+As shown in the example, sometimes `scope.wait_until_continued()` comes at the end of a chain of method calls. We will need to pass `post_navigation_handlers` down through all that chain. `scope.wait_until_continued()` will use a nullish coalescer to set the default handlers list. Because of that, when destructuring parameters, any method that doesn't need to override the final handlers should use `null` as its own default value for the handlers list. Passing `null` will allow the next method in the chain to use its own default handlers list.
+
+As option 1 describes, a risk of this approach is that we will forget to include the critical error throwers in `post_navigation_handlers`. We will implement a validator that checks for the presence of the required functions.
+
+## Pros and Cons of the Options
+
+### 1. A list of handlers
+
+The caller passes in a list of all the functions they want run once the navigation attempt is complete.
+
+Pros:
+1. Seems more straightforward and consistent.
+2. The behavior is less buried. We can see the flow of functions in one place.
+
+Cons:
+1. We duplicate handing in the required failure handlers.
+2. This might be going too far, providing more flexibility than we really need.
+3. A possible risk is writing a caller that doesn't include the critical error throwers.
+
+### 2. 2 separate handlers
+
+The caller passes in 2 handlers. We call the visible system error, then the 1st function, then we call the timeout error, and finally we call the 2nd function.
+
+Pros:
+1. Enforces required failures so no one else has to think about them.
+
+Cons:
+1. Much less flexible. In future, will we want to handle something before the visible system failure?
+2. The complex logic is buried in the most nested part of the code that runs.
+
+### 3. 2 lists of handlers
+
+The caller passes in 2 lists of handlers. We call the visible system error, then the first list of function, then the timeout navigation, then the last list of handlers.
+
+Pros:
+1. More flexible than option 2.
+2. Still enforces strict failures.
+
+Cons:
+1. Again, hidden complexity.
+2. Preemptive flexibility that we don't need yet.

package/lib/run_cucumber.js

@@ -36,7 +36,7 @@ function build_config() {
 
   const config = {
     publishQuiet: true,
-    require: `./lib/index.js`,
+    require: [ `./lib/index.js` ],
     format: [`progress`, `summary:${ SUMMARY_FILENAME }`],
     paths: feature_paths,
     retry: 1,