fixture_kit 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88808419ae66dfd1982be86a60e46c0b866e6e509ef50469e912a9906f99892f
-  data.tar.gz: 6a4f8cf65a36c0aff62abc8cf51dbcb58709a083cf30a5699ad1d21533968c44
+  metadata.gz: 2e0215c05b7885a41bf05f4ecd197b5df0d2bec66a8994b9ffe3c5310523d7c2
+  data.tar.gz: 41f8326c8e2b24094d977127da376efcec101471d61a3da009cbb61a8683cce8
 SHA512:
-  metadata.gz: facc136d48b32856bb74f7bae845f0c9cadbf4ef46797ff0a64884b042c9b20383dfb3cfcfdf17f46462b6b46fc1104bcd2e7f111dfd11b1371c055654b32da7
-  data.tar.gz: 72da841bb3e72a48f074c3f03468781e0039af6f417776d354c5249cd33591a232caf09eb408c3810e7a419b8485c6985141e277d7e3128555a185a881453ea1
+  metadata.gz: 5315136c139de91a4d6a7bf325fdd9710a0583928b1f0dccdee0d8584afc9be050083ee174a0ddc3d538650d8509e4fd764731c4e547d5f9dacc2651690a454a
+  data.tar.gz: f7212cae51606a7e9ef8c80f7c27d9a95e6091b02f0873d2786241780bbd2a961d0f94a1e8cb0bc42cdd188276fc56526b2f1cba1136edeba66384824e255ab4

data/README.md

@@ -98,12 +98,14 @@ RSpec.describe Book do
     expect(fixture.books.size).to eq(3)
   end
 
-  it "supports hash-style access" do
-    expect(fixture[:owner]).to eq(fixture.owner)
+  it "exposes records as methods" do
+    expect(fixture.owner.email).to eq("alice@example.com")
   end
 end
 ```
 
+`fixture` returns a `FixtureSet` and exposes records as methods (for example, `fixture.owner`).
+
 ### 3. Configure RSpec
 
 ```ruby
@@ -128,14 +130,25 @@ FixtureKit.configure do |config|
 
   # Whether to regenerate caches on every run (default: true)
   config.autogenerate = true
+
+  # Optional: customize how pregeneration is wrapped.
+  # Default is FixtureKit::TestCase::Generator.
+  # config.generator = FixtureKit::TestCase::Generator
 end
 ```
 
+Custom generators should subclass `FixtureKit::Generator` and implement `#run`.
+`#run` receives the pregeneration block and should execute it in whatever lifecycle you need.
+
 ### Autogenerate
 
 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.
 
-When `autogenerate` is `false`, FixtureKit pre-generates all fixture caches at suite start. This happens in rolled-back transactions so no data persists to the database. Any fixtures that already have caches are skipped. This mode is useful for CI where you want consistent, predictable cache generation.
+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.
+
+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 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.
 
 ### Preserving Cache Locally
 

data/lib/fixture_kit/configuration.rb

@@ -4,11 +4,13 @@ module FixtureKit
   class Configuration
     attr_writer :fixture_path
     attr_writer :cache_path
+    attr_accessor :generator
     attr_accessor :autogenerate
 
     def initialize
       @fixture_path = nil
       @cache_path = nil
+      @generator = FixtureKit::TestCase::Generator
       @autogenerate = true
     end
 

data/lib/fixture_kit/fixture_runner.rb

@@ -27,15 +27,16 @@ module FixtureKit
     end
 
     # Generate cache only (used for pregeneration in before(:suite))
-    # Wraps execution in a transaction that rolls back, so no data persists
+    # 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)
 
-      ActiveRecord::Base.transaction do
+      FixtureKit.configuration.generator.run do
         execute_and_cache
-        raise ActiveRecord::Rollback
       end
 
       true

data/lib/fixture_kit/fixture_set.rb

@@ -4,17 +4,10 @@ module FixtureKit
   class FixtureSet
     def initialize(exposed_records)
       @records = exposed_records
+      @records.each_value { |value| value.freeze if value.is_a?(Array) }
       define_accessors
     end
 
-    def [](name)
-      @records[name.to_sym]
-    end
-
-    def to_h
-      @records.dup
-    end
-
     private
 
     def define_accessors

data/lib/fixture_kit/generator.rb

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

data/lib/fixture_kit/rspec/declaration.rb

@@ -0,0 +1,17 @@
+# 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/rspec/generator.rb

@@ -0,0 +1,45 @@
+# 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/rspec.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 require "fixture_kit"
+require_relative "rspec/declaration"
+require_relative "rspec/generator"
 
 module FixtureKit
   module RSpec
+    DECLARATION_METADATA_KEY = :fixture_kit_declaration
+    PRESERVE_CACHE_ENV_KEY = "FIXTURE_KIT_PRESERVE_CACHE"
+
     # Class methods (extended via config.extend)
     module ClassMethods
       # Declare which fixture to use for this example group.
@@ -26,7 +31,7 @@ module FixtureKit
       #     end
       #   end
       def fixture(name)
-        metadata[:fixture_name] = name.to_s
+        metadata[FixtureKit::RSpec::DECLARATION_METADATA_KEY] = FixtureKit::RSpec::Declaration.new(name)
       end
     end
 
@@ -35,28 +40,33 @@ module FixtureKit
       # Returns the FixtureSet for the current example's fixture.
       # Access exposed records as methods: fixture.alice, fixture.posts
       def fixture
-        @_fixture_loaded ||= begin
-          fixture_name = self.class.metadata[:fixture_name]
-          raise "No fixture declared for this example group. Use `fixture \"name\"` in your describe/context block." unless fixture_name
-
-          FixtureKit::FixtureRegistry.load_fixture(fixture_name)
-        end
+        @_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
+
 # Configure RSpec integration
 RSpec.configure do |config|
   config.extend FixtureKit::RSpec::ClassMethods
   config.include FixtureKit::RSpec::InstanceMethods
 
+  # 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
+
   # 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["FIXTURE_KIT_PRESERVE_CACHE"].to_s.match?(/\A(1|true|yes)\z/i)
+      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

data/lib/fixture_kit/singleton.rb

@@ -5,8 +5,7 @@ require "pathname"
 module FixtureKit
   module Singleton
     def configure
-      @configuration = Configuration.new
-      yield(@configuration) if block_given?
+      yield(configuration) if block_given?
       self
     end
 

data/lib/fixture_kit/test_case/generator.rb

@@ -0,0 +1,37 @@
+# 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

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

data/lib/fixture_kit/version.rb

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

data/lib/fixture_kit.rb

@@ -5,6 +5,7 @@ module FixtureKit
   class DuplicateFixtureError < Error; end
   class DuplicateNameError < Error; end
   class CacheMissingError < Error; end
+  class PregenerationError < Error; end
   class ExposedRecordNotFound < Error; end
 
   autoload :VERSION,         File.expand_path("fixture_kit/version", __dir__)
@@ -17,6 +18,8 @@ module FixtureKit
   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 :TestCase,        File.expand_path("fixture_kit/test_case", __dir__)
 
   extend Singleton
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fixture_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Ngan Pham
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-19 00:00:00.000000000 Z
+date: 2026-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -127,9 +141,14 @@ files:
 - 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/rspec.rb
+- lib/fixture_kit/rspec/declaration.rb
+- lib/fixture_kit/rspec/generator.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/version.rb
 homepage: https://github.com/Gusto/fixture_kit
 licenses: