apify-test-tools 0.10.2-beta.2 → 0.10.2-beta.20

package/dist/workflow-scripts-src/run-with-apify-tokens.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=run-with-apify-tokens.d.ts.map

package/dist/workflow-scripts-src/run-with-apify-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-with-apify-tokens.d.ts","sourceRoot":"","sources":["../../workflow-scripts-src/run-with-apify-tokens.ts"],"names":[],"mappings":""}

package/dist/workflow-scripts-src/run-with-apify-tokens.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Runs apify-test-tools and passes it only secrets needed for the Actors, no other secrets are leaked.
+//
+//     jq ... | node .github/scripts/run-with-apify-tokens.mjs apify-test-tools build --version-number 0.99
+//
+// The step passes the reusable workflow's whole secrets map as WORKFLOW_SECRETS. The token names
+// come from `tokenEnvVar` in the repo's apify-test-tools.config.json, which is the same file
+// apify-test-tools itself reads, so the two can't drift. Everything else in the secrets map (npm,
+// Slack, GitHub, anything else the repo holds) is left out, and WORKFLOW_SECRETS itself is dropped,
+// so the blob never reaches the CLI or anything under node_modules.
+//
+// Each token is looked up in the CONFIG_SECRETS secret first, a JSON object of secret name -> value,
+// and then among the top-level secrets, which is where `secrets: inherit` puts them. The secrets the
+// workflows read by name (NPM_TOKEN, TESTER_APIFY_TOKEN, ...) never come from CONFIG_SECRETS.
+//
+// The command runs without a shell, so branch names and other interpolated arguments are passed
+// through as literal argv entries.
+import { spawnSync } from 'node:child_process';
+import { CONFIG_FILE_NAME, readBaseConfigFile } from '../bin/utils/config/load-config.js';
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const [command, ...args] = process.argv.slice(2);
+if (!command)
+    fail('Usage: run-with-apify-tokens.mjs <command> [args...]');
+const { WORKFLOW_SECRETS, ...baseEnv } = process.env;
+if (!WORKFLOW_SECRETS) {
+    fail('WORKFLOW_SECRETS is not set. Add `WORKFLOW_SECRETS: ${{ toJSON(secrets) }}` to the step env.');
+}
+let workflowSecrets;
+try {
+    workflowSecrets = JSON.parse(WORKFLOW_SECRETS);
+}
+catch (error) {
+    fail(`WORKFLOW_SECRETS is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+}
+const workflowSecretsMap = workflowSecrets;
+if (!isRecord(workflowSecretsMap)) {
+    fail('WORKFLOW_SECRETS must be a JSON object of secret names and values.');
+}
+// Never includes the parse error: Node quotes the input in it, and the input is a secret.
+const unpackConfigSecrets = () => {
+    const packed = workflowSecretsMap.CONFIG_SECRETS;
+    if (!packed)
+        return {};
+    if (typeof packed !== 'string')
+        fail('The CONFIG_SECRETS secret is not valid JSON.');
+    let value;
+    try {
+        value = JSON.parse(packed);
+    }
+    catch {
+        fail('The CONFIG_SECRETS secret is not valid JSON.');
+    }
+    if (!isRecord(value)) {
+        fail('The CONFIG_SECRETS secret must be a JSON object.');
+    }
+    return value;
+};
+const secrets = { ...workflowSecretsMap, ...unpackConfigSecrets() };
+let actorConfigs;
+try {
+    actorConfigs = await readBaseConfigFile();
+}
+catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+}
+const tokenNames = [...new Set(actorConfigs.map(({ tokenEnvVar }) => tokenEnvVar))].sort();
+// Declared but absent is a warning, not an error. A repo can carry an Actor whose token isn't
+// configured and still build fine as long as that Actor never changes, and apify-test-tools raises
+// a precise error naming the Actor at the point it actually needs the token.
+const missing = tokenNames.filter((name) => !(name in secrets));
+if (missing.length > 0) {
+    console.error(`Warning: ${CONFIG_FILE_NAME} declares ${missing.join(', ')}, but no such secret was passed ` +
+        `to this workflow, neither inside CONFIG_SECRETS nor inherited. Check the repository secrets ` +
+        `and the workflow's \`secrets:\` if a build fails on a missing token.`);
+}
+const present = tokenNames.filter((name) => name in secrets);
+// Names only. The values are secrets and must never be printed, even though the runner masks
+// registered secrets in logs.
+console.error(`Passing ${present.length} Actor token(s) to \`${command}\`: ${present.join(', ') || '(none)'}`);
+const env = { ...baseEnv };
+for (const name of present) {
+    const value = secrets[name];
+    if (typeof value !== 'string')
+        fail(`Secret "${name}" must be a string.`);
+    env[name] = value;
+}
+const result = spawnSync(command, args, { stdio: 'inherit', env });
+if (result.error) {
+    fail(`Failed to run \`${command}\`: ${result.error.message}`);
+}
+// Preserve the child's exit code so the step fails exactly when the command does. A child killed
+// by a signal reports a null status, which would otherwise be read as success.
+process.exit(result.status ?? 1);
+//# sourceMappingURL=run-with-apify-tokens.js.map

package/dist/workflow-scripts-src/run-with-apify-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-with-apify-tokens.js","sourceRoot":"","sources":["../../workflow-scripts-src/run-with-apify-tokens.ts"],"names":[],"mappings":"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"}

package/docs/cli.md

@@ -0,0 +1,469 @@
+# CLI API
+
+The package includes the `apify-test-tools` binary. The [reusable workflows](workflows.md) call it to find changed
+Actors, build them, and report results, and you can run it locally the same way:
+
+```bash
+npx apify-test-tools <command> [flags]
+```
+
+Run every command from the root of the Actor repository; it reads `apify-test-tools.config.json` from there.
+Results are written to stdout as JSON, diagnostics to stderr, so commands can be piped into each other and into `jq`.
+
+| Command                                                               | Does                                                    | Needs                |
+| --------------------------------------------------------------------- | ------------------------------------------------------- | -------------------- |
+| [`get-affected-actors`](#finding-affected-actors-get-affected-actors) | Lists the Actors changed in a commit range              | git only             |
+| [`build`](#building-actors-build)                                     | Builds the Actors given on stdin from the pushed branch | Actor tokens         |
+| [`build-from-local`](#build-from-local-source-build-from-local)       | Builds Actors from local files                          | Actor tokens         |
+| [`test`](#running-tests-test)                                         | Runs the platform tests on the builds given on stdin    | `TESTER_APIFY_TOKEN` |
+| [`notify`](#notifying-notify)                                         | Posts a test report or a release to Slack               | a Slack token        |
+| [`delete-old-builds`](#deleting-old-builds-delete-old-builds)         | Deletes old builds of the Actors                        | Actor tokens         |
+| [`get-actor-configs`](#listing-actors-get-actor-configs)              | Prints the resolved config                              | nothing              |
+
+"Actor tokens" are the environment variables named by each Actor's `tokenEnvVar` in the config. A command only needs
+the tokens of the Actors it touches.
+
+## Global flags
+
+| Flag          | Default | Meaning                                                                                                          |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--log-level` | `info`  | Minimum level written to stderr: `debug`, `info`, `warn`, `error`, or `silent`. Results on stdout are unaffected |
+
+## Selecting Actors (`--actors`, `--ignore`)
+
+Commands that read the config take `--actors` and `--ignore`, each a list of `actorFullName`s (space-separated,
+or the flag repeated). `--actors` keeps only the listed Actors, `--ignore` drops them. An unknown
+name is an error rather than silently selecting nothing.
+
+## Dry runs (`--dry-run`)
+
+Every command that changes something (`build`, `build-from-local`, `notify`, `delete-old-builds`) takes
+`--dry-run`. A dry run:
+
+- **Changes nothing.** No versions or builds are created, nothing is uploaded or deleted, and no Slack message is
+  posted.
+- **Does every read and check the real run does**, so it fails wherever the real run would: change detection, the
+  Apify token and Actor lookup, the [repository check](#repository-check), collecting and zipping local sources, and
+  the Slack token (verified with Slack's read-only `auth.test`).
+- **Needs the same tokens as the real run.** Read-only tokens are enough, since nothing is written. A dry run can't
+  tell whether a token is also allowed to write, because the Apify API has no dry-run mode of its own.
+- **Prints a plan, not results.** Logs start with `[DRY RUN] Would …`. `build` and `build-from-local` write
+  `{ "dryRun": true, "builds": [...] }` to stdout instead of the build array, so the plan can't be passed to tests as
+  `ACTOR_BUILDS` by mistake.
+
+## Change detection
+
+When a PR is opened or code is pushed, the tool determines which Actors need to be built and tested based on the
+changed files. For each changed file, for each Actor:
+
+1. **Sibling exclusion** — files inside another Actor's `folder` are excluded first. This prevents an Actor with
+   broad context from being triggered by changes that belong to a sibling Actor.
+2. **CHANGELOG classification** — a `CHANGELOG.md` file is always `cosmetic` (only triggers a release build, not
+   tests), for every Actor, regardless of context or folder. (See
+   [issue #106](https://github.com/apify/apify-test-tools/issues/106).)
+3. **Context matching** — the file must fall within one of the Actor's context paths (`dockerContextDir` from
+   `actor.json` by default, or `overrideActorContext` from config if set). Files outside every context path are
+   skipped.
+4. **Hardcoded ignore list, context-aware** — the file path is first "hoisted" relative to the context path it
+   matched (e.g. a standalone Actor's own `.eslintrc` is checked as just `.eslintrc`, not the full
+   repo-root-relative path), then checked against repo-level dev file patterns (`.vscode/`, `.gitignore`, `.husky/`,
+   `.eslintrc`, `eslint.config.mjs`, `.prettierrc`, `.editorconfig`). Directories like `code/` or `shared/`
+   get no special treatment: to treat them as top-level, list them in `overrideActorContext`.
+5. **`.dockerignore` filtering** — if a `.dockerignore` exists at the root of the Actor's `dockerContextDir`,
+   matching files are ignored. Patterns are resolved relative to `dockerContextDir`, matching Docker's own behavior.
+   Platform test files are the exception, see the next step.
+   **Platform test files** — a file that matches `platformTestsGlob` from the config file (a glob from the repo root,
+   default `test/platform/**`, helpers included) is a `test` change, also when `.dockerignore` lists it. This is
+   checked before the `.dockerignore` filtering. A test change puts the Actor in `testChangedActors`, so its tests
+   run, but it is neither functional nor cosmetic, so a release doesn't build it. Context matching still applies, so
+   tests outside an Actor's `dockerContextDir` (e.g. a root `test/` with standalone Actors) need to be listed in its
+   `overrideActorContext`; `get-affected-actors` logs a warning for changed test files outside every Actor's context.
+6. **README classification** — a `README.md` file is `cosmetic` (only triggers a release build, not tests) if it
+   lives inside the Actor's own `folder`; otherwise it's ignored entirely, since it isn't documentation for this
+   Actor.
+7. **Cosmetic JSON classification** — `.json` files inside the Actor's own `.actor/` directory with only cosmetic
+   schema changes (whitespace, key ordering) only trigger a release build.
+8. **Functional** — everything else triggers both build and tests.
+
+## Finding affected Actors (`get-affected-actors`)
+
+`get-affected-actors` lists the Actors whose context changed in a commit range, using the rules in
+[Change detection](#change-detection). It only reads git and the config file, so it needs no tokens. The range always
+ends at the checked-out `HEAD`, so check out the branch you want to inspect first.
+
+```bash
+# A PR: the branch's own changes, narrowed to the Actors that changed since its last validated commit
+npx apify-test-tools get-affected-actors --base origin/master --since <sha>
+
+# A release: everything after the last released commit
+npx apify-test-tools get-affected-actors --since <sha>
+```
+
+| Flag       | Default | Meaning                                                                                |
+| ---------- | ------- | -------------------------------------------------------------------------------------- |
+| `--base`   |         | Only what `HEAD` changes compared to this branch counts, like `git diff <base>...HEAD` |
+| `--since`  |         | Only changes after this commit count (see below)                                       |
+| `--actors` | all     | Only report these Actors                                                               |
+| `--ignore` | none    | Never report these Actors                                                              |
+
+Pass `--base`, `--since`, or both:
+
+- **`--base` only** inspects what the branch changes, the same files GitHub's "Files changed" tab shows: the diff
+  from where the branch forked from `--base`, or the last commit of `--base` it merged in. What it merged in from
+  `--base` is already validated there, so it doesn't count.
+- **`--base` and `--since`** also inspects what changed after the branch's last validated commit, and reports only
+  the Actors that changed in both. An Actor in only one of them is already validated, by this branch or on `--base`.
+  When both changed an Actor, the changes can interact, so it is reported, but as functional only when both changes
+  are functional. A validated functional change followed by README edits is cosmetic, and so is a functional
+  change merged in from `--base` that meets only cosmetic changes of the branch. `--since` doesn't have to be on
+  the branch, so a rebase only re-checks the Actors that `--base` changed too. If `--since` is not in the local
+  history (a force-push), or it is `HEAD` (a rerun), it is ignored and the whole branch is checked.
+- **`--since` only** inspects everything after it up to `HEAD`. It must be an ancestor of `HEAD` and fails
+  otherwise, see [Releasing Actors](#releasing-actors). If `HEAD` is `--since`, nothing is reported.
+
+`commits`, `changedFiles` and `changelog` describe the whole range, `--base...HEAD` or `--since..HEAD`: `--since`
+together with `--base` only narrows the Actor lists.
+
+The output is a JSON document:
+
+```json
+{
+    "version": 1,
+    "head": "<sha of HEAD>",
+    "commits": [{ "sha": "…", "author": "…", "date": "…", "message": "…" }],
+    "changedFiles": ["src/main.ts", "CHANGELOG.md"],
+    "changelog": "Lines added to CHANGELOG.md, or null",
+    "functionallyChangedActors": [{ "actorFullName": "john.doe/my-actor" }],
+    "cosmeticallyChangedActors": [{ "actorFullName": "john.doe/other-actor" }],
+    "testChangedActors": [{ "actorFullName": "john.doe/my-actor" }]
+}
+```
+
+`functionallyChangedActors` have at least one functional change, so they need a new build and tests.
+`cosmeticallyChangedActors` have cosmetic changes and no functional one (see [Change detection](#change-detection)), so
+they need a new build only when released. An Actor is in at most one of these two lists. `testChangedActors` have a
+changed platform test (`platformTestsGlob` in the config) in their context, whatever else changed, so their tests need
+to run. A test change alone needs no release. The PR workflow builds `functionallyChangedActors` and
+`testChangedActors`. The release workflow builds `functionallyChangedActors` and `cosmeticallyChangedActors`.
+
+With `--base` and `--since`, an Actor is in `testChangedActors` when its tests changed on the branch and again since
+`--since`, the same rule as for functional changes.
+
+## Building Actors (`build`)
+
+`build` builds exactly the Actors it is given on stdin, from the checked-out branch as it is on the remote, and
+prints the builds as the same JSON array `build-from-local` prints. An Actor listed twice is built once, so the lists
+of `get-affected-actors` can be joined without removing duplicates first. A detached HEAD is an error, since there is
+no branch to build from. It doesn't look at git history: which Actors to build is up to you, usually picked from the
+output of [`get-affected-actors`](#finding-affected-actors-get-affected-actors).
+
+```bash
+# A PR: the Actors whose code or platform tests the branch changed, built into the test version
+npx apify-test-tools get-affected-actors --base origin/master \
+  | jq '{ actors: (.functionallyChangedActors + .testChangedActors) }' \
+  | npx apify-test-tools build --version-number 0.99
+
+# A release: every Actor changed since the last release, into the version users run
+npx apify-test-tools get-affected-actors --since <sha> \
+  | jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' \
+  | npx apify-test-tools build --version-number default
+
+# One Actor, whatever changed
+echo '{ "actors": [{ "actorFullName": "john.doe/my-actor" }] }' | npx apify-test-tools build --version-number 0.99
+```
+
+The input is `{ "actors": [{ "actorFullName": "<owner/name>" }] }`; other fields are ignored. An empty `actors` list
+builds nothing and prints `[]`. Empty or invalid input is an error, so a failed command earlier in the pipe can't turn
+into a successful run that built nothing. In GitHub Actions, give such a step `shell: bash` so the pipe also fails on
+its own (the default shell has no `pipefail`).
+
+| Flag                         | Default             | Meaning                                                                                                                |
+| ---------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `--version-number`           | required            | Version to build, like `0.99`, or `default` for each Actor's default version (the one its default build tag points to) |
+| `--repo-url`                 | the `origin` remote | Repository to build from, see [Repository check](#repository-check)                                                    |
+| `--require-env-vars-in-sync` | `false`             | Fail unless the built version's env var names match the default version's, see [Env var check](#env-var-check)         |
+| `--dry-run`                  | `false`             | See [Dry runs](#dry-runs---dry-run)                                                                                    |
+
+The output is the build array the vitest library reads from `ACTOR_BUILDS`:
+
+```json
+[{ "buildId": "...", "actorRawId": "...", "buildNumber": "...", "actorFullName": "john.doe/my-actor" }]
+```
+
+`build` never sets or changes build tags. A build gets the tag its version is configured with on the platform, so
+building the default version moves its tag (usually `latest`) to the new build, and building a version without a
+tag leaves every tag where it is. Builds always use the Docker cache.
+
+### Repository check
+
+`build` points each Actor's version at the `origin` remote. Because a build overwrites the version's Git URL,
+building from a fork or a mirror would repoint the Actor. So, before building, the remote is compared with the Git
+URL of the Actor's default version (the one its default build tag points to), and the command fails if they differ
+or if the default version isn't built from a Git repository. The URL form doesn't matter
+(`https://github.com/org/repo` equals `git@github.com:org/repo.git`).
+
+To build from a different repository on purpose, e.g. when moving an Actor, pass `--repo-url`. That skips the check.
+
+### Env var check
+
+Tests should run the Actor with the same env vars users run it with. Pass `--require-env-vars-in-sync` to `build` or
+`build-from-local` to compare the env vars of the version they build (e.g. `0.99`, or `0.98` for `build-from-local`)
+with those of the default version, and fail if a name is missing or extra. Only names are compared, since the API
+doesn't return secret values. A version that doesn't exist yet counts as having no env vars, so if the default
+version has any, create the test version on the platform with the same env vars first. A dry run checks the env vars
+too.
+
+The CLI leaves it off by default, so a one-off build, e.g. of a debug branch, isn't held up by it.
+[`public_pr-build-test.yaml`](workflows.md#public_pr-build-testyaml) turns it on by default; set its
+`require-env-vars-in-sync` input to `false` to turn it off.
+
+## Build from local source (`build-from-local`)
+
+Builds Actors directly from your local files, with no push needed: the sources are zipped into the Actor's
+`actor-<id>-source` key-value store and built as `TARBALL`, like `apify push`. It prints the same build array as
+`build`.
+
+```bash
+APIFY_TOKEN_JOHN_DOE=<token> npx apify-test-tools build-from-local --actors john.doe/my-actor
+```
+
+| Flag                         | Default | Meaning                                                                                                  |
+| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `--actors`                   | all     | Only build these Actors. Point vitest at their tests only, for quicker feedback                          |
+| `--ignore`                   | none    | Never build these Actors                                                                                 |
+| `--require-env-vars-in-sync` | `false` | Fail unless the env var names of `0.98` match the default version's, see [Env var check](#env-var-check) |
+| `--dry-run`                  | `false` | Check the token, the Actor and the zipped sources without uploading or building                          |
+
+## Releasing Actors
+
+A release is three commands: find what changed since the last released commit, build those Actors into their
+default version (the one users run), and announce it.
+
+```bash
+npx apify-test-tools get-affected-actors --since <sha> > affected.json
+
+jq '{ actors: (.functionallyChangedActors + .cosmeticallyChangedActors) }' affected.json \
+  | npx apify-test-tools build --version-number default --dry-run
+
+npx apify-test-tools notify --slack-channel "#notif-my-repo" --dry-run < affected.json
+```
+
+[`notify`](#notifying-notify) says what it posts for a release.
+
+### The last released commit (`--since`)
+
+The last commit that is **already released**. Everything after it, up to `HEAD`, is released. Git alone can't tell
+which commits a push brought, and guessing wrong silently leaves Actors on old code, so it has to be passed.
+
+The changed files come from diffing `--since` and `HEAD` directly, so this works for every merge strategy as long as
+`--since` is the branch tip from **before** the push:
+
+| Merge strategy                 | What lands on the branch          | What to pass                                                           |
+| ------------------------------ | --------------------------------- | ---------------------------------------------------------------------- |
+| Squash and merge               | 1 new commit                      | the push's "before" commit (`HEAD~1` also works)                       |
+| Merge commit                   | the PR's commits + 1 merge commit | the push's "before" commit (`HEAD^1`, the first parent, also works)    |
+| Rebase and merge / direct push | N new commits                     | the push's "before" commit (`HEAD~1` would miss the first N-1 commits) |
+
+On GitHub, the push's "before" commit is `${{ github.event.before }}`, which the reusable workflow passes for you.
+On other CIs use the equivalent, e.g. `$CI_COMMIT_BEFORE_SHA` on GitLab. The checkout needs the full history
+(`fetch-depth: 0` in `actions/checkout`) so the commit is available locally.
+
+`get-affected-actors --since` without `--base` fails instead of guessing when:
+
+- the commit is all zeros (GitHub sends this for a push that created the branch)
+- the commit isn't in the local history (shallow checkout) or isn't an ancestor of `HEAD` (the branch was
+  force-pushed)
+
+In those cases, rerun it with a `--since` you pick yourself: an ancestor of `HEAD` from before the changes you want
+to release (for a shallow checkout, fetch the full history instead). `--actors` only narrows which of the changed
+Actors are reported; it never forces a build, so on its own it doesn't get past these errors. If `HEAD` is
+`--since`, nothing is reported, so nothing is built or announced.
+
+A failed release isn't retried by the next push: that push's base commit is the failed one's head, so its changes
+are skipped. Re-run the failed workflow run, or release the Actors manually.
+
+## Running tests (`test`)
+
+`test` runs the repository's own vitest (the version in its `node_modules`, so the tests keep the lib version
+the repository locked) on the Actors it is given on stdin, and prints a report of the run for
+[`notify`](#notifying-notify). Only the tests of those Actors run.
+
+```bash
+# A PR: test what was just built
+... | npx apify-test-tools build --version-number 0.99 | npx apify-test-tools test > test-report.json
+
+# Scheduled tests: every Actor in the config, on its default build
+npx apify-test-tools get-actor-configs \
+    | npx apify-test-tools test --test-files-glob 'test/platform/{hourly,hourly-without-pr}/**' > test-report.json
+
+# Only some of them
+npx apify-test-tools get-actor-configs --actors john.doe/my-actor | npx apify-test-tools test > test-report.json
+```
+
+The input is a JSON array of Actors, each given by its full name, its raw ID or both:
+`[{ "actorFullName": "<owner/name>" }]` or `[{ "actorRawId": "<id>" }]`. An Actor's tests run against the build given
+with it (`buildId` and `buildNumber`, as `build` and `build-from-local` print them), or against its default build
+without one. Other fields are ignored, so the output of [`get-actor-configs`](#listing-actors-get-actor-configs) works
+as it is. `test` looks up the ID an Actor is listed without with `TESTER_APIFY_TOKEN`, so its tests run whichever ID
+they name it by. An Actor the token can't see keeps only the ID it was listed with, and a warning names it, so an
+Actor no test uses doesn't stop the run. A dry-run plan, empty or invalid input is an error, as with `build`. So is a
+missing `TESTER_APIFY_TOKEN`: without it the lib skips every platform test, and the run would pass having tested
+nothing. `test` passes the Actors to vitest as `ACTOR_BUILDS`, in place of any
+`ACTOR_BUILDS` in its own environment.
+
+It runs vitest with `--maxConcurrency=20 --fileParallelism --maxWorkers=100`, since platform tests mostly wait on
+Actor runs rather than the CPU, and with the default reporter plus the JSON one the report is read from. These
+replace any `reporters` in the repository's vitest config; add more with `--reporter`, e.g. `github-actions` to
+annotate the failing tests in a GitHub Actions run. It takes no other vitest options; for those, e.g. `-t` to run one
+test by name, run vitest directly with the builds in `ACTOR_BUILDS` (see
+[Running tests locally](lib.md#running-tests-locally)).
+
+| Flag                   | Default            | Meaning                                                                                                                         |
+| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `--test-files-glob`    | `test/platform/**` | Glob from the repo root of the test files to run, see below                                                                     |
+| `--vitest-output-file` |                    | Also keep vitest's own JSON report there, e.g. to upload it                                                                     |
+| `--reporter`           |                    | [Vitest reporter](https://vitest.dev/guide/reporters) to add to `default` and `json`, e.g. `github-actions`. Repeat it for more |
+
+`test` takes no test paths as arguments, only `--test-files-glob`. The glob is read the same way as
+`platformTestsGlob` in the config file. Vitest filters are parts of a file path, not globs, so `test` finds the files
+the glob matches and passes vitest as few paths as it can: each folder whose files all match, with a trailing `/`, and
+the other matched files one by one. `test/platform/{daily,hourly}/**` becomes two folders however many tests they
+hold, so the command line stays short. Vitest still applies its own `include` and `exclude`, so helper files in the
+glob run nothing. A glob that matches no file is an error, because vitest without filters would run every test of the
+repo. Quote the glob, so the shell doesn't expand it.
+
+Vitest's own output goes to stderr, followed by a summary that lists every test with the link to its run. Stdout
+gets only the report:
+
+```json
+{
+    "kind": "test-report",
+    "version": 1,
+    "success": false,
+    "summary": { "total": 3, "passed": 1, "failed": 1, "skipped": 1 },
+    "tests": [
+        {
+            "name": "john.doe/my-actor: finishes",
+            "file": "test/platform/my-actor.test.ts",
+            "status": "failed",
+            "durationMs": 61234,
+            "failureMessages": ["AssertionError: expected 'FAILED' to be 'SUCCEEDED'"],
+            "run": { "actorId": "john.doe/my-actor", "runId": "…", "runLink": "https://console.apify.com/view/runs/…" }
+        }
+    ],
+    "errors": ["test/platform/other.test.ts: Cannot find package 'foo'"]
+}
+```
+
+`failureMessages` keeps the first line of each failure; diffs and stack traces are in the vitest output. `run` is
+`null` for a test that started no run. `errors` lists what failed outside of any test: a test file that failed to
+load, or vitest exiting without a report. `test` exits with 1 whenever `success` is false, and prints the report
+anyway, so `notify` still hears about the failure.
+
+## Notifying (`notify`)
+
+`notify` tells one target about what it reads on stdin: a test run, as [`test`](#running-tests-test) reports it,
+or a release, as [`get-affected-actors`](#finding-affected-actors-get-affected-actors) reports it. It tells the two
+apart by the report's `kind` and the release's `commits`, so either can be piped in as it is. Slack is the only target for now. To post to more
+places, call it once for each.
+
+```bash
+# A test run: posts only when the tests failed, the failure counts and the first failure, linked to its run,
+# with the other failures in the message's thread
+npx apify-test-tools notify --slack-channel '#notif-my-repo' < test-report.json
+npx apify-test-tools notify --slack-channel '#my-team' < test-report.json
+
+# Or straight from test. With `set -o pipefail` (`shell: bash` in GitHub Actions), failed tests still fail the pipe
+npx apify-test-tools get-actor-configs | npx apify-test-tools test | npx apify-test-tools notify --slack-channel '#notif-my-repo'
+
+# A release, see Releasing Actors
+npx apify-test-tools get-affected-actors --since <sha> | npx apify-test-tools notify --slack-channel '#notif-my-repo'
+```
+
+| Flag              | Input   | Default             | Meaning                                                           |
+| ----------------- | ------- | ------------------- | ----------------------------------------------------------------- |
+| `--slack-channel` | both    |                     | Slack channel to post to                                          |
+| `--on`            | tests   | `failure`           | `failure` posts only when the tests failed, `always` on every run |
+| `--title`         | tests   | `-`                 | What the message calls the run, e.g. the CI workflow name         |
+| `--job-url`       | tests   |                     | Link to the CI job, included in the message                       |
+| `--repo-url`      | release | the `origin` remote | The repository the release is named after and its commits link to |
+
+A flag the input has no use for, e.g. `--repo-url` with a test report, is an error rather than ignored. Both kinds
+of notification post with `SLACK_BOT_TOKEN`.
+
+Without a target, `notify` posts nothing and needs no token. With one, it checks the token on every run, also when
+there is nothing to post, so a broken token shows up on a green run rather than on the day tests fail. A release
+with no new commits is the exception: there is nothing to announce, so it needs no token either.
+
+For a release, `notify` posts the changelog additions, then the commits, oldest first. Each commit is its title (cut
+at 200 characters) linked to its page on GitHub, and its author. A merge commit or a squash merge is one commit; a
+rebase merge lists every commit it brought. A repository hosted elsewhere gets the titles without links. The release
+is named after the `origin` remote (or `--repo-url`) and the author of the newest commit. Nothing is posted when there
+are no new commits:
+
+```text
+*my-repo* – New release (by Jane Doe):
+
+- Fixed pagination on the search page
+
+*Commits*:
+1. <https://github.com/my-org/my-repo/commit/1a2b3c…|fix: pagination on the search page> – Jane Doe
+```
+
+## Deleting old builds (`delete-old-builds`)
+
+Deletes builds older than 30 days of every selected Actor. It never deletes the default build, or a build tagged
+`latest`, `version…`, `v-…` or `v0`–`v9…`. A build tagged `devel` is kept for only 7 days.
+
+| Flag        | Default | Meaning                                                     |
+| ----------- | ------- | ----------------------------------------------------------- |
+| `--actors`  | all     | Only these Actors                                           |
+| `--ignore`  | none    | Never these Actors                                          |
+| `--dry-run` | `false` | List the builds that would be deleted without deleting them |
+
+## Listing Actors (`get-actor-configs`)
+
+Prints the [config](../README.md#config-file) as the tool resolves it: one entry per Actor, with the group's values
+applied and `actor.json` read. Takes `--actors` and `--ignore`. Useful to check a config change.
+
+## Running locally
+
+Running the tests locally is useful when you only want to update the testing code in `test/`, because you can
+iterate on it without pushing new code to the remote. If you only change tests, skip the builds entirely and run
+them against the default builds, see [Running tests locally](lib.md#running-tests-locally).
+
+To test changed Actor source, you need builds of it. The quickest way is
+[`build-from-local`](#build-from-local-source-build-from-local), which needs no push:
+
+```bash
+APIFY_TOKEN_JOHN_DOE=apify_api_xxx \
+    npx apify-test-tools build-from-local --actors john.doe/my-actor > builds.json
+```
+
+To build from git, like CI does:
+
+1. Switch to a dummy branch that you will push and can later delete
+2. `npm i apify-test-tools@latest -D`
+3. Push your code (changes you want to test)
+4. Build the Actors on Apify (with your new code)
+5. Run tests against those builds. You can change tests and run on the same builds.
+
+```bash
+npx apify-test-tools get-affected-actors --base origin/master \
+    | jq '{ actors: (.functionallyChangedActors + .testChangedActors) }' \
+    | APIFY_TOKEN_JOHN_DOE=apify_api_xxx npx apify-test-tools build --version-number 0.99 > builds.json
+```
+
+Run it with your dummy branch checked out: it builds the Actors that branch changed functionally, from the branch as
+it is on the remote, into the test version `0.99`. Add `--dry-run` to `build` to print the plan (the version and Git
+URL each Actor would be built from) first, and update `--base` to the branch you compare against. Tests only run for
+Actors in `ACTOR_BUILDS`, so the `jq` filter also builds the Actors whose platform tests changed.
+
+If you want to test against existing builds instead, skip the build and write the build array by hand, only for the
+Actors you need to test.
+
+Then run the tests against the builds with [`test`](#running-tests-test), as often as you like:
+
+```bash
+TESTER_APIFY_TOKEN=apify_api_yyy npx apify-test-tools test < builds.json
+```