crspec 0.1.2 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e70183d3b574744a0de1061ba25f99d495bdbaa4d9940cb76f76d37124701328
-  data.tar.gz: 02f551a7420e923ae7fd5f6357ee6c55256600adac922f6adeab7b3e811cae65
+  metadata.gz: c0d7564354ce4a30b067d3786a53d52e414b0d6710e4e50c798bbf47c87309db
+  data.tar.gz: 68168ea426d446bcddd2fd4e148efe891cf266854b3d0136a91636d553a3fde0
 SHA512:
-  metadata.gz: b9abb32f9cbb3411ce1de2ab806395e5629c42802f83b1cc6f346f164d87c6c487ceea69a64c6650f2a2f2267436eedf06c30b64ba4313c4b757f9bb803bf901
-  data.tar.gz: b29fba9882c81d8bae86250693e764ed49c17cba74d180e05536e522bc6bf5d9f0faf293340937b39d1a7bf88a4b65a9fe7e617d635749f144548ad7598fe49b
+  metadata.gz: b5dfb9faa9089603b0fbb618f24d535de6f618439a2f495579a23ba7eed182a7006072e153d88c95dbcd9a4102cdb09a19d909f5cd4314cc6fde7ed8b4ce0ca2
+  data.tar.gz: 70431def1aa0f7e85bc75c114408c3c73d4fbcebe0c3d795102b1007e0c565f8a1549517359d46ff95413a7a2bf3be74627bbd93793e14cf41f0cc933b804ed9

data/CHANGELOG.md

@@ -1,5 +1,96 @@
 ## [Unreleased]
 
+### Added (Phases 2–5)
+
+- **Fiber tier** (`--fibers M`, `config.fibers`): each worker thread runs up
+  to M concurrent example-fibers on the Async reactor; IO-bound examples
+  overlap within a thread. `async` is a soft dependency (add it to your
+  Gemfile on CRuby); without it `--fibers` falls back to 1.
+- **JRuby support**: full test suite passes on JRuby 10; threads scale
+  across all cores (no GVL), so `-c N` is the multi-core tier there.
+  `--processes N` raises with guidance (no fork); `--processes auto`
+  gracefully falls back to threads.
+- **Process tier** (`--processes P`, `--processes auto` = physical cores):
+  forks after spec loading (`Process.warmup`), shards examples by persisted
+  timings (LPT bin-packing, round-robin on first run), streams marshalled
+  results over binary pipes, creates per-process `db_N` databases via
+  `ActiveRecord::TestDatabases`, offsets `SystemServer` ports by
+  `TEST_ENV_NUMBER`, and propagates fail-fast via SIGTERM.
+- **Timing persistence** (`example_status_persistence_file_path`, CLI
+  default `tmp/crspec_status.json`): slowest-first scheduling,
+  `--only-failures`, and deterministic `--seed N` random ordering.
+- **Real pending/skip**: `xit`, `skip`, `pending`, blockless `it`,
+  `skip:`/`pending:` metadata, and `xdescribe`/`xcontext` no longer execute;
+  reported as pending in the summary.
+- **Verifying `instance_double`**: stubbing a method the doubled class does
+  not implement raises `Crspec::Mock::MockError`; string class names are
+  resolved.
+- **Matchers**: `be_a`/`be_an`/`be_an_instance_of`/`be_falsey`, `match`,
+  `match_array`/`contain_exactly`, `have_attributes`, `all`, `satisfy`,
+  `be_within.of/.percent_of`, `start_with`/`end_with`,
+  `output.to_stdout/.to_stderr`, `yield_control`/`yield_with_args`/
+  `yield_successive_args`, compound `.and`/`.or`, custom-matcher DSL with
+  `failure_message`/`failure_message_when_negated`/`description`/`chain`.
+- **Mocks**: `spy` + `have_received` (with count/argument constraints),
+  argument matchers (`anything`, `hash_including`, `hash_excluding`,
+  `array_including`, `an_instance_of`, `kind_of`, `duck_type`),
+  `and_call_original`, `receive_messages`.
+- **Shared groups**: `shared_examples`/`shared_context`/`it_behaves_like`/
+  `include_context`/`include_examples` (block re-registration; parallel-safe).
+- **Filtering**: `--tag TAG[:VALUE]`, line-number filters (`spec.rb:42`),
+  `fit`/`fdescribe`/`fcontext` focus, `aggregate_failures` backed by a
+  fiber-local accumulator (`MultipleExpectationsNotMetError`).
+- **Transpiler**: auto-rewrites `before(:all)`→`before(:each)` (annotated),
+  `RSpec::Matchers.define`→`Crspec::Matchers.define`, focus aliases
+  normalized; static thread-safety lints (class variables, constant
+  mutation, `ENV[]=`, Timecop, `any_instance_of`) with severities;
+  `--report` migration report with per-file safety scores; `--diff` dry-run
+  and `.bak` backups; removed the dangerous `**/*.rb` fallback glob.
+
+### Changed (breaking, pre-release)
+
+- `before`/`after` with `:all`/`:context`/`:suite` scope raise
+  `Crspec::MigrationError` at load time (also from `Crspec.configure`).
+- `allow_any_instance_of`/`expect_any_instance_of` raise
+  `Crspec::MigrationError` at runtime.
+- Mock interceptor methods are removed after each run
+  (`Mock::Interceptor.cleanup!`) instead of accumulating for the process
+  lifetime.
+
+### Changed (Phase 1 — concurrency kernel)
+
+- **Removed `DatabaseIsolation::MUTEX`**, which serialized all transactional
+  examples. Each worker now leases its own connection per writing pool
+  (`lease_connection`, `pool.checkout` fallback) with a root non-joinable
+  transaction; every example runs in a nested transaction (savepoint) rolled
+  back afterwards. Fiber-Storage-keyed connection handoff makes fibers
+  spawned inside an example see that example's connection. SQLite pools fall
+  back to serialized per-example transactions (single-writer limitation).
+  **Breaking:** the `pin_connection!` path was dropped.
+- Runner queue rewritten: `Queue#close` + blocking pop replaces the racy
+  `empty?`/`pop(true)`/`rescue` pattern; fail-fast drains the queue instead
+  of using an abort flag.
+- Result recording decontended: per-worker result arrays merged at join,
+  formatter notifications outside any runner lock, buffered progress-dot
+  output with periodic flush.
+- Per-group example classes are built once per group/spec-type and cached
+  (previously rebuilt for every example); all `ancestor_*` walks (hooks,
+  lets, metadata, modules) are memoized and frozen via `ExampleGroup#finalize!`;
+  `World` is frozen at the CLI boundary before the run starts.
+- **Removed the `ENV["TEST_ENV_NUMBER"]` cross-thread race**: worker identity
+  now lives in Fiber Storage (`Crspec::Rails::Parallel.current_worker_number`);
+  ENV is never mutated from worker threads. Thread-scoped per-worker database
+  switching (`db_N`) was removed — it returns at the process tier
+  (`--processes`) where the convention is safe.
+
+### Fixed
+
+- POST/PUT/PATCH request helpers now send `Content-Type: application/json`
+  for JSON bodies, so controllers parse params correctly.
+- `Parallel.teardown_worker` uses `clear_active_connections!` instead of
+  `clear_all_connections!`, which destroyed other workers' leased
+  connections.
+
 ## [0.1.0] - 2026-07-29
 
 - Initial release

data/README.md

@@ -166,7 +166,7 @@ Configure worker counts and setup/teardown hooks:
 ```ruby
 Crspec::Rails::Parallel.parallelize(workers: 4) do
   parallelize_setup do |worker_number|
-    puts "Worker #{worker_number} starting (TEST_ENV_NUMBER=#{ENV['TEST_ENV_NUMBER']})"
+    puts "Worker #{worker_number} starting"
   end
 
   parallelize_teardown do |worker_number|

data/lib/crspec/cli.rb

@@ -13,9 +13,16 @@ module Crspec
     def initialize(args)
       @args = args
       @concurrency = Crspec.configuration.concurrency
+      @fibers = nil
       @paths = []
       @requires = []
       @init_mode = false
+      @fail_fast = false
+      @seed = nil
+      @only_failures = false
+      @processes = 1
+      @tags = {}
+      @locations = []
     end
 
     def run
@@ -35,26 +42,66 @@ module Crspec
       load_specs
 
       concurrency = @concurrency || Crspec.configuration.concurrency
-      runner = Runner.new(concurrency: concurrency)
+      fibers = @fibers || Crspec.configuration.fibers
+      persistence_path = Crspec.configuration.example_status_persistence_file_path ||
+                         File.join("tmp", "crspec_status.json")
+      multi_process = @processes == :auto || (@processes.is_a?(Integer) && @processes > 1)
+      if multi_process && !ProcessRunner.fork_supported?
+        if @processes == :auto
+          # auto = "use the best multi-core strategy"; on engines without a
+          # GVL, threads already are that strategy.
+          puts "#{RUBY_ENGINE} has no fork; --processes auto falling back to #{concurrency} threads."
+          multi_process = false
+        else
+          warn "Error: --processes requires fork, which #{RUBY_ENGINE} does not support."
+          warn "On #{RUBY_ENGINE} threads use all cores; use -c/--concurrency instead."
+          return false
+        end
+      end
+      runner = if multi_process
+                 ProcessRunner.new(processes: @processes, concurrency: concurrency,
+                                   fibers: fibers, fail_fast: @fail_fast, seed: @seed,
+                                   only_failures: @only_failures,
+                                   persistence_path: persistence_path)
+               else
+                 Runner.new(concurrency: concurrency, fibers: fibers, fail_fast: @fail_fast,
+                            seed: @seed, only_failures: @only_failures,
+                            persistence_path: persistence_path,
+                            tags: @tags.empty? ? nil : @tags,
+                            locations: @locations.empty? ? nil : @locations)
+               end
       groups = Crspec.world.example_groups
+      Crspec.world.freeze!
 
       if groups.empty?
         puts "No example groups found."
         return true
       end
 
-      puts "Running Crspec suite with concurrency #{concurrency}..."
+      banner = "Running Crspec suite with concurrency #{concurrency}"
+      banner += ", #{@processes == :auto ? 'auto' : @processes} processes" if multi_process
+      banner += ", #{fibers} fibers/worker" if fibers && fibers > 1
+      banner += ", seed #{@seed}" if @seed
+      puts "#{banner}..."
       runner.run(groups)
 
       puts "\nFinished in #{runner.total_duration.round(4)} seconds"
-      puts "#{runner.passed_examples.size + runner.failed_examples.size} examples, #{runner.failed_examples.size} failures"
+      total = runner.passed_examples.size + runner.failed_examples.size + runner.pending_examples.size
+      summary = "#{total} examples, #{runner.failed_examples.size} failures"
+      summary += ", #{runner.pending_examples.size} pending" unless runner.pending_examples.empty?
+      puts summary
 
       unless runner.failed_examples.empty?
         puts "\nFailures:"
         runner.failed_examples.each_with_index do |ex, idx|
           puts "#{idx + 1}) #{ex.description}"
-          puts "   Failure/Error: #{ex.error.message}"
-          puts "   #{ex.error.backtrace&.first}" if ex.error.backtrace
+          if ex.respond_to?(:error) && ex.error
+            puts "   Failure/Error: #{ex.error.message}"
+            puts "   #{ex.error.backtrace&.first}" if ex.error.backtrace
+          elsif ex.respond_to?(:error_message)
+            puts "   Failure/Error: #{ex.error_message}"
+            puts "   #{ex.error_backtrace&.first}" if ex.error_backtrace
+          end
         end
       end
 
@@ -71,6 +118,10 @@ module Crspec
           @concurrency = n
         end
 
+        opts.on("--fibers M", Integer, "Concurrent example fibers per worker thread (default 1)") do |m|
+          @fibers = m
+        end
+
         opts.on("-r", "--require PATH", String, "Require a file before running specs") do |path|
           @requires << path
         end
@@ -79,6 +130,27 @@ module Crspec
           @init_mode = true
         end
 
+        opts.on("--fail-fast [N]", Integer, "Abort the run after N failures (default 1)") do |n|
+          @fail_fast = n || 1
+        end
+
+        opts.on("--seed N", Integer, "Randomize example order with the given seed") do |n|
+          @seed = n
+        end
+
+        opts.on("--only-failures", "Run only examples that failed in the previous run") do
+          @only_failures = true
+        end
+
+        opts.on("--processes P", String, "Fork P worker processes ('auto' = physical cores)") do |p|
+          @processes = p == "auto" ? :auto : Integer(p)
+        end
+
+        opts.on("--tag TAG", String, "Run only examples with the given tag (TAG or TAG:VALUE)") do |t|
+          key, value = t.split(":", 2)
+          @tags[key.to_sym] = value.nil? ? true : parse_tag_value(value)
+        end
+
         opts.on("-h", "--help", "Show help") do
           puts opts
           exit 0
@@ -87,6 +159,25 @@ module Crspec
 
       @paths = parser.parse(@args)
       @paths = ["spec"] if @paths.empty?
+
+      # Extract path:42 line-number filters.
+      @paths = @paths.map do |p|
+        if p =~ /\A(.+\.rb):(\d+)\z/
+          @locations << [Regexp.last_match(1), Regexp.last_match(2).to_i]
+          Regexp.last_match(1)
+        else
+          p
+        end
+      end
+    end
+
+    def parse_tag_value(value)
+      case value
+      when "true" then true
+      when "false" then false
+      when /\A\d+\z/ then value.to_i
+      else value.to_sym
+      end
     end
 
     def load_requires
@@ -96,6 +187,8 @@ module Crspec
     end
 
     def load_specs
+      spec_dir = File.expand_path("spec")
+      $LOAD_PATH.unshift(spec_dir) if File.directory?(spec_dir) && !$LOAD_PATH.include?(spec_dir)
       files = []
       @paths.each do |p|
         if File.directory?(p)

data/lib/crspec/configuration.rb

@@ -3,12 +3,16 @@
 require "etc"
 
 module Crspec
+  class MigrationError < StandardError; end
+
   class Configuration
-    attr_accessor :concurrency, :use_transactional_fixtures, :formatter
+    attr_accessor :concurrency, :fibers, :use_transactional_fixtures, :formatter, :example_status_persistence_file_path, :fixture_paths
+    attr_writer :file_fixture_path
     attr_reader :before_hooks, :after_hooks, :around_hooks, :included_modules
 
     def initialize
       @concurrency = Etc.nprocessors
+      @fibers = 1
       @use_transactional_fixtures = true
       @formatter = nil
       @before_hooks = []
@@ -16,22 +20,30 @@ module Crspec
       @around_hooks = []
       @included_modules = []
       @infer_spec_type = false
+      @fixture_paths = []
+      @file_fixture_path = nil
+    end
+
+    def file_fixture_path
+      @file_fixture_path || File.join("spec", "fixtures", "files")
     end
 
-    def before(_scope = :each, &block)
-      @before_hooks << block
+    def before(*args, **kwargs, &block)
+      reject_serial_scope!(:before, args)
+      @before_hooks << { block: block, filters: args, kwfilters: kwargs }
     end
 
-    def after(_scope = :each, &block)
-      @after_hooks.unshift(block)
+    def after(*args, **kwargs, &block)
+      reject_serial_scope!(:after, args)
+      @after_hooks.unshift({ block: block, filters: args, kwfilters: kwargs })
     end
 
-    def around(_scope = :each, &block)
-      @around_hooks << block
+    def around(*args, **kwargs, &block)
+      @around_hooks << { block: block, filters: args, kwfilters: kwargs }
     end
 
-    def include(mod)
-      @included_modules << mod
+    def include(mod, *filters, **kwfilters)
+      @included_modules << { module: mod, filters: filters, kwfilters: kwfilters }
     end
 
     def infer_spec_type_from_file_location!
@@ -41,6 +53,47 @@ module Crspec
     def infer_spec_type?
       !!@infer_spec_type
     end
+
+    def infer_type_for_file_path(file_path)
+      return nil unless @infer_spec_type
+      case file_path.to_s
+      when %r{spec/controllers/} then :controller
+      when %r{spec/requests/}, %r{spec/api/} then :request
+      when %r{spec/models/} then :model
+      when %r{spec/helpers/} then :helper
+      when %r{spec/system/} then :system
+      when %r{spec/views/} then :view
+      when %r{spec/components/} then :component
+      when %r{spec/mailers/} then :mailer
+      when %r{spec/jobs/} then :job
+      when %r{spec/services/} then :service
+      end
+    end
+
+    def filter_rails_from_backtrace!
+    end
+
+    def define_derived_metadata(*args)
+    end
+
+    def expect_with(*args)
+    end
+
+    def mock_with(*args)
+    end
+
+    private
+
+    def reject_serial_scope!(hook_name, args)
+      scope = args.first
+      return unless scope.is_a?(Symbol) && %i[all context suite].include?(scope)
+
+      raise MigrationError, <<~MSG
+        config.#{hook_name}(:#{scope}) is not supported by Crspec: shared state
+        across examples is inherently serial and breaks the concurrent
+        execution model. Use config.#{hook_name}(:each) or let/let! instead.
+      MSG
+    end
   end
 
   class << self

data/lib/crspec/dsl.rb

@@ -16,15 +16,41 @@ module Crspec
 
     def initialize
       @example_groups = []
+      @frozen = false
     end
 
     def register(group)
+      raise Error, "Cannot register example groups after the run has started" if @frozen
+
       @example_groups << group
     end
+
+    def freeze!
+      @frozen = true
+      @example_groups.freeze
+      self
+    end
+
+    def frozen?
+      @frozen
+    end
   end
 
-  def self.describe(description, metadata = {}, &block)
-    group = ExampleGroup.define(description, metadata, nil, &block)
+  def self.describe(*args, **kwargs, &block)
+    metadata = kwargs.dup
+    metadata.merge!(args.pop) if args.last.is_a?(Hash)
+    if metadata[:type].nil? && Crspec.configuration.infer_spec_type?
+      loc = caller_locations(1, 10).find { |l| l.path.include?("spec/") }
+      if loc
+        inferred = Crspec.configuration.infer_type_for_file_path(loc.path)
+        metadata[:type] = inferred if inferred
+      end
+    end
+    described = args.first.is_a?(Module) ? args.first : nil
+    description = described && args.size == 1 ? described : args.map(&:to_s).join(" ")
+    group = ExampleGroup.new(description, metadata, nil)
+    group.described_module = described
+    group.instance_eval(&block) if block
     World.instance.register(group)
     group
   end
@@ -36,4 +62,42 @@ module Crspec
   def self.reset!
     World.reset!
   end
+
+  def self.freeze_world!
+    World.instance.freeze!
+  end
+
+  def self.xdescribe(*args, **kwargs, &block)
+    describe(*args, **kwargs, &block).mark_pending!
+  end
+
+  def self.fdescribe(*args, **kwargs, &block)
+    describe(*args, **kwargs, &block).mark_focused!
+  end
+
+  module DSL
+    def shared_examples(name, &block)
+      Crspec.shared_examples(name, &block)
+    end
+    alias shared_examples_for shared_examples
+    alias shared_context shared_examples
+
+    def describe(*args, **kwargs, &block)
+      Crspec.describe(*args, **kwargs, &block)
+    end
+
+    def xdescribe(*args, **kwargs, &block)
+      Crspec.xdescribe(*args, **kwargs, &block)
+    end
+    alias xcontext xdescribe
+
+    def fdescribe(*args, **kwargs, &block)
+      Crspec.fdescribe(*args, **kwargs, &block)
+    end
+    alias fcontext fdescribe
+  end
 end
+
+main = TOPLEVEL_BINDING.eval("self")
+main.extend(Crspec::DSL)
+include Crspec::DSL

data/lib/crspec/example.rb

@@ -4,27 +4,71 @@ require "securerandom"
 
 module Crspec
   class Example
-    attr_reader :id, :description, :metadata, :example_group, :block, :status, :error, :execution_time
+    attr_reader :id, :description, :metadata, :example_group, :block, :status, :error, :execution_time, :file_path, :line_number
+    attr_accessor :focused
 
-    def initialize(description, metadata, example_group, block)
+    def initialize(description, metadata, example_group, block, pending: false, location: nil)
       @id = SecureRandom.uuid
       @description = description
       @metadata = metadata.freeze
       @example_group = example_group
       @block = block
       @status = :pending
+      @pending = pending || block.nil? || metadata[:skip] || metadata[:pending] ? true : false
+      @focused = metadata[:focus] ? true : false
       @error = nil
       @execution_time = 0
+      location ||= block&.source_location
+      @file_path, @line_number = location if location
+    end
+
+    def focused?
+      @focused
+    end
+
+    def pending?
+      @pending
+    end
+
+    def persistence_key
+      @persistence_key ||= begin
+        parts = []
+        group = @example_group
+        while group
+          parts.unshift(group.description.to_s)
+          group = group.parent
+        end
+        parts << @description.to_s
+        parts.join(" > ")
+      end
+    end
+
+    class ExampleInvocation
+      def initialize(runner_proc)
+        @runner_proc = runner_proc
+      end
+
+      def execute!
+        @runner_proc.call
+      end
+      alias run execute!
+      alias call execute!
     end
 
     def execute!
+      return if @pending
+
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       instance = @example_group.create_instance(self)
 
       begin
-        run_hooks(instance, :before)
-        instance.instance_exec(&@block) if @block
-        @status = :passed
+        around_hooks = @example_group.ancestor_hooks(:around, self)
+        run_around_hooks(instance, around_hooks) do
+          @example_group.run_eager_lets(instance)
+          run_hooks(instance, :before)
+          instance.instance_exec(&@block) if @block
+          @status = :passed
+        end
       rescue StandardError, ExpectationNotMetError => e
         @status = :failed
         @error = e
@@ -43,8 +87,18 @@ module Crspec
 
     private
 
+    def run_around_hooks(instance, hooks, &final_block)
+      if hooks.empty?
+        final_block.call
+      else
+        head, *tail = hooks
+        inv = ExampleInvocation.new(-> { run_around_hooks(instance, tail, &final_block) })
+        instance.instance_exec(inv, &head)
+      end
+    end
+
     def run_hooks(instance, type)
-      hooks = @example_group.ancestor_hooks(type)
+      hooks = @example_group.ancestor_hooks(type, self)
       hooks.each do |hook|
         instance.instance_exec(&hook)
       end