diff --git a/docs/components/ALKiln/advanced.mdx b/docs/components/ALKiln/advanced.mdx
index 40bda4689..5a84dc509 100644
--- a/docs/components/ALKiln/advanced.mdx
+++ b/docs/components/ALKiln/advanced.mdx
@@ -38,7 +38,7 @@ You don't have to choose just one way to run ALKiln, you can use all of them. He
**What ALKiln is doing**
-([Moving](setup.mdx#diy-stages))
+([Moving](writing_tests.mdx#diy-stages))
When you run Playground tests, they do the following:
@@ -76,7 +76,7 @@ These tests run on GitHub, but they still interact with your server and basicall
**What ALKiln is doing**
-([Moving](setup.mdx#gNy-stages))
+([Moving](writing_tests.mdx#gNy-stages))
Whenever you push (or commit) to GitHub, GitHub will run the tests automatically. You can also [trigger them manually](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow).
@@ -127,7 +127,7 @@ These tests also run on GitHub, but they create a new docassemble server on GitH
**What ALKiln is doing**
-([Moving](setup.mdx#sandbox-stages))
+([writing_tests(setup.mdx#sandbox-stages))
Like the other GitHub test method, whenever you push (or commit) to GitHub, GitHub will run the tests automatically. You can [run these manually](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow) as well.
diff --git a/docs/components/ALKiln/automated_testing.mdx b/docs/components/ALKiln/automated_testing.mdx
index 85d6687db..ae35d6f75 100644
--- a/docs/components/ALKiln/automated_testing.mdx
+++ b/docs/components/ALKiln/automated_testing.mdx
@@ -5,6 +5,8 @@ sidebar_label: Overview
slug: alkiln
---
+import { Anchor } from '/docs/react_components/\Anchor.js';
+
**Any docassemble package can use ALKiln**, though it does have special features created especially for projects using AssemblyLine. Give us feedback and propose ideas by making issues at https://github.com/SuffolkLITLab/ALKiln/issues.
@@ -532,7 +534,7 @@ This Step can also be used anywhere else in your Scenario to give Steps more tim
([Moving](writing_tests.mdx#sign-in))
-You can use the `log in` Step to sign into your docassemble server before going to the interview:
+You can use the log in Step to sign into your docassemble server before going to the interview:
```
Given I log in with the email "USER_EMAIL" and the password "USER_PASSWORD"
@@ -758,7 +760,7 @@ You can also use environment variables to set values with [the `secret variables
([Moving](writing_tests.mdx#secret-val))
-The secret variables Step can set variables that have sensitive information. For example, a password. The value of this variable will not appear anywhere in the report or in the console. If there is an error on this page, ALKiln will still avoid taking a picture of the screen.
+The secret variables Step can set variables that have sensitive information. For example, a password. The value of this variable will not appear anywhere in the report or in the console. If there is an error on this page, ALKiln will still avoid taking a picture of the screen.
This is a complex Step to use and currently only works with tests running in GitHub (though it's in development for the Playground version). You can use a GitHub "secret" to store the value. To learn how to create and add a secret for the test, see the [GitHub secrets section](#github-secrets).
@@ -911,7 +913,7 @@ In a story table, use the name of the variable as usual and use the name of the
([Moving](writing_tests.mdx#custom-timeout))
-Use the `custom timeout` Step to give your pages or Steps more time to finish. The default maximum time is 30 seconds. This Step can be useful if you know that a page or an interaction with a field will take longer. You can also use it to shorten the time to let tests fail faster. If you need, you can use it in multiple places in each Scenario.
+Use the custom timeout Step to give your pages or Steps more time to finish. The default maximum time is 30 seconds. This Step can be useful if you know that a page or an interaction with a field will take longer. You can also use it to shorten the time to let tests fail faster. If you need, you can use it in multiple places in each Scenario.
```
Then the maximum seconds for each Step is 200
@@ -1202,11 +1204,10 @@ That warning isn't a bug, but if the above doesn't apply to you, you can ignore
If you are using a story table with index variables or generic objects, you need to add some code to the interview file where you set your [`default screen parts` block](https://docassemble.org/docs/initial.html#default%20screen%20parts).
-
([Moving](writing_tests.mdx#special-html))
-Add exactly this code to your `default screen parts` block to insert an invisible element in all your screens:
+Add exactly this code to your `default screen parts` block to insert an invisible element in all your screens:
```yml
default screen parts:
@@ -1316,7 +1317,7 @@ In addition, here are some actions you can take to manage the security of the te
### Disable the tests
-([Moving](writing_tests.mdx#disable-test))
+([Moving](setup.mdx#disable-test))
If you become worried about the tests, there are different ways you can stop the tests from running.
@@ -1325,7 +1326,7 @@ In order to run, the test setup interview added a "workflow" file to your reposi
#### Disabling tests in one repository
-([Moving](writing_tests.mdx#disable-repo))
+([Moving](setup.mdx#disable-repo))
GitHub lets you disable workflow files like these. See their instructions at https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow.
@@ -1336,7 +1337,7 @@ Another option is to disable or limit all tests, all actions, in your repository
#### Disabling tests for the whole organization
-([Moving](writing_tests.mdx#disable-org))
+([Moving](setup.mdx#disable-org))
You can disable these tests, or any actions, for a whole organization. GitHub's documentation for managing organization actions is at https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#managing-github-actions-permissions-for-your-organization.
@@ -1361,7 +1362,7 @@ In addition, some general good practices are:
GitHub has documentation on some best practices as well: https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions
-### Use ALKiln's commit sha
+### Use ALKiln's commit sha {#freeze}
([Moving](security.mdx#freeze))
@@ -1384,7 +1385,7 @@ When you want to update to a new version of the ALKiln, update that sha manually
([Moving](security.mdx#freeze))
-This section requires prior technical knowledge about [npm](https://docs.npmjs.com/about-npm) and [GitHub workflow files](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). Feel free to [ask us](../../get_started/intro.md#get-involved) any questions you might have.
+This section requires prior technical knowledge about [npm](https://docs.npmjs.com/about-npm) and [GitHub workflow files](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). Feel free to [ask us](/docs/get_started/beginners_guide.md#join) any questions you might have.
You can use an exact npm version of ALKiln by using your workflow file's `ALKILN_VERSION` input. The default uses a carat, for example `^4.0.0`. That means it will use the latest minor or patch in version 4 of ALKiln. You can instead use an exact version, for example `4.3.0`. See our section on [setting optional inputs](#optional-inputs).
@@ -1393,8 +1394,8 @@ You can use an exact npm version of ALKiln by using your workflow file's `ALKILN
-- ([Moving](security.mdx#secrets) - secrets)
-- ([Moving](security.mdx#env-vars) - env vars)
+- ([Moving](writing_tests.mdx#secrets) - secrets)
+- ([Moving](writing_tests.mdx#env-vars) - env vars)
- ([Moving](security.mdx#sensitive-info-github) - using sensitive info)
@@ -1470,7 +1471,7 @@ If you are still worried about the logs and artifacts in GitHub, [you can delete
## Your workflow file
-([Moving](security.mdx#workflows))
+([Moving](writing_tests.mdx#workflows))
**Where is it?**
@@ -1486,7 +1487,7 @@ Among other things, the workflow file:
You can also use the whole suite of GitHub's workflow and action functionality to do other things, like creating issues when tests fail.
-These following sections probably require prior technical knowledge about [GitHub workflow files](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). Feel free to [ask us](../../get_started/intro.md#get-involved) any questions you might have.
+These following sections probably require prior technical knowledge about [GitHub workflow files](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions). Feel free to [ask us](/docs/get_started/beginners_guide.md#join) any questions you might have.
### Required inputs
@@ -1517,7 +1518,7 @@ There are also optional inputs that can go under `with:`.
`MAX_SECONDS_FOR_SETUP` lets you to set how long to allow ALKiln to try to pull your interview package's code into the docassemble Playground. The default is currently 120 seconds (2 minutes).
-`ALKILN_VERSION` can be useful for security. It gives lets you control what npm version of ALKiln you're using. Read about that in [the "ALKiln's npm version" security section](#set-alkiln-s-npm-version).
+`ALKILN_VERSION` can be useful for security. It gives lets you control what npm version of ALKiln you're using. Read about that in [the "ALKiln's npm version" security section](#freeze).
If you're using a GitHub repository or organization secret, it will look very similar to the [required inputs described above](#required-inputs). Here the values are in context:
diff --git a/docs/components/ALKiln/components/_secure_env_vars.md b/docs/components/ALKiln/components/_secure_env_vars.md
index ba2ad99a8..4394a4096 100644
--- a/docs/components/ALKiln/components/_secure_env_vars.md
+++ b/docs/components/ALKiln/components/_secure_env_vars.md
@@ -1,7 +1,10 @@
-Since [workflow environment variables](writing#env-vars) might hold sensitive information, ALKiln avoids taking pictures or downloading the HTML of pages that use environment variables, even when the test has an error on that page. ALKiln avoids printing the value of an environment variable anywhere in the [report](writing#reports) or in the [console log](writing#console).
+Since [workflow environment variables](writing#env-vars) might hold sensitive information, ALKiln avoids taking pictures or downloading the HTML of pages that use environment variables. It even [avoids taking pictures when the test has an error on that page](writing#error-pics) and during [the sign-in Step](writing#sign-in). ALKiln avoids printing the value of an environment variable anywhere in the [report](writing#report) or in the [console log](writing#console).
diff --git a/docs/components/ALKiln/intro.mdx b/docs/components/ALKiln/intro.mdx
index e30fe23ea..04ab5dbd8 100644
--- a/docs/components/ALKiln/intro.mdx
+++ b/docs/components/ALKiln/intro.mdx
@@ -85,7 +85,7 @@ ALKiln uses [cucumber](https://cucumber.io/), [puppeteerjs](https://pptr.dev/),
Even though ALKiln is built using cucumber, this framework has a different, less lofty, purpose. Cucumber focuses on BDD (behavior driven development). This framework mostly deals with regression testing and other conveniences.
-For security, [ALKiln freezes the versions of its third-party libraries](#alkiln-freezes-dependencies) and only updates them after we check their changes.
+For security, [ALKiln freezes the versions of its third-party libraries](security.mdx#alkiln-freezes-dependencies) and only updates them after we check their changes.
## Where are our repositories? {#repos}
diff --git a/docs/components/ALKiln/security.mdx b/docs/components/ALKiln/security.mdx
index 896c9e996..ce9aa3b54 100644
--- a/docs/components/ALKiln/security.mdx
+++ b/docs/components/ALKiln/security.mdx
@@ -263,11 +263,11 @@ If you need to use sensitive information in your tests:
**This is for:** Everyone
-Avoid visually showing personal or security-critical data on an interview page. For example, you can show a server config value on an interview page in the text of a `subquestion`. Even though you yourself can try to avoid [taking pictures](writing_tests.mdx#pics) of those pages, an error can happen on that page. ALKiln takes pictures of pages that error and there is no way that ALKiln can know what text you are choosing to show to the user.
+
-Using ALKiln to fill in answers in the interview is different. You can safely use sensitive information to fill in fields by using the ["secret value" Step](#secret-val).
+It is possible, though, for your interview to visually show personal or security-critical data on an interview page to the user. For example, you can show a server config value on an interview page in the text of a `subquestion`. There is no way ALKiln can know about that and might take a picture. For example, if there is an error on that page, ALKiln will take a picture. You can try to avoid [taking pictures](writing_tests.mdx#pic) of those pages yourself, but that may not be enough. Since there is no way that ALKiln can know what text you are choosing to show to the user, you should avoid putting sensitive information visually on the screen or you should avoid testing pages or interviews that show sensitive information.
-
+Using ALKiln to fill in sensitive answers with environment variables in the interview is different. You can safely use sensitive information to fill in fields by using the ["secret value" Step](writing_tests.mdx#secret-val).
### Avoid JSON Steps with sensitive data {#json-vars}
@@ -296,7 +296,7 @@ These are the only people that can create [GitHub secrets](writing_tests.mdx#sec
-Sometimes authors do need to pass personal or security-critical information to their tests. For example, some tests require the "user" to [sign in](writing_tests.mdx##sign-in), so the tests need to know the email and password for that user. In GitHub, you can do this securely by using [GitHub secrets](writing_tests.mdx#secrets) and adding environment variables to your repository's GitHub workflow file. You can also read about [how to use sensitive information with tests](#sensitive-info-diy).
+Sometimes authors do need to pass personal or security-critical information to their tests. For example, some tests require the "user" to [sign in](writing_tests.mdx#sign-in), so the tests need to know the email and password for that user. In GitHub, you can do this securely by using [GitHub secrets](writing_tests.mdx#secrets) and adding environment variables to your repository's GitHub workflow file. You can also read about [how to use sensitive information with tests](#sensitive-info-diy).
1. Follow the [GitHub instructions](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to set up one or more GitHub secrets. You can add these secrets to one secrets or you can add these to your organization[^org_secrets], whichever is right for you.
2. [Find your workflow file](writing_tests.mdx#workflows-where).
@@ -573,7 +573,7 @@ Private repositories can ignore this since they would first have to share their
On GitHub, workflow job logs and artifacts of public repositories are visible to the public, just like the code. Also, any logged-in user can download those workflow artifacts.
-That might be fine. Part of being transparent is letting the public understand how your packages are working. Also, there are [some ways](#secret-val) ALKiln lets you set variables that you want to keep secret. That said, if you are concerned about your logs and artifacts, there are some things you can do to make these less available:
+That might be fine. Part of being transparent is letting the public understand how your packages are working. Also, there are [some ways](writing_tests.mdx#secret-val) ALKiln lets you set variables that you want to keep secret. That said, if you are concerned about your logs and artifacts, there are some things you can do to make these less available:
- Make your repository private
- [Delete the logs](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#deleting-logs) and [delete the artifacts](https://docs.github.com/en/actions/managing-workflow-runs/removing-workflow-artifacts).
diff --git a/docs/components/ALKiln/setup.mdx b/docs/components/ALKiln/setup.mdx
index 2884335da..fde138037 100644
--- a/docs/components/ALKiln/setup.mdx
+++ b/docs/components/ALKiln/setup.mdx
@@ -305,7 +305,7 @@ bookmark
For some people:
-- If you have `restrict input variables` set to `True` in your server's config and have signature screens in the interview you are testing, you *must* have the [trigger variable HTML](#special-html) in your interview for signatures.
+- If you have `restrict input variables` set to `True` in your server's config and have signature screens in the interview you are testing, you *must* have the [trigger variable HTML](writing_tests.mdx#special-html) in your interview for signatures.
@@ -318,7 +318,7 @@ For some people:
The tests are automated tests that you trigger manually from an interview you install on your docassemble [testing server](security.mdx#testing-server). The tests then run right on that server.
-Remember to use a [separate server](security.mdx#testing-server) for these types of tests. You can read more about [running tests](writing_tests.mdx#trigger-autodiy) in other documentation.
+Remember to use a [testing or development server](security.mdx#testing-server) for these types of tests. You can read more about [running tests](writing_tests.mdx#trigger-autodiy) in other documentation.
@@ -355,7 +355,7 @@ For everyone:
For some people:
- If you are using a docassemble Docker image created before April 9th, 2023, you will have to do a ["system upgrade"](https://docassemble.org/docs/docker.html#upgrading) to update your server to a newer docassemble Docker image. Any version of https://github.com/jhpyle/docassemble-os that is older than 1.0.8 uses versions of `node` that are too old for ALKiln. As of February 11th, 2024, ALKiln is using node version 18. A lot of people have upgraded already and it is a very good idea to do that, for security at the very least. If you do need to upgrade, though, you need to back up all your data, delete your old image and container, get the new image, create a new container, and restore your data. It may sound simple, but it is a tricky process.
-- If you have `restrict input variables` set to `True` in your server's config and have signature screens in the interview you are testing, you *must* have the [trigger variable HTML](#special-html) in your interview for signatures.
+- If you have `restrict input variables` set to `True` in your server's config and have signature screens in the interview you are testing, you *must* have the [trigger variable HTML](writing_tests.mdx#special-html) in your interview for signatures.
## test details {#sandbox-details}
@@ -415,7 +415,7 @@ For some people:
[ALKiln works hard to protect you from security vulnerabilities](security.mdx#alkilns-precautions) and there are lots of ways for you to [improve your own security](security.mdx). Even so, if you ever become uncomfortable or concerned about your ALKiln tests showing [personal or security-critical data](security.mdx#privilege), there are multiple ways you can disable the tests.
-If you are worried you have already shown sensitive information in your GitHub tests, you can delete your [logs and artifacts](writing_tests.mdx#github-output).
+If you are worried you have already shown sensitive information in your GitHub tests, you can [delete the GitHub action that ran the workflow](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/deleting-a-workflow-run). You can also just [delete your GitHub logs](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs#deleting-logs) and [delete your GitHub artifacts](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/removing-workflow-artifacts).
@@ -443,7 +443,7 @@ The old tests will still be in the version history of your repository if you eve
GitHub lets you disable or limit all tests, or all actions, in your repository. You can read [GitHub's documentation for managing repository actions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository) for more information.
-Another option is to [disable an individual workflow (action)](https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow). Your package's GitHub [workflow file](#workflows) is what triggers ALKiln tests on GitHub.
+Another option is to [disable an individual workflow (action)](https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow). Your package's GitHub [workflow file](writing_tests.mdx#workflows) is what triggers ALKiln tests on GitHub.
You can also [delete](https://docs.github.com/en/repositories/working-with-files/managing-files/deleting-files-in-a-repository) the [workflow file that is in your repository](writing_tests.mdx#workflows-where) completely.
diff --git a/docs/components/ALKiln/troubleshooting.mdx b/docs/components/ALKiln/troubleshooting.mdx
index 8ca8215e5..6b16c085a 100644
--- a/docs/components/ALKiln/troubleshooting.mdx
+++ b/docs/components/ALKiln/troubleshooting.mdx
@@ -177,7 +177,7 @@ Some possible causes:
1. You have changed your code to remove a variable or value and have not yet updated your tests.
- Look at the error message closely. Look at the [picture and HTML of the error page](#writing_tests.mdx#error-pics). Try to find the variable or value in your interview code or in the code of included or imported files. See if that variable or value is also in your test file.
+ Look at the error message closely. Look at the [picture and HTML of the error page](writing_tests.mdx#error-pics). Try to find the variable or value in your interview code or in the code of included or imported files. See if that variable or value is also in your test file.
1. The field is hidden behind a `show if` of some kind.
diff --git a/docs/components/ALKiln/writing_tests.mdx b/docs/components/ALKiln/writing_tests.mdx
index 62edae0fe..4558946de 100644
--- a/docs/components/ALKiln/writing_tests.mdx
+++ b/docs/components/ALKiln/writing_tests.mdx
@@ -14,6 +14,7 @@ import WithSecretsForOrgs from './components/\_with_secrets.md';
import { GTOYS, AutoDIY, KittyLitter } from './components/\_test_types.js';
import { ScenarioDir } from './components/\_scenario_folder_contents.js';
import { RobotStage } from './components/\_robot_stage.js';
+import { Anchor } from '/docs/react_components/\Anchor.js';
:::warning
@@ -45,7 +46,7 @@ If you are coming back and just need some resource reminders, here is a short li
- By default, each Step or page **must** be completed in at most 30 seconds. You can change that with the ["max seconds" Step](#custom-timeout).
- ALKiln creates test [reports](#report) and pictures. For example, ALKiln saves [pictures and the HTML of pages that caused errors](#error-pics). In GitHub, those files are in the zip file in [your workflow's artifact section](#artifacts).
- There are some field types that ALKiln cannot yet handle, including some `object`-type fields.
-- The tests use the [gherkin language and syntax](#gherkin).
+- The tests use the [gherkin language and syntax](#gherkin-keywords).
Here is an example of a more complex test for a quick refresher on some of ALKiln's features:
@@ -153,7 +154,7 @@ The Step format:
The two blanks to fill in are `` and ``. Each of them must be the name of an [environment variable](#env-vars) that you have already added to your [workflow file](#workflows).
-The `` variable should contain the username of a [dedicated account](security.mdx#test_accounts) on your docassemble server. The `` variable should contain the password of that account.
+The `` variable should contain the username of a [dedicated account](security.mdx#test-accounts) on your docassemble server. The `` variable should contain the password of that account.
To use this Step:
@@ -179,7 +180,7 @@ env:
You can have as many of these accounts as you want.
:::danger Sensitive information
-If you run this in a test, you **must** use [GitHub secrets](#secrets) to set the [environment variables](#env-vars) in order to keep the information secure. You should also use a [separate account](security.mdx#test_accounts) for signing in like this. [Never use a real person's account or information](security.mdx#mock-data).
+If you run this in a test, you **must** use [GitHub secrets](#secrets) to set the [environment variables](#env-vars) in order to keep the information secure. You should also use a [separate account](security.mdx#test-accounts) for signing in like this. [Never use a real person's account or information](security.mdx#mock-data).
:::
ALKiln does avoid taking pictures or downloading the HTML for this Step, even when the test has an error on that page, so that information is still protected. ALKiln also avoids printing the value of these variables anywhere in the report or in the console. Even so, it is possible for you to [expose this information](security.mdx#no-show).
@@ -234,7 +235,7 @@ To set up the API key, do the following:
1. Write this "sign in and clean up" Step in your `.feature` test file.
:::danger Sensitive information
-If you run this in a test, you **must** use [GitHub secrets](#secrets) to set the [environment variables](#env-vars) in order to keep the information secure. You should also use a [separate account](security.mdx#test_accounts) for signing in like this. [Never use a real person's account or information](security.mdx#mock-data).
+If you run this in a test, you **must** use [GitHub secrets](#secrets) to set the [environment variables](#env-vars) in order to keep the information secure. You should also use a [separate account](security.mdx#test-accounts) for signing in like this. [Never use a real person's account or information](security.mdx#mock-data).
:::
ALKiln does avoid taking pictures or downloading the HTML for this Step, even when the test has an error on that page, so that information is still protected. ALKiln also avoids printing the value of these variables anywhere in the report or in the console. Even so, it is possible for you to [expose this information](security.mdx#no-show).
@@ -383,7 +384,7 @@ You can use this Step to [upload files](#upload) and [fill in a signature](#sign
:::
-->
-Right now, Story Tables are unable to use environment variables to fill in answers, so you cannot use them to [set sensitive information](#secret-val) like passwords.
+Right now, Story Tables are unable to use environment variables to fill in answers, so you cannot use them to [set sensitive information](#secret-val) like passwords.
:::warning Unused rows
The Story Table does not care about extra rows that never get used. This can make Story Tables easier to write, but it also means that the tests will technically "pass" even if variables that *should* get set are never filled in.
@@ -426,7 +427,7 @@ The format of the Step:
And I set the variable "" to ""
```
-There are two types of blanks you need to fill for this Step. The first set of quotes in this Step contain the name of the variable you need to set. The second set of quotes contain the value you want to set. This is the same as the [Story Table's](#story-tables)'s `var` column and `value` column.
+There are two types of blanks you need to fill for this Step. The first set of quotes in this Step contain the name of the variable you need to set. The second set of quotes contain the value you want to set. This is the same as the [Story Table's](#story-table)'s `var` column and `value` column.
This Step is "linear". That is, unlike Story Table rows, these "linear" variable-setting Steps have to be in the correct order and you **must** make sure your test has reached the exact page that has the field. Otherwise your test will fail.
@@ -1305,7 +1306,7 @@ Example:
-
+
### `I get the page's JSON variables and values` {#get-json}
@@ -1509,13 +1510,18 @@ Scenario Outline: I allow visitation
### Tags {#tags}
-You can use [Gherkin tags](https://cucumber.io/docs/cucumber/api/?lang=java#tags) to choose to run only specific tests or files.
+You can tell ALKiln to run only some tests this way:
-To use a tag expression for GitHub tests you can [trigger your tests](#trigger-github) manually. When you do that, GitHub will offer you a drop down where you can give some inputs for your test run. One of the optional fields there will let you write a tag expression if you want. You can also add a tag expression to your workflow file as an [input](#optional-inputs).
+1. Add [Gherkin tags](https://cucumber.io/docs/cucumber/api/?lang=java#tags) at the top of your `.feature` file or above your `Scenario`.
+2. Use [a tag expression](https://cucumber.io/docs/cucumber/api/?lang=java#tag-expressions) when you run your tests.
+
+For GitHub tests, you can use a tag expression when you [trigger your tests manually](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow#running-a-workflow). When you do that, GitHub will offer you a drop down where you can give some inputs for your test run (like that documentation describes). One of the optional fields there will let you write a tag expression if you want. If you want to *always* only run some GitHub tests, you can add a tag expression to your workflow file as an [input](#optional-inputs).
The test interview has a field where you can add a tag expression if you want.
-To use tags, you must first add them to your [test files](#test-files). You can add them above the `Feature` keyword, or above `Scenario` keywords, or both.
+This documentation will only show some basics about tags and tag expressions themselves.
+
+This is an example of adding tags to your [test files](#test-files). You can add them above the `Feature` keyword, or above `Scenario` keywords, or both.
```gherkin
@likes_bears
@@ -1534,9 +1540,7 @@ Scenario: I like Jaime
# Test 3 Steps...
```
-A [tag expression](https://cucumber.io/docs/cucumber/api/?lang=java#tag-expressions) is the magic formula an author can use to tell ALKiln which tests to run.
-
-This documentation will only show some basics about tags. Based on the example test file above, these are some examples of tag expressions and which tests they will run:
+Based on the example test file above, these are some examples of tag expressions and which tests they will run:
| Tag expression | What tests run? |
| - | - |
@@ -1657,7 +1661,7 @@ The [ test method](setup.mdx#recommended) workflow file has
You can see examples of these inputs in the correct [ALKiln file](#workflows-examples).
- `SERVER_URL` is the url of [your docassemble testing server](security.mdx#testing-server) - the server the tests should run on. If you are using ALKiln for a GitHub organization, you should store the value for this input in a [GitHub secret](#secrets) so that all your organization repositories can share it.
-- `DOCASSEMBLE_DEVELOPER_API_KEY` is a developer API key for the ALKiln [testing account](security.mdx#test_accounts) on your server. You should store the value for this input in a [GitHub secret](#secrets) so that no one can see this secure information.
+- `DOCASSEMBLE_DEVELOPER_API_KEY` is a developer API key for the ALKiln [testing account](security.mdx#test-accounts) on your server. You should store the value for this input in a [GitHub secret](#secrets) so that no one can see this secure information.
If you do not already have these secrets, add them to your package's repository or GitHub organization[^org].
@@ -1675,7 +1679,7 @@ These are values you can put in your workflow file directly under the `with:` ke
-->
-[^org]: If your server is part of a GitHub organization, we recommend creating some of these values as organization secrets. That way, if you need to change the value of an input or environment variable you can do it one place.
+[^org]: If your server is part of a GitHub organization, we recommend creating some of these values as [organization secrets](#org-secrets). That way, if you need to change the value of an input or environment variable you can do it one place.
### Required inputs for tests {#sandbox-inputs}
@@ -1996,9 +2000,9 @@ You can [make secrets for individual GitHub repositories](https://docs.github.co
# other code
```
- Remember to create a [separate account](security.mdx#test_accounts) for that "user".
+ Remember to create a [separate account](security.mdx#test-accounts) for that "user".
-2. GitHub secrets are useful for sharing values between GitHub organization repositories. All the repositories of a GitHub organization can see its secrets, so you can affect all of those repositories at once from one location.
+2. GitHub secrets are useful for sharing values between GitHub organization repositories. All the repositories of a GitHub organization can see its secrets, so you can affect all of those repositories at once from one location.
Example situation
@@ -2091,9 +2095,9 @@ This section will talk about ways to start (trigger) [different types of tests](
**This is for:** Everyone
-You control when your tests run and which tests run. How you do that depends on the [type of test](setup.mdx#types) you are using.
+You control when your tests run and which tests run. How you do that depends on the [type of test](setup.mdx#types) you are using.
-** and tests:**
+** and tests:**
By default, you can trigger tests on GitHub by committing your edits to your repository or by running the tests manually.
@@ -2107,11 +2111,11 @@ You can use your [workflow file](#workflows) to customize some ALKiln test run s
-You can also [trigger your tests manually](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow#running-a-workflow). When you run your tests manually, you can use [tags](#tags) to limit which tests to run. You can also [use tags in your workflow file](#optional-inputs).
+You can also [trigger your tests manually](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow#running-a-workflow). When you run your tests manually, you can use [tags](#tags) to limit which tests to run. You can also [use tags in your workflow file](#optional-inputs).
-You can also edit your workflow file to [trigger your GitHub tests other ways](#workflow-extras).
+You can also edit your workflow file to [trigger your GitHub tests other ways](#workflow-extras).
-** tests:**
+** tests:**
You can run tests manually whenever you want to.
@@ -2312,7 +2316,7 @@ The console output should include at least one of these items, from top to botto
- `F` - a test failed.
3. The [ALKiln report](#report).
-1. Any errors from [the third-party libraries ALKiln uses](#dependencies). We are keeping the errors from the third-party libraries until we handle all cases of the errors ourselves.
+1. Any errors from [the third-party libraries ALKiln uses](intro.mdx#dependencies). We are keeping the errors from the third-party libraries until we handle all cases of the errors ourselves.
1. How many tests pass or failed.
1. In GitHub, data from the take-down processes as ALKiln and GitHub clean up.
@@ -2448,7 +2452,7 @@ We're always trying to understand what people would find helpful in these report
+
+[get_cacheable_documents()](https://github.com/SuffolkLITLab/docassemble-AssemblyLine/blob/76ead20669674d1a458c15af99aeba44899866cd/docassemble/AssemblyLine/al_document.py#L1826) is a new method that generates
all **enabled** documents in the bundle and returns a list, where each item is a tuple of the DOCX and
PDF versions of the document.
diff --git a/docs/get_started/beginners_guide.md b/docs/get_started/beginners_guide.md
index 70e6e2fe7..a36647d95 100644
--- a/docs/get_started/beginners_guide.md
+++ b/docs/get_started/beginners_guide.md
@@ -14,7 +14,7 @@ Here are the steps:
1. [Do the Hello, World exercise](#do-the-hello-world-exercise) for a friendly introduction to Docassemble
2. [Watch a demonstration of the Weaver](#watch-a-demonstration-of-the-weaver), a Document Assembly Line tool for quickly turning prepared forms into draft Docassemble interviews
3. [Review the interview project management page](#review-the-interview-project-management-guide)
-4. [Join the Document Assembly Line community](#join-the-document-assembly-line-community)
+4. [Join the Document Assembly Line community](#join)
5. [Start building your first interview!](#start-building-your-first-interview)
:::tip
@@ -49,7 +49,7 @@ Building a successful interview involves more than just coding in the Docassembl
**➡️ [Review the interview project management guide.](project_management.md)**
-## Join the Document Assembly Line community
+## Join the Document Assembly Line community {#join}
You know enough to get started, but you will need help. The Document Assembly Line community meets weekly on Zoom for live support, and coding help is available 24/7 in our Microsoft Teams forum.
diff --git a/docs/react_components/Anchor.js b/docs/react_components/Anchor.js
new file mode 100644
index 000000000..83ef26062
--- /dev/null
+++ b/docs/react_components/Anchor.js
@@ -0,0 +1,6 @@
+import useBrokenLinks from '@docusaurus/useBrokenLinks';
+
+export function Anchor(props) {
+ useBrokenLinks().collectAnchor(props.id);
+ return ;
+}