fixture_kit 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9c12d67129c3c71b587913a62cea49c41f55a7ab9c0f4308961906517f7b6f7
-  data.tar.gz: 92e5dec6ccdb3084d5b699fd1f462fb145667dd46caeb7f65aba8d782244bdbd
+  metadata.gz: c052323f7423cfeb258b137bc8372833eff2f4c8b826b3fa22b25a171b2b2c0f
+  data.tar.gz: '0728daee8814033465d2b93a67e15a00eff4abe5543967167077f81e68db7dde'
 SHA512:
-  metadata.gz: 75484ce7d299f78263f0c268a39eacb4c33896075b90138ed6741e253b95d312144ced9481ae2e7e6328a4b8817bf8e566c7d56df86975e236b2f2a248643376
-  data.tar.gz: c7644edbec83c88df2d5cc24a206ccabd4d3f1077a199fd2317c81e7e128801a58ed86738b229ed679b6ca3c1b979fe0f2b5adbf2334ed4ab16dbd2fa04b3ccf
+  metadata.gz: 82149fa2c3598b2af00b2cd9b8e3691e8694f18bdc40a0abf3a47540e7c319e0821250bec0e3dce4d8aaf692ea614a17cda09970a476503b0280c7a301b95e2f
+  data.tar.gz: f4fe1ea329c354aee57ad6f53d22682309b8db9704340f52d18c4b01b42a83a47701d36fe11e739d644e13b72d02171190a530df6847386770a5edc6b786cbf2

data/README.md

@@ -106,6 +106,22 @@ 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
 
 ```ruby
@@ -117,7 +133,7 @@ RSpec.configure do |config|
 end
 ```
 
-When you call `fixture "name"` in an example group, FixtureKit registers that fixture with its runner.
+When you call `fixture "name"` or `fixture do ... end` in an example group, FixtureKit registers that fixture with its runner.
 
 ### 4. Configure Minitest
 
@@ -130,7 +146,7 @@ class ActiveSupport::TestCase
 end
 ```
 
-When you call `fixture "name"` in a test class, FixtureKit registers that fixture with its runner and mounts it during test setup.
+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.
 
 ## Configuration
 
@@ -152,8 +168,14 @@ FixtureKit.configure do |config|
 
   # Optional callback, called right before a fixture cache is generated.
   # Called on first generation and forced regeneration.
-  # Receives the fixture name as a String.
-  # config.on_cache = ->(fixture_name) { puts "cached #{fixture_name}" }
+  # Receives the fixture identifier:
+  # - named fixtures: String (e.g. "teams/basic")
+  # - anonymous fixtures: scope class
+  # 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.
+  # config.on_cache_mount = ->(identifier) { puts "mounted #{identifier}" }
 end
 ```
 
@@ -168,7 +190,7 @@ When using `fixture_kit/rspec`, FixtureKit sets `FixtureKit::RSpecIsolator`. It
 
 Fixture generation is managed by `FixtureKit::Runner`.
 
-1. Calling `fixture "name"` registers the fixture with the 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.
@@ -180,6 +202,13 @@ 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 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:
@@ -207,9 +236,18 @@ end
 fixture "teams/sales"
 ```
 
+## Anonymous Fixture Cache Paths
+
+Anonymous fixture caches are written under the `_anonymous/` directory inside `cache_path`.
+
+- 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 isolator, subscribes to `sql.active_record` notifications to track created/updated/deleted models, queries those model tables, and caches INSERT statements for current table contents.
+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.
 
 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.
 
@@ -224,8 +262,8 @@ 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)"
+    "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 },

data/lib/fixture_kit/cache.rb

@@ -7,17 +7,30 @@ require "active_support/inflector"
 
 module FixtureKit
   class Cache
+    ANONYMOUS_DIRECTORY = "_anonymous"
+
     include ConfigurationHelper
 
     attr_reader :fixture
 
-    def initialize(fixture, definition)
+    def initialize(fixture)
       @fixture = fixture
-      @definition = definition
     end
 
     def path
-      File.join(configuration.cache_path, "#{fixture.name}.json")
+      File.join(configuration.cache_path, "#{identifier}.json")
+    end
+
+    def identifier
+      @identifier ||= begin
+        raw_identifier = fixture.identifier
+        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))
+        end
+      end
     end
 
     def exists?
@@ -26,7 +39,7 @@ module FixtureKit
 
     def load
       unless exists?
-        raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{fixture.name}'"
+        raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{fixture.identifier}'"
       end
 
       @data ||= JSON.parse(File.read(path))
@@ -46,12 +59,12 @@ module FixtureKit
     def save
       FixtureKit.runner.isolator.run do
         models = SqlSubscriber.capture do
-          @definition.evaluate
+          fixture.definition.evaluate
         end
 
         @data = {
           "records" => generate_statements(models),
-          "exposed" => build_exposed_mapping(@definition.exposed)
+          "exposed" => build_exposed_mapping(fixture.definition.exposed)
         }
       end
 
@@ -77,7 +90,7 @@ module FixtureKit
       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}'"
+        "Could not find #{model_name} with id=#{id} for exposed record '#{exposed_name}' in fixture '#{@fixture.identifier}'"
     end
 
     def generate_statements(models)

data/lib/fixture_kit/configuration.rb

@@ -5,13 +5,15 @@ module FixtureKit
     attr_writer :fixture_path
     attr_writer :cache_path
     attr_accessor :isolator
-    attr_accessor :on_cache
+    attr_accessor :on_cache_save
+    attr_accessor :on_cache_mount
 
     def initialize
       @fixture_path = "fixture_kit"
       @cache_path = nil
       @isolator = FixtureKit::MinitestIsolator
-      @on_cache = nil
+      @on_cache_save = nil
+      @on_cache_mount = nil
     end
 
     def fixture_path

data/lib/fixture_kit/definition.rb

@@ -2,10 +2,11 @@
 
 module FixtureKit
   class Definition
-    attr_reader :exposed
+    attr_reader :exposed, :source_location
 
     def initialize(&definition)
       @definition = definition
+      @source_location = definition.source_location
       @exposed = {}
     end
 

data/lib/fixture_kit/fixture.rb

@@ -4,37 +4,28 @@ module FixtureKit
   class Fixture
     include ConfigurationHelper
 
-    attr_reader :name, :path
+    attr_reader :identifier, :definition
 
-    def initialize(name, path)
-      @name = name
-      @path = path
-      @cache = Cache.new(self, definition)
+    def initialize(identifier, definition)
+      @identifier = identifier
+      @definition = definition
+      @cache = Cache.new(self)
     end
 
     def cache(force: false)
       return if @cache.exists? && !force
 
-      configuration.on_cache&.call(name)
+      configuration.on_cache_save&.call(@cache.identifier)
       @cache.save
     end
 
     def mount
       unless @cache.exists?
-        raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{name}'"
+        raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{identifier}'"
       end
 
+      configuration.on_cache_mount&.call(@cache.identifier)
       @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/minitest.rb

@@ -8,8 +8,8 @@ module FixtureKit
     DECLARATION_CLASS_ATTRIBUTE = :fixture_kit_declaration
 
     module ClassMethods
-      def fixture(name)
-        self.fixture_kit_declaration = FixtureKit.runner.register(name)
+      def fixture(name = nil, &definition_block)
+        self.fixture_kit_declaration = FixtureKit.runner.register(self, name, &definition_block)
       end
     end
 

data/lib/fixture_kit/registry.rb

@@ -1,35 +1,56 @@
 # frozen_string_literal: true
 
-require "pathname"
-
 module FixtureKit
   class Registry
     include ConfigurationHelper
 
     def initialize
-      @registry = {}
+      @declarations = {}
+      @fixtures = {}
     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}'"
+    def add(scope, name_or_block)
+      if @declarations.key?(scope)
+        raise FixtureKit::MultipleFixtures, "cannot load multiple fixtures in the same context"
       end
 
-      @registry[name] = Fixture.new(name, file_path)
+      @declarations[scope] =
+        case name_or_block
+        when String
+          fetch_named_fixture(name_or_block)
+        when Proc
+          fetch_anonymous_fixture(scope, name_or_block)
+        else
+          raise FixtureKit::InvalidFixtureDeclaration, "unsupported fixture declaration type: #{name_or_block.class}"
+        end
     end
 
     def fixtures
-      @registry.values
+      @fixtures.values
     end
 
     private
 
-    def fixture_file_path(name)
-      File.expand_path(File.join(configuration.fixture_path, "#{name}.rb"))
+    def fetch_named_fixture(name)
+      @fixtures[name] ||= Fixture.new(name, load_named_definition(name))
+    end
+
+    def fetch_anonymous_fixture(scope, definition)
+      @fixtures[scope] ||= Fixture.new(scope, Definition.new(&definition))
+    end
+
+    def load_named_definition(name)
+      file_path = File.expand_path(File.join(configuration.fixture_path, "#{name}.rb"))
+
+      unless File.file?(file_path)
+        raise FixtureKit::FixtureDefinitionNotFound,
+          "cannot find fixture definition file for '#{name}' at '#{file_path}'"
+      end
+
+      definition = eval(File.read(file_path), TOPLEVEL_BINDING.dup, file_path)
+      return definition if definition.is_a?(Definition)
+
+      raise FixtureKit::FixtureDefinitionNotFound, "cannot find fixture definition at '#{file_path}'"
     end
   end
 end

data/lib/fixture_kit/rspec.rb

@@ -27,8 +27,8 @@ module FixtureKit
       #       end
       #     end
       #   end
-      def fixture(name)
-        metadata[DECLARATION_METADATA_KEY] = ::RSpec.configuration.fixture_kit.register(name)
+      def fixture(name = nil, &definition_block)
+        metadata[DECLARATION_METADATA_KEY] = ::RSpec.configuration.fixture_kit.register(self, name, &definition_block)
       end
     end
 

data/lib/fixture_kit/runner.rb

@@ -15,8 +15,8 @@ module FixtureKit
       @started = false
     end
 
-    def register(name)
-      registry.add(name).tap do |fixture|
+    def register(scope, name = nil, &definition_block)
+      registry.add(scope, normalize_registration(name, definition_block)).tap do |fixture|
         fixture.cache if started?
       end
     end
@@ -46,5 +46,16 @@ module FixtureKit
     def preserve_cache?
       ENV[PRESERVE_CACHE_ENV_KEY].to_s.match?(/\A(1|true|yes)\z/i)
     end
+
+    def normalize_registration(name, definition_block)
+      if name && definition_block
+        raise FixtureKit::InvalidFixtureDeclaration, "cannot provide both fixture name and definition block"
+      end
+
+      name_or_block = name || definition_block
+      return name_or_block if name_or_block
+
+      raise FixtureKit::InvalidFixtureDeclaration, "must provide fixture name or definition block"
+    end
   end
 end

data/lib/fixture_kit/version.rb

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

data/lib/fixture_kit.rb

@@ -3,6 +3,8 @@
 module FixtureKit
   class Error < StandardError; end
   class DuplicateNameError < Error; end
+  class InvalidFixtureDeclaration < Error; end
+  class MultipleFixtures < Error; end
   class CacheMissingError < Error; end
   class FixtureDefinitionNotFound < Error; end
   class ExposedRecordNotFound < Error; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fixture_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Ngan Pham