Two lines, then a full run.

Install

curl -sSL https://get.bellwether.example | sh
bellwether login

The binary is about 14 MB and has no runtime dependencies. It writes to .bellwether/ in the repository root, which you should commit.

Wire it into the pipeline

GitHub Actions, as an example. The shape is the same everywhere:

- run: bellwether select --diff ${{ github.event.pull_request.base.sha }}
- run: bundle exec rspec $(cat .bellwether/selected)

The first command writes the selection to .bellwether/selected and the skip list beside it. The second is your existing test command, reading that file instead of a glob. Nothing else in the pipeline changes.

The first run

Run bellwether record once against a full suite, on a branch, out of everybody’s way. It takes as long as your suite takes plus about four percent. When it finishes, select starts returning a real subset.

Until then select returns every test. That is deliberate: an unbuilt map is indistinguishable from a map that says nothing is affected, and the safe reading of the two is the same.

Reading the skip list

$ bellwether why api/webhooks/retry_spec.rb
skipped  api/webhooks/retry_spec.rb
  map recorded  2 hours ago, run 8841
  loads         12 files, none of them in this diff
  nearest       packages/core/result.ts  (not loaded by this test)

Every test on every commit answers why, and the answer is one of exactly eight. There is no ninth verdict and there is no partial credit: a test is never forty percent selected.

1. reaches selected, the map puts it on a changed file
2. stale selected, its map entry is older than the test
3. unmapped selected, it has never been recorded
4. pinned selected, an always-run rule names it
5. unreachable skipped, no path from the diff
6. quarantined skipped, it disagreed with itself
7. excluded skipped, your config excludes it
8. other shard skipped, it runs on a different machine

Four of the eight are ways of saying run it anyway, which is the direction the tool is built to fail in. The same eight are why every photograph on this site is printed at eight steps of one ink and no ninth.

Turning it off

Delete the two lines. There is no uninstall, no data migration and no export window. Everything Bellwether knows about your repository lives in .bellwether/ and in an account you can delete from the dashboard.