@suffolklitlab/alkiln 5.17.0 → 5.17.1-fix-stop-on-error-3

package/.github/workflows/{da_image_v_sha_7d13853.yml → al_da_image_latest.yml}

@@ -1,10 +1,13 @@
-name: Use docassemble image version
+name: Sandbox with AL da image version
 
 on:
   push:
   pull_request:
   workflow_dispatch:
     inputs:
+      tags:
+        required: False
+        description: 'Optional. Use a "tag expression" specify which tagged tests to run (https://cucumber.io/docs/cucumber/api/#tag-expressions)'
       show_docker_output:
         required: false
         default: false
@@ -16,10 +19,12 @@ on:
         description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
         required: false
         default: false
+  schedule:
+    - cron: "0 1 * * SUN"
 
 jobs:
 
-  github-server-tests:
+  sandbox-al-tests:
     # Avoids running double tests when someone on the team makes a pull request
     # 1: Trigger job on push or dispatch from this repository
     # 2: Trigger job on pull request from a fork
@@ -42,7 +47,7 @@ jobs:
         uses: ./action_for_github_server
         with:
           SHOW_DOCKER_OUTPUT: "${{ github.event.inputs.show_docker_output }}"
-          DOCASSEMBLE_IMAGE: "ghcr.io/suffolklitlab/docassemble:sha-7d13853"
+          DOCASSEMBLE_IMAGE: "ghcr.io/suffolklitlab/docassemble:latest"
       - run: echo "ALKiln finished starting the isolated GitHub docassemble server"
         shell: bash
 
@@ -62,4 +67,4 @@ jobs:
           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_VERSION: "stop_on_error"

package/.github/workflows/github_server.yml

@@ -1,4 +1,4 @@
-name: GitHub server installation
+name: Sandbox with latest da image
 
 on:
   push:
@@ -19,10 +19,12 @@ on:
         description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
         required: false
         default: false
+  schedule:
+    - cron: "0 1 * * SUN"
 
 jobs:
 
-  github-server-tests:
+  sandbox-da-tests:
     #### Developer note: If you have both `push` and `pull_request` in the
     #### `on` section (above), this avoids running double tests when someone
     #### on the team makes a pull request
@@ -157,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: "stop_on_error"
 
       #### Developer note: Example of making an issue when tests fail
       #### that includes the text of the failure output file

package/.github/workflows/playground.yml

@@ -13,7 +13,7 @@ on:
 
 jobs:
 
-  puppeteer-tests:
+  alkiln-tests:
     #### Developer note: If you have both `push` and `pull_request` in the
     #### `on` section (above), this avoids running double tests when someone
     #### editing the repository makes a pull request
@@ -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: "stop_on_error"

package/CHANGELOG.md

@@ -21,6 +21,7 @@ Format:
 - 
 
 ## [1.0.0] - 2021-01-16
+
 ### Added
 - 
 
@@ -45,6 +46,55 @@ Format:
 
 ## [Unreleased]
 
+### 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.
+- 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
+
+- Restores 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.
+- Ensured new file upload buttons don't warn about duplicates since they have the same selectors.
+
+### 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
+
+## [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)
+  - Unable to find some continue buttons
+    - Single-line fields like `yesno: likes_good_things`
+    - Buttons created with `buttons:`
+    - Continue buttons on signature pages
+  - 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.
+
+### 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
+- Fixed typo in fixture
+
 ## [5.17.0] - 2026-09-10
 
 ### Changed
@@ -54,7 +104,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/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/docassemble/docassemble_api_interface.js

@@ -377,6 +377,9 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
           log.debug({ code: `ALK0193`, context, },
             `Status ${ response.status }. Got ${ response.data.items[0].session }.`
           );
+          // Discuss: Do we need to handle pagination? Think most recent
+          // sessions are listed first, so perhaps not a problem.
+          // https://docassemble.org/docs/api.html#user_interviews
           return response.data.items[0];
         } else {
           log.debug({ code: `ALK0194`, context, },