aspect cache diff - Aspect Build

Selective testing runs only the tests a change can affect, instead of every test on every commit. aspect cache diff finds that set by asking the remote cache rather than analyzing the source: it lists the test targets affected by the current working tree and runs no tests. Which tests are affected? Ask the cache, run nothing. explains how it works and how it compares with other approaches. Two Bazel invocations on the same warm output base probe the cache with --experimental_remote_require_cached: every cache hit means “unaffected”, and every miss is attributed to the dependent tests. It’s a remote-cache operation; it needs no remote execution.

aspect cache diff                       # affected tests under //...
aspect cache diff //services/...        # scope to a sub-tree
aspect cache diff --output=json         # scriptable output
aspect cache diff --exec="bazel test"   # pipe affected labels into a command

When to use it

Debug cache misses. Find the exact set of cache-missed actions that explain why a CI run rebuilt or re-ran more than expected.
Validate CI cache coverage. Run it against a clean checkout to confirm your CI uploads the baseline you expect. A populated cache reports Affected 0 of N.
Pre-flight a change. Before pushing, list the tests affected by your edits and pipe them into bazel test to run only what matters.
Drive selective CI. Use the lines or json output to gate downstream jobs on the affected target set.

How it works

Enumerates the test targets in scope with tests(<patterns>).
Runs one Bazel invocation with --experimental_remote_require_cached. Each action’s up-to-date check resolves against the remote cache; on a miss, execution is denied so the probe runs nothing.
Reads the gRPC log of GetActionResult calls. A miss anywhere in a test’s transitive closure trips at that action, the frontier.
Attributes the affected tests from the frontier (overreport) or only from missing test actions (precise).

Affected labels stream to stdout; progress, per-target reasons, and the summary go to stderr, so you can pipe stdout cleanly.

Prerequisites

A writable --remote_cache, in .bazelrc or on the command line. The task stops early if none is configured.
A populated baseline: a cache hit is what makes a target “unaffected”, so the mainline’s action results must already be uploaded. Normally this happens as a byproduct of regular CI:
bazel test //... --remote_upload_local_results
Seed on a clean checkout (or a fresh --output_base): on a warm output base Bazel finds everything locally cached, executes nothing, and uploads nothing. CI checkouts are cold, so this is automatic there.
Bazel 7 or later. Test selection follows Bazel’s test patterns and filters. Wildcards such as //... exclude manual-tagged tests; name a manual test explicitly to include it. Pass negative patterns after --.
The probe and the baseline must resolve the same Bazel flags, so they compute the same action digests. The probe reuses the same rc/config as aspect build / aspect test, so they line up by default. A flag that changes an action’s environment (for example --action_env=FOO) must be present on both sides or neither.

Modes

Pick a mode with --mode:

Mode	What it does	Cost
`overreport` (default)	Reverse-deps from each cache-missed target to its dependent tests.	Runs nothing. May flag a test even when its dependency would rebuild to an identical output.
`precise`	First runs `bazel build` to build and upload the missing non-test actions, then flags a test only when its own test action misses.	Costs the build of the missing non-test actions. Narrows the result to genuine input changes.

Execution guarantee: no test ever runs in either mode. overreport executes nothing; precise executes only the missing non-test actions (it builds with bazel build, which cannot execute TestRunner). The lone exception is actions tagged no-remote, local, no-remote-exec or no-cache: they bypass the remote path entirely, so they run locally and read as affected.

Output

By default, affected labels stream to stdout, one per line:

$ aspect cache diff
//backend/api:integration_test
//backend/api:unit_test
//libs/auth:token_test

Pipe directly into Bazel:

aspect cache diff | xargs bazel test

Or hand the labels to any command with --exec:

aspect cache diff --exec="bazel test"

For scripting, switch to JSON:

$ aspect cache diff --output=json
{
  "mode": "overreport",
  "total_tests": 124,
  "affected_count": 2,
  "affected": [
    {
      "label": "//backend/api:integration_test",
      "caused_by": [
        { "target": "//libs/auth:token", "mnemonic": "GoCompile" }
      ]
    },
    {
      "label": "//libs/auth:token_test",
      "caused_by": [
        { "target": "//libs/auth:token_test", "mnemonic": "TestRunner" }
      ]
    }
  ]
}

Progress, per-target reasons (including the cache-missed target that each test is “caused by”), and the final Affected X of N test target(s). summary go to stderr.

Configuration flags

Flag	Default	Description
`--mode`	`overreport`	`overreport` or `precise`. See Modes.
`--output`	`lines`	`lines` (one label per line) or `json` (single document on stdout). `--format` is a deprecated alias that still works but warns.
`--exec`	(empty)	Run the given command with the affected labels appended as arguments (for example `--exec="bazel test"`). No-op when nothing is affected. Overrides `--output`.
`--bazel-flag`	none	A Bazel flag for the probe and the precise build, for when one collides with a task flag. Bazel flags typed directly (`--config=ci`) are forwarded too. Repeatable.
`--bazel-startup-flag`	none	A Bazel startup flag. Repeatable. Changing startup flags restarts the Bazel server.
`--announce-bazel-rc`, `--announce-bazel-version`, `--announce-bazel-command`	`auto`	Print the resolved rc flags, the Bazel version or the Bazel command line. `auto` prints on CI and stays quiet locally.
positional	`//...`	Target patterns scoping the affected set (intersected with `tests(<patterns>)`).

Run aspect cache diff --help for the complete list of flags.

Examples

Scope to a sub-tree and run only the affected tests:

aspect cache diff //services/... | xargs bazel test

Use a CI config so the probe matches your CI baseline’s flags:

aspect cache diff --config=ci //...

Narrow overreport noise to genuine input changes:

aspect cache diff --mode=precise //...

Drive a downstream job from JSON:

aspect cache diff --output=json > affected.json
jq -r '.affected[].label' affected.json | xargs bazel test

Soundness and limits

The result is bounded by your baseline’s cache coverage:

A hit means the target is unaffected.
A miss means the target is either changed or never-uploaded/evicted.

Against a fully-populated baseline this is exact. Against a sparse cache, overreport over-reports and precise narrows the result to genuine input changes. The probe runs in two passes on one warm output base. The first flips a salt in the action’s exec properties, which invalidates the ACTION_EXECUTION nodes without discarding the analysis; the second re-checks them with --nouse_action_cache, forcing a fresh remote GetActionResult per action. Keeping the analysis is the point — it needs no separate or wiped output base, and it replaces the old --nokeep_state_after_build, which re-analyzed on every probe.

aspect build & aspect test: the same task lifecycle that seeds the cache baseline.
Driving the CLI from scripts and AI agents: using aspect describe and --output=json to script or automate the CLI.
Aspect Workflows: Aspect Workflows runners configure the remote cache that aspect cache diff reads from.

​When to use it

​How it works

​Prerequisites

​Modes

​Output

​Configuration flags

​Examples

​Soundness and limits

​Related