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

package/.github/scripts/run-with-apify-tokens.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 // Runs apify-test-tools and passes it only secrets needed for the Actors, no other secrets are leaked.
 //
-//     node .github/scripts/run-with-apify-tokens.mjs npx apify-test-tools build --target-branch ...
+//     node .github/scripts/run-with-apify-tokens.mjs apify-test-tools build --target-branch ...
 //
 // The step passes the whole secrets map as ALL_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 ALL_SECRETS itself is dropped, so the blob never reaches npx or
+// repo holds) is left out, and ALL_SECRETS itself is dropped, so the blob never reaches the CLI or
 // anything under node_modules.
 //
 // The command runs without a shell, so branch names and other interpolated arguments are passed

package/.github/workflows/_check_code.yaml

@@ -92,3 +92,28 @@ jobs:
               run: npm ci
             - name: Build
               run: npm run build
+
+    # The composite action runs the CLI from .github/cli/apify-test-tools.mjs, which the pre-commit
+    # hook rebuilds. This catches commits that skipped the hook, so a stale bundle never ships.
+    cli_bundle:
+        name: CLI bundle
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v6
+            - name: Use Node.js
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: 'npm'
+                  cache-dependency-path: 'package-lock.json'
+            - name: Install dependencies
+              run: npm ci
+            - name: Check the bundle is up to date
+              run: |
+                  npm run bundle
+                  if ! git diff --quiet -- .github/cli/; then
+                      echo "::error::.github/cli/apify-test-tools.mjs is out of date. Run \`npm run bundle\` and commit the result."
+                      exit 1
+                  fi
+                  node .github/cli/apify-test-tools.mjs --help > /dev/null

package/.github/workflows/_move_major_tag.yaml

@@ -1,13 +1,8 @@
 name: Move major version tag
 
-# Consumer repos track a floating major tag (`...@v0`), not `master`, so merging to master does not
-# ship anything by itself. This workflow is what ships: it moves that tag forward, but only once the
-# package version the workflows pin in .github/workflows-package-version is actually on npm.
-#
-# That gate is the whole point. The workflows and the npm package release on their own schedules, so
-# the only combination that can break consumers is a workflow that calls a CLI feature which has not
-# been published yet. In that case the tag simply stays where it is and production keeps running the
-# previous workflows until someone cuts a release.
+# Consumer repos track a floating major tag (`...@workflows-v0`), not `master`. This workflow is what
+# ships: it moves that tag forward. The workflows and the CLI they call (bundled in .github/cli/)
+# live in the same commit, so whatever the tag points at is consistent on its own.
 
 on:
     workflow_call:
@@ -16,13 +11,6 @@ on:
                 description: Commit to move the tag to. Defaults to the commit that triggered the caller.
                 type: string
                 default: ''
-            wait_for_publish:
-                description: >-
-                    Set by a release that has just published the pinned version. npm accepts a publish
-                    before the version is readable, so the check waits instead of treating the gap as
-                    a held tag, and fails if the version never appears.
-                type: boolean
-                default: false
 
 permissions:
     contents: read
@@ -63,54 +51,7 @@ jobs:
               with:
                   ref: ${{ inputs.ref || github.sha }}
 
-            - name: Check the required package version is published
-              id: check
-              env:
-                  # npm accepts a publish and processes it asynchronously ("Your package is being
-                  # processed and may take a few minutes to become available"). Observed at ~19
-                  # minutes for a provenance-signed release, so the release path waits well past
-                  # npm's own estimate rather than shipping a tag consumers cannot install against.
-                  WAIT_SECONDS: ${{ inputs.wait_for_publish && 2400 || 0 }}
-              run: |
-                  pinned_version=$(cat .github/workflows-package-version)
-                  echo "pinned_version=$pinned_version" >> "$GITHUB_OUTPUT"
-
-                  deadline=$(( $(date +%s) + WAIT_SECONDS ))
-                  while :; do
-                      # --prefer-online so a 404 cached from an earlier attempt cannot outlive the
-                      # publish it was polling for.
-                      if output=$(npm view "apify-test-tools@$pinned_version" version --prefer-online 2>&1); then
-                          echo "apify-test-tools@$pinned_version is on npm"
-                          echo "published=true" >> "$GITHUB_OUTPUT"
-                          exit 0
-                      fi
-
-                      # Anything that is not "this version does not exist" is a registry, network or
-                      # auth problem. Sitting in the retry loop would hide it behind a held tag.
-                      if ! grep -q 'code E404' <<< "$output"; then
-                          echo "::error::npm view failed for a reason other than the version being absent."
-                          echo "$output"
-                          exit 1
-                      fi
-
-                      if [ "$(date +%s)" -ge "$deadline" ]; then
-                          break
-                      fi
-                      echo "apify-test-tools@$pinned_version is not on npm yet, retrying in 30s"
-                      sleep 30
-                  done
-
-                  echo "published=false" >> "$GITHUB_OUTPUT"
-
-                  # A release waited for its own publish and never saw it. That is a broken release,
-                  # not a held tag, and it has to be red so it can be re-run once npm catches up.
-                  if [ "$WAIT_SECONDS" -gt 0 ]; then
-                      echo "::error::apify-test-tools@$pinned_version was published by this run but is still not readable after $((WAIT_SECONDS / 60))m. Re-run this job once it appears on npm."
-                      exit 1
-                  fi
-
             - name: Move tag
-              if: steps.check.outputs.published == 'true'
               env:
                   TARGET_SHA: ${{ inputs.ref || github.sha }}
               run: |
@@ -120,23 +61,4 @@ jobs:
                       echo "### \`$MAJOR_TAG\` moved"
                       echo
                       echo "Now points at \`$TARGET_SHA\`."
-                      echo "Pins \`apify-test-tools@${{ steps.check.outputs.pinned_version }}\`, which is published."
-                  } >> "$GITHUB_STEP_SUMMARY"
-
-            # Not a failure. Holding the tag is the designed outcome of merging a workflow change
-            # that needs an unreleased package feature, and consumers are unaffected while it waits.
-            - name: Report held tag
-              if: steps.check.outputs.published != 'true'
-              env:
-                  TARGET_SHA: ${{ inputs.ref || github.sha }}
-              run: |
-                  {
-                      echo "### \`$MAJOR_TAG\` held"
-                      echo
-                      echo "\`$TARGET_SHA\` pins \`apify-test-tools@${{ steps.check.outputs.pinned_version }}\`, which is not on npm."
-                      echo "Consumers keep running the workflows \`$MAJOR_TAG\` already points at."
-                      echo
-                      echo "Publish that version with the **Stable release** workflow. The tag moves on the"
-                      echo "next master push, or immediately via the **Move major version tag** workflow."
                   } >> "$GITHUB_STEP_SUMMARY"
-                  echo "::warning::$MAJOR_TAG not moved: apify-test-tools@${{ steps.check.outputs.pinned_version }} is not published yet."

package/.github/workflows/_tests.yaml

@@ -3,6 +3,10 @@ name: Tests
 on:
     workflow_dispatch:
     workflow_call:
+        secrets:
+            # Token of an isolated sandbox account that can only reach the e2e test's two dummy Actors.
+            E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR:
+                required: false
 
 permissions:
     contents: read
@@ -33,3 +37,33 @@ jobs:
 
             - name: Unit tests
               run: npm test
+
+    # Runs the shipped CLI bundle against real Actors (test/e2e). Node 24 only, so one push builds
+    # and runs the sandbox Actors once rather than once per Node version.
+    e2e_tests:
+        name: E2E tests
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v6
+
+            - name: Use Node.js
+              uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: 'npm'
+                  cache-dependency-path: 'package-lock.json'
+
+            - name: Install dependencies
+              run: npm ci
+
+            # The token is only on this step. Fork and Dependabot PRs don't get the secret, and the
+            # suite skips itself without it.
+            - name: E2E tests
+              env:
+                  E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR: ${{ secrets.E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR }}
+              run: |
+                  if [ -z "$E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR" ]; then
+                      echo "::notice::E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR is not available to this run, the e2e tests are skipped."
+                  fi
+                  npm run test:e2e

package/.github/workflows/_update_release_metadata.yaml

@@ -77,18 +77,6 @@ jobs:
                   write-mode: overwrite
                   contents: ${{ needs.release_metadata.outputs.changelog }}
 
-            # The reusable workflows install this exact version, so the commit that releases a
-            # version is the commit that pins it. That is what lets a frozen major tag keep
-            # installing the library it was tested against instead of drifting to whatever is
-            # newest.
-            #
-            # Skipped for prereleases: master pushes release a `-beta` that consumer repos must
-            # never install. Their pin stays on the last stable, and the beta stays reachable
-            # through the lockfile path in the setup action, which is how branch testing works.
-            - name: Update the version the workflows pin
-              if: inputs.release_type != 'prerelease'
-              run: echo "${{ needs.release_metadata.outputs.version_number }}" > .github/workflows-package-version
-
             - name: Commit changes
               id: commit
               uses: apify/actions/signed-commit@v1.0.0

package/.github/workflows/manual_move_major_tag.yaml

@@ -1,8 +1,8 @@
 name: Move major version tag
 
-# Escape hatch for the two cases the automatic move does not cover: shipping a workflow change right
-# after the release that unblocked it, without waiting for the next master push, and rolling the tag
-# back to an earlier commit when a shipped workflow turns out to be broken.
+# Escape hatch for what the automatic move on master pushes does not cover: rolling the tag back to
+# an earlier commit when a shipped workflow or CLI turns out to be broken, or moving it after a push
+# whose checks failed for an unrelated reason.
 
 on:
     workflow_dispatch:

package/.github/workflows/manual_release_stable.yaml

@@ -36,6 +36,9 @@ jobs:
     tests:
         name: Tests
         uses: ./.github/workflows/_tests.yaml
+        # Only the sandbox token, not `secrets: inherit`: the test job runs test code.
+        secrets:
+            E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR: ${{ secrets.E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR }}
 
     release_metadata:
         name: Update release metadata
@@ -79,16 +82,3 @@ jobs:
                           "ref": "${{ needs.release_metadata.outputs.changelog_commitish }}",
                           "tag": "latest"
                       }
-
-    # This release is what unblocks a major tag being held for an unpublished package version, so
-    # try the move again now rather than making someone wait for the next master push. A no-op when
-    # the tag was not being held.
-    move_major_tag:
-        name: Move major version tag
-        needs: [release_metadata, npm_publish]
-        permissions:
-            contents: write
-        uses: ./.github/workflows/_move_major_tag.yaml
-        with:
-            ref: ${{ needs.release_metadata.outputs.changelog_commitish }}
-            wait_for_publish: true

package/.github/workflows/on_master.yaml

@@ -24,14 +24,18 @@ jobs:
         if: "!startsWith(github.event.head_commit.message, 'docs')"
         name: Tests
         uses: ./.github/workflows/_tests.yaml
+        # Only the sandbox token, not `secrets: inherit`: the test job runs test code.
+        secrets:
+            E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR: ${{ secrets.E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR }}
 
-    # Ships any workflow change in this push to consumer repos. Deliberately independent of the npm
-    # release below: a workflow-only change needs no release, and a package-only release leaves the
-    # workflows byte-identical. `code_checks` runs actionlint, which is what validates the workflows;
-    # `tests` covers the npm package and is skipped for docs commits, so it is not a dependency here.
+    # Ships this push to consumer repos: the workflows and the CLI bundled in .github/cli/ go live
+    # together. Independent of the npm release below, which only matters to people importing the lib.
+    # `code_checks` runs actionlint and checks the bundle is up to date. `tests` cover the CLI but are
+    # skipped for docs commits, so a skipped run does not hold the tag; a failed one does.
     move_major_tag:
         name: Move major version tag
-        needs: [code_checks]
+        needs: [code_checks, tests]
+        if: ${{ !failure() && !cancelled() }}
         permissions:
             contents: write
         uses: ./.github/workflows/_move_major_tag.yaml

package/.github/workflows/on_pull_request.yaml

@@ -21,51 +21,6 @@ jobs:
     tests:
         name: Tests
         uses: ./.github/workflows/_tests.yaml
-
-    # Catches the one combination that breaks consumers: a workflow starting to use a CLI feature
-    # from the same PR. Merging ships the workflow immediately, so the pinned version has to move in
-    # the same change or the workflow goes live calling something that is not published.
-    package_version_bump_needed:
-        name: Package version bump needed
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v6
-              with:
-                  fetch-depth: 0
-                  ref: ${{ github.event.pull_request.head.sha }}
-
-            - name: Check whether this PR needs a version bump
-              env:
-                  BASE_REF: ${{ github.base_ref }}
-                  PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
-              run: |
-                  git fetch --no-tags origin "$BASE_REF"
-                  git diff --name-only FETCH_HEAD...HEAD | node .github/scripts/check-package-version-bump.mjs
-
-    # Reports whether merging this PR will ship the workflows or hold the major tag until a release.
-    # Never fails: pinning a version ahead of the release that publishes it is a supported way to
-    # land the package change and the workflow change that needs it in one PR.
-    workflows_package_version:
-        name: Workflows package version
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v6
-
-            - name: Check the pinned package version is published
-              run: |
-                  pinned_version=$(cat .github/workflows-package-version)
-                  if npm view "apify-test-tools@$pinned_version" version >/dev/null 2>&1; then
-                      echo "Workflows pin apify-test-tools@$pinned_version, which is published."
-                      echo "The major tag moves on merge and these workflows go live." >> "$GITHUB_STEP_SUMMARY"
-                  else
-                      {
-                          echo "### Major tag will be held on merge"
-                          echo
-                          echo "These workflows pin \`apify-test-tools@$pinned_version\`, which is not on npm yet."
-                          echo "Merging is fine: consumers keep running the current workflows until you cut a"
-                          echo "stable release, and the tag moves once that version is published."
-                      } >> "$GITHUB_STEP_SUMMARY"
-                      echo "::notice::Merging will not ship these workflows until apify-test-tools $pinned_version is released."
-                  fi
+        # Only the sandbox token, not `secrets: inherit`: the test job runs test code.
+        secrets:
+            E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR: ${{ secrets.E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR }}

package/.github/workflows/public_platform-tests.yaml

@@ -47,7 +47,7 @@ jobs:
                     --fileParallelism=true \
                     --maxWorkers 100
                   return_code=$?
-                  npx apify-test-tools report-tests \
+                  apify-test-tools report-tests \
                     --report-file ./test-output.json \
                     --workflow-name "${{ github.workflow }}" \
                     --job-url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \

package/.github/workflows/public_pr-build-test.yaml

@@ -65,7 +65,7 @@ jobs:
                   )
                   [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
                   actor_builds=$(node "$SCRIPTS_PATH/run-with-apify-tokens.mjs" \
-                    npx apify-test-tools build "${args[@]}")
+                    apify-test-tools build "${args[@]}")
                   echo "actor_builds=$actor_builds" | tee -a "$GITHUB_OUTPUT"
 
             # Runs the repo's test code and its whole import graph, so it gets the tester token only.
@@ -88,7 +88,7 @@ jobs:
                     --target-branch "origin/$BASE_REF"
                   )
                   [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
-                  npx apify-test-tools get-latest-commit "${args[@]}" > ./base_commit.txt
+                  apify-test-tools get-latest-commit "${args[@]}" > ./base_commit.txt
                   echo "New last validated (base) commit: $(cat base_commit.txt)"
 
     # Pure static checks against the repo. Needs no Apify or Slack credentials, only the npm

package/.github/workflows/public_push-build-latest.yaml

@@ -36,11 +36,11 @@ jobs:
                   SLACK_TOKEN_RELEASES_BOT: ${{ secrets.SLACK_TOKEN_RELEASES_BOT }}
               run: |
                   node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-                    npx apify-test-tools release --base-commit ${{ github.event.before }} --release-slack-channel "#delivery-public-actors" --report-slack-channel "${{ inputs.report-slack-channel || format('#notif-{0}', github.event.repository.name) }}" --use-docker-cache
+                    apify-test-tools release --base-commit ${{ github.event.before }} --release-slack-channel "#delivery-public-actors" --report-slack-channel "${{ inputs.report-slack-channel || format('#notif-{0}', github.event.repository.name) }}" --use-docker-cache
 
             - name: Delete old builds
               env:
                   ALL_SECRETS: ${{ toJSON(secrets) }}
               run: |
                   node "${{ steps.setup.outputs.scripts-path }}/run-with-apify-tokens.mjs" \
-                    npx apify-test-tools delete-old-builds
+                    apify-test-tools delete-old-builds

package/.husky/pre-commit

@@ -1,6 +1,11 @@
 echo "pre-commit: typechecking, linting, testing, checking code formatting, checking for unused exports & validating schemas"
 
 
+# The workflows run the CLI from this bundle, so it ships with every commit that changes bin/ or its
+# dependencies. Rebuilding takes well under a second.
+npm run -s bundle
+git add .github/cli/apify-test-tools.mjs
+
 npm test
 npm run format:check
 # We typecheck & lint last when we know our code works

package/.prettierignore

@@ -8,3 +8,6 @@ CHANGELOG.md
 
 # Fixtures must stay byte-exact — several are deliberately malformed or empty
 test/fixtures
+
+# Generated by `npm run bundle`
+.github/cli/

package/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 <!-- git-cliff-unreleased-start -->
 ## 0.10.2 - **not yet released**
 
+### 🚀 Features
+
+- **ci:** Ship the workflows&#x27; CLI as a bundle in the action instead of installing it ([#200](https://github.com/apify/apify-test-tools/pull/200)) ([a0ef975](https://github.com/apify/apify-test-tools/commit/a0ef9756123a30a8210590b080a2a289c6a9c17c)) by [@metalwarrior665](https://github.com/metalwarrior665)
+
 ### 🐛 Bug Fixes
 
 - **toBeObject:** Reject null ([#191](https://github.com/apify/apify-test-tools/pull/191)) ([6bdae49](https://github.com/apify/apify-test-tools/commit/6bdae4905756e0ae8dd6146942e6fc04dbead48e)) by [@JuanGalilea](https://github.com/JuanGalilea), closes [#88](https://github.com/apify/apify-test-tools/issues/88)

package/CONTRIBUTING.md

@@ -89,24 +89,14 @@ Consumers pin `@workflows-v0`, not `@master`. See
 [Versioning and releases](./README.md#versioning-and-releases) in the README for how the tag and the
 npm release relate — the short version:
 
-- changing only a workflow needs no npm release
-- changing only the package needs no workflow change
-- a workflow that calls a **new** CLI feature must set `.github/workflows-package-version` to the
-  version that will contain it, in the same PR. The `workflows-v0` tag is then held until that version is on
-  npm, so merging can't ship a workflow that calls a CLI that doesn't exist yet.
-
-`.github/workflows-package-version` holds one exact version, and the stable release writes it. The
-workflows install exactly it, which is what makes a frozen major tag stay frozen — it keeps the
-library it was tested with instead of following `latest` forever.
-
-The `Package version bump needed` check enforces the point above: a PR touching both a `public_`
-workflow (or the composite action) and `bin/`, `lib/` or `index.ts` has to move the pin. When the
-two changes are unrelated and the workflow doesn't need the new code, label the PR
-`no-version-bump-needed`.
-
-It only looks at a single PR, so it won't catch a workflow that starts using a CLI feature merged in
-an earlier, still-unreleased PR. That needs someone to land a CLI change and sit on it unreleased;
-catching it would mean flagging every workflow edit made while any package change is unreleased.
+- the workflows and the CLI ship together on every master push, through the tag; no npm release needed
+- the lib ships through a stable npm release
+- the CLI runs from `.github/cli/apify-test-tools.mjs`, a bundle the pre-commit hook rebuilds with
+  `npm run bundle`. If you commit with `--no-verify`, run it yourself: the `CLI bundle` check fails
+  on a stale bundle, and a stale bundle would hold the tag.
+- `npm test` covers the bundle without network (`test/bundle/`). `npm run test:e2e` runs it against two
+  dummy Actors in an isolated sandbox account (`test/e2e/`) and skips itself unless
+  `E2E_TEST_APIFY_TOKEN_DBYPODOIHUZABNQTR` is set. CI passes that secret only to the `E2E tests` job.
 
 `npm run lint` and `actionlint` (via the `Code checks` workflow) both gate master, so run them before
 pushing workflow changes.

package/README.md

@@ -308,48 +308,35 @@ Slack credentials in scope, so a postinstall script in the dependency tree canno
 
 ## Versioning and releases
 
-The workflows and the npm package live in one repo but ship on their own schedules. Two pointers
-decide what a consumer repo actually runs:
-
-| Pointer                             | What it selects                                | Moves when                                               |
-| ----------------------------------- | ---------------------------------------------- | -------------------------------------------------------- |
-| the `@workflows-v0` tag in `uses:`  | which workflows run                            | a master push, once the version below is published       |
-| `.github/workflows-package-version` | which `apify-test-tools` the workflows install | a stable release writes it; you may set it ahead of time |
-
-The setup action installs that **exact** version — not a range. A tag is therefore a complete
-statement: these workflows _and_ this library. The stable release writes the file into the same
-commit that bumps `package.json` and `CHANGELOG.md`, so a released commit always names the version
-it published, and rollout latency is unchanged: the release publishes and moves the tag in one run.
-
-Prereleases are excluded. Master pushes publish a `-beta` that consumer repos must never install, so
-the pin only moves on a stable release; betas stay reachable through the lockfile path in the setup
-action, which is how branch testing works.
-
-Nothing is coupled that doesn't need to be:
-
-- **Workflow-only change** — merge it. `workflows-v0` moves, it goes live, no release needed.
-- **Package-only change** — merge it, then cut a release when you want it out. The workflows are
-  unchanged, so consumers see nothing until the release lands.
-- **A workflow that calls a new CLI feature** — the one case that can break consumers, and the only
-  one with any ceremony. Put the package change, the workflow change, and the new pin in one PR. On
-  merge the tag is **held**: the CI job reports that the pinned version isn't on npm and leaves `workflows-v0`
-  where it is, so consumers keep running the previous workflows. Cut a stable release, and the tag
-  moves on its own. Run **Move major version tag** if you don't want to wait for the next master
-  push.
+The workflows and the npm package live in one repo but ship on their own schedules:
+
+| What                                         | Consumers get it through                   | Ships when              |
+| -------------------------------------------- | ------------------------------------------ | ----------------------- |
+| the workflows and the CLI they call          | the `@workflows-v0` tag in `uses:`         | every master push       |
+| the lib (`testActor`, `describe`, matchers…) | `apify-test-tools` in their `package.json` | a stable release on npm |
+
+The CLI is bundled with its dependencies into `.github/cli/apify-test-tools.mjs` (`npm run bundle`,
+run by the pre-commit hook and checked in CI), and the setup action runs it from there. Nothing is
+installed for it, so a tag is a complete statement: these workflows and this CLI, with the exact
+dependency versions from `package-lock.json` at that commit. The consumer's own `node_modules` is
+left alone, so their tests keep the lib version they locked.
+
+- **Workflow or CLI change** — merge it. `workflows-v0` moves once checks and tests pass, and it goes
+  live. No release needed, even when a workflow starts using a new CLI feature: both are in the
+  same commit.
+- **Lib change** — merge it, then cut a release when you want it out. Consumers pick it up when
+  they update `apify-test-tools`.
+
+The CLI and the lib in one job can be different versions now, so the formats between them are a
+contract: the `ACTOR_BUILDS` JSON that `build` writes and the lib reads, and the vitest JSON report
+`report-tests` reads. Add fields freely; renaming or removing one needs a new major tag.
 
 `workflows-v0` moving on every master push means `@workflows-v0` is as live as `@master` was —
-there's no staging step, just a gate on the package version. What the tag buys you is a
-`workflows-v1` for breaking workflow changes, so repos migrate one at a time instead of all at once,
-and a way to roll back by pointing the tag at an earlier commit. Bump `MAJOR_TAG` in
+there's no staging step. What the tag buys you is a `workflows-v1` for breaking workflow changes,
+so repos migrate one at a time instead of all at once, and a way to roll back by pointing the tag at
+an earlier commit (**Move major version tag** workflow). Bump `MAJOR_TAG` in
 `.github/workflows/_move_major_tag.yaml` to cut the next major; the old tag then freezes where it is
-and keeps working.
-
-Freezing is real, which is the whole reason the version is pinned rather than a floor. A frozen `workflows-v0`
-points at a commit whose pinned version never changes, so it keeps installing the library it was
-tested against no matter how far the package moves on. Had the workflows installed `>=<floor>`, a
-frozen `workflows-v0` would still resolve to whatever is newest — and since the release that enables
-`workflows-v1` is usually the same release that breaks `workflows-v0`, the migration window would
-have been zero.
+and keeps working, CLI included, since the bundle is part of the frozen commit.
 
 The tag tracks the **workflows'** contract, not the npm package version. They move independently on
 purpose, so `@workflows-v0` is expected to stay `@workflows-v0` after the package reaches 1.0 —
@@ -360,9 +347,8 @@ and those refs disagree, which is the mistake that would otherwise ship silently
 ### Testing workflow changes
 
 - Point [testing-repo-for-github-actions](https://github.com/apify-store/testing-repo-for-github-actions)
-  at your branch (`uses: ...@your-branch`). It has real attached Actors and tests. Because the
-  package lives here too, a master push publishes a `beta`, and the lockfile-beta path in the setup
-  action installs that exact version — so one branch tests both halves of a change together.
+  at your branch (`uses: ...@your-branch`). It has real attached Actors and tests. The branch carries
+  its own CLI bundle, so one branch tests the workflows and the CLI together.
 - To change the composite action itself, repoint the `uses:` refs inside the reusable workflows at
   your branch as well, and change them back before merging.
 - Make sure the shell code actually works on your laptop first.
@@ -580,6 +566,15 @@ describe('standby tests', () => {
 
 The package includes a CLI binary used by CI workflows to build Actors, detect changes, and report test results. You can also run it locally.
 
+### Dry runs (`--dry-run`)
+
+Every command that changes something (`build`, `build-from-local`, `release`, `delete-old-builds`, `report-tests`) 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.
+
 ### Running locally
 
 Running the testing library 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.
@@ -610,7 +605,7 @@ APIFY_TOKEN_JOHN_DOE=<token> \
     --dry-run
 ```
 
-Remove `--dry-run` to actually trigger builds and update the branch names/ The command outputs a JSON array of build objects to stdout:
+With `--dry-run`, it prints the plan (the version and Git URL each Actor would be built from). Remove `--dry-run` to actually trigger builds and update the branch names. The command outputs a JSON array of build objects to stdout:
 
 ```json
 [{ "buildId": "...", "actorRawId": "...", "buildNumber": "...", "actorFullName": "john.doe/my-actor" }]
@@ -625,7 +620,7 @@ APIFY_TOKEN_JOHN_DOE=<token> \
   npx apify-test-tools build-from-local --actors john.doe/my-actor
 ```
 
-Pass a hardcoded actor name via `--actors` to build only that Actor (comma-separate multiple names). Omit `--actors` to build all Actors in the repo, or add `--dry-run` to preview without building. It outputs the same JSON build array as `build`, so you run tests against it the same way as in step 5 below:
+Pass a hardcoded actor name via `--actors` to build only that Actor (comma-separate multiple names). Omit `--actors` to build all Actors in the repo, or add `--dry-run` to check the token, the Actor and the zipped sources without uploading or building. It outputs the same JSON build array as `build`, so you run tests against it the same way as in step 5 below:
 
 ```bash
 # Build from local source and capture output