fixture_kit 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e0215c05b7885a41bf05f4ecd197b5df0d2bec66a8994b9ffe3c5310523d7c2
-  data.tar.gz: 41f8326c8e2b24094d977127da376efcec101471d61a3da009cbb61a8683cce8
+  metadata.gz: 23151d16a20be7d13a1c4a15ce4dca10a2c742ba68a1d43af339bdad65490679
+  data.tar.gz: 1c9da63eae90bbe6843d204d138fafbf3b933f0ea4fd9f42c4108331509f472b
 SHA512:
-  metadata.gz: 5315136c139de91a4d6a7bf325fdd9710a0583928b1f0dccdee0d8584afc9be050083ee174a0ddc3d538650d8509e4fd764731c4e547d5f9dacc2651690a454a
-  data.tar.gz: f7212cae51606a7e9ef8c80f7c27d9a95e6091b02f0873d2786241780bbd2a961d0f94a1e8cb0bc42cdd188276fc56526b2f1cba1136edeba66384824e255ab4
+  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:**
 
@@ -104,7 +104,7 @@ RSpec.describe Book do
 end
 ```
 
-`fixture` returns a `FixtureSet` and exposes records as methods (for example, `fixture.owner`).
+`fixture` returns a `Repository` and exposes records as methods (for example, `fixture.owner`).
 
 ### 3. Configure RSpec
 
@@ -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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "active_support/core_ext/array/wrap"
+require "active_support/inflector"
+
+module FixtureKit
+  class Cache
+    attr_reader :fixture
+
+    def initialize(fixture, definition)
+      @fixture = fixture
+      @definition = definition
+    end
+
+    def path
+      File.join(FixtureKit.configuration.cache_path, "#{fixture.name}.json")
+    end
+
+    def exists?
+      @data || File.exist?(path)
+    end
+
+    def load
+      unless exists?
+        raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{fixture.name}'"
+      end
+
+      @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
+
+      build_repository(@data.fetch("exposed"))
+    end
+
+    def save
+      FixtureKit.configuration.isolator.run do
+        models = SqlSubscriber.capture do
+          @definition.evaluate
+        end
+
+        @data = {
+          "records" => generate_statements(models),
+          "exposed" => build_exposed_mapping(@definition.exposed)
+        }
+      end
+
+      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)
+      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
+      end
+
+      Repository.new(exposed_records)
+    end
+
+    private
+
+    def find_exposed_record(model_name, id, exposed_name)
+      model = ActiveSupport::Inflector.constantize(model_name)
+      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}'"
+    end
+
+    def generate_statements(models)
+      statements_by_model = {}
+
+      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)
+            model.connection.quote(value)
+          end
+          rows << "(#{row_values.join(", ")})"
+        end
+
+        next if rows.empty?
+
+        sql = build_insert_sql(model.table_name, columns, rows, model.connection)
+        statements_by_model[model.name] = sql
+      end
+
+      statements_by_model
+    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)
+    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
+      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/{fixture_context.rb → definition.rb}

@@ -1,23 +1,22 @@
 # frozen_string_literal: true
 
 module FixtureKit
-  class FixtureContext
+  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)
-      @name = name.to_sym
-      @block = block
+    def initialize(name, path)
+      @name = name
+      @path = path
+      @cache = Cache.new(self, definition)
     end
 
-    def execute
-      context = FixtureContext.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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module FixtureKit
+  class Registry
+    def initialize(configuration)
+      @configuration = configuration
+      @registry = {}
+    end
+
+    def add(name)
+      return @registry[name] if @registry.key?(name)
+
+      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
+
+      @registry[name] = Fixture.new(name, file_path)
+    end
+
+    def fixtures
+      @registry.values
+    end
+
+    private
+
+    def fixture_file_path(name)
+      File.expand_path(File.join(@configuration.fixture_path, "#{name}.rb"))
+    end
+  end
+end

data/lib/fixture_kit/{fixture_set.rb → repository.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module FixtureKit
-  class FixtureSet
+  class Repository
     def initialize(exposed_records)
       @records = exposed_records
       @records.each_value { |value| value.freeze if value.is_a?(Array) }

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

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
 require "fixture_kit"
-require_relative "rspec/declaration"
-require_relative "rspec/generator"
 
 module FixtureKit
   module RSpec
+    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
@@ -31,45 +30,38 @@ module FixtureKit
       #     end
       #   end
       def fixture(name)
-        metadata[FixtureKit::RSpec::DECLARATION_METADATA_KEY] = FixtureKit::RSpec::Declaration.new(name)
+        metadata[DECLARATION_METADATA_KEY] = ::RSpec.configuration.fixture_kit.register(name)
       end
     end
 
     # Instance methods (included via config.include)
     module InstanceMethods
-      # Returns the FixtureSet for the current example's fixture.
+      # 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.")
       end
     end
-  end
-end
 
-# Install the RSpec generator by default for this entrypoint.
-FixtureKit.configuration.generator = FixtureKit::RSpec::Generator
+    def self.configure!(config)
+      config.add_setting(:fixture_kit, default: FixtureKit.runner)
+      FixtureKit.configuration.isolator = Isolator
 
-# Configure RSpec integration
-RSpec.configure do |config|
-  config.extend FixtureKit::RSpec::ClassMethods
-  config.include FixtureKit::RSpec::InstanceMethods
+      config.extend ClassMethods
+      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, FixtureKit::RSpec::DECLARATION_METADATA_KEY) do |example|
-    declaration = example.metadata[FixtureKit::RSpec::DECLARATION_METADATA_KEY]
-    @_fixture_kit_fixture_set = declaration.fixture_set
-  end
+      # 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|
+        @_fixture_kit_fixture_set = example.metadata[DECLARATION_METADATA_KEY].mount
+      end
 
-  # Setup caches at suite start based on autogenerate setting
-  # - autogenerate=true: Clear all caches (unless FIXTURE_KIT_PRESERVE_CACHE is set)
-  # - autogenerate=false: Pre-generate all caches so tests don't fail
-  config.before(:suite) do
-    if FixtureKit.configuration.autogenerate
-      preserve_cache = ENV[FixtureKit::RSpec::PRESERVE_CACHE_ENV_KEY].to_s.match?(/\A(1|true|yes)\z/i)
-      FixtureKit::FixtureCache.clear unless preserve_cache
-    else
-      FixtureKit::FixtureCache.pregenerate_all
+      config.append_before(:suite) do
+        config.fixture_kit.start
+      end
     end
   end
 end
+
+# Configure RSpec integration
+FixtureKit::RSpec.configure!(RSpec.configuration)

data/lib/fixture_kit/runner.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module FixtureKit
+  class Runner
+    PRESERVE_CACHE_ENV_KEY = "FIXTURE_KIT_PRESERVE_CACHE"
+
+    attr_reader :configuration, :registry
+
+    def initialize
+      @configuration = Configuration.new
+      @registry = Registry.new(configuration)
+      @started = false
+    end
+
+    def register(name)
+      registry.add(name).tap do |fixture|
+        fixture.cache if started?
+      end
+    end
+
+    def start
+      raise RunnerAlreadyStartedError, "FixtureKit::Runner has already been started" if started?
+      @started = true
+
+      clear_cache unless preserve_cache?
+      registry.fixtures.each(&:cache)
+    end
+
+    def started?
+      @started
+    end
+
+    private
+
+    def clear_cache
+      FileUtils.rm_rf(configuration.cache_path)
+    end
+
+    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)
-      FixtureRegistry.register(fixture)
-      fixture
+    def define(&block)
+      Definition.new(&block)
     end
 
     def reset
-      @configuration = nil
-      FixtureRegistry.reset
-      FixtureCache.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.1.2"
+  VERSION = "0.3.0"
 end

data/lib/fixture_kit.rb

@@ -6,19 +6,21 @@ module FixtureKit
   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 :FixtureContext,  File.expand_path("fixture_kit/fixture_context", __dir__)
-  autoload :FixtureRegistry, File.expand_path("fixture_kit/fixture_registry", __dir__)
-  autoload :FixtureSet,      File.expand_path("fixture_kit/fixture_set", __dir__)
-  autoload :SqlCapture,      File.expand_path("fixture_kit/sql_capture", __dir__)
-  autoload :FixtureCache,    File.expand_path("fixture_kit/fixture_cache", __dir__)
-  autoload :FixtureRunner,   File.expand_path("fixture_kit/fixture_runner", __dir__)
-  autoload :Generator,       File.expand_path("fixture_kit/generator", __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 :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.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Ngan Pham
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-20 00:00:00.000000000 Z
+date: 2026-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -134,21 +134,20 @@ files:
 - LICENSE
 - README.md
 - lib/fixture_kit.rb
+- lib/fixture_kit/cache.rb
 - lib/fixture_kit/configuration.rb
+- lib/fixture_kit/definition.rb
 - lib/fixture_kit/fixture.rb
-- lib/fixture_kit/fixture_cache.rb
-- lib/fixture_kit/fixture_context.rb
-- lib/fixture_kit/fixture_registry.rb
-- lib/fixture_kit/fixture_runner.rb
-- lib/fixture_kit/fixture_set.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/fixture_cache.rb

@@ -1,179 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "fileutils"
-require "active_support/core_ext/array/wrap"
-require "active_support/inflector"
-
-module FixtureKit
-  class FixtureCache
-    # In-memory cache to avoid re-reading/parsing JSON for every test
-    @memory_cache = {}
-
-    class << self
-      attr_accessor :memory_cache
-
-      def clear_memory_cache(fixture_name = nil)
-        if fixture_name
-          @memory_cache.delete(fixture_name.to_s)
-        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
-
-      # Pre-generate caches for all fixtures.
-      # Each fixture is generated in a transaction that rolls back, so no data persists.
-      def pregenerate_all
-        fixture_path = FixtureKit.configuration.fixture_path
-
-        # First, load all fixture files to register them
-        FixtureRegistry.load_definitions(fixture_path)
-
-        # Then iterate over the registry and generate caches
-        FixtureRegistry.all_names.each do |name|
-          runner = FixtureRunner.new(name)
-          runner.generate_cache_only
-        end
-      end
-    end
-
-    attr_reader :records, :exposed
-
-    def initialize(fixture_name)
-      @fixture_name = fixture_name.to_s
-      @records = {}
-      @exposed = {}
-    end
-
-    def cache_file_path
-      cache_path = FixtureKit.configuration.cache_path
-      File.join(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)
-    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
-      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
-
-      true
-    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
-      }
-
-      # Store in memory cache
-      self.class.memory_cache[@fixture_name] = data
-
-      File.write(cache_file_path, JSON.pretty_generate(data))
-    end
-
-    # Query exposed records from the database and return a FixtureSet
-    def build_fixture_set
-      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
-      end
-
-      FixtureSet.new(exposed_records)
-    end
-
-    private
-
-    def find_exposed_record(model_name, id, exposed_name)
-      model = ActiveSupport::Inflector.constantize(model_name)
-      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}'"
-    end
-
-    def generate_statements(models_with_connections)
-      statements_by_model = {}
-
-      models_with_connections.each do |model, connection|
-        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)
-          end
-          rows << "(#{row_values.join(", ")})"
-        end
-
-        next if rows.empty?
-
-        sql = build_insert_sql(model.table_name, columns, rows, connection)
-        statements_by_model[model.name] = sql
-      end
-
-      statements_by_model
-    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)
-    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
-      end
-    end
-  end
-end

data/lib/fixture_kit/fixture_registry.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module FixtureKit
-  module FixtureRegistry
-    class << self
-      def register(fixture)
-        fixtures[fixture.name.to_s] = fixture
-      end
-
-      def find(name)
-        fixtures[name.to_s]
-      end
-
-      def all_names
-        fixtures.keys
-      end
-
-      # Load all fixture definition files from the given path.
-      # 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)
-        Dir.glob(File.join(fixture_path, "**/*.rb")).each do |file|
-          load file
-        end
-      end
-
-      def reset
-        @fixtures = nil
-      end
-
-      # Load a fixture's records into the database and return a FixtureSet.
-      # Uses cached INSERT statements if available, otherwise executes fixture and caches.
-      def load_fixture(name)
-        name = name.to_s
-
-        # Load the file on-demand if fixture not yet registered
-        unless find(name)
-          fixture_path = FixtureKit.configuration.fixture_path
-          file_path = File.expand_path(File.join(fixture_path, "#{name}.rb"))
-          load file_path
-        end
-
-        runner = FixtureRunner.new(name)
-        runner.run
-      end
-
-      private
-
-      def fixtures
-        @fixtures ||= {}
-      end
-    end
-  end
-end

data/lib/fixture_kit/fixture_runner.rb

@@ -1,104 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/inflector"
-
-module FixtureKit
-  class FixtureRunner
-    def initialize(fixture_name)
-      @fixture_name = fixture_name.to_sym
-      @cache = FixtureCache.new(@fixture_name)
-    end
-
-    def run
-      if @cache.exists?
-        execute_from_cache
-      elsif FixtureKit.configuration.autogenerate
-        execute_and_cache
-      else
-        raise FixtureKit::CacheMissingError, <<~ERROR
-          Cache not found for fixture '#{@fixture_name}'.
-
-          Run your tests with autogenerate enabled to generate the cache:
-            FixtureKit.configuration.autogenerate = true
-
-          Or generate caches by running your test suite once with autogenerate enabled.
-        ERROR
-      end
-    end
-
-    # Generate cache only (used for pregeneration in before(:suite))
-    # Wraps execution in the configured generator lifecycle.
-    # The default generator uses ActiveRecord::TestFixtures transactions.
-    # Entry points (like `fixture_kit/rspec`) can install richer generators.
-    # Always regenerates the cache, even if one exists
-    def generate_cache_only
-      # Clear any existing cache for this fixture
-      FixtureCache.clear(@fixture_name.to_s)
-
-      FixtureKit.configuration.generator.run do
-        execute_and_cache
-      end
-
-      true
-    end
-
-    private
-
-    def execute_and_cache
-      fixture = FixtureRegistry.find(@fixture_name)
-      raise ArgumentError, "Fixture '#{@fixture_name}' not found" unless fixture
-
-      # 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
-
-      # Save cache
-      @cache.save(
-        models_with_connections: models_with_connections,
-        exposed_mapping: build_exposed_mapping(exposed)
-      )
-
-      # Return FixtureSet from the exposed records
-      FixtureSet.new(exposed)
-    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 FixtureSet
-      @cache.build_fixture_set
-    end
-
-    def build_exposed_mapping(exposed)
-      mapping = {}
-
-      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
-
-      mapping
-    end
-  end
-end

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.to_s
-      end
-
-      def fixture_set
-        FixtureKit::FixtureRegistry.load_fixture(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