fixture_kit 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c052323f7423cfeb258b137bc8372833eff2f4c8b826b3fa22b25a171b2b2c0f
-  data.tar.gz: '0728daee8814033465d2b93a67e15a00eff4abe5543967167077f81e68db7dde'
+  metadata.gz: 9c4966344ca2fed5d11b47404694babb874ee5ac505ed64fda79acab147b4230
+  data.tar.gz: da1b34e717a3e6aa1b776b6be68e71c104d28612b879daf1b63c30a0b83244e0
 SHA512:
-  metadata.gz: 82149fa2c3598b2af00b2cd9b8e3691e8694f18bdc40a0abf3a47540e7c319e0821250bec0e3dce4d8aaf692ea614a17cda09970a476503b0280c7a301b95e2f
-  data.tar.gz: f4fe1ea329c354aee57ad6f53d22682309b8db9704340f52d18c4b01b42a83a47701d36fe11e739d644e13b72d02171190a530df6847386770a5edc6b786cbf2
+  metadata.gz: 8d127ec7c68e6839bda857231d2fe0f70263d208aad9615834cad70e47ea2cbecd3b270dea7f795d02452a72b0f155694b3c6e78eb589349a639e7158bfcf902
+  data.tar.gz: 69149bc49f370405cd89043eced96984cc4a3a3efa3e85ce3e45ba15a4859db3805862b14ebfb7171a7b88059d52e1479b201fbb2ee582b379be6c8ef2de9830

data/README.md

@@ -10,7 +10,7 @@ Test data setup is slow. Every `Model.create!` or `FactoryBot.create` hits the d
 
 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.
+Combined with framework transactions (`use_transactional_fixtures` in RSpec, `use_transactional_tests` in Minitest), each test runs in a transaction that rolls back, so cached data can be reused safely between tests.
 
 ## Installation
 
@@ -162,29 +162,39 @@ 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
 
-  # Wrapper used to isolate generation work (default: FixtureKit::MinitestIsolator)
-  # config.isolator = FixtureKit::MinitestIsolator
-  # config.isolator = FixtureKit::RSpecIsolator
+  # Adapter used to isolate generation work (default: FixtureKit::MinitestAdapter)
+  # config.adapter(FixtureKit::MinitestAdapter)
+  # config.adapter(FixtureKit::RSpecAdapter)
+  # config.adapter(CustomAdapter, option1: "value1")
+  #
+  # Calling `adapter` with args sets adapter class + options.
+  # Calling `adapter` with no args returns the configured adapter class.
 
   # Optional callback, called right before a fixture cache is generated.
   # Called on first generation and forced regeneration.
-  # Receives the fixture identifier:
-  # - named fixtures: String (e.g. "teams/basic")
-  # - anonymous fixtures: scope class
+  # Receives the cache identifier as a String (path-like, without ".json").
+  # - named fixtures: "teams/basic"
+  # - anonymous fixtures: "_anonymous/foo/with_fixture_kit/hello"
   # config.on_cache_save = ->(identifier) { puts "cached #{identifier}" }
 
   # Optional callback, called right before a fixture cache is mounted.
-  # Receives the same fixture identifier shape as on_cache_save.
+  # Receives the same String cache identifier as on_cache_save.
   # config.on_cache_mount = ->(identifier) { puts "mounted #{identifier}" }
 end
 ```
 
-Custom isolators should subclass `FixtureKit::Isolator` and implement `#run`.
-`#run` receives the generation block and should execute it in whatever lifecycle you need.
+Custom adapters should subclass `FixtureKit::Adapter` and implement:
+- `#execute`
+- `#identifier_for`
 
-By default, FixtureKit uses `FixtureKit::MinitestIsolator`, which runs generation inside an internal `ActiveSupport::TestCase` and removes that harness case from minitest runnables.
+`#execute` receives the generation block and should run it in whatever lifecycle you need.
+`#identifier_for` receives a non-string fixture identifier (for anonymous fixtures) and must return a normalized String identifier. Cache namespace/prefixing is applied by `FixtureKit::Cache`.
 
-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.
+Options passed via `config.adapter(...)` are provided to your adapter initializer as a hash and available as `options`.
+
+By default, FixtureKit uses `FixtureKit::MinitestAdapter`, which runs generation inside an internal `ActiveSupport::TestCase` and removes that harness case from minitest runnables.
+
+When using `fixture_kit/rspec`, FixtureKit sets `FixtureKit::RSpecAdapter`. It runs generation inside an internal RSpec example, and uses a null reporter so harness runs do not count toward suite example totals.
 
 ## Lifecycle
 
@@ -192,15 +202,16 @@ Fixture generation is managed by `FixtureKit::Runner`.
 
 1. Calling `fixture "name"` or `fixture do ... end` 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.
+   - clears `cache_path` (unless preserve-cache is enabled).
+3. Cache generation is framework-driven:
+   - RSpec: each declaring example group runs `fixture.cache` in `before(:context)`.
+   - Minitest: each declaring test class runs `fixture.cache` in class-level `run_suite` before test methods execute.
 4. At test runtime, `fixture` mounts from cache and returns a `Repository`.
 
 When runner start happens:
 
 - `fixture_kit/rspec`: in `before(:suite)`.
-- `fixture_kit/minitest`: lazily during test setup for the first test class that declares `fixture`.
+- `fixture_kit/minitest`: in class-level `run_suite` for test classes that declare `fixture`.
 
 ## Fixture Declaration Rules
 
@@ -239,6 +250,7 @@ fixture "teams/sales"
 ## Anonymous Fixture Cache Paths
 
 Anonymous fixture caches are written under the `_anonymous/` directory inside `cache_path`.
+That `_anonymous/...` value is also the cache identifier passed to `on_cache_save` and `on_cache_mount`.
 
 - Minitest: class name is underscored into a path.
   - `MyFeatureTest` -> `_anonymous/my_feature_test.json`
@@ -247,7 +259,7 @@ Anonymous fixture caches are written under the `_anonymous/` directory inside `c
 
 ## How It Works
 
-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 SQL statements for current table contents.
+1. **Cache generation**: FixtureKit executes your definition block inside the configured adapter, subscribes to `sql.active_record` notifications to track model writes (`Insert`, `Upsert`, `Create`, `Update`, `Delete`, `Destroy`, including bulk variants), queries those model tables, and caches SQL statements for current table contents.
 
 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.
 
@@ -273,7 +285,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.
+- **records**: Maps model names to their INSERT statements (or `null` when a tracked table is empty). 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.
 
 ## Cache Management

data/lib/fixture_kit/adapter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class Adapter
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = options
+    end
+
+    def execute
+      raise NotImplementedError, "#{self.class} must implement #execute"
+    end
+
+    def identifier_for(_identifier)
+      raise NotImplementedError, "#{self.class} must implement #identifier_for"
+    end
+  end
+end

data/lib/fixture_kit/{isolators/minitest_isolator.rb → adapters/minitest_adapter.rb}

@@ -2,12 +2,13 @@
 
 require "active_support/test_case"
 require "active_record/fixtures"
+require "active_support/inflector"
 
 module FixtureKit
-  class MinitestIsolator < FixtureKit::Isolator
+  class MinitestAdapter < FixtureKit::Adapter
     TEST_NAME = "fixture kit cache pregeneration"
 
-    def run(&block)
+    def execute(&block)
       test_class = build_test_class
       test_method = test_class.test(TEST_NAME) do
         block.call
@@ -20,6 +21,10 @@ module FixtureKit
       raise result.failures.first.error
     end
 
+    def identifier_for(identifier)
+      ActiveSupport::Inflector.underscore(identifier.to_s)
+    end
+
     private
 
     def build_test_class

data/lib/fixture_kit/{isolators/rspec_isolator.rb → adapters/rspec_adapter.rb}

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "active_support/inflector"
+
 module FixtureKit
-  class RSpecIsolator < FixtureKit::Isolator
-    def run(&block)
+  class RSpecAdapter < FixtureKit::Adapter
+    def execute(&block)
       previous_example = ::RSpec.current_example
       previous_scope = ::RSpec.current_scope
       example_group = build_example_group
@@ -19,6 +21,11 @@ module FixtureKit
       raise example.exception unless succeeded
     end
 
+    def identifier_for(identifier)
+      normalized_scope = identifier.to_s.sub(/\ARSpec::ExampleGroups::/, "")
+      ActiveSupport::Inflector.underscore(normalized_scope)
+    end
+
     private
 
     def build_example_group

data/lib/fixture_kit/cache.rb

@@ -27,8 +27,7 @@ module FixtureKit
         if raw_identifier.is_a?(String)
           raw_identifier
         else
-          normalized_scope = raw_identifier.to_s.sub(/\ARSpec::ExampleGroups::/, "")
-          File.join(ANONYMOUS_DIRECTORY, ActiveSupport::Inflector.underscore(normalized_scope))
+          File.join(ANONYMOUS_DIRECTORY, FixtureKit.runner.adapter.identifier_for(raw_identifier))
         end
       end
     end
@@ -43,13 +42,11 @@ module FixtureKit
       end
 
       @data ||= JSON.parse(File.read(path))
-      @data.fetch("records").each do |model_name, sql|
-        model = ActiveSupport::Inflector.constantize(model_name)
-        connection = model.connection
+      statements_by_connection(@data.fetch("records")).each do |connection, statements|
         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")
+          connection.__send__(:execute_batch, statements, "FixtureKit Load")
         end
       end
 
@@ -57,7 +54,7 @@ module FixtureKit
     end
 
     def save
-      FixtureKit.runner.isolator.run do
+      FixtureKit.runner.adapter.execute do
         models = SqlSubscriber.capture do
           fixture.definition.evaluate
         end
@@ -133,5 +130,15 @@ module FixtureKit
         hash[name] = was_array ? records : records.first
       end
     end
+
+    def statements_by_connection(records)
+      records.each_with_object({}) do |(model_name, sql), grouped|
+        model = ActiveSupport::Inflector.constantize(model_name)
+        connection = model.connection
+        grouped[connection] ||= []
+        grouped[connection] << build_delete_sql(model)
+        grouped[connection] << sql if sql
+      end
+    end
   end
 end

data/lib/fixture_kit/configuration.rb

@@ -4,14 +4,15 @@ module FixtureKit
   class Configuration
     attr_writer :fixture_path
     attr_writer :cache_path
-    attr_accessor :isolator
     attr_accessor :on_cache_save
     attr_accessor :on_cache_mount
+    attr_reader :adapter_options
 
     def initialize
       @fixture_path = "fixture_kit"
       @cache_path = nil
-      @isolator = FixtureKit::MinitestIsolator
+      @adapter_class = FixtureKit::MinitestAdapter
+      @adapter_options = {}
       @on_cache_save = nil
       @on_cache_mount = nil
     end
@@ -24,6 +25,13 @@ module FixtureKit
       @cache_path ||= detect_cache_path
     end
 
+    def adapter(adapter_class = nil, **options)
+      return @adapter_class if adapter_class.nil? && options.empty?
+
+      @adapter_class = adapter_class
+      @adapter_options = options
+    end
+
     private
 
     def detect_cache_path

data/lib/fixture_kit/minitest.rb

@@ -11,6 +11,17 @@ module FixtureKit
       def fixture(name = nil, &definition_block)
         self.fixture_kit_declaration = FixtureKit.runner.register(self, name, &definition_block)
       end
+
+      def run_suite(reporter, options = {})
+        declaration = fixture_kit_declaration
+        if declaration && !filter_runnable_methods(options).empty?
+          runner = FixtureKit.runner
+          runner.start unless runner.started?
+          declaration.cache
+        end
+
+        super
+      end
     end
 
     module InstanceMethods
@@ -21,7 +32,7 @@ module FixtureKit
 
     def self.configure!(test_case)
       FixtureKit.runner.configuration.fixture_path = "test/fixture_kit"
-      FixtureKit.runner.configuration.isolator = FixtureKit::MinitestIsolator
+      FixtureKit.runner.configuration.adapter(FixtureKit::MinitestAdapter)
 
       test_case.class_attribute DECLARATION_CLASS_ATTRIBUTE, instance_accessor: false
       test_case.extend ClassMethods
@@ -31,7 +42,6 @@ module FixtureKit
         declaration = self.class.fixture_kit_declaration
         next unless declaration
 
-        FixtureKit.runner.start unless FixtureKit.runner.started?
         @_fixture_kit_repository = declaration.mount
       end
     end

data/lib/fixture_kit/rspec.rb

@@ -28,7 +28,12 @@ module FixtureKit
       #     end
       #   end
       def fixture(name = nil, &definition_block)
-        metadata[DECLARATION_METADATA_KEY] = ::RSpec.configuration.fixture_kit.register(self, name, &definition_block)
+        declaration = ::RSpec.configuration.fixture_kit.register(self, name, &definition_block)
+        metadata[DECLARATION_METADATA_KEY] = declaration
+
+        prepend_before(:context) do
+          self.class.metadata[DECLARATION_METADATA_KEY].cache
+        end
       end
     end
 
@@ -42,9 +47,9 @@ module FixtureKit
     end
 
     def self.configure!(config)
-      FixtureKit.runner.configuration.fixture_path = "spec/fixture_kit"
       config.add_setting(:fixture_kit, default: FixtureKit.runner)
-      FixtureKit.runner.configuration.isolator = FixtureKit::RSpecIsolator
+      FixtureKit.runner.configuration.fixture_path = "spec/fixture_kit"
+      FixtureKit.runner.configuration.adapter(FixtureKit::RSpecAdapter)
 
       config.extend ClassMethods
       config.include InstanceMethods, DECLARATION_METADATA_KEY

data/lib/fixture_kit/runner.rb

@@ -11,14 +11,12 @@ module FixtureKit
     def initialize
       @configuration = Configuration.new
       @registry = Registry.new
-      @isolator = nil
+      @adapter = nil
       @started = false
     end
 
     def register(scope, name = nil, &definition_block)
-      registry.add(scope, normalize_registration(name, definition_block)).tap do |fixture|
-        fixture.cache if started?
-      end
+      registry.add(scope, normalize_registration(name, definition_block))
     end
 
     def start
@@ -26,11 +24,10 @@ module FixtureKit
       @started = true
 
       clear_cache unless preserve_cache?
-      registry.fixtures.each(&:cache)
     end
 
-    def isolator
-      @isolator ||= configuration.isolator.new
+    def adapter
+      @adapter ||= configuration.adapter.new(configuration.adapter_options)
     end
 
     def started?

data/lib/fixture_kit/version.rb

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

data/lib/fixture_kit.rb

@@ -21,9 +21,9 @@ module FixtureKit
   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__)
+  autoload :Adapter,       File.expand_path("fixture_kit/adapter", __dir__)
+  autoload :MinitestAdapter, File.expand_path("fixture_kit/adapters/minitest_adapter", __dir__)
+  autoload :RSpecAdapter,  File.expand_path("fixture_kit/adapters/rspec_adapter", __dir__)
 
   extend Singleton
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fixture_kit
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ngan Pham
@@ -134,14 +134,14 @@ files:
 - LICENSE
 - README.md
 - lib/fixture_kit.rb
+- lib/fixture_kit/adapter.rb
+- lib/fixture_kit/adapters/minitest_adapter.rb
+- lib/fixture_kit/adapters/rspec_adapter.rb
 - lib/fixture_kit/cache.rb
 - lib/fixture_kit/configuration.rb
 - lib/fixture_kit/configuration_helper.rb
 - lib/fixture_kit/definition.rb
 - lib/fixture_kit/fixture.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

data/lib/fixture_kit/isolator.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-module FixtureKit
-  # Base class for fixture cache isolators.
-  class Isolator
-    def self.run(&block)
-      new.run(&block)
-    end
-
-    def run
-      raise NotImplementedError, "#{self.class} must implement #run"
-    end
-  end
-end