crspec 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 649f2c29f7f22f52d1291691f9c96c2c9718ab907c38e8ea27604fab5ec9ef8f
-  data.tar.gz: cfaac3973542770dc81f08c921bb29b054ed64f3dae0913ca75b175d42438242
+  metadata.gz: 7abc092d66324287e2b4c429b9961025c131dfb3f02dfd40e2d61d8342a9db45
+  data.tar.gz: c5a3573fb6acddcea79ee61b34f861b0b6f781ef3d810d7e384faedb4f0bc650
 SHA512:
-  metadata.gz: 85dc17da65b7d4bb59766cb7a00220f9009fec3b4e869969d3dde17fbafe7c8f63b190b083d2fbd243f3e6b3e02470f0e3076a9142b38b5d5e65ddb7ad595894
-  data.tar.gz: '0257282967b6ed5ca718bd01cf7329a920f8fca18266d44a59e196453bbd8db2d0bdaf52e646b9553cf86eed375c2f00c7e33139435d36876ae43bb4ddbd689a'
+  metadata.gz: c57dca0e4f4c8108e81d66ae6e36c12a313d1a89c8b0f19e0a67486d9d27c7db8de96abab20d177b2f9c5ae74d854da6e4b638dc918d4e113618bdecc7a6e0a0
+  data.tar.gz: 92aa3ae4a9b7310059ba7fce8a6e17fe1807bf6ca6c21e0a348cf9744074d8ca755a3bffafa37a1ac7003b2d6491d91bbc94da5cb15a8493fc81e4dded0652cb

data/README.md

@@ -8,9 +8,10 @@
 
 - **Fiber Storage Context Isolation**: Solves legacy thread-local (`Thread.current`) state leakage by routing all execution metadata and `let` memoization through inherited Fiber storage (`Fiber[:crspec_execution_context]`).
 - **Fiber-Aware Mocking (`crspec-mock`)**: Prevents mock registry corruption across parallel tests using prepended method interceptors bound to `Fiber[:crspec_mock_space]`.
-- **Rails Connection Leasing & Parallel Testing (`crspec-rails`)**: Leases database connections per example fiber (`ActiveRecord::Base.lease_connection`), handles savepoint transaction strategies (`SAVEPOINT ex_root`), and integrates with Rails parallel worker suites (`Crspec::Rails::Parallel`).
+- **Rails Integration & ActiveSupport Reuse (`crspec-rails`)**: Direct integration with `ActiveSupport::Testing::Assertions`, `ActiveSupport::Testing::TimeHelpers`, and `ActiveSupport::Testing::FileFixtures`. Leases database connections per example fiber (`ActiveRecord::Base.lease_connection`), handles savepoint transaction strategies (`SAVEPOINT ex_root`), and integrates with Rails parallel worker suites (`Crspec::Rails::Parallel`).
+- **Rails Request Specs**: Expressive HTTP request verb helpers (`get`, `post`, `put`, `patch`, `delete`), response status inspection (`response.status`), headers, and `json_response` parsing.
 - **Prism-Based AST Transpiler (`crspec-transpiler`)**: Automated migration tool using `ruby/prism` C-parser to convert existing RSpec codebases to Crspec syntax and flag thread-unsafe constructs like `before(:all)`.
-- **Concurrent Execution Kernel**: Multi-threaded worker pool integrated with non-blocking fiber schedulers (`Async::Scheduler`).
+- **Concurrent Execution Kernel**: Multi-threaded worker pool integrated with real-time progress dot formatting and non-blocking fiber schedulers (`Async::Scheduler`).
 
 ---
 
@@ -30,12 +31,30 @@ mise exec -- bundle install
 
 ---
 
+## Spec Helpers & Generator
+
+Initialize standard `spec_helper.rb` (and `rails_helper.rb` if run within a Rails project):
+
+```bash
+mise exec -- crspec --init
+```
+
+Spec files include helpers explicitly via standard `require` statements:
+
+```ruby
+require "spec_helper"
+# or
+require "rails_helper"
+```
+
+---
+
 ## Writing Specs
 
 `crspec` provides a familiar RSpec-style DSL for structuring example groups and expectations:
 
 ```ruby
-require "crspec"
+require "spec_helper"
 
 Crspec.describe User, type: :model do
   let(:valid_attributes) { { name: "Jane Doe", email: "jane@example.com" } }
@@ -45,6 +64,12 @@ Crspec.describe User, type: :model do
     expect(user.valid?).to be(true)
   end
 
+  it "changes user count when created" do
+    expect {
+      User.create!(valid_attributes)
+    }.to change(User, :count).by(1)
+  end
+
   context "when email is omitted" do
     let(:valid_attributes) { { name: "Jane Doe", email: nil } }
 
@@ -62,6 +87,7 @@ end
 - `include(*items)`
 - `raise_error(ExceptionClass, "message")`
 - `respond_to(*methods)`
+- `change(receiver, :method).by(amount)` / `change { ... }.by(amount)` / `.from(val).to(val)`
 
 ### Advanced: Execution Context & Extensions
 Regular spec authors do not need to interact with `execution_context` at all—`crspec` automatically isolates `let` memoization, database connections, and stubs invisibly per test.
@@ -90,7 +116,7 @@ Crspec.describe PaymentGateway do
 
   it "stubs credit card processing concurrently" do
     allow(stripe_client).to receive(:create).with(amount: 5000).and_return(status: "succeeded")
-    
+
     result = stripe_client.create(amount: 5000)
     expect(result[:status]).to eq("succeeded")
   end
@@ -99,15 +125,37 @@ end
 
 ---
 
-## Rails Concurrency & Parallel Testing (`crspec-rails`)
+## Rails Concurrency & Request Specs (`crspec-rails`)
 
 ### Database Isolation & Connection Leasing
-Wrap examples in connection leasing and transaction savepoints:
+`rails_helper.rb` automatically configures database-independent transaction isolation using your application's `config/database.yml`:
 
 ```ruby
-Crspec.describe User, type: :model do
-  around do |example|
-    Crspec::Rails::DatabaseIsolation.wrap_example(example)
+Crspec.configure do |config|
+  config.use_transactional_fixtures = true
+  config.infer_spec_type_from_file_location!
+  config.include(Crspec::Rails::RequestHelpers)
+
+  config.around(:each) do |example|
+    if defined?(ActiveRecord::Base) && config.use_transactional_fixtures
+      Crspec::Rails::DatabaseIsolation.wrap_example(example)
+    else
+      example.execute!
+    end
+  end
+end
+```
+
+### Request Specs
+Perform full REST API controller testing with built-in request helpers:
+
+```ruby
+Crspec.describe "Books API", type: :request do
+  it "creates a book via POST" do
+    post "/books", params: { name: "Refactoring", author: "Martin Fowler" }
+
+    expect(response.status).to eq(201)
+    expect(json_response[:name]).to eq("Refactoring")
   end
 end
 ```
@@ -118,7 +166,6 @@ Configure worker counts and setup/teardown hooks:
 ```ruby
 Crspec::Rails::Parallel.parallelize(workers: 4) do
   parallelize_setup do |worker_number|
-    # Prepare worker database, seed data, etc.
     puts "Worker #{worker_number} starting (TEST_ENV_NUMBER=#{ENV['TEST_ENV_NUMBER']})"
   end
 
@@ -128,13 +175,6 @@ Crspec::Rails::Parallel.parallelize(workers: 4) do
 end
 ```
 
-### Multi-Fiber Integration Server
-Boot an embedded multi-threaded/multi-fiber Puma server for system/browser specs:
-
-```ruby
-Crspec::Rails::SystemServer.start_concurrent_server!(Rails.application, 9887)
-```
-
 ---
 
 ## Migrating from RSpec (`crspec-transpile`)
@@ -151,6 +191,16 @@ mise exec -- crspec-transpile --write spec/
 
 ---
 
+## Sample Rails Bookstore App
+
+Explore the working sample Rails application in [`samples/book_store`](file:///Users/tachyons/code/crspec/samples/book_store):
+
+```bash
+mise exec -- ./exe/crspec samples/book_store/spec/
+```
+
+---
+
 ## Running Specs
 
 Execute your test suite concurrently using the `crspec` executable:

data/benchmark/README.md

@@ -0,0 +1,56 @@
+# Crspec Native Benchmark Suite
+
+This directory contains benchmarking utilities comparing default native framework runner performance across **crspec**, **RSpec**, and **Minitest** without any manual thread-slicing or concurrency controls in the benchmark script.
+
+---
+
+## Directory Structure
+
+```text
+benchmark/
+├── target_service.rb                        # Domain target class under test (UserService)
+├── spec/
+│   ├── user_service_crspec_spec.rb          # Idiomatic Crspec spec (Crspec.describe)
+│   └── user_service_rspec_spec.rb           # Idiomatic RSpec spec (RSpec.describe)
+├── test/
+│   └── user_service_test.rb                 # Idiomatic Minitest test (class UserServiceTest < Minitest::Test)
+├── run.rb                                   # Clean benchmark runner script
+└── README.md
+```
+
+---
+
+## Evaluated Configurations
+
+Each framework is executed using its native default runner invocation:
+- **Crspec (Native Default Runner)**: Uses `Crspec::Runner.new` default multi-threaded / fiber execution kernel.
+- **RSpec (Native Default Runner)**: Native standard RSpec runner.
+- **Minitest (Native Default Runner)**: Native Minitest runner.
+
+---
+
+## How to Run
+
+```bash
+mise exec -- ruby benchmark/run.rb
+```
+
+---
+
+## Benchmark Results (macOS arm64 / Ruby 4.0.2)
+
+```text
+==========================================================================
+  Crspec vs RSpec vs Minitest Benchmark Suite
+  Test Workload: 100 examples per framework
+  Evaluating Default Native Framework Runners (No Manual Concurrency Controls)
+==========================================================================
+
+Results Summary:
+Framework Engine                              | Duration (s) | Throughput (ops/s)
+------------------------------------------------------------------------------
+Crspec (Native Default Runner)                | 0.0211       | 4749.47        
+RSpec (Native Default Runner)                 | 0.1375       | 727.15         
+Minitest (Native Default Runner)              | 0.1259       | 794.45         
+==============================================================================
+```

data/benchmark/run.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift File.expand_path(__dir__)
+
+require "crspec"
+require "rspec/core"
+require "minitest"
+require "stringio"
+
+NUMBER_OF_TESTS = 100
+
+Rails.logger.debug "=========================================================================="
+Rails.logger.debug "  Crspec vs RSpec vs Minitest Benchmark Suite"
+Rails.logger.debug { "  Test Workload: #{NUMBER_OF_TESTS} examples per framework" }
+Rails.logger.debug "  Evaluating Default Native Framework Runners (No Manual Concurrency Controls)"
+Rails.logger.debug "=========================================================================="
+
+results = {}
+null_formatter = Crspec::Formatters::NullFormatter.new
+
+# -----------------------------------------------------------------------------
+# 1. Crspec Native Execution (Default Concurrency Kernel)
+# -----------------------------------------------------------------------------
+Crspec.reset!
+load File.expand_path("spec/user_service_crspec_spec.rb", __dir__)
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+Crspec::Runner.new(formatter: null_formatter).run(Crspec.world.example_groups)
+t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+results["Crspec (Native Default Runner)"] = t1 - t0
+
+# -----------------------------------------------------------------------------
+# 2. RSpec Native Execution
+# -----------------------------------------------------------------------------
+config = RSpec::Core::Configuration.new
+config.output_stream = StringIO.new
+world = RSpec::Core::World.new(config)
+RSpec.instance_variable_set(:@world, world)
+load File.expand_path("spec/user_service_rspec_spec.rb", __dir__)
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+world.example_groups.first.run(config.reporter)
+t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+results["RSpec (Native Default Runner)"] = t1 - t0
+
+# -----------------------------------------------------------------------------
+# 3. Minitest Native Execution
+# -----------------------------------------------------------------------------
+load File.expand_path("test/user_service_test.rb", __dir__)
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+Minitest::CompositeReporter.new
+UserServiceTest.runnable_methods.each do |method_name|
+  UserServiceTest.new(method_name).run
+end
+t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+results["Minitest (Native Default Runner)"] = t1 - t0
+
+# -----------------------------------------------------------------------------
+# Summary Output
+# -----------------------------------------------------------------------------
+Rails.logger.debug "\nResults Summary:"
+Rails.logger.debug format("%-45s | %-12s | %-15s", "Framework Engine", "Duration (s)", "Throughput (ops/s)")
+Rails.logger.debug "-" * 78
+
+results.each do |engine, duration|
+  throughput = (NUMBER_OF_TESTS / duration).round(2)
+  Rails.logger.debug format("%-45s | %-12.4f | %-15.2f", engine, duration, throughput)
+end
+
+Rails.logger.debug "=" * 78

data/benchmark/spec/user_service_crspec_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "../target_service"
+
+Crspec.describe UserService do
+  100.times do |i|
+    let(:"user_#{i}") { UserService.process_user(i, "User #{i}", "user#{i}@example.com") }
+
+    it "processes user #{i}" do
+      u = send(:"user_#{i}")
+      expect(u[:valid]).to be(true)
+      expect(u[:token]).not_to be_nil
+    end
+  end
+end

data/benchmark/spec/user_service_rspec_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require_relative "../target_service"
+
+RSpec.describe UserService do
+  100.times do |i|
+    let(:"user_#{i}") { UserService.process_user(i, "User #{i}", "user#{i}@example.com") }
+
+    it "processes user #{i}" do
+      u = send(:"user_#{i}")
+      expect(u[:valid]).to be(true)
+      expect(u[:token]).not_to be_nil
+    end
+  end
+end

data/benchmark/target_service.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "digest"
+
+class UserService
+  def self.process_user(id, name, email)
+    # Simulate non-blocking I/O query (e.g. database lease / HTTP call)
+    sleep 0.001
+    token = Digest::SHA256.hexdigest("#{id}-#{name}-#{email}")
+    { id: id, name: name, email: email, token: token, valid: true }
+  end
+end

data/benchmark/test/user_service_test.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "minitest"
+require_relative "../target_service"
+
+Minitest.seed ||= srand
+
+class UserServiceTest < Minitest::Test
+  parallelize_me! if respond_to?(:parallelize_me!)
+
+  100.times do |i|
+    define_method(:"test_user_#{i}") do
+      u = UserService.process_user(i, "User #{i}", "user#{i}@example.com")
+      assert u[:valid]
+      refute_nil u[:token]
+    end
+  end
+end

data/demo.rb

@@ -6,9 +6,12 @@ gemfile do
   source "https://rubygems.org"
   gem "crspec", path: __dir__
   gem "prism"
+  gem "rails", "~> 8.0"
+  gem "sqlite3"
 end
 
 require "crspec"
+require "rails"
 
 puts "================================================================="
 puts "  Crspec Single-File Inline Demo & Feature Verification          "
@@ -86,11 +89,11 @@ end
 
 # 3. Rails Parallel Worker Integration (crspec-rails)
 Crspec::Rails::Parallel.parallelize(workers: 4) do
-  parallelize_setup do |worker_num|
-    # Per-worker setup hook (e.g. database setup for worker_num)
+  parallelize_setup do |_worker_num|
+    # Per-worker setup hook
   end
 
-  parallelize_teardown do |worker_num|
+  parallelize_teardown do |_worker_num|
     # Per-worker teardown hook
   end
 end

data/lib/crspec/cli.rb

@@ -2,6 +2,7 @@
 
 require "optparse"
 require_relative "../crspec"
+require_relative "generators/init"
 
 module Crspec
   class CLI
@@ -11,14 +12,30 @@ module Crspec
 
     def initialize(args)
       @args = args
-      @concurrency = Etc.nprocessors
+      @concurrency = Crspec.configuration.concurrency
       @paths = []
+      @requires = []
+      @init_mode = false
     end
 
     def run
       parse_options
+
+      if @init_mode
+        created = Generators::Init.generate
+        if created.empty?
+          puts "No helper files were created (already exists or not a Rails project)."
+        else
+          created.each { |f| puts "  create #{f}" }
+        end
+        return true
+      end
+
+      load_requires
       load_specs
-      runner = Runner.new(concurrency: @concurrency)
+
+      concurrency = @concurrency || Crspec.configuration.concurrency
+      runner = Runner.new(concurrency: concurrency)
       groups = Crspec.world.example_groups
 
       if groups.empty?
@@ -26,7 +43,7 @@ module Crspec
         return true
       end
 
-      puts "Running Crspec suite with concurrency #{@concurrency}..."
+      puts "Running Crspec suite with concurrency #{concurrency}..."
       runner.run(groups)
 
       puts "\nFinished in #{runner.total_duration.round(4)} seconds"
@@ -54,6 +71,14 @@ module Crspec
           @concurrency = n
         end
 
+        opts.on("-r", "--require PATH", String, "Require a file before running specs") do |path|
+          @requires << path
+        end
+
+        opts.on("--init", "Initialize spec_helper.rb (and rails_helper.rb if Rails project)") do
+          @init_mode = true
+        end
+
         opts.on("-h", "--help", "Show help") do
           puts opts
           exit 0
@@ -64,6 +89,12 @@ module Crspec
       @paths = ["spec"] if @paths.empty?
     end
 
+    def load_requires
+      @requires.each do |req|
+        require req
+      end
+    end
+
     def load_specs
       files = []
       @paths.each do |p|

data/lib/crspec/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Crspec
+  class Configuration
+    attr_accessor :concurrency, :use_transactional_fixtures, :formatter
+    attr_reader :before_hooks, :after_hooks, :around_hooks, :included_modules
+
+    def initialize
+      @concurrency = Etc.nprocessors
+      @use_transactional_fixtures = true
+      @formatter = nil
+      @before_hooks = []
+      @after_hooks = []
+      @around_hooks = []
+      @included_modules = []
+      @infer_spec_type = false
+    end
+
+    def before(_scope = :each, &block)
+      @before_hooks << block
+    end
+
+    def after(_scope = :each, &block)
+      @after_hooks.unshift(block)
+    end
+
+    def around(_scope = :each, &block)
+      @around_hooks << block
+    end
+
+    def include(mod)
+      @included_modules << mod
+    end
+
+    def infer_spec_type_from_file_location!
+      @infer_spec_type = true
+    end
+
+    def infer_spec_type?
+      !!@infer_spec_type
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration if block_given?
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/crspec/example_group.rb

@@ -3,6 +3,7 @@
 require_relative "expectations"
 require_relative "example"
 require_relative "mock/double"
+require_relative "configuration"
 
 module Crspec
   class ExampleGroup
@@ -21,6 +22,7 @@ module Crspec
       @after_hooks = []
       @let_blocks = {}
       @eager_lets = []
+      @included_modules = []
     end
 
     def self.define(description, metadata = {}, parent = nil, &block)
@@ -43,6 +45,10 @@ module Crspec
     end
     alias specify it
 
+    def include(mod)
+      @included_modules << mod
+    end
+
     def let(name, &block)
       @let_blocks[name.to_sym] = block
     end
@@ -71,6 +77,8 @@ module Crspec
 
     def ancestor_hooks(type)
       hooks = []
+      hooks.concat(Crspec.configuration.before_hooks) if type == :before
+
       curr = self
       ancestors = []
       while curr
@@ -82,6 +90,9 @@ module Crspec
         list = type == :before ? grp.before_hooks : grp.after_hooks
         hooks.concat(list)
       end
+
+      hooks.concat(Crspec.configuration.after_hooks) if type == :after
+
       hooks
     end
 
@@ -109,11 +120,31 @@ module Crspec
       eager
     end
 
+    def ancestor_included_modules
+      mods = []
+      curr = self
+      ancestors = []
+      while curr
+        ancestors.unshift(curr)
+        curr = curr.parent
+      end
+      ancestors.each do |grp|
+        mods.concat(grp.instance_variable_get(:@included_modules) || [])
+      end
+      mods
+    end
+
     def create_instance(example)
+      modules_to_include = (Crspec.configuration.included_modules + ancestor_included_modules).uniq
+
       klass = Class.new do
         include Expectations
         include Mock::DSL
 
+        modules_to_include.each do |mod|
+          include mod
+        end
+
         attr_reader :__crspec_example__
 
         def initialize(example)

data/lib/crspec/execution_context.rb

@@ -37,7 +37,7 @@ module Crspec
       @monitor.synchronize do
         return @memoized_values[key] if @memoized_values.key?(key)
 
-        @memoized_values[key] = block.call
+        @memoized_values[key] = yield
       end
     end