fixture_kit 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 311fd09f37153fae9d8a09e3e41357c38f18e1e343794a758ae943dfdca3c40a
-  data.tar.gz: ee4257fc3c840f809a25204f300c766f872688c5c7417dc22155f001ba424882
+  metadata.gz: b9c12d67129c3c71b587913a62cea49c41f55a7ab9c0f4308961906517f7b6f7
+  data.tar.gz: 92e5dec6ccdb3084d5b699fd1f462fb145667dd46caeb7f65aba8d782244bdbd
 SHA512:
-  metadata.gz: bd8c58de66c08eeceab67e4f0b83a8a95d25291401272e96b51725db2b7a9f2b2592c24f1d6f6cb7b4f6b4716fa93fc768c4fc81afcf1974b9339e14b1b61fa9
-  data.tar.gz: 8d335927771e40d35142a69ee9bf911fcfb6c660af6cde28269a16643e86a468c017cf2f54e362f09d90a78bfeffe6320071d0230f6240969fc495de0e91c8f2
+  metadata.gz: 75484ce7d299f78263f0c268a39eacb4c33896075b90138ed6741e253b95d312144ced9481ae2e7e6328a4b8817bf8e566c7d56df86975e236b2f2a248643376
+  data.tar.gz: c7644edbec83c88df2d5cc24a206ccabd4d3f1077a199fd2317c81e7e128801a58ed86738b229ed679b6ca3c1b979fe0f2b5adbf2334ed4ab16dbd2fa04b3ccf

data/README.md

@@ -8,7 +8,7 @@ Test data setup is slow. Every `Model.create!` or `FactoryBot.create` hits the d
 
 ## The Solution
 
-FixtureKit caches database records as raw SQL INSERT statements. On first use, it executes your fixture definition, captures the resulting database state, and generates optimized batch INSERT statements. Subsequent loads replay these statements directly—no ORM overhead, no callbacks, just fast SQL.
+FixtureKit caches database records as raw SQL INSERT statements. It executes your fixture definition once, captures the resulting database state, and generates optimized batch INSERT statements. Fixture loads then replay these statements directly: no ORM overhead, no callbacks, just fast SQL.
 
 Combined with RSpec's transactional fixtures, each test runs in a transaction that rolls back—so cached data can be reused across tests without cleanup.
 
@@ -26,7 +26,7 @@ end
 
 ### 1. Define a Fixture
 
-Create fixture files in `spec/fixture_kit/`. Use whatever method you prefer to create records—FixtureKit doesn't care.
+Create fixture files in `spec/fixture_kit/` (or `test/fixture_kit/` for test-unit/minitest-style setups). Use whatever method you prefer to create records.
 
 **Using ActiveRecord directly:**
 
@@ -117,60 +117,80 @@ RSpec.configure do |config|
 end
 ```
 
+When you call `fixture "name"` in an example group, FixtureKit registers that fixture with its runner.
+
+### 4. Configure Minitest
+
+```ruby
+# test/test_helper.rb
+require "fixture_kit/minitest"
+
+class ActiveSupport::TestCase
+  self.use_transactional_tests = true
+end
+```
+
+When you call `fixture "name"` in a test class, FixtureKit registers that fixture with its runner and mounts it during test setup.
+
 ## Configuration
 
 ```ruby
 # spec/support/fixture_kit.rb
 FixtureKit.configure do |config|
-  # Where fixture definitions live (default: spec/fixture_kit)
+  # Where fixture definitions live (default: fixture_kit).
+  # Framework entrypoints set a framework-specific default:
+  # - fixture_kit/rspec -> spec/fixture_kit
+  # - fixture_kit/minitest -> test/fixture_kit
   config.fixture_path = Rails.root.join("spec/fixture_kit").to_s
 
   # Where cache files are stored (default: tmp/cache/fixture_kit)
   config.cache_path = Rails.root.join("tmp/cache/fixture_kit").to_s
 
-  # Whether to regenerate caches on every run (default: true)
-  config.autogenerate = true
+  # Wrapper used to isolate generation work (default: FixtureKit::MinitestIsolator)
+  # config.isolator = FixtureKit::MinitestIsolator
+  # config.isolator = FixtureKit::RSpecIsolator
 
-  # Optional: customize how pregeneration is wrapped.
-  # Default is FixtureKit::TestCase::Generator.
-  # config.generator = FixtureKit::TestCase::Generator
+  # Optional callback, called right before a fixture cache is generated.
+  # Called on first generation and forced regeneration.
+  # Receives the fixture name as a String.
+  # config.on_cache = ->(fixture_name) { puts "cached #{fixture_name}" }
 end
 ```
 
-Custom generators should subclass `FixtureKit::Generator` and implement `#run`.
-`#run` receives the pregeneration block and should execute it in whatever lifecycle you need.
+Custom isolators should subclass `FixtureKit::Isolator` and implement `#run`.
+`#run` receives the generation block and should execute it in whatever lifecycle you need.
+
+By default, FixtureKit uses `FixtureKit::MinitestIsolator`, which runs generation inside an internal `ActiveSupport::TestCase` and removes that harness case from minitest runnables.
+
+When using `fixture_kit/rspec`, FixtureKit sets `FixtureKit::RSpecIsolator`. It runs generation inside an internal RSpec example, and uses a null reporter so harness runs do not count toward suite example totals.
 
-### Autogenerate
+## Lifecycle
 
-When `autogenerate` is `true` (the default), FixtureKit clears all caches at the start of each test run, then regenerates them on first use. Subsequent tests that use the same fixture reuse the cache from earlier in the run. This ensures your test data always matches your fixture definitions.
+Fixture generation is managed by `FixtureKit::Runner`.
 
-When `autogenerate` is `false`, FixtureKit pre-generates all fixture caches at suite start. This runs through the configured `generator`, and still rolls back database changes.
+1. Calling `fixture "name"` registers the fixture with the runner.
+2. Runner `start`:
+   - clears `cache_path` (unless preserve-cache is enabled),
+   - generates caches for all already-registered fixtures.
+3. If new tests are loaded after start (for example, queue-mode CI runners), newly registered fixtures are cached immediately.
+4. At test runtime, `fixture` mounts from cache and returns a `Repository`.
 
-By default, FixtureKit uses `FixtureKit::TestCase::Generator`, which runs pregeneration inside an internal `ActiveSupport::TestCase` so setup/teardown hooks and transactional fixture behavior run as expected. The internal test case is removed from Minitest runnables, so it does not count toward suite totals.
+When runner start happens:
 
-When using `fixture_kit/rspec`, FixtureKit sets `FixtureKit::RSpec::Generator` as the generator. This runs pregeneration inside an internal RSpec example so your normal `before`/`around`/`after` hooks apply. The internal example uses a null reporter, so it does not count toward suite example totals.
+- `fixture_kit/rspec`: in `before(:suite)`.
+- `fixture_kit/minitest`: lazily during test setup for the first test class that declares `fixture`.
 
 ### Preserving Cache Locally
 
-If you want to skip cache clearing at suite start (e.g., to reuse caches across test runs during local development), set the `FIXTURE_KIT_PRESERVE_CACHE` environment variable:
+If you want to skip cache clearing when the runner starts (e.g., to reuse caches across test runs during local development), set the `FIXTURE_KIT_PRESERVE_CACHE` environment variable:
 
 ```bash
 FIXTURE_KIT_PRESERVE_CACHE=1 bundle exec rspec
 ```
 
-This is useful when you're iterating on tests and your fixture definitions haven't changed.
-
-### CI Setup
-
-For CI, set `autogenerate` to `false`. FixtureKit will automatically generate any missing caches at suite start:
+Truthy values are case-insensitive: `1`, `true`, `yes`.
 
-```ruby
-FixtureKit.configure do |config|
-  config.autogenerate = !ENV["CI"]
-end
-```
-
-This means CI "just works" - no need to pre-generate caches or commit them to the repository. The first test run will generate all caches, and subsequent runs (if caches are preserved between builds) will reuse them.
+This is useful when you're iterating on tests and your fixture definitions haven't changed.
 
 ## Nested Fixtures
 
@@ -189,13 +209,13 @@ fixture "teams/sales"
 
 ## How It Works
 
-1. **First load (cache miss)**: FixtureKit executes your definition block, subscribes to `sql.active_record` notifications to track which tables received INSERTs, queries all records from those tables, and generates batch INSERT statements with conflict handling (`INSERT OR IGNORE` for SQLite, `ON CONFLICT DO NOTHING` for PostgreSQL, `INSERT IGNORE` for MySQL).
+1. **Cache generation**: FixtureKit executes your definition block inside the configured isolator, subscribes to `sql.active_record` notifications to track created/updated/deleted models, queries those model tables, and caches INSERT statements for current table contents.
 
-2. **Subsequent loads (cache hit)**: FixtureKit loads the cached JSON file and executes the raw SQL INSERT statements directly. No ORM instantiation, no callbacks—just fast SQL execution.
+2. **Mounting**: FixtureKit loads the cached JSON file, clears each tracked table, and executes the raw SQL INSERT statements directly. No ORM instantiation, no callbacks.
 
-3. **In-memory caching**: Once a cache file is parsed, the data is stored in memory. Multiple tests using the same fixture within a single test run don't re-read or re-parse the JSON file.
+3. **Repository build**: FixtureKit resolves exposed records by model + id and returns a `Repository` for method-based access.
 
-4. **Transaction isolation**: RSpec's `use_transactional_fixtures` wraps each test in a transaction that rolls back, so data doesn't persist between tests.
+4. **Transaction isolation**: Use framework transactions (`use_transactional_fixtures` in RSpec, `use_transactional_tests` in Minitest) so test writes roll back and cached data can be reused safely between tests.
 
 ### Cache Format
 
@@ -216,7 +236,7 @@ Caches are stored as JSON files in `tmp/cache/fixture_kit/`:
 ```
 
 - **records**: Maps model names to their INSERT statements. Using model names (not table names) allows FixtureKit to use the correct database connection for multi-database setups.
-- **exposed**: Maps fixture accessor names to their model class and ID for querying after cache replay
+- **exposed**: Maps fixture accessor names to their model class and ID for querying after cache replay.
 
 ## Cache Management
 
@@ -225,7 +245,7 @@ Delete the cache directory to force regeneration:
 rm -rf tmp/cache/fixture_kit
 ```
 
-Caches are automatically cleared at suite start when `autogenerate` is enabled, so manual clearing is rarely needed.
+Caches are cleared at runner start unless `FIXTURE_KIT_PRESERVE_CACHE` is truthy.
 
 ## Multi-Database Support
 

data/lib/fixture_kit/cache.rb

@@ -7,109 +7,61 @@ require "active_support/inflector"
 
 module FixtureKit
   class Cache
-    # In-memory cache to avoid re-reading/parsing JSON for every test
-    @memory_cache = {}
+    include ConfigurationHelper
 
-    class << self
-      attr_accessor :memory_cache
+    attr_reader :fixture
 
-      def clear_memory_cache(fixture_name = nil)
-        if fixture_name
-          @memory_cache.delete(fixture_name)
-        else
-          @memory_cache.clear
-        end
-      end
-
-      # Clear fixture cache (both memory and disk)
-      def clear(fixture_name = nil)
-        clear_memory_cache(fixture_name)
-
-        cache_path = FixtureKit.configuration.cache_path
-        if fixture_name
-          cache_file = File.join(cache_path, "#{fixture_name}.json")
-          FileUtils.rm_f(cache_file)
-        else
-          FileUtils.rm_rf(cache_path)
-        end
-      end
-
-      # Generate caches for all fixtures.
-      # Each fixture is generated in a transaction that rolls back, so no data persists.
-      def generate_all
-        Registry.load_definitions
-        Registry.fixtures.each { |fixture| generate(fixture.name) }
-      end
-
-      def generate(fixture_name)
-        clear(fixture_name)
-
-        FixtureKit.configuration.generator.run do
-          Runner.run(fixture_name, force: true)
-        end
-      end
-    end
-
-    attr_reader :records, :exposed
-
-    def initialize(fixture_name)
-      @fixture_name = fixture_name
-      @records = {}
-      @exposed = {}
+    def initialize(fixture, definition)
+      @fixture = fixture
+      @definition = definition
     end
 
-    def cache_file_path
-      cache_path = FixtureKit.configuration.cache_path
-      File.join(cache_path, "#{@fixture_name}.json")
+    def path
+      File.join(configuration.cache_path, "#{fixture.name}.json")
     end
 
     def exists?
-      # Check in-memory cache first, then disk
-      self.class.memory_cache.key?(@fixture_name) || File.exist?(cache_file_path)
+      @data || File.exist?(path)
     end
 
     def load
-      # Check in-memory cache first
-      if self.class.memory_cache.key?(@fixture_name)
-        data = self.class.memory_cache[@fixture_name]
-        @records = data.fetch("records")
-        @exposed = data.fetch("exposed")
-        return true
+      unless exists?
+        raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{fixture.name}'"
       end
 
-      # Fall back to disk
-      return false unless File.exist?(cache_file_path)
-
-      data = JSON.parse(File.read(cache_file_path))
-      @records = data.fetch("records")
-      @exposed = data.fetch("exposed")
-
-      # Store in memory for subsequent loads
-      self.class.memory_cache[@fixture_name] = data
+      @data ||= JSON.parse(File.read(path))
+      @data.fetch("records").each do |model_name, sql|
+        model = ActiveSupport::Inflector.constantize(model_name)
+        connection = model.connection
+        connection.disable_referential_integrity do
+          # execute_batch is private in current supported Rails versions.
+          # This should be revisited when Rails 8.2 makes it public.
+          connection.__send__(:execute_batch, [build_delete_sql(model), sql].compact, "FixtureKit Load")
+        end
+      end
 
-      true
+      build_repository(@data.fetch("exposed"))
     end
 
-    def save(models_with_connections:, exposed_mapping:)
-      @records = generate_statements(models_with_connections)
-      @exposed = exposed_mapping
-
-      FileUtils.mkdir_p(File.dirname(cache_file_path))
-
-      data = {
-        "records" => @records,
-        "exposed" => @exposed
-      }
+    def save
+      FixtureKit.runner.isolator.run do
+        models = SqlSubscriber.capture do
+          @definition.evaluate
+        end
 
-      # Store in memory cache
-      self.class.memory_cache[@fixture_name] = data
+        @data = {
+          "records" => generate_statements(models),
+          "exposed" => build_exposed_mapping(@definition.exposed)
+        }
+      end
 
-      File.write(cache_file_path, JSON.pretty_generate(data))
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(@data))
     end
 
     # Query exposed records from the database and return a Repository.
-    def build_repository
-      exposed_records = @exposed.each_with_object({}) do |(name, value), hash|
+    def build_repository(exposed)
+      exposed_records = exposed.each_with_object({}) do |(name, value), hash|
         was_array = value.is_a?(Array)
         records = Array.wrap(value).map { |record_info| find_exposed_record(record_info.fetch("model"), record_info.fetch("id"), name) }
         hash[name.to_sym] = was_array ? records : records.first
@@ -125,54 +77,47 @@ module FixtureKit
       model.find(id)
     rescue ActiveRecord::RecordNotFound
       raise FixtureKit::ExposedRecordNotFound,
-        "Could not find #{model_name} with id=#{id} for exposed record '#{exposed_name}' in fixture '#{@fixture_name}'"
+        "Could not find #{model_name} with id=#{id} for exposed record '#{exposed_name}' in fixture '#{@fixture.name}'"
     end
 
-    def generate_statements(models_with_connections)
+    def generate_statements(models)
       statements_by_model = {}
 
-      models_with_connections.each do |model, connection|
+      models.each do |model|
         columns = model.column_names
 
         rows = []
         model.order(:id).find_each do |record|
           row_values = columns.map do |col|
             value = record.read_attribute_before_type_cast(col)
-            connection.quote(value)
+            model.connection.quote(value)
           end
           rows << "(#{row_values.join(", ")})"
         end
 
-        next if rows.empty?
-
-        sql = build_insert_sql(model.table_name, columns, rows, connection)
+        sql = rows.empty? ? nil : build_insert_sql(model.table_name, columns, rows, model.connection)
         statements_by_model[model.name] = sql
       end
 
       statements_by_model
     end
 
+    def build_delete_sql(model)
+      "DELETE FROM #{model.quoted_table_name}"
+    end
+
     def build_insert_sql(table_name, columns, rows, connection)
       quoted_table = connection.quote_table_name(table_name)
       quoted_columns = columns.map { |c| connection.quote_column_name(c) }
 
-      sql = "INSERT INTO #{quoted_table} (#{quoted_columns.join(", ")}) VALUES #{rows.join(", ")}"
-
-      add_conflict_handling(sql, connection)
+      "INSERT INTO #{quoted_table} (#{quoted_columns.join(", ")}) VALUES #{rows.join(", ")}"
     end
 
-    def add_conflict_handling(sql, connection)
-      adapter_name = connection.adapter_name.downcase
-
-      case adapter_name
-      when /sqlite/
-        sql.sub(/\AINSERT INTO/i, "INSERT OR IGNORE INTO")
-      when /postgresql/, /postgis/
-        "#{sql} ON CONFLICT DO NOTHING"
-      when /mysql/, /trilogy/
-        sql.sub(/\AINSERT INTO/i, "INSERT IGNORE INTO")
-      else
-        sql
+    def build_exposed_mapping(exposed)
+      exposed.each_with_object({}) do |(name, value), hash|
+        was_array = value.is_a?(Array)
+        records = Array.wrap(value).map { |record| { "model" => record.class.name, "id" => record.id } }
+        hash[name] = was_array ? records : records.first
       end
     end
   end

data/lib/fixture_kit/configuration.rb

@@ -4,18 +4,18 @@ module FixtureKit
   class Configuration
     attr_writer :fixture_path
     attr_writer :cache_path
-    attr_accessor :generator
-    attr_accessor :autogenerate
+    attr_accessor :isolator
+    attr_accessor :on_cache
 
     def initialize
-      @fixture_path = nil
+      @fixture_path = "fixture_kit"
       @cache_path = nil
-      @generator = FixtureKit::TestCase::Generator
-      @autogenerate = true
+      @isolator = FixtureKit::MinitestIsolator
+      @on_cache = nil
     end
 
     def fixture_path
-      @fixture_path ||= detect_fixture_path
+      @fixture_path
     end
 
     def cache_path
@@ -24,20 +24,6 @@ module FixtureKit
 
     private
 
-    def detect_fixture_path
-      if defined?(RSpec)
-        "spec/fixture_kit"
-      elsif defined?(Minitest)
-        "test/fixture_kit"
-      elsif Dir.exist?("spec")
-        "spec/fixture_kit"
-      elsif Dir.exist?("test")
-        "test/fixture_kit"
-      else
-        "spec/fixture_kit"
-      end
-    end
-
     def detect_cache_path
       "tmp/cache/fixture_kit"
     end

data/lib/fixture_kit/configuration_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  module ConfigurationHelper
+    private
+
+    def configuration
+      FixtureKit.runner.configuration
+    end
+  end
+end

data/lib/fixture_kit/{definition_context.rb → definition.rb}

@@ -1,23 +1,22 @@
 # frozen_string_literal: true
 
 module FixtureKit
-  class DefinitionContext
+  class Definition
     attr_reader :exposed
 
-    def initialize
+    def initialize(&definition)
+      @definition = definition
       @exposed = {}
     end
 
+    def evaluate
+      instance_eval(&@definition)
+    end
+
     def expose(**records)
       records.each do |name, record|
-        name = name.to_sym
-
         if @exposed.key?(name)
-          raise FixtureKit::DuplicateNameError, <<~ERROR
-            Duplicate expose name :#{name}
-
-            A record with this name has already been exposed in this fixture.
-          ERROR
+          raise FixtureKit::DuplicateNameError, "Name #{name} already exposed"
         end
 
         @exposed[name] = record

data/lib/fixture_kit/fixture.rb

@@ -2,17 +2,39 @@
 
 module FixtureKit
   class Fixture
-    attr_reader :name, :block
+    include ConfigurationHelper
 
-    def initialize(name, &block)
+    attr_reader :name, :path
+
+    def initialize(name, path)
       @name = name
-      @block = block
+      @path = path
+      @cache = Cache.new(self, definition)
+    end
+
+    def cache(force: false)
+      return if @cache.exists? && !force
+
+      configuration.on_cache&.call(name)
+      @cache.save
     end
 
-    def execute
-      context = DefinitionContext.new
-      context.instance_eval(&block) if block
-      context.exposed
+    def mount
+      unless @cache.exists?
+        raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{name}'"
+      end
+
+      @cache.load
+    end
+
+    private
+
+    def definition
+      @definition ||= begin
+        definition = eval(File.read(@path), TOPLEVEL_BINDING.dup, @path)
+        raise FixtureKit::FixtureDefinitionNotFound, "Could not find fixture definition at '#{@path}'" unless definition.is_a?(Definition)
+        definition
+      end
     end
   end
 end

data/lib/fixture_kit/{generator.rb → isolator.rb}

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module FixtureKit
-  # Base class for fixture cache generators.
-  class Generator
+  # Base class for fixture cache isolators.
+  class Isolator
     def self.run(&block)
       new.run(&block)
     end

data/lib/fixture_kit/isolators/minitest_isolator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_support/test_case"
+require "active_record/fixtures"
+
+module FixtureKit
+  class MinitestIsolator < FixtureKit::Isolator
+    TEST_NAME = "fixture kit cache pregeneration"
+
+    def run(&block)
+      test_class = build_test_class
+      test_method = test_class.test(TEST_NAME) do
+        block.call
+        pass
+      end
+
+      result = test_class.new(test_method).run
+      return if result.passed?
+
+      raise result.failures.first.error
+    end
+
+    private
+
+    def build_test_class
+      Class.new(ActiveSupport::TestCase) do
+        ::Minitest::Runnable.runnables.delete(self)
+        include(::ActiveRecord::TestFixtures)
+      end
+    end
+  end
+end

data/lib/fixture_kit/isolators/rspec_isolator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class RSpecIsolator < FixtureKit::Isolator
+    def run(&block)
+      previous_example = ::RSpec.current_example
+      previous_scope = ::RSpec.current_scope
+      example_group = build_example_group
+      example = example_group.example { block.call }
+      instance = example_group.new
+      succeeded =
+        begin
+          example.run(instance, ::RSpec::Core::NullReporter)
+        ensure
+          ::RSpec.current_example = previous_example
+          ::RSpec.current_scope = previous_scope
+        end
+
+      raise example.exception unless succeeded
+    end
+
+    private
+
+    def build_example_group
+      ::RSpec::Core::ExampleGroup.subclass(
+        ::RSpec::Core::ExampleGroup,
+        "FixtureKit",
+        [],
+        []
+      )
+    end
+  end
+end

data/lib/fixture_kit/minitest.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "fixture_kit"
+require "active_support/lazy_load_hooks"
+
+module FixtureKit
+  module Minitest
+    DECLARATION_CLASS_ATTRIBUTE = :fixture_kit_declaration
+
+    module ClassMethods
+      def fixture(name)
+        self.fixture_kit_declaration = FixtureKit.runner.register(name)
+      end
+    end
+
+    module InstanceMethods
+      def fixture
+        @_fixture_kit_repository || raise("No fixture declared for this test class. Use `fixture \"name\"` in your test class.")
+      end
+    end
+
+    def self.configure!(test_case)
+      FixtureKit.runner.configuration.fixture_path = "test/fixture_kit"
+      FixtureKit.runner.configuration.isolator = FixtureKit::MinitestIsolator
+
+      test_case.class_attribute DECLARATION_CLASS_ATTRIBUTE, instance_accessor: false
+      test_case.extend ClassMethods
+      test_case.include InstanceMethods
+
+      test_case.setup do
+        declaration = self.class.fixture_kit_declaration
+        next unless declaration
+
+        FixtureKit.runner.start unless FixtureKit.runner.started?
+        @_fixture_kit_repository = declaration.mount
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_support_test_case) do
+  FixtureKit::Minitest.configure!(self)
+end

data/lib/fixture_kit/registry.rb

@@ -1,58 +1,35 @@
 # frozen_string_literal: true
 
-module FixtureKit
-  module Registry
-    class << self
-      def fetch(name)
-        fixture = find(name)
-        return fixture if fixture
-
-        file_path = fixture_file_path(name)
-        unless File.file?(file_path)
-          raise FixtureKit::FixtureDefinitionNotFound,
-            "Could not find fixture definition file for '#{name}' at '#{file_path}'"
-        end
-
-        load file_path
-        find(name)
-      end
+require "pathname"
 
-      def find(name)
-        registry[name]
-      end
+module FixtureKit
+  class Registry
+    include ConfigurationHelper
 
-      def fixtures
-        registry.values
-      end
+    def initialize
+      @registry = {}
+    end
 
-      def register(fixture)
-        registry[fixture.name] = fixture
-      end
+    def add(name)
+      return @registry[name] if @registry.key?(name)
 
-      # Load all fixture definition files.
-      # Uses `load` instead of `require` to ensure fixtures are registered
-      # even if the files were previously required (e.g., after a reset).
-      def load_definitions
-        fixture_path = FixtureKit.configuration.fixture_path
-        Dir.glob(File.join(fixture_path, "**/*.rb")).each do |file|
-          load file
-        end
+      file_path = fixture_file_path(name)
+      unless File.file?(file_path)
+        raise FixtureKit::FixtureDefinitionNotFound,
+          "Could not find fixture definition file for '#{name}' at '#{file_path}'"
       end
 
-      def reset
-        @registry = nil
-      end
+      @registry[name] = Fixture.new(name, file_path)
+    end
 
-      private
+    def fixtures
+      @registry.values
+    end
 
-      def fixture_file_path(name)
-        fixture_path = FixtureKit.configuration.fixture_path
-        File.expand_path(File.join(fixture_path, "#{name}.rb"))
-      end
+    private
 
-      def registry
-        @registry ||= {}
-      end
+    def fixture_file_path(name)
+      File.expand_path(File.join(configuration.fixture_path, "#{name}.rb"))
     end
   end
 end

data/lib/fixture_kit/rspec.rb

@@ -4,11 +4,7 @@ require "fixture_kit"
 
 module FixtureKit
   module RSpec
-    autoload :Declaration, File.expand_path("rspec/declaration", __dir__)
-    autoload :Generator, File.expand_path("rspec/generator", __dir__)
-
     DECLARATION_METADATA_KEY = :fixture_kit_declaration
-    PRESERVE_CACHE_ENV_KEY = "FIXTURE_KIT_PRESERVE_CACHE"
 
     # Class methods (extended via config.extend)
     module ClassMethods
@@ -32,7 +28,7 @@ module FixtureKit
       #     end
       #   end
       def fixture(name)
-        metadata[DECLARATION_METADATA_KEY] = Declaration.new(name)
+        metadata[DECLARATION_METADATA_KEY] = ::RSpec.configuration.fixture_kit.register(name)
       end
     end
 
@@ -41,46 +37,28 @@ module FixtureKit
       # Returns the Repository for the current example's fixture.
       # Access exposed records as methods: fixture.alice, fixture.posts
       def fixture
-        @_fixture_kit_fixture_set || raise("No fixture declared for this example group. Use `fixture \"name\"` in your describe/context block.")
+        @_fixture_kit_repository || raise("No fixture declared for this example group. Use `fixture \"name\"` in your describe/context block.")
       end
     end
 
     def self.configure!(config)
-      FixtureKit.configuration.generator = Generator
+      FixtureKit.runner.configuration.fixture_path = "spec/fixture_kit"
+      config.add_setting(:fixture_kit, default: FixtureKit.runner)
+      FixtureKit.runner.configuration.isolator = FixtureKit::RSpecIsolator
+
       config.extend ClassMethods
-      config.include InstanceMethods
+      config.include InstanceMethods, DECLARATION_METADATA_KEY
 
       # Load declared fixtures at the beginning of each example.
       # Runs inside transactional fixtures and before user-defined before hooks.
       config.prepend_before(:example, DECLARATION_METADATA_KEY) do |example|
-        declaration = example.metadata[DECLARATION_METADATA_KEY]
-        @_fixture_kit_fixture_set = declaration.fixture_set
+        @_fixture_kit_repository = example.metadata[DECLARATION_METADATA_KEY].mount
       end
 
-      # Setup caches at suite start only when at least one fixture-backed
-      # example exists in the loaded suite.
-      config.when_first_matching_example_defined(DECLARATION_METADATA_KEY) do
-        config.before(:suite) do
-          if FixtureKit.configuration.autogenerate
-            preserve_cache = ENV[PRESERVE_CACHE_ENV_KEY].to_s.match?(/\A(1|true|yes)\z/i)
-            Cache.clear unless preserve_cache
-          else
-            fixture_names_for_loaded_examples.each do |fixture_name|
-              Cache.generate(fixture_name)
-            end
-          end
-        end
+      config.append_before(:suite) do
+        config.fixture_kit.start
       end
     end
-
-    def self.fixture_names_for_loaded_examples
-      ::RSpec.world.filtered_examples.each_value.with_object(Set.new) do |examples, names|
-        examples.each do |example|
-          declaration = example.metadata[DECLARATION_METADATA_KEY]
-          names << declaration.name if declaration
-        end
-      end.to_a
-    end
   end
 end
 

data/lib/fixture_kit/runner.rb

@@ -1,93 +1,50 @@
 # frozen_string_literal: true
 
-require "active_support/inflector"
+require "fileutils"
 
 module FixtureKit
   class Runner
-    def self.run(fixture_name, force: false)
-      new(fixture_name).run(force: force)
-    end
-
-    def initialize(fixture_name)
-      @fixture_name = fixture_name
-      @cache = Cache.new(@fixture_name)
-    end
+    PRESERVE_CACHE_ENV_KEY = "FIXTURE_KIT_PRESERVE_CACHE"
 
-    def run(force: false)
-      if force
-        execute_and_cache
-      elsif @cache.exists?
-        execute_from_cache
-      elsif FixtureKit.configuration.autogenerate
-        execute_and_cache
-      else
-        raise FixtureKit::CacheMissingError, <<~ERROR
-          Cache not found for fixture '#{@fixture_name}'.
+    attr_reader :configuration, :registry
 
-          Run your tests with autogenerate enabled to generate the cache:
-            FixtureKit.configuration.autogenerate = true
+    def initialize
+      @configuration = Configuration.new
+      @registry = Registry.new
+      @isolator = nil
+      @started = false
+    end
 
-          Or generate caches by running your test suite once with autogenerate enabled.
-        ERROR
+    def register(name)
+      registry.add(name).tap do |fixture|
+        fixture.cache if started?
       end
     end
 
-    private
-
-    def execute_and_cache
-      fixture = Registry.fetch(@fixture_name)
-
-      # Start capturing SQL
-      capture = SqlCapture.new
-      capture.start
-
-      # Execute fixture definition - returns exposed records hash
-      exposed = fixture.execute
-
-      # Stop capturing and get affected models with their connections
-      models_with_connections = capture.stop
+    def start
+      raise RunnerAlreadyStartedError, "FixtureKit::Runner has already been started" if started?
+      @started = true
 
-      # Save cache
-      @cache.save(
-        models_with_connections: models_with_connections,
-        exposed_mapping: build_exposed_mapping(exposed)
-      )
-
-      # Return Repository from the exposed records
-      Repository.new(exposed)
+      clear_cache unless preserve_cache?
+      registry.fixtures.each(&:cache)
     end
 
-    def execute_from_cache
-      @cache.load
-
-      # Execute cached SQL statements by model
-      @cache.records.each do |model_name, sql|
-        next if sql.nil? || sql.empty?
-
-        model = ActiveSupport::Inflector.constantize(model_name)
-        connection = model.connection
-        connection.execute(sql)
-      end
+    def isolator
+      @isolator ||= configuration.isolator.new
+    end
 
-      # Query exposed records and build Repository.
-      @cache.build_repository
+    def started?
+      @started
     end
 
-    def build_exposed_mapping(exposed)
-      mapping = {}
+    private
 
-      exposed.each do |name, record_or_records|
-        if record_or_records.is_a?(Array)
-          mapping[name.to_s] = record_or_records.map do |record|
-            { "model" => record.class.name, "id" => record.id }
-          end
-        else
-          record = record_or_records
-          mapping[name.to_s] = { "model" => record.class.name, "id" => record.id }
-        end
-      end
+    def clear_cache
+      FileUtils.rm_rf(configuration.cache_path)
+    end
 
-      mapping
+    def preserve_cache?
+      ENV[PRESERVE_CACHE_ENV_KEY].to_s.match?(/\A(1|true|yes)\z/i)
     end
   end
 end

data/lib/fixture_kit/singleton.rb

@@ -1,35 +1,22 @@
 # frozen_string_literal: true
 
-require "pathname"
-
 module FixtureKit
   module Singleton
     def configure
-      yield(configuration) if block_given?
+      yield(runner.configuration) if block_given?
       self
     end
 
-    def configuration
-      @configuration ||= Configuration.new
+    def runner
+      @runner ||= Runner.new
     end
 
     def define(&block)
-      caller_file = File.expand_path(caller_locations(1, 1).first.path)
-      fixture_path = File.expand_path(configuration.fixture_path)
-
-      # "/abs/path/spec/fixtures/teams/basic.rb" -> "teams/basic"
-      relative_path = Pathname.new(caller_file).relative_path_from(Pathname.new(fixture_path))
-      name = relative_path.to_s.sub(/\.rb$/, "")
-
-      fixture = Fixture.new(name, &block)
-      Registry.register(fixture)
-      fixture
+      Definition.new(&block)
     end
 
     def reset
-      @configuration = nil
-      Registry.reset
-      Cache.clear_memory_cache
+      @runner = nil
     end
   end
 end

data/lib/fixture_kit/sql_subscriber.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require "active_support/inflector"
+
+module FixtureKit
+  class SqlSubscriber
+    EVENT = "sql.active_record"
+    NAME_PATTERN = /\A(?<model_name>.+?) (?:(?:Bulk )?(?:Insert|Upsert)|Create|Destroy|(?:Update|Delete)(?: All)?)\z/
+
+    def self.capture(&block)
+      models = Set.new
+      subscriber = lambda do |_event_name, _start, _finish, _id, payload|
+        name = payload[:name].to_s
+        model_name = name[NAME_PATTERN, :model_name]
+        next unless model_name
+
+        models.add(ActiveSupport::Inflector.constantize(model_name))
+      end
+
+      ActiveSupport::Notifications.subscribed(subscriber, EVENT, monotonic: true, &block)
+
+      models.to_a
+    end
+  end
+end

data/lib/fixture_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FixtureKit
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/fixture_kit.rb

@@ -2,25 +2,26 @@
 
 module FixtureKit
   class Error < StandardError; end
-  class DuplicateFixtureError < Error; end
   class DuplicateNameError < Error; end
   class CacheMissingError < Error; end
-  class PregenerationError < Error; end
   class FixtureDefinitionNotFound < Error; end
   class ExposedRecordNotFound < Error; end
+  class RunnerAlreadyStartedError < Error; end
 
-  autoload :VERSION,         File.expand_path("fixture_kit/version", __dir__)
-  autoload :Configuration,   File.expand_path("fixture_kit/configuration", __dir__)
-  autoload :Singleton,       File.expand_path("fixture_kit/singleton", __dir__)
-  autoload :Fixture,         File.expand_path("fixture_kit/fixture", __dir__)
-  autoload :DefinitionContext, File.expand_path("fixture_kit/definition_context", __dir__)
-  autoload :Registry,        File.expand_path("fixture_kit/registry", __dir__)
-  autoload :Repository,      File.expand_path("fixture_kit/repository", __dir__)
-  autoload :SqlCapture,      File.expand_path("fixture_kit/sql_capture", __dir__)
-  autoload :Cache,           File.expand_path("fixture_kit/cache", __dir__)
-  autoload :Runner,          File.expand_path("fixture_kit/runner", __dir__)
-  autoload :Generator,       File.expand_path("fixture_kit/generator", __dir__)
-  autoload :TestCase,        File.expand_path("fixture_kit/test_case", __dir__)
+  autoload :VERSION,       File.expand_path("fixture_kit/version", __dir__)
+  autoload :Configuration, File.expand_path("fixture_kit/configuration", __dir__)
+  autoload :ConfigurationHelper, File.expand_path("fixture_kit/configuration_helper", __dir__)
+  autoload :Singleton,     File.expand_path("fixture_kit/singleton", __dir__)
+  autoload :Fixture,       File.expand_path("fixture_kit/fixture", __dir__)
+  autoload :Definition,    File.expand_path("fixture_kit/definition", __dir__)
+  autoload :Registry,      File.expand_path("fixture_kit/registry", __dir__)
+  autoload :Repository,    File.expand_path("fixture_kit/repository", __dir__)
+  autoload :SqlSubscriber, File.expand_path("fixture_kit/sql_subscriber", __dir__)
+  autoload :Cache,         File.expand_path("fixture_kit/cache", __dir__)
+  autoload :Runner,        File.expand_path("fixture_kit/runner", __dir__)
+  autoload :Isolator,      File.expand_path("fixture_kit/isolator", __dir__)
+  autoload :MinitestIsolator, File.expand_path("fixture_kit/isolators/minitest_isolator", __dir__)
+  autoload :RSpecIsolator, File.expand_path("fixture_kit/isolators/rspec_isolator", __dir__)
 
   extend Singleton
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fixture_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ngan Pham
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-21 00:00:00.000000000 Z
+date: 2026-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -136,19 +136,19 @@ files:
 - lib/fixture_kit.rb
 - lib/fixture_kit/cache.rb
 - lib/fixture_kit/configuration.rb
-- lib/fixture_kit/definition_context.rb
+- lib/fixture_kit/configuration_helper.rb
+- lib/fixture_kit/definition.rb
 - lib/fixture_kit/fixture.rb
-- lib/fixture_kit/generator.rb
+- lib/fixture_kit/isolator.rb
+- lib/fixture_kit/isolators/minitest_isolator.rb
+- lib/fixture_kit/isolators/rspec_isolator.rb
+- lib/fixture_kit/minitest.rb
 - lib/fixture_kit/registry.rb
 - lib/fixture_kit/repository.rb
 - lib/fixture_kit/rspec.rb
-- lib/fixture_kit/rspec/declaration.rb
-- lib/fixture_kit/rspec/generator.rb
 - lib/fixture_kit/runner.rb
 - lib/fixture_kit/singleton.rb
-- lib/fixture_kit/sql_capture.rb
-- lib/fixture_kit/test_case.rb
-- lib/fixture_kit/test_case/generator.rb
+- lib/fixture_kit/sql_subscriber.rb
 - lib/fixture_kit/version.rb
 homepage: https://github.com/Gusto/fixture_kit
 licenses:

data/lib/fixture_kit/rspec/declaration.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module FixtureKit
-  module RSpec
-    class Declaration
-      attr_reader :name
-
-      def initialize(name)
-        @name = name
-      end
-
-      def fixture_set
-        FixtureKit::Runner.run(name)
-      end
-    end
-  end
-end

data/lib/fixture_kit/rspec/generator.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module FixtureKit
-  module RSpec
-    class Generator < FixtureKit::Generator
-      def run(&block)
-        previous_example = ::RSpec.current_example
-        previous_scope = ::RSpec.current_scope
-        example_group = build_example_group
-        example = build_example(example_group, &block)
-        instance = example_group.new(example.inspect_output)
-        succeeded =
-          begin
-            example.run(instance, ::RSpec::Core::NullReporter)
-          ensure
-            example_group.remove_example(example)
-            ::RSpec.current_example = previous_example
-            ::RSpec.current_scope = previous_scope
-          end
-
-        unless succeeded
-          raise example.exception if example.exception
-          raise FixtureKit::PregenerationError, "FixtureKit pregeneration failed"
-        end
-      end
-
-      private
-
-      def build_example(example_group, &block)
-        example_group.example(
-          "FixtureKit cache pregeneration"
-        ) { block.call }
-      end
-
-      def build_example_group
-        ::RSpec::Core::ExampleGroup.subclass(
-          ::RSpec::Core::ExampleGroup,
-          "FixtureKit::RSpec::Generator",
-          [],
-          []
-        )
-      end
-    end
-  end
-end

data/lib/fixture_kit/sql_capture.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/notifications"
-require "active_support/inflector"
-
-module FixtureKit
-  class SqlCapture
-    SQL_EVENT = "sql.active_record"
-
-    def initialize
-      @models = {}  # { Model => connection }
-      @subscription = nil
-    end
-
-    def start
-      @subscription = ActiveSupport::Notifications.subscribe(SQL_EVENT) do |*, payload|
-        next unless payload[:sql] =~ /\AINSERT INTO/i
-
-        # payload[:name] is like "User Create" - extract model name
-        name = payload[:name]
-        next unless name&.end_with?(" Create")
-
-        model_name = name.sub(/ Create\z/, "")
-        model = ActiveSupport::Inflector.constantize(model_name)
-        @models[model] ||= payload[:connection]
-      rescue NameError
-        # Skip if model can't be found
-      end
-    end
-
-    def stop
-      ActiveSupport::Notifications.unsubscribe(@subscription) if @subscription
-      @subscription = nil
-      @models
-    end
-  end
-end

data/lib/fixture_kit/test_case/generator.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/test_case"
-require "active_record/fixtures"
-
-module FixtureKit
-  module TestCase
-    class Generator < FixtureKit::Generator
-      TEST_METHOD_NAME = "test_fixture_kit_cache_pregeneration"
-
-      def run(&block)
-        result = build_test_class(&block).run
-        return if result.passed?
-
-        failure = result.failures.first
-        raise failure.error if failure.respond_to?(:error)
-        raise failure if failure
-
-        raise FixtureKit::PregenerationError, "FixtureKit pregeneration failed"
-      end
-
-      private
-
-      def build_test_class(&block)
-        Class.new(ActiveSupport::TestCase) do
-          ::Minitest::Runnable.runnables.delete(self)
-          include(::ActiveRecord::TestFixtures)
-
-          define_method(TEST_METHOD_NAME) do
-            block.call
-            pass
-          end
-        end.new(TEST_METHOD_NAME)
-      end
-    end
-  end
-end

data/lib/fixture_kit/test_case.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module FixtureKit
-  module TestCase
-    autoload :Generator, File.expand_path("test_case/generator", __dir__)
-  end
-end