fixtury 1.0.0.beta1 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02d3acd3d4f3904ae6e00f53e81a5c29b3aa65b53a0bba96029625e99deb618e
-  data.tar.gz: 12a1fa78d029e6781ce240a3bed206b63b0fd02589773a84deeb80f18556585d
+  metadata.gz: cd14efe323fc1de1a2ec63805508e7fb816db30f028998e951c78e95cbe14dfe
+  data.tar.gz: e0a1055bf1ebfff930569a5b678b1b433c21b48e2a4305197bdeb7938e22332a
 SHA512:
-  metadata.gz: 69b2c38ebddf785a673adb7084ae1f18acc9dce299381ca747af1db6d7a1a2e38772e09d8f4848b7f923d7ade9acac3d3780540c5b42c83b23e547897c3379f3
-  data.tar.gz: 9ef4c658ab06864de8192111596af75c44498ae26c9af3178c63c11e915bda8a6634fa5d1540eb85491085a90e4d58c00772599f4a85df0e286a825befb95b0d
+  metadata.gz: d819ff4d3096eee7a2ac3c4617f89463b28b7826f3046efbf391408b595b8758f52ac556c8e337eae396109839a148a033750b2ae5ac10ebddce27a041344be3
+  data.tar.gz: febce1127eceb8f3ef6e148b7212591e657dab0d62f4b57d0ab6e8b6f8ba8d9c210180f6713fe78d5de6ce35356a5c448cfd9903d60a406efe5bc835c9cbbe11

data/Gemfile.lock

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

data/lib/fixtury/configuration.rb

@@ -0,0 +1,117 @@
+require "digest"
+
+module Fixtury
+  # Provides an interface for managing settings and dependencies related to fixture
+  # generation.
+  class Configuration
+
+    attr_reader :filepath, :fixture_files, :dependency_files
+
+    def initialize
+      @filepath = nil
+      @fixture_files = Set.new
+      @dependency_files = Set.new
+    end
+
+    def log_level
+      return @log_level if @log_level
+
+      @log_level = ENV["FIXTURY_LOG_LEVEL"]
+      @log_level ||= DEFAULT_LOG_LEVEL
+      @log_level = @log_level.to_s.to_sym
+      @log_level
+    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.
+    def add_fixture_path(*path_or_globs)
+      @fixture_files = fixture_files | Dir[*path_or_globs]
+    end
+    alias add_fixture_paths add_fixture_path
+
+    # Add a file or glob pattern to the list of dependency files.
+    #
+    # @param path_or_globs [String, Array<String>] The file or glob pattern(s) to add.
+    def add_dependency_path(*path_or_globs)
+      @dependency_files = dependency_files | Dir[*path_or_globs]
+    end
+    alias add_dependency_paths add_dependency_path
+
+    # The references stored in the dependency file. When stores are initialized
+    # these will be used to bootstrap the references.
+    #
+    # @return [Hash] The references stored in the dependency file.
+    def stored_references
+      return {} if stored_data.nil?
+
+      stored_data[:references] || {}
+    end
+
+    # Dump the current state of the dependency manager to the storage file.
+    def dump_file
+      return unless filepath
+
+      FileUtils.mkdir_p(File.dirname(filepath))
+      File.binwrite(filepath, file_data.to_yaml)
+    end
+
+    private
+
+    def file_data
+      checksums = {}
+      calculate_checksums do |filepath, checksum|
+        checksums[filepath] = checksum
+      end
+
+      {
+        dependencies: checksums,
+        references: ::Fixtury.store.references,
+      }
+    end
+
+    def stored_data
+      return nil unless filepath
+      return nil unless File.file?(filepath)
+
+      YAML.unsafe_load_file(filepath)
+    end
+
+    def files_changed?
+      return true 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
+
+        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
+    end
+
+    def calculate_checksums(&block)
+      (fixture_files.to_a | dependency_files.to_a).sort.each do |filepath|
+        yield filepath, Digest::MD5.file(filepath).hexdigest
+      end
+    end
+
+
+  end
+end

data/lib/fixtury/definition.rb

@@ -28,13 +28,6 @@ module Fixtury
       @callable = block
     end
 
-    # Returns the type of the schema node.
-    #
-    # @return [String] The schema node type.
-    def schema_node_type
-      "dfn"
-    end
-
     # Indicates whether the Definition acts like a Fixtury definition.
     #
     # @return [Boolean] `true` if it acts like a Fixtury definition, `false` otherwise.

data/lib/fixtury/locator.rb

@@ -8,6 +8,24 @@ module Fixtury
   # The backend is expected to implement the following methods: recognizable_key?, recognized_value?, load_recognized_reference, dump_recognized_value.
   class Locator
 
+    def self.from(thing)
+      case thing
+      when ::Fixtury::Locator
+        thing
+      when nil
+         ::Fixtury::Locator.new
+      when Symbol
+        begin
+          require "fixtury/locator_backend/#{thing}"
+        rescue LoadError
+        end
+        backend = ::Fixtury::LocatorBackend.const_get(thing.to_s.camelize, false).new
+        ::Fixtury::Locator.new(backend: backend)
+      else
+        raise ArgumentError, "Unable to create a locator from #{thing.inspect}"
+      end
+    end
+
     attr_reader :backend
 
     def initialize(backend: ::Fixtury::LocatorBackend::Memory.new)

data/lib/fixtury/locator_backend/{globalid.rb → global_id.rb}

@@ -5,7 +5,7 @@ require "globalid"
 
 module Fixtury
   module LocatorBackend
-    class GlobalID
+    class GlobalId
 
       include ::Fixtury::LocatorBackend::Common
 

data/lib/fixtury/locator_backend/memory.rb

@@ -8,7 +8,7 @@ module Fixtury
 
       include ::Fixtury::LocatorBackend::Common
 
-      MATCHER = /^fixtury-oid-(?<object_id>[\d]+)$/.freeze
+      MATCHER = /^fixtury-oid-(?<process_id>[\d]+)-(?<object_id>[\d]+)$/.freeze
 
       def recognizable_key?(locator_value)
         locator_value.is_a?(String) && MATCHER.match?(locator_value)
@@ -21,6 +21,7 @@ module Fixtury
       def load_reference(locator_value)
         match = MATCHER.match(locator_value)
         return nil unless match
+        return nil unless match[:process_id].to_i == Process.pid
 
         ::ObjectSpace._id2ref(match[:object_id].to_i)
       rescue RangeError
@@ -28,7 +29,7 @@ module Fixtury
       end
 
       def dump_value(stored_value)
-        "fixtury-oid-#{stored_value.object_id}"
+        "fixtury-oid-#{Process.pid}-#{stored_value.object_id}"
       end
 
     end

data/lib/fixtury/schema.rb

@@ -1,43 +1,69 @@
 # frozen_string_literal: true
 
 module Fixtury
+  # A Fixtury::SchemaNode implementation that represents a top-level schema
+  # or a namespace within a schema.
   class Schema
 
     include ::Fixtury::SchemaNode
 
+    # @param name [String] the name of the schema, defaults to "" to represent
+    # a new top-level schema.
     def initialize(name: "", **options)
       super(name: name, **options)
     end
 
+    # Object#acts_like? adherence.
     def acts_like_fixtury_schema?
       true
     end
 
+    # Open up self for child definitions.
+    # @param block [Proc] The block to be executed in the context of the schema.
+    # @return [Fixtury::Schema] self
     def define(&block)
       instance_eval(&block)
       self
     end
 
+    # Returns "schema" if top-level, otherwise returns "namespace".
+    # @return [String] the type of the schema node.
     def schema_node_type
-      first_ancestor? ? "schema" : "ns"
+      first_ancestor? ? "schema" : "namespace"
     end
 
-    def namespace(name, **options, &block)
-      child = get("./#{name}")
+    # Create a child schema at the given relative name. If a child by the name
+    # already exists it will be reopened as long as it's a fixtury schema.
+    #
+    # @param relative_name [String] The relative name of the child schema.
+    # @param options [Hash] Additional options for the child schema, applied after instantiation.
+    # @param block [Proc] A block of code to be executed in the context of the child schema.
+    # @return [Fixtury::Schema] The child schema.
+    # @raise [Fixtury::Errors::AlreadyDefinedError] if the child is already defined and not a fixtury schema.
+    def namespace(relative_name, **options, &block)
+      child = get("./#{relative_name}")
 
       if child && !child.acts_like?(:fixtury_schema)
         raise Errors::AlreadyDefinedError, child.pathname
       end
 
-      child ||= self.class.new(name: name, parent: self)
+      child ||= self.class.new(name: relative_name, parent: self)
       child.apply_options!(options)
       child.instance_eval(&block) if block_given?
       child
     end
 
-    def fixture(name, **options, &block)
+    # Create a fixture definition at the given relative name. If the name is already
+    # used, a Fixtury::Errors::AlreadyDefinedError will be raised.
+    #
+    # @param relative_name [String] The relative name of the fixture.
+    # @param options [Hash] Additional options for the fixture.
+    # @param block [Proc] The block representing the build function of the fixture.
+    # @return [Fixtury::Definition] The fixture definition.
+    #
+    def fixture(relative_name, **options, &block)
       ::Fixtury::Definition.new(
-        name: name,
+        name: relative_name,
         parent: self,
         **options,
         &block

data/lib/fixtury/schema_node.rb

@@ -1,4 +1,7 @@
 module Fixtury
+  # This module is used to provide a common interface for all nodes in the schema tree.
+  # Namespaces and fixture definitions adhere to this interface and are provided with
+  # common behaviors for registration, traversal, inspection, etc
   module SchemaNode
 
     extend ActiveSupport::Concern
@@ -6,9 +9,16 @@ module Fixtury
     VALID_NODE_NAME = /^[a-zA-Z0-9_]*$/
 
     included do
-      attr_reader :name, :pathname, :parent, :children, :options
+      attr_reader :name, :pathname, :parent, :first_ancestor, :children, :options
     end
 
+    # Constructs a new SchemaNode object.
+    #
+    # @param name [String] The relative name of the node.
+    # @param parent [Object] The parent node of the node.
+    # @param options [Hash] Additional options for the node.
+    # @return [Fixtury::SchemaNode] The new SchemaNode object.
+    # @raise [ArgumentError] if the name does not match the VALID_NODE_NAME regex.
     def initialize(name:, parent: nil, **options)
       name = name.to_s
       raise ArgumentError, "#{name.inspect} is an invalid node name" unless name.match?(VALID_NODE_NAME)
@@ -19,25 +29,35 @@ module Fixtury
       @children = {}
       @options = {}
       apply_options!(options)
-      @parent.add_child(self) if @parent
+      @first_ancestor = @parent&.first_ancestor || self
+      @parent&.add_child(self)
     end
 
+    # Inspect the SchemaNode object without representing the parent or children to avoid
+    # large prints.
+    #
+    # @return [String] The inspection string.
     def inspect
       "#{self.class}(pathname: #{pathname.inspect}, children: #{children.size})"
     end
 
+    # An identifier used during the printing of the tree structure.
+    #
+    # @return [String] The demodularized class name.
     def schema_node_type
-      raise NotImplementedError
+      self.class.name.demodulize.underscore
     end
 
+    # Adherance to the acts_like? interface
     def acts_like_fixtury_schema_node?
       true
     end
 
-    def first_ancestor
-      first_ancestor? ? self : parent.first_ancestor
-    end
-
+    # Adds child to the node's children hash as long as another is not already defined.
+    #
+    # @param child [Fixtury::SchemaNode] The child node to add.
+    # @raise [Fixtury::Errors::AlreadyDefinedError] if the child is already defined and not the provided child.
+    # @return [Fixtury::Errors::AlreadyDefinedError] the child that was suscessfully added
     def add_child(child)
       if children.key?(child.name) && children[child.name] != child
         raise Errors::AlreadyDefinedError, child.pathname
@@ -46,19 +66,35 @@ module Fixtury
       children[child.name] = child
     end
 
+    # Is the current node the first ancestor?
+    #
+    # @return [TrueClass, FalseClass] `true` if the node is the first ancestor, `false` otherwise.
     def first_ancestor?
       parent.nil?
     end
 
+    # Determines the isolation key in a top-down manner. It first accepts an isolation key
+    # set by the parent, then it checks for an isolation key set by the node itself. If no
+    # isolation key is found, it defaults to the node's name unless default is set to falsy.
+    #
+    # @param default [TrueClass, FalseClass, String] if no isolation key is present, what should the default value be?
+    #   @option default [true] The default value is the node's name.
+    #   @option default [String] The default value is a custom string.
+    #   @option default [false, nil, ""] No isolation key should be represented
+    # @return [String, NilClass] The isolation key.
     def isolation_key(default: true)
       from_parent = parent&.isolation_key(default: nil)
       return from_parent if from_parent
 
       value = options[:isolate] || default
       value = (value == true ? pathname : value&.to_s).presence
-      value == "/" ? nil : value # special case to accommodate root nodes
+      value = (value == "/" ? nil : value) # special case to accommodate root nodes
+      value.presence
     end
 
+    # Performs get() but raises if the result is nil.
+    # @raise [Fixtury::Errors::SchemaNodeNotDefinedError] if the search does not return a node.
+    # (see #get)
     def get!(search)
       thing = get(search)
       raise Errors::SchemaNodeNotDefinedError.new(pathname, search) unless thing
@@ -66,6 +102,14 @@ module Fixtury
       thing
     end
 
+    # Retrieves a node in the tree relative to self. Absolute and relative searches are
+    # accepted. The potential absolute paths are determined by a Fixtury::PathResolver instance
+    # relative to this node's pathname.
+    #
+    # @param search [String] The search to be used for finding the node.
+    # @return [Fixtury::SchemaNode, NilClass] The node if found, `nil` otherwise.
+    # @raise [ArgumentError] if the search is blank.
+    # @alias []
     def get(search)
       raise ArgumentError, "`search` must be provided" if search.blank?
 
@@ -87,18 +131,36 @@ module Fixtury
     end
     alias [] get
 
-    # helpful for inspection
+    # Generates a string representing the structure of the schema tree.
+    # The string will be in the form of "type:name[isolation_key](options)". The children
+    # will be on the next line and indented by two spaces.
+    #
+    # @param prefix [String] The prefix to be used for any lines produced.
+    # @return [String] The structure string.
     def structure(prefix = "")
       out = []
+
+      opts = options.except(:isolate)
+      opts.compact!
+
       my_structure = +"#{prefix}#{schema_node_type}:#{name}"
-      my_structure << "(#{options.inspect})" if options.present?
+      iso = isolation_key(default: nil)
+      my_structure << "[#{iso}]" if iso
+      my_structure << "(#{opts.to_a.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")})" if opts.present?
       out << my_structure
+
       children.each_value do |child|
         out << child.structure("#{prefix}  ")
       end
       out.join("\n")
     end
 
+    # Applies options to the node and raises if a collision occurs.
+    # This is useful for reopening a node and ensuring options are not altered.
+    #
+    # @param opts [Hash] The options to apply to the node.
+    # @raise [Fixtury::Errors::OptionCollisionError] if the option is already set and the new value is different.
+    # @return [void]
     def apply_options!(opts = {})
       opts.each do |key, value|
         if options.key?(key) && options[key] != value

data/lib/fixtury/store.rb

@@ -1,62 +1,69 @@
 # frozen_string_literal: true
 
+require "concurrent/atomic/thread_local_var"
 require "fileutils"
 require "singleton"
 require "yaml"
 
 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
 
-    attr_reader :filepath
-    attr_reader :loaded_isolation_keys
     attr_reader :locator
-    attr_reader :log_level
-    attr_reader :references
     attr_reader :schema
     attr_reader :ttl
 
-    def initialize(filepath: nil, locator: nil, ttl: nil, schema: nil)
+    # 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 || ::Fixtury::Locator.new
-      @filepath = filepath
-      @references = load_reference_from_file || {}
+      @locator = ::Fixtury::Locator.from(locator)
       @ttl = ttl&.to_i
-      @loaded_isolation_keys = {}
+      self.references = ::Fixtury.configuration.stored_references
     end
 
+    def references
+      @references ||= ::Concurrent::ThreadLocalVar.new({})
+      @references.value
+    end
+
+    def references=(value)
+      references.clear
+      @references.value = value
+    end
+
+    def loaded_isolation_keys
+      @loaded_isolation_keys ||= ::Concurrent::ThreadLocalVar.new({})
+      @loaded_isolation_keys.value
+    end
+
+    # Empty the store of any references and loaded isolation keys.
+    def reset
+      references.clear
+      loaded_isolation_keys.clear
+    end
+
+    # Summarize the current state of the store.
+    #
+    # @return [String]
     def inspect
       parts = []
       parts << "schema: #{schema.inspect}"
       parts << "locator: #{locator.inspect}"
-      parts << "filepath: #{filepath.inspect}" if filepath
       parts << "ttl: #{ttl.inspect}" if ttl
       parts << "references: #{references.size}"
 
       "#{self.class}(#{parts.join(", ")})"
     end
 
-    def dump_to_file
-      return unless filepath
-
-      ::FileUtils.mkdir_p(File.dirname(filepath))
-
-      writable = references.each_with_object({}) do |(pathname, ref), h|
-        h[pathname] = ref if ref.real?
-      end
-
-      ::File.binwrite(filepath, writable.to_yaml)
-    end
-
-    def load_reference_from_file
-      return unless filepath
-      return unless File.file?(filepath)
-
-      ::YAML.unsafe_load_file(filepath)
-    end
-
+    # Clear any references that are beyond their ttl or are no longer recognizable by the locator.
+    #
+    # @return [void]
     def clear_stale_references!
-      return unless ttl
-
       references.delete_if do |name, ref|
         stale = reference_stale?(ref)
         log("expiring #{name}", level: LOG_LEVEL_DEBUG) if stale
@@ -64,6 +71,11 @@ module Fixtury
       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.children.each_value do |item|
         get(item.name) if item.acts_like?(:fixtury_definition)
@@ -71,19 +83,12 @@ module Fixtury
       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
@@ -92,53 +97,38 @@ module Fixtury
       @schema = prior
     end
 
-    def loaded?(name)
-      dfn = schema.get!(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 #{dfn.pathname}" : "miss #{dfn.pathname}", level: LOG_LEVEL_ALL)
       result
     end
 
-    def loaded_or_loading?(pathname)
-      !!references[pathname]
-    end
-
-    def maybe_load_isolation_dependencies(definition)
-      isolation_key = definition.isolation_key
-      return if loaded_isolation_keys[isolation_key]
-
-      load_isolation_dependencies(isolation_key, schema.first_ancestor)
-    end
-
-    def load_isolation_dependencies(isolation_key, target_schema)
-      loaded_isolation_keys[isolation_key] = true
-      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
-
     # 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.
-    def get(name)
-      log("getting #{name}", level: LOG_LEVEL_DEBUG)
+    #
+    # @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!(name)
-      raise ArgumentError, "#{name.inspect} must refer to a definition" unless dfn.acts_like?(:fixtury_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)
+      maybe_load_isolation_dependencies(dfn.isolation_key)
 
       # See if we already hold a reference to the fixture.
       ref = references[pathname]
@@ -190,16 +180,65 @@ module Fixtury
     end
     alias [] get
 
+    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
+
+    # 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
+
+    # 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
 
+    # 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.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

@@ -4,6 +4,54 @@ 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
 
     def self.prepended(klass)
@@ -18,17 +66,17 @@ module Fixtury
 
     module ClassMethods
 
-      def fixtury_store
-        ::Fixtury.store
-      end
-
-      def fixtury_schema
-        ::Fixtury.schema
-      end
-
+      # 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 = Fixtury.schema.get!(search)
           dfn.pathname
         end
 
@@ -66,41 +114,47 @@ module Fixtury
 
     end
 
+    # Minitest before_setup hook. This will load the fixtures before the test.
     def before_setup(...)
       fixtury_setup if fixtury_dependencies.any?
       super
     end
 
+    # 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(name)
-      return nil unless self.class.fixtury_store
-
-      dfn = self.class.fixtury_schema.get!(name)
+    # 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
 
-      self.class.fixtury_store.get(dfn.pathname)
-    end
-
-    def fixtury_loaded?(name)
-      return false unless self.class.fixtury_store
-
-      self.class.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
+      return [] unless defined?(ActiveRecord::Base)
+
       ActiveRecord::Base.connection_handler.connection_pool_list(:writing).map(&:connection)
     end
 
+    # Load all dependenct fixtures and begin a transaction for each database connection.
     def fixtury_setup
-      fixtury_clear_stale_fixtures!
+      Fixtury.store.clear_stale_references!
       fixtury_load_all_fixtures!
       return unless fixtury_use_transactions?
 
@@ -109,6 +163,7 @@ module Fixtury
       end
     end
 
+    # Rollback any changes made to the fixtures
     def fixtury_teardown
       return unless fixtury_use_transactions?
 
@@ -117,21 +172,19 @@ module Fixtury
       end
     end
 
-    def fixtury_clear_stale_fixtures!
-      return unless self.class.fixtury_store
-
-      self.class.fixtury_store.clear_stale_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|
-        unless fixtury_loaded?(name)
-          ::Fixtury.log("preloading #{name.inspect}", name: "test", level: ::Fixtury::LOG_LEVEL_INFO)
-          fixtury(name)
-        end
+        next if Fixtury.store.loaded?(name)
+
+        ::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 = "1.0.0.beta1"
+  VERSION = "1.0.0.beta2"
 
 end

data/lib/fixtury.rb

@@ -9,6 +9,7 @@ require "active_support/core_ext/object/blank"
 
 require "fixtury/version"
 
+require "fixtury/configuration"
 require "fixtury/definition_executor"
 require "fixtury/dependency"
 require "fixtury/dependency_store"
@@ -38,6 +39,17 @@ module Fixtury
 
   DEFAULT_LOG_LEVEL = LOG_LEVEL_INFO
 
+  def self.configuration
+    @configuration ||= ::Fixtury::Configuration.new
+    yield @configuration if block_given?
+    @configuration
+  end
+
+  def self.configure(&block)
+    self.configuration(&block)
+  end
+
+
   # Shortcut for opening the top level schema.
   def self.define(&block)
     schema.define(&block)
@@ -61,24 +73,45 @@ module Fixtury
 
   # Default store for fixtures. This is a shared store that can be used across the application.
   def self.store
-    @store ||= ::Fixtury::Store.new(schema: schema)
+    @store ||= ::Fixtury::Store.new
   end
 
   def self.store=(store)
     @store = store
   end
 
-  def self.log_level
-    return @log_level if @log_level
+  # Require each schema file to ensure that all definitions are loaded.
+  def self.load_all_schemas
+    configuration.fixture_files.each do |filepath|
+      require filepath
+    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
+  end
+
+  # 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
 
-    @log_level = ENV["FIXTURY_LOG_LEVEL"]
-    @log_level ||= DEFAULT_LOG_LEVEL
-    @log_level = @log_level.to_s.to_sym
-    @log_level
+  # Perform a reset if any of the tracked files have changed.
+  def self.reset_if_changed
+    if configuration.files_changed?
+      reset
+    else
+      log("no changes, skipping reset", level: LOG_LEVEL_INFO)
+    end
   end
 
   def self.log(text = nil, level: LOG_LEVEL_DEBUG, name: nil, newline: true)
-    desired_level = LOG_LEVELS.fetch(log_level) { DEFAULT_LOG_LEVEL }
+    desired_level = LOG_LEVELS.fetch(configuration.log_level) { DEFAULT_LOG_LEVEL }
     return if desired_level == LOG_LEVEL_NONE
 
     message_level = LOG_LEVELS.fetch(level) { LOG_LEVEL_DEBUG }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fixtury
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta1
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Mike Nelson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-11 00:00:00.000000000 Z
+date: 2024-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -154,6 +154,7 @@ files:
 - bin/setup
 - fixtury.gemspec
 - lib/fixtury.rb
+- lib/fixtury/configuration.rb
 - lib/fixtury/definition.rb
 - lib/fixtury/definition_executor.rb
 - lib/fixtury/dependency.rb
@@ -162,7 +163,7 @@ files:
 - lib/fixtury/hooks.rb
 - lib/fixtury/locator.rb
 - lib/fixtury/locator_backend/common.rb
-- lib/fixtury/locator_backend/globalid.rb
+- lib/fixtury/locator_backend/global_id.rb
 - lib/fixtury/locator_backend/memory.rb
 - lib/fixtury/mutation_observer.rb
 - lib/fixtury/path_resolver.rb
@@ -171,7 +172,6 @@ files:
 - lib/fixtury/schema.rb
 - lib/fixtury/schema_node.rb
 - lib/fixtury/store.rb
-- lib/fixtury/tasks.rake
 - lib/fixtury/test_hooks.rb
 - lib/fixtury/version.rb
 homepage: https://github.com/guideline-tech/fixtury

data/lib/fixtury/tasks.rake

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-namespace :fixtury do
-  task :setup
-
-  desc "Clear fixtures from your cache. Accepts a pattern or fixture name such as foo/bar or /foo/*. Default pattern is /*"
-  task :clear_cache, [:pattern] => :setup do |_t, args|
-    ::Fixtury::Store.instance.clear_cache!(pattern: args[:pattern])
-  end
-end