apify-test-tools 0.10.2-beta.0 → 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

@@ -59,44 +59,21 @@ jobs:
                   args=(
                     --source-branch "origin/$HEAD_REF"
                     --target-branch "origin/$BASE_REF"
+                    # TODO: Temporary hotfix until build glob matching aligns with Vitest's test selection glob.
+                    --test-files-glob 'test/platform/**'
                     --use-docker-cache
                   )
                   [ -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"
 
-            # Test files are outside every actor's Docker build context, so the diff above finds nothing
-            # to build and every test skips. Right for "rebuild?", wrong for "test?".
-            - name: Find changed platform tests
-              id: changed_tests
-              env:
-                  # Branch names are attacker-controlled on fork PRs, so they reach the script as
-                  # environment variables rather than being interpolated into it.
-                  HEAD_REF: ${{ github.head_ref }}
-                  BASE_REF: ${{ github.base_ref }}
-              run: |
-                  changed=$(git diff --name-only --diff-filter=d "origin/$BASE_REF...HEAD" -- test/platform/ \
-                    | sed "s|^|./|" | tr '\n' ' ')
-                  branch_actors=$(npx apify-test-tools get-affected-actors \
-                    --source-branch "origin/$HEAD_REF" \
-                    --target-branch "origin/$BASE_REF")
-                  if [ -n "$changed" ] && [ "$branch_actors" = "[]" ]; then
-                    echo "target=$changed" | tee -a "$GITHUB_OUTPUT"
-                  elif [ -n "$changed" ]; then
-                    echo "Platform tests: the changed platform tests did not run. This branch also changes actor code validated at an earlier commit, so they could only have run against the deployed build, which lacks those changes. Re-run this job from scratch to rebuild and test together." >> "$GITHUB_STEP_SUMMARY"
-                  fi
-
             # Runs the repo's test code and its whole import graph, so it gets the tester token only.
             - name: Test
               env:
                   ACTOR_BUILDS: ${{ steps.build.outputs.actor_builds }}
                   TESTER_APIFY_TOKEN: ${{ secrets.TESTER_APIFY_TOKEN }}
-                  # No build to pin to, so lift the per-actor gate and let each run use the deployed build.
-                  RUN_ALL_PLATFORM_TESTS: ${{ steps.changed_tests.outputs.target && '1' || '' }}
-              # `related` runs the tests that import each changed file, so a changed helper runs its dependents.
-              # A plain filter would match no test for a helper and exit 1; `related` exits 0 when nothing imports it.
-              run: npx vitest ${{ steps.changed_tests.outputs.target && format('related {0}', steps.changed_tests.outputs.target) || format('./test/platform/{0}', inputs.test-files-glob) }} --run --maxConcurrency 20 --fileParallelism=true --maxWorkers 100
+              run: npx vitest ./test/platform/${{ inputs.test-files-glob }} --run --maxConcurrency 20 --fileParallelism=true --maxWorkers 100
 
             # NOTE: This is an optimization that if we did functional changes and later only cosmetic changes (e.g. dev readme), we will compare changes files only for the last commit. This must run after tests because we want to cache the latest commit only if the tests are successful
             - name: Store last validated commit to cache
@@ -111,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,9 +5,14 @@ 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)
+- Build and test on test-only changes even when .dockerignore lists the tests ([#177](https://github.com/apify/apify-test-tools/pull/177)) ([5cb1b5a](https://github.com/apify/apify-test-tools/commit/5cb1b5ab5f6f43ec279f9624b402e73d55a5974a)) by [@artogahr](https://github.com/artogahr), closes [#145](https://github.com/apify/apify-test-tools/issues/145)
 
 
 <!-- git-cliff-unreleased-end -->

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.