fixture_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88808419ae66dfd1982be86a60e46c0b866e6e509ef50469e912a9906f99892f
+  data.tar.gz: 6a4f8cf65a36c0aff62abc8cf51dbcb58709a083cf30a5699ad1d21533968c44
+SHA512:
+  metadata.gz: facc136d48b32856bb74f7bae845f0c9cadbf4ef46797ff0a64884b042c9b20383dfb3cfcfdf17f46462b6b46fc1104bcd2e7f111dfd11b1371c055654b32da7
+  data.tar.gz: 72da841bb3e72a48f074c3f03468781e0039af6f417776d354c5249cd33591a232caf09eb408c3810e7a419b8485c6985141e277d7e3128555a185a881453ea1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,229 @@
+# FixtureKit
+
+Fast test fixtures with SQL caching.
+
+## The Problem
+
+Test data setup is slow. Every `Model.create!` or `FactoryBot.create` hits the database, and complex test scenarios can require dozens of inserts per test.
+
+## 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.
+
+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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+group :test do
+  gem "fixture_kit"
+end
+```
+
+## Quick Start
+
+### 1. Define a Fixture
+
+Create fixture files in `spec/fixture_kit/`. Use whatever method you prefer to create records—FixtureKit doesn't care.
+
+**Using ActiveRecord directly:**
+
+```ruby
+# spec/fixture_kit/bookstore.rb
+FixtureKit.define do
+  store = Store.create!(name: "Powell's Books")
+  owner = User.create!(name: "Alice", email: "alice@example.com", store: store)
+
+  books = 3.times.map do |i|
+    Book.create!(title: "Book #{i + 1}", store: store)
+  end
+
+  featured = Book.create!(title: "Dune", store: store, featured: true)
+
+  expose(store: store, owner: owner, books: books, featured: featured)
+end
+```
+
+**Using FactoryBot:**
+
+```ruby
+# spec/fixture_kit/bookstore.rb
+FixtureKit.define do
+  store = FactoryBot.create(:store, name: "Powell's Books")
+  owner = FactoryBot.create(:user, :admin, store: store)
+  books = FactoryBot.create_list(:book, 3, store: store)
+  featured = FactoryBot.create(:book, :bestseller, store: store, title: "Dune")
+
+  expose(store: store, owner: owner, books: books, featured: featured)
+end
+```
+
+The filename determines the fixture name—no need to pass a name to `define`.
+
+You can call `expose` multiple times to organize your setup code:
+
+```ruby
+FixtureKit.define do
+  # Set up users
+  admin = User.create!(name: "Admin", role: "admin")
+  member = User.create!(name: "Member", role: "member")
+  expose(admin: admin, member: member)
+
+  # Set up projects
+  project = Project.create!(name: "Website", owner: admin)
+  expose(project: project)
+
+  # Set up tasks
+  tasks = 3.times.map { |i| Task.create!(title: "Task #{i + 1}", project: project) }
+  expose(tasks: tasks)
+end
+```
+
+Exposing the same name twice raises `FixtureKit::DuplicateNameError`.
+
+### 2. Use in Tests
+
+```ruby
+# spec/models/book_spec.rb
+RSpec.describe Book do
+  fixture "bookstore"
+
+  it "belongs to a store" do
+    expect(fixture.featured.store).to eq(fixture.store)
+  end
+
+  it "has multiple books" do
+    expect(fixture.books.size).to eq(3)
+  end
+
+  it "supports hash-style access" do
+    expect(fixture[:owner]).to eq(fixture.owner)
+  end
+end
+```
+
+### 3. Configure RSpec
+
+```ruby
+# spec/rails_helper.rb
+require "fixture_kit/rspec"
+
+RSpec.configure do |config|
+  config.use_transactional_fixtures = true
+end
+```
+
+## Configuration
+
+```ruby
+# spec/support/fixture_kit.rb
+FixtureKit.configure do |config|
+  # Where fixture definitions live (default: spec/fixture_kit)
+  config.fixture_path = Rails.root.join("spec/fixture_kit").to_s
+
+  # Where cache files are stored (default: tmp/cache/fixture_kit)
+  config.cache_path = Rails.root.join("tmp/cache/fixture_kit").to_s
+
+  # Whether to regenerate caches on every run (default: true)
+  config.autogenerate = true
+end
+```
+
+### 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.
+
+### Preserving Cache Locally
+
+If you want to skip cache clearing at suite start (e.g., to reuse caches across test runs during local development), set the `FIXTURE_KIT_PRESERVE_CACHE` environment variable:
+
+```bash
+FIXTURE_KIT_PRESERVE_CACHE=1 bundle exec rspec
+```
+
+This is useful when you're iterating on tests and your fixture definitions haven't changed.
+
+### CI Setup
+
+For CI, set `autogenerate` to `false`. FixtureKit will automatically generate any missing caches at suite start:
+
+```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.
+
+## Nested Fixtures
+
+Organize fixtures in subdirectories:
+
+```ruby
+# spec/fixture_kit/teams/sales.rb
+FixtureKit.define do
+  # ...
+end
+```
+
+```ruby
+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).
+
+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.
+
+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.
+
+4. **Transaction isolation**: RSpec's `use_transactional_fixtures` wraps each test in a transaction that rolls back, so data doesn't persist between tests.
+
+### Cache Format
+
+Caches are stored as JSON files in `tmp/cache/fixture_kit/`:
+
+```json
+{
+  "records": {
+    "User": "INSERT OR IGNORE INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com'), (2, 'Bob', 'bob@example.com')",
+    "Project": "INSERT OR IGNORE INTO projects (id, name, user_id) VALUES (1, 'Website', 1)"
+  },
+  "exposed": {
+    "alice": { "model": "User", "id": 1 },
+    "bob": { "model": "User", "id": 2 },
+    "project": { "model": "Project", "id": 1 }
+  }
+}
+```
+
+- **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
+
+## Cache Management
+
+Delete the cache directory to force regeneration:
+```bash
+rm -rf tmp/cache/fixture_kit
+```
+
+Caches are automatically cleared at suite start when `autogenerate` is enabled, so manual clearing is rarely needed.
+
+## Multi-Database Support
+
+FixtureKit automatically handles multiple databases. Records are stored by model name in the cache, and when replaying, FixtureKit uses each model's database connection to execute the INSERT statements. This means records are automatically inserted into the correct database without any additional configuration.
+
+## Requirements
+
+- Ruby >= 3.3
+- ActiveRecord >= 8.0
+- ActiveSupport >= 8.0
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/lib/fixture_kit/configuration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class Configuration
+    attr_writer :fixture_path
+    attr_writer :cache_path
+    attr_accessor :autogenerate
+
+    def initialize
+      @fixture_path = nil
+      @cache_path = nil
+      @autogenerate = true
+    end
+
+    def fixture_path
+      @fixture_path ||= detect_fixture_path
+    end
+
+    def cache_path
+      @cache_path ||= detect_cache_path
+    end
+
+    private
+
+    def detect_fixture_path
+      if defined?(RSpec)
+        "spec/fixture_kit"
+      elsif defined?(Minitest)
+        "test/fixture_kit"
+      elsif Dir.exist?("spec")
+        "spec/fixture_kit"
+      elsif Dir.exist?("test")
+        "test/fixture_kit"
+      else
+        "spec/fixture_kit"
+      end
+    end
+
+    def detect_cache_path
+      "tmp/cache/fixture_kit"
+    end
+  end
+end

data/lib/fixture_kit/fixture.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class Fixture
+    attr_reader :name, :block
+
+    def initialize(name, &block)
+      @name = name.to_sym
+      @block = block
+    end
+
+    def execute
+      context = FixtureContext.new
+      context.instance_eval(&block) if block
+      context.exposed
+    end
+  end
+end

data/lib/fixture_kit/fixture_cache.rb

@@ -0,0 +1,179 @@
+# 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_context.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class FixtureContext
+    attr_reader :exposed
+
+    def initialize
+      @exposed = {}
+    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
+        end
+
+        @exposed[name] = record
+      end
+    end
+  end
+end

data/lib/fixture_kit/fixture_registry.rb

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

@@ -0,0 +1,103 @@
+# 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 a transaction that rolls back, so no data persists
+    # 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
+        execute_and_cache
+        raise ActiveRecord::Rollback
+      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/fixture_set.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class FixtureSet
+    def initialize(exposed_records)
+      @records = exposed_records
+      define_accessors
+    end
+
+    def [](name)
+      @records[name.to_sym]
+    end
+
+    def to_h
+      @records.dup
+    end
+
+    private
+
+    def define_accessors
+      @records.each do |name, value|
+        define_singleton_method(name) { value }
+      end
+    end
+  end
+end

data/lib/fixture_kit/rspec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "fixture_kit"
+
+module FixtureKit
+  module RSpec
+    # Class methods (extended via config.extend)
+    module ClassMethods
+      # Declare which fixture to use for this example group.
+      # Can be overridden in nested groups (like `let`).
+      #
+      # Example:
+      #   RSpec.describe User do
+      #     fixture "basic_users"
+      #
+      #     it "has users" do
+      #       expect(fixture.alice).to be_present
+      #     end
+      #
+      #     context "with admins" do
+      #       fixture "admin_users"  # Override
+      #
+      #       it "has admin" do
+      #         expect(fixture.admin).to be_present
+      #       end
+      #     end
+      #   end
+      def fixture(name)
+        metadata[:fixture_name] = name.to_s
+      end
+    end
+
+    # Instance methods (included via config.include)
+    module InstanceMethods
+      # 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
+      end
+    end
+  end
+end
+
+# Configure RSpec integration
+RSpec.configure do |config|
+  config.extend FixtureKit::RSpec::ClassMethods
+  config.include FixtureKit::RSpec::InstanceMethods
+
+  # 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)
+      FixtureKit::FixtureCache.clear unless preserve_cache
+    else
+      FixtureKit::FixtureCache.pregenerate_all
+    end
+  end
+end

data/lib/fixture_kit/singleton.rb

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

data/lib/fixture_kit/sql_capture.rb

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

data/lib/fixture_kit/version.rb

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

data/lib/fixture_kit.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class Error < StandardError; end
+  class DuplicateFixtureError < Error; end
+  class DuplicateNameError < Error; end
+  class CacheMissingError < Error; end
+  class ExposedRecordNotFound < 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__)
+
+  extend Singleton
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: fixture_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ngan Pham
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  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
+    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: rspec-rails
+  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: sqlite3
+  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: railties
+  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'
+description: FixtureKit provides lightning-fast test setup by caching database records.
+  Define fixtures using any tool (FactoryBot, raw ActiveRecord, etc.), and FixtureKit
+  caches the SQL to replay in subsequent test runs.
+email:
+- ngan.pham@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/fixture_kit.rb
+- lib/fixture_kit/configuration.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/rspec.rb
+- lib/fixture_kit/singleton.rb
+- lib/fixture_kit/sql_capture.rb
+- lib/fixture_kit/version.rb
+homepage: https://github.com/Gusto/fixture_kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Gusto/fixture_kit
+  source_code_uri: https://github.com/Gusto/fixture_kit
+  changelog_uri: https://github.com/Gusto/fixture_kit/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Fast test fixtures with SQL caching
+test_files: []