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

Abhimanyu Singh — Thu, 07 May 2026 08:51:45 +0000

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.

Run tests 2-3x faster on average

Abhimanyu Singh — Thu, 16 Sep 2021 17:48:51 +0000

I have been working on rspec-tracer that allows you to detect flaky tests with no additional effort and provides better insights on dependencies between various components in your project by analyzing specs and their dependencies by generating HTML reports. The gem safely skips all such tests with no dependent files changed, resulting in at least 2-3x faster test execution on average.

https://github.com/avmnu-sng/rspec-tracer

RSpec Tracer

Abhimanyu Singh — Fri, 27 Aug 2021 14:42:15 +0000

https://github.com/avmnu-sng/rspec-tracer

RSpec Tracer is a specs dependency analysis tool and a test skipper for RSpec. It maintains a list of files for each test, enabling itself to skip tests in the subsequent runs if none of the dependent files are changed.

It uses Ruby's built-in coverage library to keep track of the coverage for each test. For each test executed, the coverage diff provides the desired file list. RSpec Tracer takes care of reporting the correct code coverage when skipping tests by using the cached reports. Also, note that it will never skip any tests which failed or were pending in the last runs.

Knowing the examples and files dependency gives us a better insight into the codebase, and we have a clear idea of what to test for when making any changes. With this data, we can also analyze the coupling between different components and much more.

TAP Formatters for RSpec-3

Abhimanyu Singh — Fri, 01 Nov 2019 19:05:27 +0000

GitHub Repo

Software Development: The Magical Number Seven, Plus or Minus Two (Cognitive Complexity)

Abhimanyu Singh — Fri, 18 Oct 2019 15:21:44 +0000

https://blog.usejournal.com/software-development-the-magical-number-seven-plus-or-minus-two-9d1de54447d6

Algorithms behind RuboCop complexity metrics

Abhimanyu Singh — Wed, 09 Oct 2019 14:37:01 +0000

I published a series on Medium.com, explaining the algorithms behind RuboCop complexity metrics. The third part reveals the mathematical connections between different metrics. The series will help you with configuring cyclomatic complexity, perceived complexity, and, ABC size values for RuboCop analysis, which are not completely random.

In the first part we cover syntactic representation of Ruby source code. It provides all the information required to get started with the algorithms.
In the second part we go through the pseudocode of the algorithms and solve a couple of problems to see how to calculate the complexity values without drawing control flow graphs.
In the third part we do mathematical analysis to establish a relationship between the metrics and not use a random RuboCop configuration.

I would love your feedback. Thanks!

DEV Community: Abhimanyu Singh