fixture_kit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 311fd09f37153fae9d8a09e3e41357c38f18e1e343794a758ae943dfdca3c40a
-  data.tar.gz: ee4257fc3c840f809a25204f300c766f872688c5c7417dc22155f001ba424882
+  metadata.gz: 23151d16a20be7d13a1c4a15ce4dca10a2c742ba68a1d43af339bdad65490679
+  data.tar.gz: 1c9da63eae90bbe6843d204d138fafbf3b933f0ea4fd9f42c4108331509f472b
 SHA512:
-  metadata.gz: bd8c58de66c08eeceab67e4f0b83a8a95d25291401272e96b51725db2b7a9f2b2592c24f1d6f6cb7b4f6b4716fa93fc768c4fc81afcf1974b9339e14b1b61fa9
-  data.tar.gz: 8d335927771e40d35142a69ee9bf911fcfb6c660af6cde28269a16643e86a468c017cf2f54e362f09d90a78bfeffe6320071d0230f6240969fc495de0e91c8f2
+  metadata.gz: 3b75d5d28b153bb082f8097309c39c6d350633faac76e1b30e5ea7413cf3bccfa9b93a3941f6eff607306f43cd53a7bc5420fd1d331fc99c66ede324f82e3902
+  data.tar.gz: 92d48a55f2a92f4f1673a890e9bba8ce6695204b7a020e3240a9db21217747c3d0f7446297706cc634a15ea3246e29d0b0adcad870152cd449056c67b75cae45

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,6 +117,8 @@ RSpec.configure do |config|
 end
 ```
 
+When you call `fixture "name"` in an example group, FixtureKit registers that fixture with its runner.
+
 ## Configuration
 
 ```ruby
@@ -128,27 +130,35 @@ FixtureKit.configure do |config|
   # 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::TestCase::Isolator)
+  # config.isolator = FixtureKit::TestCase::Isolator
+  # config.isolator = FixtureKit::RSpec::Isolator
 
-  # Optional: customize how pregeneration is wrapped.
-  # Default is FixtureKit::TestCase::Generator.
-  # config.generator = FixtureKit::TestCase::Generator
+  # Optional callback, called once when a fixture cache is first generated.
+  # 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::TestCase::Isolator`, which runs generation inside an internal `ActiveSupport::TestCase` and removes that harness case from minitest runnables.
 
-### Autogenerate
+When using `fixture_kit/rspec`, FixtureKit sets `FixtureKit::RSpec::Isolator`. It runs generation inside an internal RSpec example, and uses a null reporter so harness runs do not count toward suite example totals.
 
-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.
+## Lifecycle
 
-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.
+Fixture generation is managed by `FixtureKit::Runner`.
 
-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.
+With `fixture_kit/rspec`:
 
-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.
+1. `fixture "name"` registers the fixture with the runner during spec file load.
+2. In `before(:suite)`, runner `start`:
+   - clears `cache_path` (unless preserve-cache is enabled),
+   - generates caches for all already-registered fixtures.
+3. If new spec files are loaded later (for example, queue-mode CI runners), newly registered fixtures are generated immediately because the runner has already started.
+4. At example runtime, fixture mounting loads from cache.
 
 ### Preserving Cache Locally
 
@@ -158,19 +168,9 @@ If you want to skip cache clearing at suite start (e.g., to reuse caches across
 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,11 +189,11 @@ 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 inserted models, queries those model tables, and generates batch INSERT statements with conflict handling (`INSERT OR IGNORE` for SQLite, `ON CONFLICT DO NOTHING` for PostgreSQL, `INSERT IGNORE` for MySQL).
 
-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 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.
 
@@ -216,7 +216,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 +225,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,54 @@ require "active_support/inflector"
 
 module FixtureKit
   class Cache
-    # In-memory cache to avoid re-reading/parsing JSON for every test
-    @memory_cache = {}
+    attr_reader :fixture
 
-    class << self
-      attr_accessor :memory_cache
-
-      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
+    def initialize(fixture, definition)
+      @fixture = fixture
+      @definition = definition
     end
 
-    attr_reader :records, :exposed
-
-    def initialize(fixture_name)
-      @fixture_name = fixture_name
-      @records = {}
-      @exposed = {}
-    end
-
-    def cache_file_path
-      cache_path = FixtureKit.configuration.cache_path
-      File.join(cache_path, "#{@fixture_name}.json")
+    def path
+      File.join(FixtureKit.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)
+        model.connection.execute(sql)
+      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.configuration.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,27 +70,27 @@ 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 = build_insert_sql(model.table_name, columns, rows, model.connection)
         statements_by_model[model.name] = sql
       end
 
@@ -175,5 +120,13 @@ module FixtureKit
         sql
       end
     end
+
+    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
 end

data/lib/fixture_kit/configuration.rb

@@ -4,14 +4,14 @@ 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
       @cache_path = nil
-      @generator = FixtureKit::TestCase::Generator
-      @autogenerate = true
+      @isolator = FixtureKit::TestCase::Isolator
+      @on_cache = nil
     end
 
     def fixture_path

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,38 @@
 
 module FixtureKit
   class Fixture
-    attr_reader :name, :block
+    attr_reader :name, :path
 
-    def initialize(name, &block)
+    def initialize(name, path)
       @name = name
-      @block = block
+      @path = path
+      @cache = Cache.new(self, definition)
     end
 
-    def execute
-      context = DefinitionContext.new
-      context.instance_eval(&block) if block
-      context.exposed
+    def cache(force: false)
+      already_cached = @cache.exists?
+      return if already_cached && !force
+
+      @cache.save
+      FixtureKit.configuration.on_cache&.call(name) unless already_cached
+    end
+
+    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/registry.rb

@@ -1,58 +1,34 @@
 # 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
+    def initialize(configuration)
+      @configuration = configuration
+      @registry = {}
+    end
 
-      def fixtures
-        registry.values
-      end
+    def add(name)
+      return @registry[name] if @registry.key?(name)
 
-      def register(fixture)
-        registry[fixture.name] = 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 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
-      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/{generator.rb → isolator.rb}

@@ -2,7 +2,7 @@
 
 module FixtureKit
   module RSpec
-    class Generator < FixtureKit::Generator
+    class Isolator < FixtureKit::Isolator
       def run(&block)
         previous_example = ::RSpec.current_example
         previous_scope = ::RSpec.current_scope
@@ -35,7 +35,7 @@ module FixtureKit
       def build_example_group
         ::RSpec::Core::ExampleGroup.subclass(
           ::RSpec::Core::ExampleGroup,
-          "FixtureKit::RSpec::Generator",
+          "FixtureKit::RSpec::Isolator",
           [],
           []
         )

data/lib/fixture_kit/rspec.rb

@@ -4,11 +4,9 @@ require "fixture_kit"
 
 module FixtureKit
   module RSpec
-    autoload :Declaration, File.expand_path("rspec/declaration", __dir__)
-    autoload :Generator, File.expand_path("rspec/generator", __dir__)
+    autoload :Isolator, File.expand_path("rspec/isolator", __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 +30,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
 
@@ -46,41 +44,22 @@ module FixtureKit
     end
 
     def self.configure!(config)
-      FixtureKit.configuration.generator = Generator
+      config.add_setting(:fixture_kit, default: FixtureKit.runner)
+      FixtureKit.configuration.isolator = Isolator
+
       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_fixture_set = 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,45 @@
 # 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(configuration)
+      @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
-
-      # 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,26 @@
 # 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
+      runner.configuration
     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$/, "")
+    def runner
+      @runner ||= Runner.new
+    end
 
-      fixture = Fixture.new(name, &block)
-      Registry.register(fixture)
-      fixture
+    def define(&block)
+      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,29 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require "active_support/inflector"
+
+module FixtureKit
+  class SqlSubscriber
+    EVENT = "sql.active_record"
+
+    def self.capture(&block)
+      models = Set.new
+      subscriber = lambda do |_event_name, _start, _finish, _id, payload|
+        sql = payload[:sql]
+        next unless 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/, "")
+        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/test_case/{generator.rb → isolator.rb}

@@ -5,7 +5,7 @@ require "active_record/fixtures"
 
 module FixtureKit
   module TestCase
-    class Generator < FixtureKit::Generator
+    class Isolator < FixtureKit::Isolator
       TEST_METHOD_NAME = "test_fixture_kit_cache_pregeneration"
 
       def run(&block)

data/lib/fixture_kit/test_case.rb

@@ -2,6 +2,6 @@
 
 module FixtureKit
   module TestCase
-    autoload :Generator, File.expand_path("test_case/generator", __dir__)
+    autoload :Isolator, File.expand_path("test_case/isolator", __dir__)
   end
 end

data/lib/fixture_kit/version.rb

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

data/lib/fixture_kit.rb

@@ -8,18 +8,19 @@ module FixtureKit
   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 :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 :SqlCapture,      File.expand_path("fixture_kit/sql_capture", __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 :Generator,       File.expand_path("fixture_kit/generator", __dir__)
+  autoload :Isolator,       File.expand_path("fixture_kit/isolator", __dir__)
   autoload :TestCase,        File.expand_path("fixture_kit/test_case", __dir__)
 
   extend Singleton

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fixture_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ngan Pham
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-21 00:00:00.000000000 Z
+date: 2026-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -136,19 +136,18 @@ files:
 - lib/fixture_kit.rb
 - lib/fixture_kit/cache.rb
 - lib/fixture_kit/configuration.rb
-- lib/fixture_kit/definition_context.rb
+- lib/fixture_kit/definition.rb
 - lib/fixture_kit/fixture.rb
-- lib/fixture_kit/generator.rb
+- lib/fixture_kit/isolator.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/rspec/isolator.rb
 - lib/fixture_kit/runner.rb
 - lib/fixture_kit/singleton.rb
-- lib/fixture_kit/sql_capture.rb
+- lib/fixture_kit/sql_subscriber.rb
 - lib/fixture_kit/test_case.rb
-- lib/fixture_kit/test_case/generator.rb
+- lib/fixture_kit/test_case/isolator.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/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