fixtury 0.4.1 → 1.0.0.beta2

data/lib/fixtury/store.rb

@@ -1,82 +1,94 @@
 # frozen_string_literal: true
 
+require "concurrent/atomic/thread_local_var"
 require "fileutils"
 require "singleton"
 require "yaml"
-require "fixtury/locator"
-require "fixtury/errors/circular_dependency_error"
-require "fixtury/reference"
 
 module Fixtury
+  # A store is a container for built fixture references. It is responsible for loading and caching fixtures
+  # based on a schema and a locator.
   class Store
 
-    cattr_accessor :instance
+    attr_reader :locator
+    attr_reader :schema
+    attr_reader :ttl
 
-    attr_reader :filepath, :references, :ttl, :auto_refresh_expired
-    attr_reader :schema, :locator
-    attr_reader :log_level
-
-    def initialize(
-      filepath: nil,
-      locator: ::Fixtury::Locator.instance,
-      ttl: nil,
-      schema: nil,
-      auto_refresh_expired: false
-    )
+    # 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)
       @schema = schema || ::Fixtury.schema
-      @locator = locator
-      @filepath = filepath
-      @references = @filepath && ::File.file?(@filepath) ? ::YAML.load_file(@filepath) : {}
-      @ttl = ttl ? ttl.to_i : ttl
-      @auto_refresh_expired = !!auto_refresh_expired
-      self.class.instance ||= self
+      @locator = ::Fixtury::Locator.from(locator)
+      @ttl = ttl&.to_i
+      self.references = ::Fixtury.configuration.stored_references
     end
 
-    def dump_to_file
-      return unless filepath
+    def references
+      @references ||= ::Concurrent::ThreadLocalVar.new({})
+      @references.value
+    end
 
-      ::FileUtils.mkdir_p(File.dirname(filepath))
+    def references=(value)
+      references.clear
+      @references.value = value
+    end
 
-      writable = references.each_with_object({}) do |(full_name, ref), h|
-        h[full_name] = ref if ref.real?
-      end
+    def loaded_isolation_keys
+      @loaded_isolation_keys ||= ::Concurrent::ThreadLocalVar.new({})
+      @loaded_isolation_keys.value
+    end
 
-      ::File.open(filepath, "wb") { |io| io.write(writable.to_yaml) }
+    # Empty the store of any references and loaded isolation keys.
+    def reset
+      references.clear
+      loaded_isolation_keys.clear
     end
 
-    def clear_expired_references!
-      return unless ttl
+    # Summarize the current state of the store.
+    #
+    # @return [String]
+    def inspect
+      parts = []
+      parts << "schema: #{schema.inspect}"
+      parts << "locator: #{locator.inspect}"
+      parts << "ttl: #{ttl.inspect}" if ttl
+      parts << "references: #{references.size}"
+
+      "#{self.class}(#{parts.join(", ")})"
+    end
 
+    # Clear any references that are beyond their ttl or are no longer recognizable by the locator.
+    #
+    # @return [void]
+    def clear_stale_references!
       references.delete_if do |name, ref|
-        is_expired = ref_invalid?(ref)
-        log("expiring #{name}", level: LOG_LEVEL_DEBUG) if is_expired
-        is_expired
+        stale = reference_stale?(ref)
+        log("expiring #{name}", level: LOG_LEVEL_DEBUG) if stale
+        stale
       end
     end
 
+    # Load all fixtures in the target schema, defaulting to the store's schema.
+    # This will load all fixtures in the schema and any child schemas.
+    #
+    # @param schema [Fixtury::Schema] The schema to load, defaults to the store's schema.
+    # @return [void]
     def load_all(schema = self.schema)
-      schema.definitions.each_pair do |_key, dfn|
-        get(dfn.name)
+      schema.children.each_value do |item|
+        get(item.name) if item.acts_like?(:fixtury_definition)
+        load_all(item) if item.acts_like?(:fixtury_schema)
       end
-
-      schema.children.each_pair do |_key, ns|
-        load_all(ns)
-      end
-    end
-
-    def clear_cache!(pattern: nil)
-      pattern ||= "*"
-      pattern = "/" + pattern unless pattern.start_with?("/")
-      glob = pattern.end_with?("*")
-      pattern = pattern[0...-1] if glob
-      references.delete_if do |key, _value|
-        hit = glob ? key.start_with?(pattern) : key == pattern
-        log("clearing #{key}", level: LOG_LEVEL_DEBUG) if hit
-        hit
-      end
-      dump_to_file
     end
 
+    # Temporarily set a contextual schema to use for loading fixtures. This is
+    # useful when evaluating dependencies of a definition while still storing the results.
+    #
+    # @param schema [Fixtury::Schema] The schema to use.
+    # @yield [void] The block to execute with the given schema.
+    # @return [Object] The result of the block
     def with_relative_schema(schema)
       prior = @schema
       @schema = schema
@@ -85,76 +97,148 @@ module Fixtury
       @schema = prior
     end
 
-    def loaded?(name)
-      dfn = schema.get_definition!(name)
-      full_name = dfn.name
-      ref = references[full_name]
+    # Is a fixture for the given search already loaded?
+    #
+    # @param search [String] The name of the fixture to search for.
+    # @return [TrueClass, FalseClass] `true` if the fixture is loaded, `false` otherwise.
+    def loaded?(search)
+      dfn = schema.get!(search)
+      ref = references[dfn.pathname]
       result = ref&.real?
-      log(result ? "hit #{full_name}" : "miss #{full_name}", level: LOG_LEVEL_ALL)
+      log(result ? "hit #{dfn.pathname}" : "miss #{dfn.pathname}", level: LOG_LEVEL_ALL)
       result
     end
 
-    def get(name, execution_context: nil)
-      dfn = schema.get_definition!(name)
-      full_name = dfn.name
-      ref = references[full_name]
+    # Fetch a fixture by name. This will load the fixture if it has not been loaded yet.
+    # If a definition contains an isolation key, all fixtures with the same isolation key will be loaded.
+    #
+    # @param search [String] The name of the fixture to search for.
+    # @return [Object] The loaded fixture.
+    # @raise [Fixtury::Errors::CircularDependencyError] if a circular dependency is detected.
+    # @raise [Fixtury::Errors::SchemaNodeNotDefinedError] if the search does not return a node.
+    # @raise [Fixtury::Errors::UnknownDefinitionError] if the search does not return a definition.
+    # @raise [Fixtury::Errors::DefinitionExecutorError] if the definition executor fails.
+    def get(search)
+      log("getting #{search} relative to #{schema.pathname}", level: LOG_LEVEL_DEBUG)
+
+      # Find the definition.
+      dfn = schema.get!(search)
+      raise ArgumentError, "#{search.inspect} must refer to a definition" unless dfn.acts_like?(:fixtury_definition)
 
+      pathname = dfn.pathname
+
+      # 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)
+
+      # See if we already hold a reference to the fixture.
+      ref = references[pathname]
+
+      # If the reference is a placeholder, we have a circular dependency.
       if ref&.holder?
-        raise ::Fixtury::Errors::CircularDependencyError, full_name
+        raise Errors::CircularDependencyError, pathname
       end
 
-      if ref && auto_refresh_expired && ref_invalid?(ref)
-        log("refreshing #{full_name}", level: LOG_LEVEL_DEBUG)
-        clear_ref(full_name)
+      # If the reference is stale, we should refresh it.
+      # We do so by clearing it from the store and setting the reference to nil.
+      if ref && reference_stale?(ref)
+        log("refreshing #{pathname}", level: LOG_LEVEL_DEBUG)
+        clear_reference(pathname)
         ref = nil
       end
 
       value = nil
 
       if ref
-        log("hit #{full_name}", level: LOG_LEVEL_ALL)
-        value = load_ref(ref.value)
+        log("hit #{pathname}", level: LOG_LEVEL_ALL)
+        value = locator.load(ref.locator_key)
         if value.nil?
-          clear_ref(full_name)
-          log("missing #{full_name}", level: LOG_LEVEL_ALL)
+          clear_reference(pathname)
+          ref = nil
+          log("missing #{pathname}", level: LOG_LEVEL_ALL)
         end
       end
 
       if value.nil?
         # set the references to a holder value so any recursive behavior ends up hitting a circular dependency error if the same fixture load is attempted
-        references[full_name] = ::Fixtury::Reference.holder(full_name)
-
-        value = dfn.call(store: self, execution_context: execution_context)
+        references[pathname] = ::Fixtury::Reference.holder(pathname)
+
+        begin
+          executor = ::Fixtury::DefinitionExecutor.new(store: self, definition: dfn)
+          value = executor.call
+        rescue StandardError
+          clear_reference(pathname)
+          raise
+        end
 
-        log("store #{full_name}", level: LOG_LEVEL_DEBUG)
+        log("store #{pathname}", level: LOG_LEVEL_DEBUG)
 
-        ref = dump_ref(full_name, value)
-        ref = ::Fixtury::Reference.new(full_name, ref)
-        references[full_name] = ref
+        locator_key = locator.dump(value, context: pathname)
+        references[pathname] = ::Fixtury::Reference.new(pathname, locator_key)
       end
 
       value
     end
     alias [] get
 
-    def load_ref(ref)
-      locator.load(ref)
+    protected
+
+    # Determine if the given pathname is already loaded or is currently being loaded.
+    #
+    # @param pathname [String] The pathname to check.
+    # @return [TrueClass, FalseClass] `true` if the pathname is already loaded or is currently being loaded, `false` otherwise.
+    def loaded_or_loading?(pathname)
+      !!references[pathname]
     end
 
-    def dump_ref(_name, value)
-      locator.dump(value)
+    # Load all fixtures with the given isolation key in the target schema
+    # if we're not already attempting to load them.
+    def maybe_load_isolation_dependencies(isolation_key)
+      return if loaded_isolation_keys[isolation_key]
+      loaded_isolation_keys[isolation_key] = true
+
+      load_isolation_dependencies(isolation_key, schema.first_ancestor)
+    end
+
+    # Load all fixtures with the given isolation key in the target schema.
+    #
+    # @param isolation_key [String] The isolation key to load fixtures for.
+    # @param target_schema [Fixtury::Schema] The schema to search within.
+    # @return [void]
+    def load_isolation_dependencies(isolation_key, target_schema)
+      target_schema.children.each_value do |child|
+        if child.acts_like?(:fixtury_definition)
+          next unless child.isolation_key == isolation_key
+          next if loaded_or_loading?(child.pathname)
+
+          get(child.pathname)
+        elsif child.acts_like?(:fixtury_schema)
+          load_isolation_dependencies(isolation_key, child)
+        else
+          raise NotImplementedError, "Unknown isolation loading behavior: #{child.class.name}"
+        end
+      end
     end
 
-    def clear_ref(name)
-      references.delete(name)
+    # Remove a reference at the given pathname from the stored references.
+    #
+    # @param pathname [String] The pathname to remove.
+    # @return [void]
+    def clear_reference(pathname)
+      references.delete(pathname)
     end
 
-    def ref_invalid?(ref)
+    # Determine if a reference is stale. A reference is stale if it is beyond its ttl or
+    # if it is no longer recognizable by the locator.
+    #
+    # @param ref [Fixtury::Reference] The reference to check.
+    # @return [TrueClass, FalseClass] `true` if the reference is stale, `false` otherwise.
+    def reference_stale?(ref)
       return true if ttl && ref.created_at < (Time.now.to_i - ttl)
 
-      !locator.recognize?(ref.value)
+      !locator.recognizable_key?(ref.locator_key)
     end
 
+    # Log a contextual message using Fixtury.log
     def log(msg, level:)
       ::Fixtury.log(msg, level: level, name: "store")
     end

data/lib/fixtury/test_hooks.rb

@@ -1,166 +1,190 @@
 # frozen_string_literal: true
 
-require "fixtury/store"
+require "fixtury"
 require "active_support/core_ext/class/attribute"
 
 module Fixtury
+  # TestHooks 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
+  # case is torn down.
+  #
+  # The module also provides a way to define fixture dependencies, and will
+  # automatically load those dependencies before the test case is setup.
+  #
+  # @example
+  #   class MyTest < Minitest::Test
+  #     prepend Fixtury::TestHooks
+  #
+  #     fixtury "user"
+  #     fixtury "post"
+  #
+  #     def test_something
+  #       user # => returns the `users` fixture
+  #       user.do_some_mutation
+  #       assert_equal 1, user.mutations.count
+  #     end
+  #   end
+  #
+  #   # In the above example, the `users` and `posts` fixtures will be loaded
+  #   # before the test case is setup, and any changes will be rolled back
+  #   # after the test case is torn down.
+  #
+  #   # The `fixtury` method also accepts a `:as` option, which can be used to
+  #   # define a named accessor method for a fixture. This is useful when
+  #   # defining a single fixture, and you want to access it using a different
+  #   # name. If no `:as` option is provided, the fixture will be accessed
+  #   # using the last segment of the fixture's pathname.
+  #
+  #   class MyTest < Minitest::Test
+  #     prepend Fixtury::TestHooks
+  #
+  #     fixtury "/my/user_record", as: :user
+  #
+  #   end
+  #
+  # A Set object named fixtury_dependencies is made available on the test class.
+  # This allows you to load all Minitest runnables and analyze what fixtures are
+  # needed. This is very helpful in CI pipelines when you want to prepare all fixtures
+  # ahead of time to share between multiple processes.
+  #
+  # 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
 
-    extend ::ActiveSupport::Concern
-
-    included do
-      class_attribute :fixtury_dependencies
-      self.fixtury_dependencies = Set.new
+    def self.prepended(klass)
+      klass.class_attribute :fixtury_dependencies
+      klass.fixtury_dependencies = Set.new
+      klass.extend ClassMethods
+    end
 
-      class_attribute :local_fixtury_dependencies
-      self.local_fixtury_dependencies = Set.new
+    def self.included(klass)
+      raise ArgumentError, "#{name} should be prepended, not included"
     end
 
     module ClassMethods
 
-      def fixtury(*names, &definition)
-        opts = names.extract_options!
-
-        # define fixtures if blocks are given
-        if block_given?
-          raise ArgumentError, "A fixture cannot be defined in an anonymous class" if name.nil?
-
-          namespace = fixtury_namespace
-
-          ns = ::Fixtury.schema
-
-          namespace.split("/").each do |ns_name|
-            ns = ns.namespace(ns_name){}
-          end
-
-          names.map! do |fixture_name|
-            ns.fixture(fixture_name, &definition)
-            new_name = "/#{namespace}/#{fixture_name}"
-            self.local_fixtury_dependencies += [new_name]
-            new_name
-          end
-
-        # otherwise, just record the dependency
-        else
-          self.fixtury_dependencies += names.flatten.compact.map(&:to_s)
+      # Declare fixtury dependencies for this test case. This will automatically
+      # load the fixtures before the test case is setup, and rollback any changes
+      # after the test case is torn down.
+      #
+      # @param searches [Array<String>] A list of fixture names to load. These should be resolvable paths relative to Fixtury.schema (root).
+      # @param opts [Hash] A list of options to customize the behavior of the fixtures.
+      #   @option opts [Symbol, String, Boolean] :as (true) The name of the accessor method to define for the fixture. If true (default), the last segment will be used.
+      # @return [void]
+      def fixtury(*searches, **opts)
+        pathnames = searches.map do |search|
+          dfn = Fixtury.schema.get!(search)
+          dfn.pathname
         end
 
+        self.fixtury_dependencies += pathnames
+
         accessor_option = opts[:as]
         accessor_option = opts[:accessor] if accessor_option.nil? # old version, backwards compatability
         accessor_option = accessor_option.nil? ? true : accessor_option
 
         if accessor_option
 
-          if accessor_option != true && names.length > 1
+          if accessor_option != true && pathnames.length > 1
             raise ArgumentError, "A named :as option is only available when providing one fixture"
           end
 
-          names.each do |fixture_name|
-            method_name = accessor_option == true ? fixture_name.split("/").last : accessor_option
-            ivar = :"@#{method_name}"
+          pathnames.each do |pathname|
+            method_name = (accessor_option == true ? pathname.split("/").last : accessor_option).to_sym
+
+            if method_defined?(method_name)
+              raise ArgumentError, "A method by the name of #{method_name} already exists in #{self}"
+            end
+
+            ivar = :"@fixtury_#{method_name}"
 
             class_eval <<-EV, __FILE__, __LINE__ + 1
               def #{method_name}
                 return #{ivar} if defined?(#{ivar})
 
-                value = fixtury("#{fixture_name}")
-                #{ivar} = value
+                #{ivar} = fixtury("#{pathname}")
               end
             EV
           end
         end
       end
 
-      def fixtury_namespace
-        name.underscore
-      end
-
     end
 
-    def fixtury(name)
-      return nil unless fixtury_store
-
-      name = name.to_s
-
-      # in the case that we're looking for a relative fixture, see if it's registered relative to the test's namespace.
-      unless name.include?("/")
-        local_name = "/#{self.class.fixtury_namespace}/#{name}"
-        if local_fixtury_dependencies.include?(local_name)
-          return fixtury_store.get(local_name, execution_context: self)
-        end
-      end
-
-      unless fixtury_dependencies.include?(name) || local_fixtury_dependencies.include?(name)
-        raise ArgumentError, "Unrecognized fixtury dependency `#{name}` for #{self.class}"
-      end
-
-      fixtury_store.get(name, execution_context: self)
+    # Minitest before_setup hook. This will load the fixtures before the test.
+    def before_setup(...)
+      fixtury_setup if fixtury_dependencies.any?
+      super
     end
 
-    def fixtury_store
-      ::Fixtury::Store.instance
+    # Minitest after_teardown hook. This will rollback any changes made to the fixtures after the test.
+    def after_teardown(...)
+      super
+      fixtury_teardown if fixtury_dependencies.any?
     end
 
-    def fixtury_loaded?(name)
-      return false unless fixtury_store
+    # Access a fixture via a search term. This will access the fixture from the Fixtury store.
+    # If the fixture was not declared as a dependency, an error will be raised.
+    #
+    # @param search [String] The search term to use to find the fixture.
+    # @return [Object] The fixture.
+    # @raise [Fixtury::Errors::UnknownTestDependencyError] if the search term does not result in a declared dependency.
+    # @raise [Fixtury::Errors::SchemaNodeNotDefinedError] if the search term does not result in a recognized fixture.
+    def fixtury(search)
+      dfn = Fixtury.schema.get!(search)
+
+      unless fixtury_dependencies.include?(dfn.pathname)
+        raise Errors::UnknownTestDependencyError, "Unrecognized fixtury dependency `#{dfn.pathname}` for #{self.class}"
+      end
 
-      fixtury_store.loaded?(name)
+      Fixtury.store.get(dfn.pathname)
     end
 
+    # Retrieve all database connections that are currently registered with a writing role.
+    #
+    # @return [Array<ActiveRecord::ConnectionAdapters::AbstractAdapter>] The list of database connections.
     def fixtury_database_connections
-      ActiveRecord::Base.connection_handler.connection_pool_list.map(&:connection)
-    end
+      return [] unless defined?(ActiveRecord::Base)
 
-    # piggybacking activerecord fixture setup for now.
-    def setup_fixtures(*args)
-      if fixtury_dependencies.any? || local_fixtury_dependencies.any?
-        setup_fixtury_fixtures
-      else
-        super
-      end
+      ActiveRecord::Base.connection_handler.connection_pool_list(:writing).map(&:connection)
     end
 
-    # piggybacking activerecord fixture setup for now.
-    def teardown_fixtures(*args)
-      if fixtury_dependencies.any? || local_fixtury_dependencies.any?
-        teardown_fixtury_fixtures
-      else
-        super
-      end
-    end
-
-    def setup_fixtury_fixtures
+    # Load all dependenct fixtures and begin a transaction for each database connection.
+    def fixtury_setup
+      Fixtury.store.clear_stale_references!
+      fixtury_load_all_fixtures!
       return unless fixtury_use_transactions?
 
-      clear_expired_fixtury_fixtures!
-      load_all_fixtury_fixtures!
-
       fixtury_database_connections.each do |conn|
         conn.begin_transaction joinable: false
       end
     end
 
-    def teardown_fixtury_fixtures
+    # Rollback any changes made to the fixtures
+    def fixtury_teardown
       return unless fixtury_use_transactions?
 
-      fixtury_database_connections.each(&:rollback_transaction)
+      fixtury_database_connections.each do |conn|
+        conn.rollback_transaction if conn.open_transactions.positive?
+      end
     end
 
-    def clear_expired_fixtury_fixtures!
-      return unless fixtury_store
-
-      fixtury_store.clear_expired_references!
-    end
+    # Load all fixture dependencies that have not previously been loaded into the store.
+    #
+    # @return [void]
+    def fixtury_load_all_fixtures!
+      fixtury_dependencies.each do |name|
+        next if Fixtury.store.loaded?(name)
 
-    def load_all_fixtury_fixtures!
-      (fixtury_dependencies | local_fixtury_dependencies).each do |name|
-        unless fixtury_loaded?(name)
-          ::Fixtury.log("preloading #{name.inspect}", name: "test", level: ::Fixtury::LOG_LEVEL_INFO)
-          fixtury(name)
-        end
+        ::Fixtury.log("preloading #{name.inspect}", name: "test", level: ::Fixtury::LOG_LEVEL_INFO)
+        fixtury(name)
       end
     end
 
+    # Adhere to common Rails test transaction settings.
     def fixtury_use_transactions?
       return use_transactional_tests if respond_to?(:use_transactional_tests)
       return use_transactional_fixtures if respond_to?(:use_transactional_fixtures)

data/lib/fixtury/version.rb

@@ -2,6 +2,6 @@
 
 module Fixtury
 
-  VERSION = "0.4.1"
+  VERSION = "1.0.0.beta2"
 
 end