fixture_kit 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6625febace1194e8bfdef5c43ab86865d8e26068e6d7593be897d6898cbfe3ab
-  data.tar.gz: f4c1ccb43f872b81ac31c4fe89d113904d82d3704a639772e12180ae423ec900
+  metadata.gz: ed0ea806a1b28f87c19ac24766790a392042ea6e4bd4888e9c7dd6e0787b70ec
+  data.tar.gz: f726a2965d20fbcd35b12f561186b1130bd32cc1b0825877ef0900e824867170
 SHA512:
-  metadata.gz: 22f9d60285534cde9741026a75ad278795f33a37e9af26c6ee4321b53f7474cdab7b3fd09728a4a40f5e3cedb678bc30a596f7b9e9670b780ff43126ca693bb3
-  data.tar.gz: 5c5a7608698b7b190e9c8863ecc66cc9c96ce0aee89431ed941b568fdbf63e184cc9f699d2aab1a220a160dc674c2d49e44f38093f88c07838beeeda8def9ef6
+  metadata.gz: 3bf15388944864caa344d383733162ba262c6198be2845b1a8ada616966c725bbd0515daaf3788ab4a53564148cc18b10bef244980c2fc6f8d6993f7d252b1df
+  data.tar.gz: c4b2530715dc65912c6fb5f22ece5f4b1cf76bd4bb20e816242365c8ef2c53f9936dc57eb48092205228afe079a1782626ce241b9183b24d37b31a1d87758d8c

data/README.md

@@ -2,20 +2,11 @@
 
 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. 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 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.
+- Full documentation (guides): [GitHub Wiki](https://github.com/Gusto/fixture_kit/wiki)
+- API/reference (canonical): [docs/reference.md](docs/reference.md)
 
 ## Installation
 
-Add to your Gemfile:
-
 ```ruby
 group :test do
   gem "fixture_kit"
@@ -24,105 +15,21 @@ end
 
 ## Quick Start
 
-### 1. Define a Fixture
-
-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:**
-
-```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:**
+### 1. Define a fixture
 
 ```ruby
-# spec/fixture_kit/bookstore.rb
+# spec/fixture_kit/project_management.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")
+  owner = User.create!(name: "Alice", email: "alice@example.com")
+  project = Project.create!(name: "Roadmap", owner: owner)
 
-  expose(store: store, owner: owner, books: books, featured: featured)
+  expose(owner: owner, project: project)
 end
 ```
 
-The filename determines the fixture name—no need to pass a name to `define`.
+### 2. Configure your framework
 
-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 "exposes records as methods" do
-    expect(fixture.owner.email).to eq("alice@example.com")
-  end
-end
-```
-
-`fixture` returns a `Repository` and exposes records as methods (for example, `fixture.owner`).
-
-You can also define fixtures anonymously inline:
-
-```ruby
-RSpec.describe Book do
-  fixture do
-    owner = User.create!(name: "Alice", email: "alice@example.com")
-    featured = Book.create!(title: "Dune", owner: owner)
-    expose(owner: owner, featured: featured)
-  end
-
-  it "uses inline fixture data" do
-    expect(fixture.featured.owner).to eq(fixture.owner)
-  end
-end
-```
-
-### 3. Configure RSpec
+RSpec:
 
 ```ruby
 # spec/rails_helper.rb
@@ -133,9 +40,7 @@ RSpec.configure do |config|
 end
 ```
 
-When you call `fixture "name"` or `fixture do ... end` in an example group, FixtureKit registers that fixture with its runner.
-
-### 4. Configure Minitest
+Minitest:
 
 ```ruby
 # test/test_helper.rb
@@ -146,160 +51,33 @@ class ActiveSupport::TestCase
 end
 ```
 
-When you call `fixture "name"` or `fixture do ... end` in a test class, FixtureKit registers that fixture with its runner and mounts it during test setup.
+### 3. Use the fixture in tests
 
-## Configuration
+RSpec:
 
 ```ruby
-# spec/support/fixture_kit.rb
-FixtureKit.configure do |config|
-  # Where fixture definitions live (default: fixture_kit).
-  # Framework entrypoints set a framework-specific default:
-  # - fixture_kit/rspec -> spec/fixture_kit
-  # - fixture_kit/minitest -> test/fixture_kit
-  config.fixture_path = Rails.root.join("spec/fixture_kit").to_s
+RSpec.describe Project do
+  fixture "project_management"
 
-  # Where cache files are stored (default: tmp/cache/fixture_kit)
-  config.cache_path = Rails.root.join("tmp/cache/fixture_kit").to_s
-
-  # 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 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 String cache identifier as on_cache_save.
-  # config.on_cache_mount = ->(identifier) { puts "mounted #{identifier}" }
+  it "loads exposed records" do
+    expect(fixture.project.owner).to eq(fixture.owner)
+  end
 end
 ```
 
-Custom adapters should subclass `FixtureKit::Adapter` and implement:
-- `#execute`
-- `#identifier_for`
-
-`#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`.
-
-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
-
-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).
-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`: in class-level `run_suite` for test classes that declare `fixture`.
-
-## Fixture Declaration Rules
-
-- Only one `fixture` declaration is allowed per test context.
-- Declaring a fixture twice in the same context raises `FixtureKit::MultipleFixtures`.
-- Child contexts/classes can declare their own fixture and override parent declarations.
-- Providing both a name and a block (or neither) raises `FixtureKit::InvalidFixtureDeclaration`.
-
-### Preserving Cache Locally
-
-If you want to skip cache clearing when the runner starts (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
-```
-
-Truthy values are case-insensitive: `1`, `true`, `yes`.
-
-This is useful when you're iterating on tests and your fixture definitions haven't changed.
-
-## Nested Fixtures
-
-Organize fixtures in subdirectories:
+Minitest:
 
 ```ruby
-# spec/fixture_kit/teams/sales.rb
-FixtureKit.define do
-  # ...
-end
-```
-
-```ruby
-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`
-- RSpec: class name is underscored after removing `RSpec::ExampleGroups::`.
-  - `RSpec::ExampleGroups::Foo::WithFixtureKit::Hello` -> `_anonymous/foo/with_fixture_kit/hello.json`
-
-## How It Works
-
-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.
-
-3. **Repository build**: FixtureKit resolves exposed records by model + id and returns a `Repository` for method-based access.
+class ProjectTest < ActiveSupport::TestCase
+  fixture "project_management"
 
-4. **Transaction isolation**: Use framework transactions (`use_transactional_fixtures` in RSpec, `use_transactional_tests` in Minitest) so test writes roll back and cached data can be reused safely between tests.
-
-### Cache Format
-
-Caches are stored as JSON files in `tmp/cache/fixture_kit/`:
-
-```json
-{
-  "records": {
-    "User": "INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com'), (2, 'Bob', 'bob@example.com')",
-    "Project": "INSERT 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 (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
-
-Delete the cache directory to force regeneration:
-```bash
-rm -rf tmp/cache/fixture_kit
+  test "loads exposed records" do
+    assert_equal fixture.owner, fixture.project.owner
+  end
+end
 ```
 
-Caches are cleared at runner start unless `FIXTURE_KIT_PRESERVE_CACHE` is truthy.
-
-## 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.
+`fixture` returns a `Repository`, and exposed names become reader methods.
 
 ## Requirements
 
@@ -309,4 +87,4 @@ FixtureKit automatically handles multiple databases. Records are stored by model
 
 ## License
 
-MIT License. See [LICENSE](LICENSE) for details.
+MIT. See [LICENSE](LICENSE).

data/lib/fixture_kit/cache.rb

@@ -50,7 +50,7 @@ module FixtureKit
         end
       end
 
-      build_repository(@data.fetch("exposed"))
+      Repository.new(@data.fetch("exposed"))
     end
 
     def save
@@ -69,27 +69,8 @@ module FixtureKit
       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.identifier}'"
-    end
-
     def generate_statements(models)
       statements_by_model = {}
 

data/lib/fixture_kit/callbacks.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class Callbacks
+    EVENTS = [
+      :cache_save,
+      :cache_saved,
+      :cache_mount,
+      :cache_mounted
+    ].freeze
+
+    def initialize
+      @callbacks = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def register(event, &block)
+      validate_event!(event)
+      @callbacks[event] << block if block
+      @callbacks[event]
+    end
+
+    def run(event, *args)
+      validate_event!(event)
+      @callbacks[event].each do |callback|
+        callback.call(*args)
+      end
+    end
+
+    private
+
+    def validate_event!(event)
+      unless EVENTS.include?(event)
+        raise ArgumentError, "Unknown callback event: #{event}"
+      end
+    end
+  end
+end

data/lib/fixture_kit/configuration.rb

@@ -2,27 +2,16 @@
 
 module FixtureKit
   class Configuration
-    attr_writer :fixture_path
-    attr_writer :cache_path
-    attr_accessor :on_cache_save
-    attr_accessor :on_cache_mount
-    attr_reader :adapter_options
+    attr_accessor :fixture_path
+    attr_accessor :cache_path
+    attr_reader :adapter_options, :callbacks
 
     def initialize
       @fixture_path = "fixture_kit"
-      @cache_path = nil
+      @cache_path = "tmp/cache/fixture_kit"
       @adapter_class = FixtureKit::MinitestAdapter
       @adapter_options = {}
-      @on_cache_save = nil
-      @on_cache_mount = nil
-    end
-
-    def fixture_path
-      @fixture_path
-    end
-
-    def cache_path
-      @cache_path ||= detect_cache_path
+      @callbacks = Callbacks.new
     end
 
     def adapter(adapter_class = nil, **options)
@@ -32,10 +21,20 @@ module FixtureKit
       @adapter_options = options
     end
 
-    private
+    def on_cache_save(&block)
+      callbacks.register(:cache_save, &block)
+    end
+
+    def on_cache_saved(&block)
+      callbacks.register(:cache_saved, &block)
+    end
+
+    def on_cache_mount(&block)
+      callbacks.register(:cache_mount, &block)
+    end
 
-    def detect_cache_path
-      "tmp/cache/fixture_kit"
+    def on_cache_mounted(&block)
+      callbacks.register(:cache_mounted, &block)
     end
   end
 end

data/lib/fixture_kit/fixture.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "benchmark"
+
 module FixtureKit
   class Fixture
     include ConfigurationHelper
@@ -15,8 +17,8 @@ module FixtureKit
     def cache(force: false)
       return if @cache.exists? && !force
 
-      configuration.on_cache_save&.call(@cache.identifier)
-      @cache.save
+      emit(:cache_save)
+      emit(:cache_saved) { @cache.save }
     end
 
     def mount
@@ -24,8 +26,25 @@ module FixtureKit
         raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{identifier}'"
       end
 
-      configuration.on_cache_mount&.call(@cache.identifier)
-      @cache.load
+      emit(:cache_mount)
+      emit(:cache_mounted) { @cache.load }
+    end
+
+    private
+
+    def emit(event)
+      cache_identifier = @cache.identifier
+      unless block_given?
+        configuration.callbacks.run(event, cache_identifier)
+        return
+      end
+
+      value = nil
+      elapsed = Benchmark.realtime do
+        value = yield
+      end
+      configuration.callbacks.run(event, cache_identifier, elapsed)
+      value
     end
   end
 end

data/lib/fixture_kit/repository.rb

@@ -1,19 +1,40 @@
 # frozen_string_literal: true
 
+require "active_support/inflector"
+
 module FixtureKit
   class Repository
     def initialize(exposed_records)
-      @records = exposed_records
-      @records.each_value { |value| value.freeze if value.is_a?(Array) }
-      define_accessors
+      @records = exposed_records.transform_keys(&:to_sym)
+      @loaded_records = {}
+      define_readers
     end
 
     private
 
-    def define_accessors
-      @records.each do |name, value|
-        define_singleton_method(name) { value }
+    def define_readers
+      @records.each_key do |name|
+        define_singleton_method(name) { fetch(name) }
       end
     end
+
+    def fetch(name)
+      return @loaded_records[name] if @loaded_records.key?(name)
+
+      @loaded_records[name] = materialize(@records.fetch(name))
+    end
+
+    def materialize(value)
+      if value.is_a?(Array)
+        value.map { |record_info| load_record(record_info) }.freeze
+      else
+        load_record(value)
+      end
+    end
+
+    def load_record(record_info)
+      model = ActiveSupport::Inflector.constantize(record_info.fetch("model"))
+      model.find_by(id: record_info.fetch("id"))
+    end
   end
 end

data/lib/fixture_kit/version.rb

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

data/lib/fixture_kit.rb

@@ -7,23 +7,23 @@ module FixtureKit
   class MultipleFixtures < Error; end
   class CacheMissingError < Error; end
   class FixtureDefinitionNotFound < Error; end
-  class ExposedRecordNotFound < Error; end
   class RunnerAlreadyStartedError < Error; end
 
-  autoload :VERSION,       File.expand_path("fixture_kit/version", __dir__)
+  autoload :VERSION, File.expand_path("fixture_kit/version", __dir__)
   autoload :Configuration, File.expand_path("fixture_kit/configuration", __dir__)
+  autoload :Callbacks, File.expand_path("fixture_kit/callbacks", __dir__)
   autoload :ConfigurationHelper, File.expand_path("fixture_kit/configuration_helper", __dir__)
-  autoload :Singleton,     File.expand_path("fixture_kit/singleton", __dir__)
-  autoload :Fixture,       File.expand_path("fixture_kit/fixture", __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 :Singleton, File.expand_path("fixture_kit/singleton", __dir__)
+  autoload :Fixture, File.expand_path("fixture_kit/fixture", __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 :Adapter,       File.expand_path("fixture_kit/adapter", __dir__)
+  autoload :Cache, File.expand_path("fixture_kit/cache", __dir__)
+  autoload :Runner, File.expand_path("fixture_kit/runner", __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__)
+  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.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Ngan Pham
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: irb
   requirement: !ruby/object:Gem::Requirement
@@ -138,6 +152,7 @@ files:
 - lib/fixture_kit/adapters/minitest_adapter.rb
 - lib/fixture_kit/adapters/rspec_adapter.rb
 - lib/fixture_kit/cache.rb
+- lib/fixture_kit/callbacks.rb
 - lib/fixture_kit/configuration.rb
 - lib/fixture_kit/configuration_helper.rb
 - lib/fixture_kit/definition.rb