branchproof 0.9.0 → 0.10.0

data/doc/README.md

@@ -1,7 +1,7 @@
 # Branchproof
 
 Branchproof measures decision, condition, modified condition/decision (MC/DC),
-and decision-table coverage from one serial Minitest run. It discovers Ruby
+and decision-table coverage from one serial Minitest or RSpec run. It discovers Ruby
 decisions through Prism, records their runtime paths, and attributes evidence
 to tests. Boolean decisions receive the coverage ladder; `case`, pattern
 alternatives, safe navigation, and conditional assignments receive alternative
@@ -22,10 +22,13 @@ Or add it to a bundle:
 bundle add branchproof
 ```
 
-Branchproof targets CRuby 3.3 and 3.4, Minitest 5.x, and Prism 1.x. The
-published core runtime matrix is the CI matrix. Rails support is optional and
-has been locally checked against Rails 8.1.3.1 on CRuby 3.4.5; Rails is
-supplied by the application and is not a runtime dependency of this gem.
+Branchproof targets CRuby 3.3 and 3.4, Minitest 5.x, RSpec 3.13, and Prism 1.x. The
+published core runtime matrix is the CI matrix. Rails/RSpec execution is limited
+to Rails 8.1.x, rspec-rails 8.x, RSpec 3.13.x, and CRuby 3.4.x; passing core
+tests on Ruby 4.0 does not imply Rails/RSpec support. Integration has been checked
+with Rails 8.1.3.1, rspec-rails 8.0.4, RSpec Core 3.13.6, and CRuby 3.4.7.
+Rails and RSpec are optional dependencies supplied by the application.
+Minitest 5.x remains a runtime dependency of this gem.
 Unsupported syntax and incomplete observations remain visible in the report
 instead of being counted as coverage.
 
@@ -33,7 +36,7 @@ instead of being counted as coverage.
 
 Run `branchproof analyze` with the source files or globs to inspect, followed by
 options. A second `--` separates Branchproof options from arguments passed to
-Minitest unchanged:
+the selected test framework:
 
 ```sh
 branchproof analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
@@ -58,22 +61,60 @@ the application's bundle and Rails version remain in effect:
 bundle exec branchproof analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
 ```
 
+Choose the test framework independently from project kind:
+
+```sh
+bundle exec branchproof analyze 'app/**/*.rb' --project rails --framework rspec
+```
+
+`--framework auto|minitest|rspec` is explicit about the adapter. Auto mode
+selects RSpec when `.rspec` or `spec/**/*_spec.rb` markers exist and Minitest
+when `test/**/*_test.rb` or `test/**/test_*.rb` markers exist. If both are
+present, specify the framework. RSpec discovery uses `spec/**/*_spec.rb`; an
+explicit `--test` selection remains authoritative. Project roots are resolved
+explicitly, and report paths are relative to that root so reports from
+different checkouts can be compared.
+
+Install `rspec` in the application's test bundle; Rails applications also need
+`rspec-rails`. RSpec reads its usual option files and `SPEC_OPTS`, including
+helper requires, filters, ordering, and file or example-ID selectors. Selectors
+from RSpec configuration replace default discovery. Combining those selectors
+with an explicit Branchproof `--test` is rejected as ambiguous; ordinary filters
+such as `--tag` and `--example` can accompany `--test`.
+
+RSpec before hooks, eager `let!`, and around-hook prefixes own setup evidence.
+The example body and helpers evaluated there own body evidence; after hooks,
+mock cleanup, and around-hook suffixes own teardown evidence. Suite and context
+hooks remain unattributed. Pending and skipped examples do not invent execution;
+an unexpectedly passing pending example remains a failure.
+
+RSpec support is serial: dry-run, bisect, DRb, custom runners, nested runs, and
+repeated example attempts are rejected. Rails/RSpec supports Rails 8.1.x with
+rspec-rails 8.x on CRuby 3.4.x. Feature and system specs use the in-process
+Capybara `rack_test` driver; browser drivers require execution-context support
+outside this release. Capybara is optional for apps that do not use those specs.
+
 For a project rooted at the current directory, `--project auto` is the
 default. It selects Rails only when both `config/application.rb` and
 `config/environment.rb` exist; otherwise it selects a plain Ruby project.
 Use `--project ruby` or `--project rails` to override detection. An explicit
 Rails project without both boot files is a usage error.
 
-Project defaults discover the sorted, de-duplicated union of
+Minitest defaults discover the sorted, de-duplicated union of
 `test/**/*_test.rb` and `test/**/test_*.rb`. Helper, support, and fixture files
 are excluded from that default set. `--test` remains authoritative when test
 files are selected explicitly. The worker prepends the project's `lib` and
-`test` directories to its child load path, so application `require` calls
+`test` directories (`lib` and `spec` for RSpec) to its child load path, so application `require` calls
 resolve without changing the parent process.
 
-Rails analysis boots `config/environment.rb` and `rails/test_help` inside the
-isolated worker after Branchproof's loader and Minitest hooks are installed. The
-child receives `RAILS_ENV=test`, `RACK_ENV=test`, `PARALLEL_WORKERS=1`,
+Rails analysis boots the application inside the isolated worker after
+Branchproof's loader and the selected framework hooks are installed. The
+application's `rails_helper` owns requiring and configuring `rspec/rails` after
+the loader; the helper must not require `branchproof` again. Selected specs
+may require only `spec_helper` and run without booting Rails,
+even when project detection selects Rails. Once Rails is loaded, Branchproof
+requires an initialized application and enforces the Rails/RSpec support limits.
+The child receives `RAILS_ENV=test`, `RACK_ENV=test`, `PARALLEL_WORKERS=1`,
 `DISABLE_BOOTSNAP=1`, and `DISABLE_SPRING=1`; the invoking process environment
 is unchanged. The Rails metadata in the report identifies the selected
 project and Rails version.
@@ -93,6 +134,17 @@ the witness pair or missing counterpart constraints beside each condition;
 Level 2 and Level 3 also list named supporting tests. Repeated supporting-set
 rows are collapsed in terminal output only.
 
+RSpec owners use the example's `full_description` and positional `example_id`.
+Terminal views include quoted rerun commands, including selectors for shared
+examples. These selectors apply to the recorded spec revision. Comparisons
+require matching spec and declaration digests before matching example owners;
+changed specs and older reports without digests are treated conservatively.
+Runner output streams to stderr while JSON reports remain on stdout.
+Pending, skipped, fixed-pending, and failed examples map to the corresponding
+baseline statuses; suite and context lifecycle events remain visible, and
+observations without a test owner are counted as unattributed. The same levels
+and terminal views are available for both adapters.
+
 For example, running the contents of the small `decision.rb` /
 `test_decision_test.rb` fixture from a project `lib/` and `test/` directory
 with the terminal format produces a summary like this:
@@ -654,12 +706,14 @@ the serial Minitest runner. This is useful for seeds and name filters:
 branchproof analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
 ```
 
-The 0.2 release supports serial Minitest execution in plain Ruby projects and
-Rails applications. Rails lazy and eager loading are supported when the
-application does not enable reloading for the test run. RSpec, parallel or
-forked runners, mutation execution, Rails system/browser tests, custom Rails
-test commands, generated tests, and reloading configurations are outside this
-release and produce diagnostics rather than a passing analysis.
+The first release supports serial Minitest and RSpec execution in plain Ruby
+projects and Rails applications. Rails lazy and eager loading are supported
+when the application does not enable reloading for the test run. Transactions
+and in-process specs are supported within the serial process policy. Parallel
+or forked runners, remote or threaded browser drivers, mutation execution,
+Rails system/browser tests, custom Rails test commands, generated tests, and
+reloading configurations are explicitly unsupported and produce diagnostics
+rather than a passing analysis.
 
 ## Library entry points
 
@@ -672,7 +726,8 @@ Branchproof::Records.id(name: "stable identity")
 
 `require "mcdc"` and `MCDC` are compatibility aliases for the same public
 namespace. The CLI is the supported way to run a complete analysis;
-`Branchproof::Project` exposes project selection and child-environment policy,
+`Branchproof::Project` exposes project and framework selection and
+child-environment policy,
 and `Branchproof::RailsSupport` is the optional Rails boot boundary. The library
 classes expose the source, runtime, evidence, analysis, and report contracts
 for adapters and integrations.
@@ -705,6 +760,10 @@ Run the commands with the Ruby executable you intend to validate. The checked
 release environments are CRuby 3.3.6 and 3.4.5. Each runtime
 must provide the declared Minitest 5.x and Prism 1.x dependencies.
 
+The repeatable native-versus-instrumented adapter benchmark and its captured
+Ruby 3.4.7 result are in
+[`docs/benchmarks/rspec-adapter.md`](docs/benchmarks/rspec-adapter.md).
+
 ## License
 
 Branchproof is available under the [Apache License, Version 2.0](LICENSE.txt).

data/lib/branchproof/cli.rb

@@ -33,10 +33,10 @@ module Branchproof
 
       inventory = build_inventory(options)
       evidence = empty_evidence(inventory, options)
-      baseline = if options[:tests].empty?
-                   { status: "INCOMPLETE", executed_tests: 0, failed_tests: 0, skipped_tests: 0, finalized: false }
-                 else
+      baseline = if run_worker?(options)
                    run_worker(options, inventory, evidence)
+                 else
+                   { status: "INCOMPLETE", executed_tests: 0, failed_tests: 0, skipped_tests: 0, finalized: false }
                  end
       if value(baseline, :evidence)
         merge_status = evidence.merge(snapshot: value(baseline, :evidence))
@@ -93,7 +93,7 @@ module Branchproof
     def help
       @stdout.write(<<~HELP)
         Usage:
-          branchproof analyze [SOURCE_GLOB ...] [--test TEST_GLOB] [--project auto|ruby|rails]
+          branchproof analyze [SOURCE_GLOB ...] [--test TEST_GLOB] [--project auto|ruby|rails] [--framework auto|minitest|rspec]
             [--view decisions|conditions|tests|decision-tables] [--level 1|2|3] [--missing-only]
             [--format terminal|json] [--output PATH] [--limits PATH] [--no-reachability] [-- RUNNER_ARGS]
           branchproof report SNAPSHOT [--view decisions|conditions|tests|decision-tables]
@@ -205,12 +205,24 @@ module Branchproof
         source = value(test, :source) || {}
         [value(test, :id), { relative_path: relative_path(value(source, :path), root), line: value(source, :line) }]
       end
-      { captured_at: Time.now.utc.iso8601, requested_level: options[:level], project_kind: options[:project][:kind],
+      project_metadata = value(baseline, :project) || options[:project]
+      selected_test_files = value(baseline, :selected_test_files)
+      test_files = selected_test_files || options[:tests]
+      metadata = {
+        captured_at: Time.now.utc.iso8601, requested_level: options[:level], project_kind: options[:project][:kind],
         project_root: root, source_patterns: options[:source_patterns].map { |path| relative_path(path, root) },
         test_patterns: options[:test_patterns].map { |path| relative_path(path, root) },
-        test_files: options[:tests].map { |path| relative_path(path, root) }, runner_args: options[:runner_args],
+        test_files: Array(test_files).map { |path| relative_path(path, root) }, runner_args: options[:runner_args],
         seed: value(baseline, :seed), limits: options[:limits], test_locations: locations,
-        reachability: options[:reachability] }
+        reachability: options[:reachability]
+      }
+      %i[selected_test_files selected_example_ids].each do |key|
+        metadata[key] = value(baseline, key) if value(baseline, key)
+      end
+      %i[framework framework_version rspec_rails_version rails_version].each do |key|
+        metadata[key] = value(project_metadata, key) if value(project_metadata, key)
+      end
+      metadata
     end
 
     def relative_path(path, root)
@@ -228,7 +240,7 @@ module Branchproof
       args = args[0...delimiter] if delimiter
       options = { level: 3, format: :terminal, output: nil, tests: [], source_paths: [], limits: Limits.default,
                   runner_args: runner_args, project: nil, missing_only: false, view: :decisions,
-                  reachability: true }
+                  reachability: true, project_mode: "auto", framework: "auto", explicit_tests: false }
       until args.empty?
         token = args.shift
         case token
@@ -255,11 +267,14 @@ module Branchproof
         when "--test"
           options[:tests] << args.shift
           raise ArgumentError, "--test requires a glob" if options[:tests].last.nil? || options[:tests].last.empty?
-        when "--project"
-          mode = args.shift
-          raise ArgumentError, "--project requires auto, ruby, or rails" if mode.nil? || mode.empty?
 
-          options[:project] = Project.new(root: Dir.pwd, mode: mode).to_h
+          options[:explicit_tests] = true
+        when "--framework"
+          options[:framework] = args.shift
+          raise ArgumentError, "--framework requires auto, minitest, or rspec" if options[:framework].nil? || options[:framework].empty?
+        when "--project"
+          options[:project_mode] = args.shift
+          raise ArgumentError, "--project requires auto, ruby, or rails" if options[:project_mode].nil? || options[:project_mode].empty?
         when "--limits"
           limits_path = args.shift
           raise ArgumentError, "--limits requires a readable JSON path" unless limits_path && File.file?(limits_path)
@@ -273,16 +288,16 @@ module Branchproof
           options[:source_paths] << token
         end
       end
+      options[:project] = Project.new(root: Dir.pwd, mode: options[:project_mode], framework: options[:framework]).to_h
       validate_view!(options)
       if options[:missing_only] && (options[:format] != :terminal || options[:level] == 1)
         raise ArgumentError, "--missing-only requires terminal format and level 2 or 3"
       end
 
-      options[:project] ||= Project.new(root: Dir.pwd, mode: "auto").to_h
       options[:source_paths] = default_sources if options[:source_paths].empty?
-      options[:tests] = default_tests if options[:tests].empty?
+      options[:tests] = default_tests(options[:project]) if options[:tests].empty?
       options[:source_patterns] = options[:source_paths].dup
-      options[:test_patterns] = argv.include?("--test") ? options[:tests].dup : %w[test/**/*_test.rb test/**/test_*.rb]
+      options[:test_patterns] = options[:explicit_tests] ? options[:tests].dup : options[:project][:test_patterns]
       options[:tests] = expand_paths(options[:tests], root: options[:project][:root])
       options
     end
@@ -315,18 +330,10 @@ module Branchproof
       begin
         directory = Dir.mktmpdir("branchproof-run-")
         config = File.join(directory, "request.json")
-        payload = {
-          inventory: inventory, limits: options[:limits], run_id: evidence.run_id,
-          test_files: options[:tests], runner_args: options[:runner_args], project: options[:project],
-          result_path: File.join(directory, "result.json"), marker_path: File.join(directory, "complete.marker")
-        }
+        payload = worker_payload(options, inventory, evidence, directory)
         File.binwrite(config, JSON.generate(normalize(payload)))
         script = "require 'branchproof'; exit(Branchproof::Worker.child_process(ARGV.fetch(0)).to_i)"
-        child_stdout, stderr, child_status = Open3.capture3(options[:project][:environment], RbConfig.ruby, "-I",
-                                                            File.expand_path("..", __dir__), "-e", script, config,
-                                                            chdir: options[:project][:root])
-        @stderr.write(child_stdout) unless child_stdout.to_s.empty?
-        @stderr.write(stderr) unless stderr.to_s.empty?
+        stderr, child_status = stream_worker(options, script, config)
         unless File.file?(payload[:marker_path]) && File.file?(payload[:result_path])
           return { status: "ERROR", executed_tests: 0, failed_tests: 0, skipped_tests: 0, finalized: false,
                    diagnostics: [{ code: "worker_incomplete", severity: "error", message: stderr.to_s.strip }] }
@@ -346,6 +353,30 @@ module Branchproof
         diagnostics: [{ code: "runner", severity: "error", message: e.message }] }
     end
 
+    def stream_worker(options, script, config)
+      diagnostic_output = +""
+      Open3.popen3(options[:project][:environment], RbConfig.ruby, "-I",
+                   File.expand_path("..", __dir__), "-e", script, config,
+                   chdir: options[:project][:root]) do |input, output, errors, child|
+        input.close
+        streams = [output, errors]
+        until streams.empty?
+          IO.select(streams).first.each do |stream|
+            chunk = stream.read_nonblock(16_384, exception: false)
+            if chunk.nil?
+              streams.delete(stream)
+            elsif chunk != :wait_readable
+              @stderr.write(chunk)
+              @stderr.flush if @stderr.respond_to?(:flush)
+              diagnostic_output << chunk
+              diagnostic_output = diagnostic_output.byteslice(-16_384, 16_384) if diagnostic_output.bytesize > 16_384
+            end
+          end
+        end
+        [diagnostic_output, child.value]
+      end
+    end
+
     def output_report(report, options)
       created = false
       if options[:output]
@@ -362,6 +393,19 @@ module Branchproof
       File.unlink(temporary) if created && temporary && File.file?(temporary)
     end
 
+    def run_worker?(options)
+      !options[:tests].empty? || options[:project][:framework].to_s == "rspec"
+    end
+
+    def worker_payload(options, inventory, evidence, directory)
+      {
+        inventory: inventory, limits: options[:limits], run_id: evidence.run_id,
+        test_files: options[:tests], runner_args: options[:runner_args], project: options[:project],
+        test_selection_explicit: options[:explicit_tests],
+        result_path: File.join(directory, "result.json"), marker_path: File.join(directory, "complete.marker")
+      }
+    end
+
     def report_string(report, format)
       buffer = StringIO.new
       report.write(io: buffer, format: format)
@@ -377,8 +421,9 @@ module Branchproof
       %w[lib/**/*.rb app/**/*.rb]
     end
 
-    def default_tests
-      candidates = Dir.glob("test/**/*_test.rb", base: Dir.pwd) + Dir.glob("test/**/test_*.rb", base: Dir.pwd)
+    def default_tests(project = nil)
+      project ||= Project.new(root: Dir.pwd, mode: "auto", framework: "auto").to_h
+      candidates = Array(project[:test_patterns]).flat_map { |pattern| Dir.glob(pattern, base: project[:root]) }
       candidates.map! { |path| File.expand_path(path, Dir.pwd) }
       candidates.reject { |path| default_test_excluded?(path) }.uniq.sort
     end
@@ -387,7 +432,8 @@ module Branchproof
       relative = Pathname.new(path).relative_path_from(Pathname.new(Dir.pwd)).to_s
       segments = relative.split(File::SEPARATOR)
       basename = File.basename(path)
-      basename == "test_helper.rb" || segments.include?("support") || segments.include?("fixtures")
+      %w[test_helper.rb spec_helper.rb rails_helper.rb].include?(basename) ||
+        segments.include?("support") || segments.include?("fixtures")
     end
 
     def expand_paths(paths, root: Dir.pwd)

data/lib/branchproof/comparison.rb

@@ -2,6 +2,7 @@
 
 # rubocop:disable Metrics/ClassLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 require "json"
+require "pathname"
 
 module Branchproof
   # Compares two complete report documents without loading or executing the project.
@@ -369,9 +370,17 @@ module Branchproof
         tests = Array(value(value(document, :observations), :tests)).to_h { |test| [value(test, :id).to_s, test] }
         rows = index.tests.to_h { |test| [test[:id].to_s, test] }
         keys = tests.to_h do |id, test|
-          parts = %i[adapter class_name method_name].map { |key| value(test, key) }
-          parts << rows.dig(id, :relative_path)
-          [id, parts.all? { |part| part.is_a?(String) && !part.empty? } ? parts : nil]
+          adapter = value(test, :adapter).to_s
+          path = rows.dig(id, :relative_path)
+          key = if adapter.downcase == "rspec"
+                  example_id = value(test, :example_id).to_s
+                  # Scoped IDs are positional selectors, valid only within the same spec revision.
+                  [adapter, rspec_example_path(document, example_id) || path, rspec_scope(example_id),
+                   value(test, :name), path, value(test, :spec_digest), value(test, :source_digest)]
+                else
+                  [adapter, value(test, :class_name), value(test, :method_name), path]
+                end
+          [id, key.all? { |part| part.is_a?(String) && !part.empty? } ? key : nil]
         end
         results = Array(value(value(document, :analysis), :decisions)).flat_map do |decision|
           Array(value(decision, :condition_results))
@@ -447,6 +456,13 @@ module Branchproof
       if context(@before)[:test_keys].values.sort_by(&:to_s) != context(@after)[:test_keys].values.sort_by(&:to_s)
         changes << "test population differs"
       end
+      if [@before, @after].any? do |document|
+        context(document)[:tests].any? do |id, test|
+          value(test, :adapter).to_s.downcase == "rspec" && context(document)[:test_keys][id].nil?
+        end
+      end
+        changes << "RSpec example identity is uncertain: missing spec revision or selector evidence"
+      end
       changes << "Deltas describe observed runs; nondeterminism and external environment changes are not ruled out."
       changes
     end
@@ -454,9 +470,10 @@ module Branchproof
     def comparability_reasons(changed_paths)
       reasons = []
       reasons << "source files changed: #{changed_paths.sort.join(", ")}" unless changed_paths.empty?
-      %i[project_kind runner_args source_patterns test_patterns limits runtime].each do |key|
-        left = metadata(@before, key)
-        right = metadata(@after, key)
+      %i[project_kind framework framework_version rspec_rails_version runner_args source_patterns test_patterns limits
+         runtime].each do |key|
+        left = key == :framework ? comparison_framework(@before) : metadata(@before, key)
+        right = key == :framework ? comparison_framework(@after) : metadata(@after, key)
         if key == :runner_args
           left = comparable_runner_args(left)
           right = comparable_runner_args(right)
@@ -467,6 +484,35 @@ module Branchproof
       reasons
     end
 
+    def comparison_framework(document)
+      explicit = metadata(document, :framework)
+      return explicit unless explicit.nil? || explicit.to_s.empty?
+
+      adapters = Array(value(value(document, :observations), :tests)).filter_map do |test|
+        adapter = value(test, :adapter).to_s.downcase
+        adapter unless adapter.empty? || adapter == "unknown"
+      end.uniq
+      adapters.length == 1 ? adapters.first : nil
+    end
+
+    def rspec_scope(example_id)
+      match = example_id.to_s.match(/(\[[^\]]+\])\z/)
+      match && match[1]
+    end
+
+    def rspec_example_path(document, example_id)
+      path = example_id.to_s.sub(/\[[^\]]+\]\z/, "")
+      return nil if path.empty?
+      return path.sub(%r{\A\./}, "") unless path.start_with?("/")
+
+      root = value(value(document, :source_inventory), :root) || metadata(document, :project_root)
+      return nil unless root
+
+      Pathname.new(path).relative_path_from(Pathname.new(root.to_s)).to_s
+    rescue ArgumentError
+      nil
+    end
+
     def source_selection(document)
       value(value(document, :run_metadata), :source_patterns)
     end

data/lib/branchproof/evidence.rb

@@ -120,6 +120,10 @@ module Branchproof
       nil
     end
 
+    def test_phase_counts
+      @tests.transform_values { |test| test[:phase_counts].dup.freeze }.freeze
+    end
+
     def snapshot
       deep_freeze(deep_dup({ schema_version: SCHEMA_VERSION, tool_version: TOOL_VERSION,
                              criterion_version: CRITERION_VERSION,

data/lib/branchproof/focused_report.rb

@@ -238,6 +238,8 @@ module Branchproof
       lines << "Test: #{row[:name]}"
       lines << "Location: #{location(row[:relative_path], row[:line], unavailable: "location unavailable")}"
       lines << "Status: #{row[:status] || "unknown"}"
+      command = @coordinator.rerun_command(row[:id])
+      lines << "Rerun: #{command}" if command
       lines << "Phases: #{row[:phases].join(", ")}" unless row[:phases].empty?
       render_test_observations(lines, observations)
       lines << ""
@@ -341,6 +343,9 @@ module Branchproof
       return id.to_s unless test
 
       label = "#{test[:name]} (#{location(test[:relative_path], test[:line])})"
+      command = @coordinator.rerun_command(id)
+      return "#{label} (rerun: #{command})" if command
+
       duplicates = @test_name_counts[[test[:name], test[:relative_path], test[:line]]]
       duplicates > 1 ? "#{label} [#{id}]" : label
     end

data/lib/branchproof/project.rb

@@ -4,6 +4,7 @@ module Branchproof
   # Resolves the project policy used by the isolated analysis worker.
   class Project
     MODES = %w[auto ruby rails].freeze
+    FRAMEWORKS = %w[auto minitest rspec].freeze
     RAILS_ENVIRONMENT = {
       "RAILS_ENV" => "test",
       "RACK_ENV" => "test",
@@ -12,19 +13,24 @@ module Branchproof
       "DISABLE_SPRING" => "1"
     }.freeze
 
-    def initialize(root:, mode: "auto")
+    def initialize(root:, mode: "auto", framework: "auto")
       @root = File.expand_path(root)
       @mode = mode.to_s
+      @framework = framework.to_s
       raise ArgumentError, "project must be auto, ruby, or rails" unless MODES.include?(@mode)
+      raise ArgumentError, "framework must be auto, minitest, or rspec" unless FRAMEWORKS.include?(@framework)
 
       validate_root!
+      resolve_framework!
     end
 
     def to_h
       {
         kind: kind,
         root: @root,
-        load_paths: [File.join(@root, "lib"), File.join(@root, "test")],
+        framework: framework,
+        test_patterns: test_patterns,
+        load_paths: load_paths,
         environment: kind == "rails" ? RAILS_ENVIRONMENT.dup : {}
       }
     end
@@ -43,6 +49,47 @@ module Branchproof
         File.file?(File.join(@root, "config", "environment.rb"))
     end
 
+    def framework
+      @resolved_framework
+    end
+
+    def resolve_framework!
+      rspec = rspec_markers?
+      minitest = minitest_markers?
+      if @framework == "auto"
+        raise_both_frameworks if rspec && minitest
+        @resolved_framework = rspec ? "rspec" : "minitest"
+      else
+        @resolved_framework = @framework
+      end
+    end
+
+    def rspec_markers?
+      File.file?(File.join(@root, ".rspec")) || !Dir.glob(File.join(@root, "spec", "**", "*_spec.rb")).empty?
+    end
+
+    def raise_both_frameworks
+      raise ArgumentError,
+            "project contains both RSpec and Minitest markers; specify --framework rspec or --framework minitest"
+    end
+
+    def minitest_markers?
+      !Dir.glob(File.join(@root, "test", "**", "*_test.rb")).empty? ||
+        !Dir.glob(File.join(@root, "test", "**", "test_*.rb")).empty?
+    end
+
+    def test_patterns
+      if framework == "rspec"
+        %w[spec/**/*_spec.rb].freeze
+      else
+        %w[test/**/*_test.rb test/**/test_*.rb].freeze
+      end
+    end
+
+    def load_paths
+      [File.join(@root, "lib"), File.join(@root, framework == "rspec" ? "spec" : "test")]
+    end
+
     def validate_root!
       raise ArgumentError, "project root does not exist: #{@root}" unless File.directory?(@root)
       return unless @mode == "rails" && !rails_files?