fixtury 1.0.0.beta3 → 1.0.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e87073aed4eaadac63331ef0ca8613b5ed5534ad2d29886bc8c7a2a34a828d52
-  data.tar.gz: adf2bdb804f103bcafa7967bf47d7a405c9a05d1c2ac11f56826491c892133bd
+  metadata.gz: 297aa8d54ad35f629cfb75dc8c7599660dc24393ad87b03de039ad8f4dfd691a
+  data.tar.gz: c89efb954c5bebe6751628d22b29ecc4fb1fd61020d53d321b7e782e93608007
 SHA512:
-  metadata.gz: c6e0314bbc8fbb13465d8cb1a27f7b431f1c9ba788a218bc9754926a2c18390d6ebbd95897e547cc675e002704954e6616cec3dc0375def04852f0a49070a4ea
-  data.tar.gz: d4cadd16d4aad50d5ec31d56eb5a66a8e2d3afc14d22d1bec298768bcf9af342bb13db0126a48d9b61e4fd19e1691f3d647b6213105e9f3f4b49791db4db5234
+  metadata.gz: 9af1d90c107d075bfdf89c50ed59b59b0ae264a7799058bab495ae66f0e0451876c90d119e24219880d193f6dc6a869798cb7f568885a5b85e5f676f9871221d
+  data.tar.gz: de852c51ecd2a53fa9ae050deea5d150fef75819c287330c831c99c9307b00ea98854e6c13df3dc9b03e5dd5119bf6805cee69a139199c22a0867b0a848d25ad

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    fixtury (1.0.0.beta3)
+    fixtury (1.0.0.beta5)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,17 +1,18 @@
 # Fixtury
 
-Fixtury aims to provide an interface for creating, managing, and accessing test data in a simple and efficient way. It has no opinion on how you generate the data, it simply provides efficient ways to access it.
+Fixtury aims to provide an interface for creating, managing, and accessing test data in a simple and on-demand way. It has no opinion on how you generate the data, it simply provides efficient ways to access it.
 
-Often, fixture frameworks require you to either heavily maintain static fixtures or generate all your fixtures at runtime. Fixtury attempts to find a middle ground that enables a faster and more effecient development process.
+Often, fixture frameworks require you to either heavily maintain static fixtures or generate all your fixtures at runtime. Fixtury attempts to find a middle ground that enables a faster and more effecient development process while allowing you to generate realistic test data.
 
 For example, if a developer is running a test locally in their development environment there's no reason to build all fixtures for your suite of 30k tests. Instead, if we're able to track the fixture dependencies of the tests that are running we can build (and cache) the data relevant for the specific tests that are run.
 
 ```ruby
-class MyTest < ::ActiveSupport::TestCase
-  prepend ::Fixtury::TestHooks
+require "fixtury/minitest_hooks"
 
-  fixtury "users/fresh"
-  let(:user) { fixtury("users/fresh") }
+class MyTest < ::Minitest::Test
+  prepend ::Fixtury::MintestHooks
+
+  fixtury "users/fresh", as: :user
 
   def test_whatever
     assert_eq "Doug", user.first_name
@@ -20,6 +21,91 @@ class MyTest < ::ActiveSupport::TestCase
 end
 ```
 
-Loading this file would ensure `users/fresh` is loaded into the fixture set before the suite is run. In the context of ActiveSupport::TestCase, the Fixtury::Hooks file will ensure the database records are present prior to your suite running. Setting `use_transactional_fixtures` ensures all records are rolled back prior to running another test.
+Loading this file would ensure `users/fresh` is loaded into the fixture set before the suite is run. In the context of Minitest::Test, the Fixtury::MinitestHooks file will ensure the database records are present prior to your suite running. If you're using ActiveRecord `use_transactional_fixtures` and `use_transactional_tests` will be respected.
+
+## Configuration
+
+If you're using Rails, you can `require "fixtury/railtie"` to accomplish a standard installation which will observe common rails files for changes and expects fixture definitions to defined in `test/fixtures`. See the railtie class for details.
+
+For non-rails environments or additional configuration, you can open up the Fixtury configuration like so:
+```ruby
+::Fixtury.configure do |config|
+  config.locator_backend = :global_id # the locator behavior to use for finding fixtures
+  config.filepath = File.join(root, "tmp/fixtury.yml") # the location to dump the fixtury references
+  config.add_fixture_path = File.join(root, "fixtures/**/*.rb")
+  config.add_dependency_path = File.join(root, "db/schema.rb")
+end
+```
+See Fixtury::Configuration for all options.
+
+When your Fixtury is configured, you should call `Fixtury.start`.
+
+For minitest integration, you should dump the configuration file after the suite runs or after your fixture dependencies are built:
+
+```ruby
+::Minitest.after_run do
+  ::Fixtury.configuration.dump_file
+end
+```
+
+In a CI environment, we'd likely want to preload all fixtures to produce a database snapshot to be shared. This can be done by configuring Fixtury, calling `Fixtury.start`, then calling `Fixtury.load_all_fixtures`. All fixtures declared in the configuration's fixture_paths will be loaded.
+
+## Defining Fixtures
+
+There are two primary principals in Fixtury: namespaces and fixture definitions. See below for an example of how they're used.
+
+```ruby
+Fixtury.define do
+
+  fixture "user" do
+    User.create(...)
+  end
+
+  namespace "addresses" do
+    fixture "sample" do
+      Address.create(...)
+    end
+  end
+
+  namespace "user_with_address" do
+    fixture "user", deps: "address" do |deps|
+      User.create(address_id: deps.address.id, ...)
+    end
+
+    fixture "address" do
+      Address.create(...)
+    end
+  end
+end
+```
+
+As you can see fixtures are named in a nested structure and can refer to each other via dependencies. See Fixtury::Dependency for more specifics.
+
+## Isolation Levels
+
+Isolation keys enable groups of fixtures to use and modify the same resources. When one fixture from an isolation level is built, all fixtures in that isolation level are built. This allows multiple fixtures to potentially mutate a resource while keeping the definition consistent.
+
+```ruby
+Fixtury.define do
+  namespace "use_cases" do
+    namespace "onboarded", isolate: true do
+
+      fixture "user" do
+        User.create(...)
+      end
+
+      fixture "profile", deps: "user" do |deps|
+        profile = Profile.create(user: deps.user, ...)
+        user.update(profiles_count: 1, onboarded_at: Time.current)
+        profile
+      end
+
+    end
+  end
+end
+```
+
+### ActiveRecord Integration
+
+When installed with the railtie, a MutationObserver module is prepended into ActiveRecord::Base. It observes record mutations and ensures a record is not mutated outside of the declared isolation level. If you're not using ActiveRecord check out Fixtury::MutationObserver to see how you could hook into other frameworks.
 
-In a CI environment, we'd likely want to preload all fixtures. This can be done by requiring all the test files, then telling the fixtury store to load all definitions.

data/lib/fixtury/configuration.rb

@@ -5,12 +5,14 @@ module Fixtury
   # generation.
   class Configuration
 
-    attr_reader :filepath, :fixture_files, :dependency_files
+    attr_reader :fixture_files, :dependency_files, :locator_backend
+    attr_accessor :filepath, :reference_ttl, :strict_dependencies
 
     def initialize
-      @filepath = nil
       @fixture_files = Set.new
       @dependency_files = Set.new
+      @locator_backend = :memory
+      @strict_dependencies = true
     end
 
     def log_level
@@ -22,19 +24,19 @@ module Fixtury
       @log_level
     end
 
+    def log_level=(level)
+      @log_level = level.to_s.to_sym
+    end
+
+    def locator_backend=(backend)
+      @locator_backend = backend.to_sym
+    end
+
     # Delete the storage file if it exists.
     def reset
       File.delete(filepath) if filepath && File.file?(filepath)
     end
 
-    # Set the location of the storage file. The storage file will maintain
-    # checksums of all tracked files and serialized references to fixtures.
-    #
-    # @param path [String] The path to the storage file.
-    def filepath=(path)
-      @filepath = path.to_s
-    end
-
     # Add a file or glob pattern to the list of fixture files.
     #
     # @param path_or_globs [String, Array<String>] The file or glob pattern(s) to add.
@@ -69,20 +71,26 @@ module Fixtury
       File.binwrite(filepath, file_data.to_yaml)
     end
 
-    def files_changed?
-      return true if stored_data.nil?
+    def changes
+      return "new: #{filepath}" if stored_data.nil?
 
       stored_checksums = (stored_data[:dependencies] || {})
       seen_filepaths = []
       calculate_checksums do |filepath, checksum|
         # Early return if the checksums don't match
-        return true unless stored_checksums[filepath] == checksum
+        return "change: #{filepath}" unless stored_checksums[filepath] == checksum
 
         seen_filepaths << filepath
       end
 
       # If we have a new file or a file has been removed, we need to report a change.
-      seen_filepaths.sort != stored_checksums.keys.sort
+      new_files = seen_filepaths - stored_checksums.keys
+      return "added: #{new_files.inspect}" if new_files.any?
+
+      removed_files = stored_checksums.keys - seen_filepaths
+      return "removed: #{removed_files.inspect}" if removed_files.any?
+
+      nil
     end
 
 

data/lib/fixtury/dependency_store.rb

@@ -14,16 +14,27 @@ module Fixtury
       "#{self.class}(definition: #{definition.pathname.inspect}, dependencies: #{definition.dependencies.keys.inspect})"
     end
 
-    # Returns the value of the dependency with the given key
+    # Returns the value of the dependency with the given key. If the key is not present in the dependencies
+    # and strict_dependencies is enabled, an error will be raised. If strict_dependencies is not enabled
+    # the store will receive the search term directly.
     #
-    # @param key [String, Symbol] the accessor of the dependency
+    # @param search [String, Symbol] the accessor of the dependency
     # @return [Object] the value of the dependency
-    # @raise [Fixtury::Errors::UnknownDependencyError] if the definition does not contain the provided dependency
-    def get(key)
-      dep = definition.dependencies.fetch(key.to_s) do
-        raise Errors::UnknownDependencyError.new(definition, key)
+    # @raise [Fixtury::Errors::UnknownDependencyError] if the definition does not contain the provided dependency and strict_dependencies is enabled
+    def get(search)
+      dep = definition.dependencies[search.to_s]
+
+      if dep.nil? && Fixtury.configuration.strict_dependencies
+        raise Errors::UnknownDependencyError.new(definition, search)
+      end
+
+      if dep
+        store.get(dep.definition.pathname)
+      else
+        store.with_relative_schema(definition.parent) do
+          store.get(search)
+        end
       end
-      store.get(dep.definition.pathname)
     end
     alias [] get
 

data/lib/fixtury/{test_hooks.rb → minitest_hooks.rb}

@@ -4,7 +4,7 @@ require "fixtury"
 require "active_support/core_ext/class/attribute"
 
 module Fixtury
-  # TestHooks is a module designed to hook into a Minitest test case, and
+  # MinitestHooks is a module designed to hook into a Minitest test case, and
   # provide a way to load fixtures into the test case. It is designed to be
   # prepended into the test case class, and will automatically load fixtures
   # before the test case is setup, and rollback any changes after the test
@@ -15,7 +15,7 @@ module Fixtury
   #
   # @example
   #   class MyTest < Minitest::Test
-  #     prepend Fixtury::TestHooks
+  #     prepend Fixtury::MinitestHooks
   #
   #     fixtury "user"
   #     fixtury "post"
@@ -38,7 +38,7 @@ module Fixtury
   #   # using the last segment of the fixture's pathname.
   #
   #   class MyTest < Minitest::Test
-  #     prepend Fixtury::TestHooks
+  #     prepend Fixtury::MinitestHooks
   #
   #     fixtury "/my/user_record", as: :user
   #
@@ -52,7 +52,7 @@ module Fixtury
   # The setup and teardown attempt to manage a transaction for each registered database
   # connection if ActiveRecord::Base is present. If use_transaction_tests or use_transactional_fixtures
   # are present, those settings will be respected. If neither are present, a transaction will be used.
-  module TestHooks
+  module MinitestHooks
 
     def self.prepended(klass)
       klass.class_attribute :fixtury_dependencies

data/lib/fixtury/mutation_observer.rb

@@ -135,6 +135,3 @@ end
 ::Fixtury.hooks.around(:execution) do |execution, &block|
   ::Fixtury::MutationObserver.observe(execution, &block)
 end
-
-# If/when activerecord loads, prepend the hooks module to ActiveRecord::Base
-ActiveSupport.on_load(:active_record) { prepend Fixtury::MutationObserver::ActiveRecordHooks }

data/lib/fixtury/railtie.rb

@@ -1,14 +1,35 @@
 # frozen_string_literal: true
 
+require "fixtury"
+
 module Fixtury
   class Railtie < ::Rails::Railtie
 
-    rake_tasks do
-      load "fixtury/tasks.rake"
+    initializer "fixtury.configure" do
+      ::Fixtury.configure do |config|
+        config.filepath = Rails.root.join("tmp/fixtury.yml")
+        config.add_dependency_path ::Rails.root.join("db/schema.rb")
+        config.add_dependency_path ::Rails.root.join("db/seeds.rb")
+        config.add_dependency_path ::Rails.root.join("db/seeds/**/*.rb")
+        config.add_fixture_path ::Rails.root.join("test/fixtures/**/*.rb")
+        config.locator_backend = :global_id
+      end
     end
 
-    initializer "fixtury.activerecord_hooks" do
-      require "fixtury/mutation_observer"
+    initializer "fixtury.load_hooks" do
+      ActiveSupport.on_load(:active_record) do
+        require "fixtury/mutation_observer"
+        prepend Fixtury::MutationObserver::ActiveRecordHooks
+      end
+
+      ActiveSupport.on_load(:active_support_test_case) do
+        require "fixtury/minitest_hooks"
+        prepend Fixtury::MinitestHooks
+
+        ::Minitest.after_run do
+          ::Fixtury.configuration.dump_file
+        end
+      end
     end
 
   end

data/lib/fixtury/reference.rb

@@ -17,7 +17,7 @@ module Fixtury
 
     attr_reader :name, :locator_key, :created_at, :options
 
-    def initialize(name, locator_key, options = {})
+    def initialize(name, locator_key, **options)
       @name = name
       @locator_key = locator_key
       @created_at = Time.now.to_i

data/lib/fixtury/schema.rb

@@ -13,6 +13,10 @@ module Fixtury
       super(name: name, **options)
     end
 
+    def reset
+      children.clear
+    end
+
     # Object#acts_like? adherence.
     def acts_like_fixtury_schema?
       true

data/lib/fixtury/store.rb

@@ -14,15 +14,9 @@ module Fixtury
     attr_reader :schema
     attr_reader :ttl
 
-    # Create a new store.
-    # @param locator [Fixtury::Locator, Symbol, NilClass] (see Fixtury::Locator#from)
-    # @param ttl [Integer, NilClass] The time-to-live for references in seconds.
-    # @param schema [Fixtury::Schema, NilClass] The schema to use for fixture definitions, defaults to the global schema.
-    # @return [Fixtury::Store]
-    def initialize(locator: nil, ttl: nil, schema: nil)
+    def initialize(schema: nil)
       @schema = schema || ::Fixtury.schema
-      @locator = ::Fixtury::Locator.from(locator)
-      @ttl = ttl&.to_i
+      @locator = ::Fixtury::Locator.from(::Fixtury.configuration.locator_backend)
       self.references = ::Fixtury.configuration.stored_references
     end
 
@@ -78,7 +72,7 @@ module Fixtury
     # @return [void]
     def load_all(schema = self.schema)
       schema.children.each_value do |item|
-        get(item.name) if item.acts_like?(:fixtury_definition)
+        get(item.pathname) if item.acts_like?(:fixtury_definition)
         load_all(item) if item.acts_like?(:fixtury_schema)
       end
     end
@@ -126,9 +120,10 @@ module Fixtury
       raise ArgumentError, "#{search.inspect} must refer to a definition" unless dfn.acts_like?(:fixtury_definition)
 
       pathname = dfn.pathname
+      isokey = dfn.isolation_key
 
       # Ensure that if we're part of an isolation group, we load all the fixtures in that group.
-      maybe_load_isolation_dependencies(dfn.isolation_key)
+      maybe_load_isolation_dependencies(isokey)
 
       # See if we already hold a reference to the fixture.
       ref = references[pathname]
@@ -173,7 +168,13 @@ module Fixtury
         log("store #{pathname}", level: LOG_LEVEL_DEBUG)
 
         locator_key = locator.dump(value, context: pathname)
-        references[pathname] = ::Fixtury::Reference.new(pathname, locator_key)
+        reference_opts = {}
+        reference_opts[:isolation_key] = isokey unless isokey == pathname
+        references[pathname] = ::Fixtury::Reference.new(
+          pathname,
+          locator_key,
+          **reference_opts
+        )
       end
 
       value
@@ -243,5 +244,9 @@ module Fixtury
       ::Fixtury.log(msg, level: level, name: "store")
     end
 
+    def ttl
+      ::Fixtury.configuration.reference_ttl&.to_i
+    end
+
   end
 end

data/lib/fixtury/version.rb

@@ -2,6 +2,6 @@
 
 module Fixtury
 
-  VERSION = "1.0.0.beta3"
+  VERSION = "1.0.0.beta5"
 
 end

data/lib/fixtury.rb

@@ -67,43 +67,48 @@ module Fixtury
     @schema ||= ::Fixtury::Schema.new
   end
 
-  def self.schema=(schema)
-    @schema = schema
-  end
-
   # Default store for fixtures. This is a shared store that can be used across the application.
   def self.store
     @store ||= ::Fixtury::Store.new
   end
 
-  def self.store=(store)
-    @store = store
+  # Load all known fixture files configured in Configuration. Reset the store references if
+  # a dependency file has changed.
+  def self.start
+    load_all_schemas
+    reset_if_changed
   end
 
   # Require each schema file to ensure that all definitions are loaded.
-  def self.load_all_schemas
+  def self.load_all_schemas(mechanism = :require)
     configuration.fixture_files.each do |filepath|
-      require filepath
+      if mechanism == :require
+        require filepath
+      elsif mechanism == :load
+        load filepath
+      else
+        raise ArgumentError, "unknown load mechanism: #{mechanism}"
+      end
     end
   end
 
   # Ensure all definitions are loaded and then load all known fixtures.
-  def self.load_all_fixtures
-    load_all_schemas
-    Fixtury.store.load_all
+  def self.load_all_fixtures(...)
+    load_all_schemas(...)
+    store.load_all
   end
 
-  # Remove all references from the active store and reset the dependency file
+  # Remove all references from the active store and reset the dependency file.
   def self.reset
-    log("resetting", level: LOG_LEVEL_INFO)
-
     configuration.reset
     store.reset
   end
 
   # Perform a reset if any of the tracked files have changed.
   def self.reset_if_changed
-    if configuration.files_changed?
+    changes = configuration.changes
+    if changes
+      log("changes found, resetting | #{changes}", level: LOG_LEVEL_INFO)
       reset
     else
       log("no changes, skipping reset", level: LOG_LEVEL_INFO)
@@ -124,6 +129,7 @@ module Fixtury
     msg << " #{yield}" if block_given?
     msg << "\n" if newline
 
+    # TODO: logger
     print msg
     msg
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fixtury
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta3
+  version: 1.0.0.beta5
 platform: ruby
 authors:
 - Mike Nelson
@@ -165,6 +165,7 @@ files:
 - lib/fixtury/locator_backend/common.rb
 - lib/fixtury/locator_backend/global_id.rb
 - lib/fixtury/locator_backend/memory.rb
+- lib/fixtury/minitest_hooks.rb
 - lib/fixtury/mutation_observer.rb
 - lib/fixtury/path_resolver.rb
 - lib/fixtury/railtie.rb
@@ -172,7 +173,6 @@ files:
 - lib/fixtury/schema.rb
 - lib/fixtury/schema_node.rb
 - lib/fixtury/store.rb
-- lib/fixtury/test_hooks.rb
 - lib/fixtury/version.rb
 homepage: https://github.com/guideline-tech/fixtury
 licenses: []