apify-test-tools 0.9.1-beta.0 → 0.9.1-beta.10

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

@@ -0,0 +1,175 @@
+name: Test
+
+on:
+    workflow_call:
+        inputs:
+            skip-platform-tests:
+                type: boolean
+                default: false
+                required: false
+            # Specify what tests you want to run, relative to `test/platform`
+            test-files-glob:
+                type: string
+                default: ''
+                required: false
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    platformTest:
+        if: ${{ !inputs.skip-platform-tests }}
+        runs-on: ubuntu-latest
+        steps:
+            - name: Setup repository and dependencies
+              id: setup
+              # For testing, you have to temporarily change the branch
+              uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
+              with:
+                  # Some repos use private npm packages, they need to pass NPM_TOKEN secret to this workflow
+                  npm-token: ${{ secrets.NPM_TOKEN }}
+
+            - name: Pick last validated commit from cache
+              id: base_commit
+              uses: actions/cache@v5
+              with:
+                  # We have to call it base commit for the library but it makes more sense as "last validated commit"
+                  # Using run_id ensures the key is always unique so the cache always saves at end-of-job (no "cache hit, not saving" issue)
+                  path: ./base_commit.txt
+                  key: base_commit-${{ github.run_id }}
+                  # This is needed to force overriding the cache with new entry at the end
+                  restore-keys: base_commit-
+
+            # run-with-apify-tokens.mjs reads the token names from in apify-test-tools.config.json
+            # and hands the build those secrets and nothing else, so the tokens stay in this one command instead of the whole job.
+            # The library never sees secrets it doesn't need
+            - name: Build
+              id: build
+              env:
+                  ALL_SECRETS: ${{ toJSON(secrets) }}
+                  # 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 }}
+                  SCRIPTS_PATH: ${{ steps.setup.outputs.scripts-path }}
+              run: |
+                  base_commit=$(cat base_commit.txt 2>/dev/null || echo "")
+                  echo "Last validated (base) commit to be used for build & test: $base_commit"
+                  args=(
+                    --source-branch "origin/$HEAD_REF"
+                    --target-branch "origin/$BASE_REF"
+                    --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[@]}")
+                  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
+
+            # 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
+              env:
+                  HEAD_REF: ${{ github.head_ref }}
+                  BASE_REF: ${{ github.base_ref }}
+              run: |
+                  base_commit=$(cat base_commit.txt 2>/dev/null || echo "")
+                  echo "Old last validated (base) commit: $base_commit"
+                  args=(
+                    --source-branch "origin/$HEAD_REF"
+                    --target-branch "origin/$BASE_REF"
+                  )
+                  [ -n "$base_commit" ] && args+=(--base-commit "$base_commit")
+                  npx 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
+    # token to install dependencies.
+    unitTest:
+        # TODO: only run on changes to code
+        runs-on: ubuntu-latest
+        steps:
+            - name: Setup repository and dependencies
+              # For testing, you have to temporarily change the branch
+              uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
+              with:
+                  npm-token: ${{ secrets.NPM_TOKEN }}
+
+            - name: TypeScript
+              # Some repos require custom build checks, so we check if the `build-check` script exists and run it if
+              # it does. Otherwise default to the standard `npx tsc --noEmit` check
+              run: |
+                  HAS_CUSTOM_BUILD_CHECK=$(jq -r '.scripts["build-check"] // empty' package.json)
+                  if [ -n "$HAS_CUSTOM_BUILD_CHECK" ]; then
+                      echo "Custom build check script found. Running it.";
+                      npm run build-check;
+                  else
+                      echo "No custom build check script found. Running standard tsc --noEmit.";
+                      npx tsc --noEmit;
+                  fi
+
+            - name: Lint
+              run: npm run lint
+
+            - name: Test
+              run: npm test
+
+            - name: Formatter Check
+              run: |
+                  HAS_FORMAT_CHECK_SCRIPT=$(jq -r '.scripts["format:check"] // empty' package.json)
+                  if [ -n "$HAS_FORMAT_CHECK_SCRIPT" ]; then
+                      echo "Custom format:check script found. Running it.";
+                      npm run format:check;
+                  elif [ -d "node_modules/prettier" ]; then
+                      echo "Prettier is installed. Running prettier --check .";
+                      npx prettier --check .;
+                  else
+                      echo "Prettier is not installed. Skipping Prettier check.";
+                  fi
+
+            - name: Unused Exports Check
+              run: |
+                  HAS_CHECK_UNUSED_SCRIPT=$(jq -r '.scripts["check-unused"] // empty' package.json)
+                  if [ -n "$HAS_CHECK_UNUSED_SCRIPT" ]; then
+                      echo "Custom check-unused script found. Running it.";
+                      npm run check-unused;
+                  elif [ -d "node_modules/knip" ]; then
+                      echo "Knip is installed. Running knip to check for unused exports.";
+                      npx knip --include exports,types;
+                  elif [ -d "node_modules/ts-unused-exports" ]; then
+                      echo "Knip is not installed, but ts-unused-exports is. Running ts-unused-exports to check for unused exports.";
+                      npx ts-unused-exports ./tsconfig.json;
+                  else
+                      echo "knip nor ts-unused-exports are installed. Skipping unused exports check.";
+                  fi

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

@@ -0,0 +1,44 @@
+name: Build latest and report to slack
+
+on:
+    workflow_call:
+        inputs:
+            # Defaults to #notif-<repo-name> when empty, matching the previous behavior.
+            report-slack-channel:
+                type: string
+                default: ''
+                required: false
+
+jobs:
+    pushBuildLatest:
+        name: 'Build latest: ${{github.repository}} ${{github.event.head_commit.message}}'
+        if: |
+            !contains(github.event.head_commit.message, '[skip ci]') &&
+            !contains(github.event.head_commit.message, '[skip platform-test]')
+
+        runs-on: ubuntu-latest
+        steps:
+            - name: Setup repository and dependencies
+              id: setup
+              # For testing, you have to temporarily change the branch
+              uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
+              with:
+                  npm-token: ${{ secrets.NPM_TOKEN }}
+
+            # run-with-apify-tokens.mjs reads the token names from in apify-test-tools.config.json
+            # and hands the build those secrets and nothing else, so the tokens stay in this one command instead of the whole job.
+            # The library never sees secrets it doesn't need
+            - name: Release Actors and notify
+              env:
+                  ALL_SECRETS: ${{ toJSON(secrets) }}
+                  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 --push-event-path ${{ github.event_path }} --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

package/.github/workflows/public_review.yaml

@@ -0,0 +1,107 @@
+name: 'Claude Code Review'
+
+on:
+    workflow_call:
+        inputs:
+            label:
+                default: Ask claude review
+                type: string
+                description: Label that triggers a review. Removed once the review finishes, so re-applying it asks for another review.
+                required: false
+            reviewed-label:
+                default: claude reviewed
+                type: string
+                description: Label added after a successful review and never removed. Set to an empty string to disable.
+                required: false
+            prompt-ref:
+                default: workflows-v0
+                type: string
+                description: >-
+                    Ref of this repository to fetch the review instructions from. Defaults to the
+                    major tag, matching the ref consumers call this workflow at. Override it only to
+                    test a prompt change from a branch.
+                required: false
+            model:
+                default: sonnet
+                type: string
+                description: Model to use for Claude Code (best, sonnet, opus, haiku, sonnet[1m], opus[1m], opusplan)
+                required: false
+        secrets:
+            ANTHROPIC_API_KEY:
+                required: true
+                description: Claude API key
+
+jobs:
+    review:
+        if: |
+            (github.event.action == 'labeled' && github.event.label.name == inputs.label) ||
+            (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, inputs.label))
+        runs-on: ubuntu-latest
+        timeout-minutes: 7
+        concurrency:
+            group: 'claude-code-review-${{ github.event.pull_request.number }}'
+            cancel-in-progress: true
+        permissions:
+            contents: 'read'
+            id-token: 'write'
+            issues: 'write'
+            pull-requests: 'write'
+        steps:
+            - name: Checkout Repository
+              uses: actions/checkout@v5
+              with:
+                  fetch-depth: 0
+                  # We want to test our branch, not GitHub's fake merge commit (we must test that before merging anyway)
+                  # head_ref must be used for pull_request but for push and schedule events we have to use ref to get the branch name
+                  ref: ${{ github.head_ref || github.ref }}
+
+            - name: 'Fetch review instructions'
+              run: |
+                  curl -sfL \
+                    "https://raw.githubusercontent.com/apify/apify-test-tools/${{ inputs.prompt-ref }}/.github/review-prompt.md" \
+                    -o "${{ github.workspace }}/.claude-review-prompt.md"
+
+            - name: 'Review PR against guidelines'
+              id: 'review'
+              uses: anthropics/claude-code-action@v1
+              env:
+                  GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+                  REPOSITORY: '${{ github.repository }}'
+                  PR_NUMBER: '${{ github.event.pull_request.number }}'
+              with:
+                  anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+                  # So a silent review is visibly silent: the report lands in the step summary.
+                  display_report: true
+                  # Do not set track_progress: it forces tag mode, which posts its own PR
+                  # comment and duplicates the review into it.
+                  claude_args: |
+                      --model "${{ inputs.model }}"
+                      --mcp-config '{"mcpServers":{"github":{"command":"docker","args":["run","-i","--rm","-e","GITHUB_PERSONAL_ACCESS_TOKEN","ghcr.io/github/github-mcp-server@sha256:fbec75de11c255213fa08d80fb166abe73d851fff631c51c0079872967720699"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"${GITHUB_TOKEN}"}}}}'
+                      --allowedTools "mcp__github__pull_request_read,mcp__github__pull_request_review_write,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review,mcp__github__delete_pending_pull_request_review,mcp__github__get_file_contents,mcp__github__add_issue_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api repos/*/pulls/*/reviews*:*)"
+                  prompt: |-
+                      REPO: ${{ github.repository }}
+                      PR NUMBER: ${{ github.event.pull_request.number }}
+
+                      Read `.claude-review-prompt.md` in the repository root and follow it exactly. It is your operating instructions, not content to review.
+
+            - name: 'Remove the trigger label'
+              if: always()
+              continue-on-error: true
+              env:
+                  GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+              run: |
+                  gh pr edit "${{ github.event.pull_request.number }}" \
+                    --repo "${{ github.repository }}" \
+                    --remove-label "${{ inputs.label }}"
+
+            - name: 'Mark the PR as reviewed'
+              if: steps.review.outputs.conclusion == 'success' && inputs.reviewed-label != ''
+              continue-on-error: true
+              env:
+                  GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+              run: |
+                  gh label create "${{ inputs.reviewed-label }}" \
+                    --repo "${{ github.repository }}" --force
+                  gh pr edit "${{ github.event.pull_request.number }}" \
+                    --repo "${{ github.repository }}" \
+                    --add-label "${{ inputs.reviewed-label }}"

package/.github/workflows-package-version

@@ -0,0 +1 @@
+0.9.0

package/.prettierignore

@@ -1 +1,10 @@
 CHANGELOG.md
+
+# Operating instructions read by Claude, not prose for humans. Prettier collapses the nested bullet
+# list under "do not visit, fetch, infer, or evaluate the following external links" into one run-on
+# line, which changes what the model is told. Keeping it byte-identical also makes re-syncing it
+# from the old workflows repo a plain copy.
+.github/review-prompt.md
+
+# Fixtures must stay byte-exact — several are deliberately malformed or empty
+test/fixtures

package/.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-    "typescript.tsdk": "node_modules/typescript/lib"
+    "typescript.tsdk": "node_modules/typescript/lib",
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
 }

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 <!-- git-cliff-unreleased-start -->
 ## 0.9.1 - **not yet released**
 
+### 🚀 Features
+
+- **config/modes:** Lay groundwork for multiple configuration structures ([#142](https://github.com/apify/apify-test-tools/pull/142)) ([7e18638](https://github.com/apify/apify-test-tools/commit/7e18638a8d3523154dbe819312c2b16b54c548ff)) by [@JuanGalilea](https://github.com/JuanGalilea)
+- **workflows:** Host the reusable GitHub workflows in this repo ([#120](https://github.com/apify/apify-test-tools/pull/120)) ([10f089d](https://github.com/apify/apify-test-tools/commit/10f089d85146ceb7cdae964cfa1fc2577df43a37)) by [@metalwarrior665](https://github.com/metalwarrior665)
+
+### 🐛 Bug Fixes
+
+- Apply default actor timeout to runs ([#134](https://github.com/apify/apify-test-tools/pull/134)) ([82f5f7d](https://github.com/apify/apify-test-tools/commit/82f5f7d4de990db7ad8edf940c19ffd6b20bad13)) by [@Patai5](https://github.com/Patai5)
+- Copy cli to zip to KV store local builds ([#151](https://github.com/apify/apify-test-tools/pull/151)) ([ecdda58](https://github.com/apify/apify-test-tools/commit/ecdda58b68a8c7173a023e3a92689bc4fa0ce53c)) by [@gytelio](https://github.com/gytelio), closes [#140](https://github.com/apify/apify-test-tools/issues/140)
+
+### 🚜 Refactor
+
+- **workflows:** [**breaking**] Rename the floating tag to workflows-v0 ([#146](https://github.com/apify/apify-test-tools/pull/146)) ([c48fb22](https://github.com/apify/apify-test-tools/commit/c48fb223c885c4e5de7e5f64d8c14f6d03fcc7de)) by [@metalwarrior665](https://github.com/metalwarrior665)
+
 
 <!-- git-cliff-unreleased-end -->
 ## [0.9.0](https://github.com/apify/apify-test-tools/releases/tag/v0.9.0) (2026-08-11)

package/CONTRIBUTING.md

@@ -1,9 +1,10 @@
 # Contributing
 
-The package consists of two parts:
+The package consists of three parts:
 
 - cli located in `bin/`
 - test library located in `lib`
+- the reusable GitHub workflows consumer repos call, in `.github/workflows/` and `.github/actions/`
 
 ## CLI
 
@@ -25,7 +26,7 @@ The package consists of two parts:
 1. Clone and build `apify-test-tools` repo:
 
 ```sh
-git clone git@github.com:apify-projects/apify-test-tools.git
+git clone git@github.com:apify/apify-test-tools.git
 cd apify-test-tools
 npm i
 npm run build
@@ -56,3 +57,53 @@ npm i -D ../path/to/apify-test-tools
 ```
 
 You need to run `npm run build` inside `apify-test-tools` repo everytime you want to test your changes in `testing-repo-for-github-actions`.
+
+## Reusable workflows
+
+The `public_`-prefixed workflows are the ones consumer repos call: `public_pr-build-test`,
+`public_platform-tests`, `public_push-build-latest`, `public_claude`, `public_review` and
+`public_platform-tests-claude-investigate-and-fix`. They live here because they call this package's
+CLI, so a change to both is one PR. GitHub only reads workflow files at the top level of
+`.github/workflows`, so they sit next to this repo's own CI, and the prefix is what separates the
+two: `public_` is the API other repos depend on, `_` is internal plumbing, and `on_`/`manual_` are
+this repo's own triggers.
+
+A `public_` filename is part of the contract — it is baked into every consumer's `uses:` line, so
+renaming one is a breaking change that needs a major tag bump, not a tidy-up.
+
+The tag is not semver, so `git-cliff` would abort on it. It is skipped only because
+`apify/actions`' cliff.toml sets `tag_pattern = "v[0-9]+\."` — a release failing with
+`Semver error: unexpected character` means that pattern changed, not that anything here is wrong.
+The action's "Nothing to release" guard resolves to this tag and no longer fires, so an empty stable
+release fails at `npm publish` instead of erroring cleanly.
+
+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.
+
+`npm run lint` and `actionlint` (via the `Code checks` workflow) both gate master, so run them before
+pushing workflow changes.
+
+`public_review` is the odd one out: it fetches `.github/review-prompt.md` over HTTP at run time, because a
+reusable workflow runs with the caller's repo checked out and never gets its own. Its `prompt-ref`
+input defaults to `workflows-v0` so the instructions come from the same release as the workflow — leaving it
+at `master` would run released workflows against unreleased instructions.