fixtury 0.4.1 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35c4db20425a837221a7c979e51371b77e00790cded54b182b31e62f7f57d8c2
-  data.tar.gz: cbdb024ba301b393b97604879594c1d9d53bfe1ffd4f24959824e8f41e1fe4e2
+  metadata.gz: 02d3acd3d4f3904ae6e00f53e81a5c29b3aa65b53a0bba96029625e99deb618e
+  data.tar.gz: 12a1fa78d029e6781ce240a3bed206b63b0fd02589773a84deeb80f18556585d
 SHA512:
-  metadata.gz: 4748b476b6683ac9275a0c62ebca36f346f5d2bea208d47f55dfd836b521283c383aee7847961ffc90726292fd187389fc65b650dd508f9c67288fa32ae88c6c
-  data.tar.gz: bc765697630a9780752ab2ab9512dbe6bd92cee4f612dfa1ba11437d1f59f3e0c58a7d5a107576704d0018507ce989bf2e8726c165f244bf8757676c301a4f4d
+  metadata.gz: 69b2c38ebddf785a673adb7084ae1f18acc9dce299381ca747af1db6d7a1a2e38772e09d8f4848b7f923d7ade9acac3d3780540c5b42c83b23e547897c3379f3
+  data.tar.gz: 9ef4c658ab06864de8192111596af75c44498ae26c9af3178c63c11e915bda8a6634fa5d1540eb85491085a90e4d58c00772599f4a85df0e286a825befb95b0d

data/.ruby-version

@@ -1 +1 @@
-2.5.1
+3.2.2

data/Gemfile.lock

@@ -1,64 +1,68 @@
 PATH
   remote: .
   specs:
-    fixtury (0.4.1)
+    fixtury (1.0.0.beta1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.3.1)
+    activemodel (7.1.3.2)
+      activesupport (= 7.1.3.2)
+    activerecord (7.1.3.2)
+      activemodel (= 7.1.3.2)
+      activesupport (= 7.1.3.2)
+      timeout (>= 0.4.0)
+    activesupport (7.1.3.2)
+      base64
+      bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2, >= 2.2.2)
-    ansi (1.5.0)
-    autotest (5.0.0)
-      minitest-autotest (~> 1.0)
-    builder (3.2.3)
-    byebug (11.0.1)
-    concurrent-ruby (1.1.6)
-    globalid (0.4.2)
-      activesupport (>= 4.2.0)
-    i18n (1.8.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.6)
+    byebug (11.1.3)
+    concurrent-ruby (1.2.3)
+    connection_pool (2.4.1)
+    drb (2.2.1)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.4)
+      concurrent-ruby (~> 1.0)
+    m (1.6.2)
+      method_source (>= 0.6.7)
+      rake (>= 0.9.2.2)
+    method_source (1.0.0)
+    mini_portile2 (2.8.5)
+    minitest (5.22.2)
+    mocha (2.1.0)
+      ruby2_keywords (>= 0.0.5)
+    mutex_m (0.2.0)
+    rake (13.1.0)
+    ruby2_keywords (0.0.5)
+    sqlite3 (1.7.2)
+      mini_portile2 (~> 2.8.0)
+    timeout (0.4.1)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    metaclass (0.0.4)
-    minitest (5.13.0)
-    minitest-autotest (1.1.1)
-      minitest-server (~> 1.0)
-      path_expander (~> 1.0)
-    minitest-reporters (1.4.2)
-      ansi
-      builder
-      minitest (>= 5.0)
-      ruby-progressbar
-    minitest-server (1.0.5)
-      minitest (~> 5.0)
-    mocha (1.8.0)
-      metaclass (~> 0.0.1)
-    path_expander (1.1.0)
-    rake (13.0.1)
-    ruby-progressbar (1.10.1)
-    sqlite (1.0.2)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    zeitwerk (2.3.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  autotest
-  bundler (~> 2.0)
+  activerecord
+  bundler
   byebug
   fixtury!
   globalid
-  minitest (~> 5.0)
-  minitest-reporters
+  m
+  minitest
   mocha
-  rake (~> 13.0)
-  sqlite
+  rake
+  sqlite3
 
 BUNDLED WITH
-   2.1.4
+   2.5.6

data/README.md

@@ -8,10 +8,10 @@ For example, if a developer is running a test locally in their development envir
 
 ```ruby
 class MyTest < ::ActiveSupport::TestCase
-  include ::Fixtury::TestHooks
+  prepend ::Fixtury::TestHooks
 
-  fixtury "users.fresh"
-  let(:user) { fixtury("users.fresh") }
+  fixtury "users/fresh"
+  let(:user) { fixtury("users/fresh") }
 
   def test_whatever
     assert_eq "Doug", user.first_name
@@ -20,6 +20,6 @@ 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 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.
 
 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/fixtury.gemspec

@@ -27,13 +27,13 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "autotest"
-  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "bundler"
   spec.add_development_dependency "byebug"
   spec.add_development_dependency "globalid"
-  spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "minitest-reporters"
+  spec.add_development_dependency "activerecord"
+  spec.add_development_dependency "m"
+  spec.add_development_dependency "minitest"
   spec.add_development_dependency "mocha"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "sqlite"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "sqlite3"
 end

data/lib/fixtury/definition.rb

@@ -1,52 +1,55 @@
 # frozen_string_literal: true
 
-require "fixtury/definition_executor"
-
 module Fixtury
+  # A class that contains the definition of a fixture. It also maintains a list of it's
+  # dependencies to allow for analysis of the fixture graph.
   class Definition
+    include ::Fixtury::SchemaNode
+    extend ::Forwardable
+
+    # Initializes a new Definition object.
+    #
+    # @param deps [Array] An array of dependencies.
+    # @param opts [Hash] Additional options for the Definition.
+    # @param block [Proc] A block of code to be executed.
+    def initialize(deps: [], **opts, &block)
+      super(**opts)
+
+      @dependencies = Array(deps).each_with_object({}) do |d, deps|
+        parsed_deps = Dependency.from(parent, d)
+        parsed_deps.each do |dep|
+          existing = deps[dep.accessor]
+          raise ArgumentError, "Accessor #{dep.accessor} is already declared by #{existing.search}" if existing
+
+          deps[dep.accessor] = dep
+        end
+      end
 
-    attr_reader :name
-    attr_reader :schema
-    alias parent schema
-    attr_reader :options
-
-    attr_reader :callable
-    attr_reader :enhancements
-
-    def initialize(schema: nil, name:, options: {}, &block)
-      @name = name
-      @schema = schema
       @callable = block
-      @options = options
-      @enhancements = []
-    end
-
-    def enhance(&block)
-      @enhancements << block
-    end
-
-    def enhanced?
-      @enhancements.any?
     end
 
-    def info
-      {
-        name: name,
-        loc: location_from_callable(callable),
-        enhancements: enhancements.map { |e| location_from_callable(e) },
-      }
+    # Returns the type of the schema node.
+    #
+    # @return [String] The schema node type.
+    def schema_node_type
+      "dfn"
     end
 
-    def call(store: nil, execution_context: nil)
-      executor = ::Fixtury::DefinitionExecutor.new(store: store, definition: self, execution_context: execution_context)
-      executor.__call
+    # Indicates whether the Definition acts like a Fixtury definition.
+    #
+    # @return [Boolean] `true` if it acts like a Fixtury definition, `false` otherwise.
+    def acts_like_fixtury_definition?
+      true
     end
 
-    def location_from_callable(callable)
-      return nil unless callable.respond_to?(:source_location)
+    # Delegates the `call` method to the `callable` object.
+    def_delegator :callable, :call
 
-      callable.source_location.join(":")
-    end
+    # Returns the parent schema of the Definition.
+    #
+    # @return [Object] The parent schema.
+    alias schema parent
 
+    attr_reader :callable, :dependencies
   end
 end

data/lib/fixtury/definition_executor.rb

@@ -1,77 +1,48 @@
 # frozen_string_literal: true
 
 module Fixtury
+  # A container that manages the execution of a definition in the context of a store.
   class DefinitionExecutor
 
-    attr_reader :value, :execution_type, :definition, :store, :execution_context
+    attr_reader :value, :definition, :store
 
-    def initialize(store: nil, execution_context: nil, definition:)
+    def initialize(store: nil, definition:)
       @store = store
       @definition = definition
-      @execution_context = execution_context
-      @execution_type = nil
       @value = nil
     end
 
-    def __call
-      maybe_set_store_context do
-        provide_schema_hooks do
-          run_callable(callable: definition.callable, type: :definition)
-          definition.enhancements.each do |e|
-            run_callable(callable: e, type: :enhancement)
-          end
-        end
-      end
-
+    def call
+      run_definition
       value
     end
 
-    def get(name)
-      raise ArgumentError, "A store is required for #{definition.name}" unless store
-
-      store.get(name, execution_context: execution_context)
-    end
-    alias [] get
-
-    def method_missing(method_name, *args, &block)
-      return super unless execution_context
-
-      execution_context.send(method_name, *args, &block)
-    end
-
-    def respond_to_missing?(method_name)
-      return super unless execution_context
-
-      execution_context.respond_to?(method_name, true)
-    end
-
     private
 
-    def run_callable(callable:, type:)
-      @execution_type = type
+    # If the callable has a positive arity we generate a DependencyStore
+    # and yield it to the callable. Otherwise we just instance_eval the callable.
+    # We wrap the actual execution of the definition with a hook for observation.
+    def run_definition
+      callable = definition.callable
 
       @value = if callable.arity.positive?
-        instance_exec(self, &callable)
+        deps = build_dependency_store
+        ::Fixtury.hooks.call(:execution, self) do
+          instance_exec(deps, &callable)
+        end
       else
-        instance_eval(&callable)
-      end
-    end
-
-    def maybe_set_store_context
-      return yield unless store
-
-      store.with_relative_schema(definition.schema) do
-        yield
+        ::Fixtury.hooks.call(:execution, self) do
+          instance_eval(&callable)
+        end
       end
+    rescue Errors::Base
+      raise
+    rescue => e
+      raise Errors::DefinitionExecutionError.new(definition.pathname, e)
     end
 
-    def provide_schema_hooks
-      return yield unless definition.schema
-
-      @value = definition.schema.around_fixture_hook(self) do
-        yield
-        value
-      end
+    def build_dependency_store
+      DependencyStore.new(definition: definition, store: store)
     end
 
   end

data/lib/fixtury/dependency.rb

@@ -0,0 +1,52 @@
+module Fixtury
+  class Dependency
+
+    # Resolve a Dependency from a multitude of input types
+    # @param parent [Fixtury::Definition] the parent definition
+    # @param thing [Fixtury::Dependency, Hash, Array, String, Symbol] the thing to resolve
+    #   @option thing [Fixtury::Dependency] a dependency will be cloned.
+    #   @option thing [Hash] a hash with exactly one key will be resolved as { accessor => search }.
+    #   @option thing [Array] an array with two elements will be resolved as [ accessor, search ].
+    #   @option thing [String, Symbol] a string or symbol will be resolved as both the accessor and the search.
+    # @return [Array<Fixtury::Dependency>] the resolved dependency
+    def self.from(parent, thing)
+      out = case thing
+      when self
+        Dependency.new(parent: parent, search: thing.search, accessor: thing.accessor)
+      when Hash
+        thing.each_with_object([]) do |(k, v), arr|
+          arr << Dependency.new(parent: parent, search: v, accessor: k)
+        end
+      when Array
+        raise ArgumentError, "Array must have an even number of elements" unless thing.size % 2 == 0
+
+        thing.each_slice(2).map do |pair|
+          Dependency.new(parent: parent, search: pair[1], accessor: pair[0])
+        end
+      when String, Symbol
+        Dependency.new(parent: parent, search: thing, accessor: thing)
+      else
+        raise ArgumentError, "Unknown dependency type: #{thing.inspect}"
+      end
+
+      Array(out)
+    end
+
+    attr_reader :parent, :search, :accessor
+
+    def initialize(parent:, search:, accessor:)
+      @parent = parent
+      @search = search.to_s
+      @accessor = accessor.to_s.split("/").last
+    end
+
+    def definition
+      @definition ||= parent&.get!(search)
+    end
+
+    def inspect
+      "#{self.class}(accessor: #{accessor.inspect}, search: #{search.inspect}, parent: #{parent.name.inspect})"
+    end
+
+  end
+end

data/lib/fixtury/dependency_store.rb

@@ -0,0 +1,45 @@
+module Fixtury
+  # An object which allows access to a specific subset of fixtures
+  # in the context of a definition's dependencies.
+  class DependencyStore
+
+    attr_reader :definition, :store
+
+    def initialize(definition:, store:)
+      @definition = definition
+      @store = store
+    end
+
+    def inspect
+      "#{self.class}(definition: #{definition.pathname.inspect}, dependencies: #{definition.dependencies.keys.inspect})"
+    end
+
+    # Returns the value of the dependency with the given key
+    #
+    # @param key [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)
+      end
+      store.get(dep.definition.pathname)
+    end
+    alias [] get
+
+    # If an accessor is used and we recognize the accessor as a dependency
+    # of our definition, we return the value of the dependency.
+    def method_missing(method, *args, &block)
+      if definition.dependencies.key?(method.to_s)
+        get(method)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      definition.dependencies.key?(method.to_s) || super
+    end
+
+  end
+end

data/lib/fixtury/errors.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Fixtury
+  module Errors
+
+    class Base < StandardError
+
+    end
+
+    class AlreadyDefinedError < Base
+
+      def initialize(name)
+        super("An element identified by #{name.inspect} already exists.")
+      end
+
+    end
+
+    class CircularDependencyError < Base
+
+      def initialize(name)
+        super("One of the dependencies of #{name.inspect} is dependent on #{name.inspect}.")
+      end
+
+    end
+
+    class DefinitionExecutionError < Base
+
+      def initialize(pathname, error)
+        super("Error while building #{pathname.inspect}: #{error}")
+      end
+
+    end
+
+    class SchemaNodeNotDefinedError < Base
+
+      def initialize(pathname, search)
+        super("A schema node identified by #{search.inspect} could not be found from #{pathname.inspect}.")
+      end
+
+    end
+
+    class SchemaNodeNameInvalidError < Base
+      def initialize(parent_name, child_name)
+        super("The schema node name #{child_name.inspect} must start with #{parent_name.inspect} to be added to it.")
+      end
+    end
+
+    class OptionCollisionError < Base
+
+      def initialize(schema_name, option_key, old_value, new_value)
+        super("The #{schema_name.inspect} schema #{option_key.inspect} option value of #{old_value.inspect} conflicts with the new value #{new_value.inspect}.")
+      end
+
+    end
+
+    class UnrecognizableLocatorError < Base
+
+      def initialize(action, thing)
+        super("Locator did not recognize #{thing} during #{action}")
+      end
+
+    end
+
+    class IsolatedMutationError < Base
+
+    end
+
+    class UnknownTestDependencyError < Base
+
+    end
+
+    class UnknownDependencyError < Base
+
+      def initialize(defn, key)
+        super("#{defn.pathname} does not contain the provided dependency: #{key}")
+      end
+
+    end
+
+  end
+end

data/lib/fixtury/hooks.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Fixtury
+  # Provides a mechanism for observing Fixtury lifecycle events.
+  class Hooks
+
+    attr_reader :hooks
+
+    def initialize
+      @hooks = Hash.new { |h, k| h[k] = { before: [], after: [], around: [], on: [] } }
+    end
+
+    # Register a hook to be called around the execution of a trigger.
+    # The around hook should ensure the return value is preserved.
+    # This also means that the hook itself could modify the return value.
+    #
+    # @param trigger_type [Symbol] the type of trigger to hook into
+    # @param hook [Proc] the hook to be called
+    def around(trigger_type, &hook)
+      register_hook(trigger_type, :around, hook)
+    end
+
+    # Register a hook to be called before the execution of a trigger.
+    # (see #register_hook)
+    def before(trigger_type, &hook)
+      register_hook(trigger_type, :before, hook)
+    end
+
+    # Register a hook to be called after the execution of a trigger.
+    # The return value will be provided as the first argument to the hook.
+    # (see #register_hook)
+    def after(trigger_type, &hook)
+      register_hook(trigger_type, :after, hook)
+    end
+
+    # Similar to after, but the return value is not injected.
+    # (see #register_hook)
+    def on(trigger_type, &hook)
+      register_hook(trigger_type, :on, hook)
+    end
+
+    # Trigger the hooks registered for a specific trigger type.
+    # :before hooks will be triggered first, followed by :around hooks,
+    # :on hooks, and finally :after hooks.
+    #
+    # @param trigger_type [Symbol] the type of trigger to initiate
+    # @param args [Array] arguments to be passed to the hooks
+    # @param block [Proc] a block of code to be executed
+    # @return [Object] the return value of the block
+    def call(trigger_type, *args, &block)
+      hook_lists = hooks[trigger_type.to_sym]
+
+      call_inline_hooks(hook_lists[:before], *args)
+      return_value = call_around_hooks(hook_lists[:around], 0, block, *args)
+      call_inline_hooks(hook_lists[:on], *args)
+      call_inline_hooks(hook_lists[:after], return_value, *args)
+
+      return_value
+    end
+
+    private
+
+    # Register a hook to be called for a specific trigger type and hook type.
+    #
+    # @param trigger_type [Symbol] the type of trigger to hook into
+    # @param hook_type [Symbol] the point in the trigger to hook into
+    # @param hook [Proc] the hook to be called
+    # @return [Fixtury::Hooks] the current instance
+    def register_hook(trigger_type, hook_type, hook)
+      hooks[trigger_type.to_sym][hook_type.to_sym] << hook
+      self
+    end
+
+    def call_around_hooks(hook_list, idx, block, *args)
+      if idx >= hook_list.length
+        block.call
+      else
+        hook_list[idx].call(*args) do
+          call_around_hooks(hook_list, idx + 1, block, *args)
+        end
+      end
+    end
+
+    def call_inline_hooks(hook_list, *args)
+      hook_list.each do |hook|
+        hook.call(*args)
+      end
+    end
+  end
+end