Skip the RSpec examples you don't need: rspec-tracer 2.0 in pre-release

A ground-up rewrite of test-skip caching for RSpec, with pluggable storage, Rails-aware tracking, and...

A ground-up rewrite of test-skip caching for RSpec, with pluggable storage, Rails-aware tracking, and a per-example tracks: DSL.

You change one model. You run bundle exec rspec. Twenty minutes later, every test in the suite has run again — including the 1,800 examples that don't touch that model.

This is the problem rspec-tracer solves. Cold run of a suite: everything runs. Second run with no edits: nothing runs. Edit one file: only the examples that depend on that file re-run.

The 1.x line has been on RubyGems since 2021. I just shipped a 2.0 pre-release after a 4-year gap and a 17-day rebuild. This post is the field guide for what changed and how to test it.

Install

Pre-releases require explicit opt-in. In your Gemfile:

# 2.0 is in pre-release. Pin to the pre-release version explicitly;
# switch to '~> 2.0' once 2.0.0 final ships.
gem 'rspec-tracer', '= 2.0.0.pre.1', group: :test, require: false

Or one-shot:

gem install rspec-tracer --pre

Then in your spec_helper.rb or rails_helper.rb, before any application code:

require 'rspec_tracer'
RSpecTracer.start

That's it for the basic install. Run your suite twice; the second run skips everything that didn't change.

What changed since 1.x

The 2.0 surface is rebuilt around an explicit input-taxonomy model (every test is a pure function of its inputs; cache invalidation is input-digest mismatch). What that translates to for users:

1. Pluggable storage

# Default: JSON (preserves 1.x layout)
storage_backend :json

# SQLite: single-file DB, MRI-only
storage_backend :sqlite

For large suites (5,000+ examples) the SQLite backend cuts cache-load time substantially. JRuby falls back to :json automatically with a one-time warn.

2. Pluggable remote cache (for CI)

The 1.x line had S3-only remote cache. 2.0 ships three backends:

# S3 (preserves the 1.x layout, including LocalStack support)
remote_cache_backend :s3, bucket: 'my-cache', prefix: 'rspec-tracer'

# Local filesystem (NFS / shared mount / dev cache)
remote_cache_backend :local_fs, path: '/mnt/shared-cache'

# Redis (with optional per-key TTL + PR-branches sidecar)
remote_cache_backend :redis,
  url: ENV['REDIS_URL'],
  ttl: 7 * 24 * 3600,
  prefix: 'rspec-tracer'

The CI flow (rake rspec_tracer:remote_cache:download / :upload) is preserved bit-for-bit. The only thing that changes is the backend you point at.

3. Per-example tracks: DSL

This is the headline new surface. RSpec metadata key:

RSpec.describe AdminController,
               tracks: { files: 'app/policies/**/*.rb', env: 'ROLE_CONFIG' } do
  it 'gates on the feature flag' do
    # ...
  end
end

Use cases the tracker can't auto-observe:

• Config files baked at boot — Oj-loaded JSON / YAML that's read once and mmap'd; the IO hooks won't see runtime reads, so declared globs are the escape hatch.
• Env-var branches — code that does if ENV['FEATURE_X'] == 'on'; flipping the env should invalidate the example.
• Pre-compiled Ruby constants — values baked at boot that the per-example coverage delta can't see.

Cascade is union (parent + child both contribute), unlike RSpec's default metadata cascade which clobbers on shared keys.

4. track_env(*names) config DSL

Symmetric to track_files but for env vars every test depends on:

# In .rspec-tracer
track_env 'AUTH_TOKEN', 'DATABASE_URL', 'RAILS_*', '*_API_KEY'

Single-wildcard patterns supported: 'PREFIX_*', '*_SUFFIX', bare '*'. Patterns are expanded against the live ENV at config-load time; the persisted env_snapshot.json carries concrete keys only.

5. Rails preset

For Rails projects, the tracker has to attach inputs Coverage doesn't observe — views, locales, fixtures, factories, helpers, config YAML, schema. The preset handles this:

# In .rspec-tracer
track_rails_defaults

Opt out per category:

track_rails_defaults except: [:views, :locales]

Plus auto-detection: when ::Rails::VERSION is defined at RSpecTracer.start time, the engine attaches an ActionView template subscriber + an opt-in AR schema subscriber.

The ERB/Slim/Jbuilder tracking via render_template.action_view was the most-requested missing 1.x feature. It's the canonical path now: a view edit invalidates exactly the examples that rendered the partial.

6. bin/rspec-tracer CLI

Five sub-commands, all opt-in:

$ rspec-tracer doctor
OK   ruby:        ruby 3.3.10 (2026-04-18)
OK   rspec-tracer: 2.0.0.pre.1
OK   root:        /Users/me/projects/my-app
OK   cache_path:  /Users/me/projects/my-app/rspec_tracer_cache
INFO SimpleCov:   not loaded (this is fine; SimpleCov is optional)
OK   Rails:       7.2.0.1
OK   schema:      v3 (matches gem)
INFO remote_cache: not configured (skip)

$ rspec-tracer cache:info
Cache size: 14.4 MiB · last run: 2026-05-06T14:13:22Z · 12 runs retained

$ rspec-tracer cache:clear
Removed: rspec_tracer_cache/, rspec_tracer_coverage/, rspec_tracer_report/

$ rspec-tracer report:open
Opening rspec_tracer_report/index.html ...

$ rspec-tracer explain spec.foo_spec.rb_42
Example: spec/foo_spec.rb:42 - "GET /admin returns 403 for unauthenticated"
Status: re-run scheduled
Reason: Files changed (app/controllers/admin_controller.rb)
Dependencies (12):
  - app/controllers/admin_controller.rb [changed since cache]
  - app/policies/admin_policy.rb
  - config/locales/en.yml
  - ...

The CLI is opt-in for local dev convenience; the rake rspec_tracer:remote_cache:* tasks remain first-class for CI integration.

7. HTML + JSON reporters

The 1.x line had a single HTML reporter. 2.0 adds a JSON reporter for CI dashboards and a terminal-summary reporter that fires after every run:

rspec-tracer: 1887 examples tracked · 5 re-run · 1882 skipped (99% cached)
by reason: 5 Files changed
cache: /path/to/rspec_tracer_cache (14.4 MiB; +6.7 KiB vs prev run)
report: /path/to/rspec_tracer_report/report.json

For parallel_tests users: 1.x emitted reports per worker, then purge_worker_dirs! deleted them — leaving users with no usable output. 2.0 emits ONCE at the merged top-level location after all workers finish.

8. SimpleCov branch coverage now works

The 1.x caveat ("SimpleCov would not report branch coverage results even when enabled") is gone. The coverage-stack rewrite decoupled rspec-tracer's line-only emission from SimpleCov's branch tracking. Users who turned enable_coverage :branch off when adopting rspec-tracer 1.x can re-enable in 2.0.

9. Boot-time warns

For two common user-trust traps:

• SimpleCov loaded but not started before RSpecTracer.start (load-order is part of the documented contract; the warn surfaces it instead of silently bolting onto a Coverage already in flight).
• track_ar_schema_notifications enabled with use_transactional_fixtures defaulting to true (per-example BEGIN/COMMIT fires sql.active_record and attributes db/schema.rb to every AR-touching example; the warn points at the README "Narrow AR-schema attribution" guidance).

10. Schema-version field + Rails 8.0 + CI recipes

Schema-version field in last_run.json for explicit cross-version cache validation. Cache-shape changes bump the field; mismatched caches refuse-to-load with an info-level "cold run" log line.

Rails 8.0 is CI-gated (Ruby 3.2+). docs/CI_RECIPES.md translates the GitHub Actions cache pattern to CircleCI / GitLab CI / Buildkite / Heroku CI — the 4-component cache-key (runner.os + .ruby-version + lib/rspec_tracer/version.rb + Gemfile-hash) translates 1:1 across providers.

Migration from 1.x

The full guide is in UPGRADING.md. Headlines:

• Ruby ≥ 3.1 is the floor (1.x supported Ruby 2.5+). Ruby 3.2 / 3.3 / 3.4 / 4.0 + JRuby 9.4 are CI-gated. Rails 7.0 / 7.1 / 7.2 / 8.0 + RSpec 3.12 / 3.13 are CI-gated.
• Cache schema bump — first run on 2.0 is cold; warm caches resume on subsequent runs. Existing CI integration (the rake tasks, env vars, rspec_tracer_cache/ directory contracts) is preserved bit-for-bit.
• Deprecated — four configs continue to work with one warn line each, slated for removal in 3.0: reports_s3_path / use_local_aws config DSL, and RSPEC_TRACER_REPORTS_S3_PATH / RSPEC_TRACER_USE_LOCAL_AWS env vars.
• Removed — cucumber feature-file integration suite (contributor-facing only), Ruby ≤ 3.0 / Rails ≤ 6.x support, Windows.

Why pre-release

A 2.0 of a gem people use in their CI deserves a real testing window. The pre-release is on RubyGems with --pre opt-in; 2.0.0 final is targeted in ~2 weeks once the observation-window feedback is incorporated.

If you're a 1.x user: the migration is bundle update rspec-tracer after pinning the pre-release version, plus optionally adopting track_rails_defaults if you're on Rails. The first run is cold (cache schema cut); subsequent runs return to warm.

If you're new to rspec-tracer: try the cookbook recipes; the Quick start gets a fresh project running in ~5 minutes.

Where to send feedback

• GitHub Discussions: the pre-release thread for usage questions, install reports, rough edges.
• Issues: open one for bugs. Add the 2.0-feedback label if applicable.
• Migration questions: comment on the discussion thread; I'll answer in the open so others see.

I'll cut a pre.2 if pre.1 surfaces blockers; otherwise 2.0.0.rc.1 in ~2 weeks, then 2.0.0 final after a final review window.

Repo: https://github.com/avmnu-sng/rspec-tracer Release: https://github.com/avmnu-sng/rspec-tracer/releases/tag/v2.0.0.pre.1 Discussion: https://github.com/avmnu-sng/rspec-tracer/discussions/180

Thanks for reading. Bug reports + thoughts welcome.