spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/spec.rb

@@ -1,126 +1,113 @@
 # frozen_string_literal: true
 
-require_relative "spec/expectation"
-
 module SpecForge
+  #
+  # Represents a test specification in SpecForge
+  #
+  # A Spec contains one or more Expectations and defines the base configuration
+  # for those expectations. It maps directly to a test defined in YAML.
+  #
+  # @example YAML representation
+  #   get_users:
+  #     path: /users
+  #     expectations:
+  #     - expect:
+  #         status: 200
+  #
   class Spec
     #
-    # Loads and defines specs with the runner. Specs can be filtered using the optional parameters
+    # @return [Boolean] True if debugging is enabled
     #
-    # @param file_name [String, nil] The name of the file without the extension.
-    # @param spec_name [String, nil] The name of the spec in a yaml file
-    # @param expectation_name [String, nil] The name of the expectation for a spec.
+    attr_predicate :debug
+
     #
-    # @return [Array<Spec>]
+    # Unique identifier for this spec
     #
-    def self.load_and_define(file_name: nil, spec_name: nil, expectation_name: nil)
-      specs = load_from_files
-
-      filter_specs(specs, file_name:, spec_name:, expectation_name:)
-
-      # Announce if we're using a filter
-      if file_name
-        filter = {file_name:, spec_name:, expectation_name:}.delete_if { |k, v| v.blank? }
-        filter.stringify_keys!
-        puts "Using filter: #{filter}"
-      end
-
-      specs.each(&:define)
-    end
+    # @return [String] The spec ID
+    #
+    attr_reader :id
 
     #
-    # Loads any specs defined in the spec files. A single file can contain one or more specs
+    # Human-readable name for this spec
     #
-    # @return [Array<Spec>] An array of specs that were loaded.
+    # @return [String] The spec name
     #
-    def self.load_from_files
-      path = SpecForge.forge.join("specs")
-      specs = []
-
-      Dir[path.join("**/*.yml")].each do |file_path|
-        content = File.read(file_path)
-        hash = YAML.load(content).deep_symbolize_keys
-
-        hash.each do |spec_name, spec_hash|
-          line_number = content.lines.index { |line| line.start_with?("#{spec_name}:") }
-
-          spec_hash[:name] = spec_name.to_s
-          spec_hash[:file_path] = file_path
-          spec_hash[:file_name] = file_path.delete_prefix("#{path}/").delete_suffix(".yml")
-          spec_hash[:line_number] = line_number ? line_number + 1 : -1
+    attr_reader :name
 
-          specs << new(**spec_hash)
-        end
-      end
-
-      specs
-    end
-
-    # @private
-    def self.filter_specs(specs, file_name: nil, spec_name: nil, expectation_name: nil)
-      # Guard against invalid partial filters
-      if expectation_name && spec_name.blank?
-        raise ArgumentError, "The spec's name is required when filtering by an expectation's name"
-      end
-
-      if spec_name && file_name.blank?
-        raise ArgumentError, "The spec's filename is required when filtering by a spec's name"
-      end
-
-      specs.select! { |spec| spec.file_name == file_name } if file_name
-      specs.select! { |spec| spec.name == spec_name } if spec_name
-
-      if expectation_name
-        specs.each do |spec|
-          spec.expectations.select! { |expectation| expectation.name == expectation_name }
-        end
-      end
+    #
+    # Absolute path to the file containing this spec
+    #
+    # @return [String] The file path
+    #
+    attr_reader :file_path
 
-      specs
-    end
+    #
+    # Base name of the file without path or extension
+    #
+    # @return [String] The file name
+    #
+    attr_reader :file_name
 
-    ############################################################################
+    #
+    # Whether to enable debugging for this spec
+    #
+    # @return [Boolean] Debug flag
+    #
+    attr_reader :debug
 
-    attr_predicate :debug
+    #
+    # Line number in the source file where this spec is defined
+    #
+    # @return [Integer] The line number
+    #
+    attr_reader :line_number
 
-    attr_reader :name, :file_path, :file_name, :line_number, :expectations
+    #
+    # The expectations to test for this spec
+    #
+    # @return [Array<Expectation>] The expectations
+    #
+    attr_accessor :expectations
 
     #
-    # Creates a Spec based on the input
+    # Creates a new spec instance
+    #
+    # @param id [String] Unique identifier
+    # @param name [String] Human-readable name
+    # @param file_path [String] Absolute path to source file
+    # @param file_name [String] Base name of file
+    # @param debug [Boolean] Whether to enable debugging
+    # @param line_number [Integer] Line number in source
+    # @param expectations [Array<Hash>] Expectation configurations
     #
-    # @param name [String] The identifier for this spec
-    # @param file_path [String] The path where this spec is defined
-    # @param **input [Hash] Any attributes related to the spec, including expectations
-    #   See Normalizer::Spec
+    # @return [Spec] A new spec instance
     #
-    def initialize(name:, file_path:, file_name:, line_number:, **input)
+    def initialize(id:, name:, file_path:, file_name:, debug:, line_number:, expectations:)
+      @id = id
       @name = name
       @file_path = file_path
       @file_name = file_name
+      @debug = debug
       @line_number = line_number
-
-      input = Normalizer.normalize_spec!(input)
-
-      # Don't pass this down to the expectations
-      @debug = input.delete(:debug) || false
-
-      global_options = normalize_global_options(input)
-
-      @expectations =
-        input[:expectations].map.with_index do |expectation_input, index|
-          Expectation.new(expectation_input, global_options:)
-        end
-    end
-
-    def define
-      Runner.define_spec(self)
+      @expectations = expectations.map { |e| Expectation.new(**e) }
     end
 
-    private
-
-    def normalize_global_options(input)
-      config = SpecForge.configuration.to_h.slice(:base_url, :headers, :query)
-      Configuration.overlay_options(config, input.except(:expectations))
+    #
+    # Converts the spec to a hash representation
+    #
+    # @return [Hash] Hash representation
+    #
+    def to_h
+      {
+        name:,
+        file_path:,
+        file_name:,
+        debug:,
+        line_number:,
+        expectations: expectations.map(&:to_h)
+      }
     end
   end
 end
+
+require_relative "spec/expectation"

data/lib/spec_forge/type.rb

@@ -1,24 +1,28 @@
 # frozen_string_literal: true
 
 module SpecForge
+  #
+  # Provides helper methods for checking types
+  # Useful for working with both regular objects and Attribute delegators
+  #
   module Type
     #
-    # Checks if the object is a Hash, or a ResolvableHash (delegator)
+    # Checks if the object is a Hash or a ResolvableHash delegator
     #
     # @param object [Object] The object to check
     #
-    # @return [Boolean]
+    # @return [Boolean] True if the object is a hash-like structure
     #
     def self.hash?(object)
       object.is_a?(Hash) || object.is_a?(Attribute::ResolvableHash)
     end
 
     #
-    # Checks if the object is an Array, or a ResolvableArray (delegator)
+    # Checks if the object is an Array or a ResolvableArray delegator
     #
     # @param object [Object] The object to check
     #
-    # @return [Boolean]
+    # @return [Boolean] True if the object is an array-like structure
     #
     def self.array?(object)
       object.is_a?(Array) || object.is_a?(Attribute::ResolvableArray)
@@ -28,8 +32,22 @@ end
 
 #
 # Represents Hash/ResolvableHash in a form that can be used in a case statement
+# Allows for type switching on hash-like objects
+#
+# @example
+#   case value
+#   when HashLike
+#     # Handle hash-like objects
+#   end
 #
 class HashLike
+  #
+  # Provides custom type matching for use in case statements
+  #
+  # @param object [Object] The object to check against the type
+  #
+  # @return [Boolean] Whether the object matches the type
+  #
   def self.===(object)
     SpecForge::Type.hash?(object)
   end
@@ -37,8 +55,22 @@ end
 
 #
 # Represents Array/ResolvableArray in a form that can be used in a case statement
+# Allows for type switching on array-like objects
+#
+# @example
+#   case value
+#   when ArrayLike
+#     # Handle array-like objects
+#   end
 #
 class ArrayLike
+  #
+  # Provides custom type matching for use in case statements
+  #
+  # @param object [Object] The object to check against the type
+  #
+  # @return [Boolean] Whether the object matches the type
+  #
   def self.===(object)
     SpecForge::Type.array?(object)
   end

data/lib/spec_forge/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module SpecForge
-  VERSION = "0.5.0"
+  #
+  # Current version of SpecForge
+  #
+  VERSION = "0.6.0"
 end

data/lib/spec_forge.rb

@@ -16,92 +16,177 @@ require "singleton"
 require "thor"
 require "yaml"
 
+#
+# SpecForge: Write expressive API tests in YAML with the power of RSpec matchers
+#
+# SpecForge is a testing framework that allows writing API tests in a YAML format
+# that reads like documentation. It combines the readability of YAML with the
+# power of RSpec matchers, Faker data generation, and FactoryBot test objects.
+#
+# @example Basic spec in YAML
+#   get_user:
+#     path: /users/1
+#     expectations:
+#     - expect:
+#         status: 200
+#         json:
+#           name: kind_of.string
+#           email: /@/
+#
+# @example Running specs
+#   # Run all specs
+#   SpecForge.run
+#
+#   # Run specific file
+#   SpecForge.run(file_name: "users")
+#
+#   # Run specific spec
+#   SpecForge.run(file_name: "users", spec_name: "create_user")
+#
+module SpecForge
+  class << self
+    #
+    # Loads all factories and specs and runs the tests with optional filtering
+    #
+    # This is the main entry point for running SpecForge tests. It loads the
+    # forge_helper.rb file if it exists, configures the environment, loads
+    # factories and specs, and runs the tests through RSpec.
+    #
+    # @param file_name [String, nil] Optional name of spec file to run
+    # @param spec_name [String, nil] Optional name of spec to run
+    # @param expectation_name [String, nil] Optional name of expectation to run
+    #
+    def run(file_name: nil, spec_name: nil, expectation_name: nil)
+      # Load spec_helper.rb
+      forge_helper = SpecForge.forge_path.join("forge_helper.rb")
+      require_relative forge_helper if File.exist?(forge_helper)
+
+      # Validate in case anything was changed
+      configuration.validate
+
+      # Load factories
+      Factory.load_and_register
+
+      # Load the specs from their files and create forges from them
+      forges = Loader.load_from_files.map { |f| Forge.new(*f) }
+
+      # Filter out the specs and expectations
+      forges = Filter.apply(forges, file_name:, spec_name:, expectation_name:)
+
+      # Tell the user that we filtered if we did
+      Filter.announce(forges, file_name:, spec_name:, expectation_name:)
+
+      # Define and run everything
+      Runner.define(forges)
+      Runner.run
+    end
+
+    #
+    # Returns the directory root for the working directory
+    #
+    # @return [Pathname] The root directory path
+    #
+    def root
+      @root ||= Pathname.pwd
+    end
+
+    #
+    # Returns SpecForge's working directory
+    #
+    # @return [Pathname] The spec_forge directory path
+    #
+    def forge_path
+      @forge_path ||= root.join("spec_forge")
+    end
+
+    #
+    # Returns SpecForge's configuration
+    #
+    # @return [Configuration] The current configuration
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    #
+    # Yields SpecForge's configuration to a block for modification
+    #
+    # @yield [config] Block that receives the configuration object
+    # @yieldparam config [Configuration] The configuration to modify
+    #
+    # @return [Configuration] The updated configuration
+    #
+    def configure(&block)
+      block&.call(configuration)
+      configuration
+    end
+
+    #
+    # Returns a backtrace cleaner configured for SpecForge
+    #
+    # Creates and configures an ActiveSupport::BacktraceCleaner to improve
+    # error messages by removing unnecessary lines and root paths.
+    #
+    # @return [ActiveSupport::BacktraceCleaner] The configured backtrace cleaner
+    #
+    def backtrace_cleaner
+      @backtrace_cleaner ||= begin
+        root = "#{SpecForge.root}/"
+
+        cleaner = ActiveSupport::BacktraceCleaner.new
+        cleaner.add_filter { |line| line.delete_prefix(root) }
+        cleaner.add_silencer { |line| /rubygems|backtrace_cleaner/.match?(line) }
+        cleaner
+      end
+    end
+
+    #
+    # Returns the current execution context
+    #
+    # @return [Context] The current context object
+    #
+    def context
+      @context ||= Context.new
+    end
+
+    #
+    # Registers a callback for a specific test lifecycle event
+    # Allows custom code execution at specific points during test execution
+    #
+    # @param name [Symbol, String] A unique identifier for this callback
+    # @yield A block to execute when the callback is triggered
+    # @yieldparam context [Object] An object containing context-specific state data, depending
+    #   on which hook the callback is triggered from.
+    #
+    # @return [Proc] The registered callback
+    #
+    # @example Registering a custom debug handler
+    #   SpecForge.register_callback(:clean_database) do |context|
+    #     DatabaseCleaner.clean
+    #   end
+    #
+    def register_callback(name, &)
+      Callbacks.register(name, &)
+    end
+  end
+end
+
 require_relative "spec_forge/attribute"
 require_relative "spec_forge/backtrace_formatter"
+require_relative "spec_forge/callbacks"
 require_relative "spec_forge/cli"
 require_relative "spec_forge/configuration"
+require_relative "spec_forge/context"
 require_relative "spec_forge/core_ext"
 require_relative "spec_forge/error"
 require_relative "spec_forge/factory"
+require_relative "spec_forge/filter"
+require_relative "spec_forge/forge"
 require_relative "spec_forge/http"
+require_relative "spec_forge/loader"
+require_relative "spec_forge/matchers"
 require_relative "spec_forge/normalizer"
 require_relative "spec_forge/runner"
 require_relative "spec_forge/spec"
 require_relative "spec_forge/type"
 require_relative "spec_forge/version"
-
-module SpecForge
-  #
-  # Loads all factories and specs located in "path", then runs all of the specs
-  #
-  # @param path [String] The file path that contains factories and specs
-  #
-  def self.run(file_name: nil, spec_name: nil, expectation_name: nil)
-    path = SpecForge.forge
-
-    # Initialize
-    forge_helper = path.join("forge_helper.rb")
-    require_relative forge_helper if File.exist?(forge_helper)
-
-    # Validate
-    configuration.validate
-
-    # Prepare
-    Factory.load_and_register
-    Spec.load_and_define(file_name:, spec_name:, expectation_name:)
-
-    # Run
-    Runner.run
-  end
-
-  #
-  # Returns the directory root for the working directory
-  #
-  # @return [Pathname]
-  #
-  def self.root
-    @root ||= Pathname.pwd
-  end
-
-  #
-  # Returns SpecForge's working directory
-  #
-  # @return [Pathname]
-  #
-  def self.forge
-    @forge ||= root.join("spec_forge")
-  end
-
-  #
-  # Returns SpecForge's configuration
-  #
-  # @return [Config]
-  #
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
-
-  #
-  # Yields SpecForge's configuration to a block
-  #
-  def self.configure(&block)
-    block&.call(configuration)
-    configuration
-  end
-
-  #
-  # Returns a backtrace cleaner configured for SpecForge
-  #
-  # @return [ActiveSupport::BacktraceCleaner]
-  #
-  def self.backtrace_cleaner
-    @backtrace_cleaner ||= begin
-      root = "#{SpecForge.root}/"
-
-      cleaner = ActiveSupport::BacktraceCleaner.new
-      cleaner.add_filter { |line| line.delete_prefix(root) }
-      cleaner.add_silencer { |line| /rubygems|backtrace_cleaner/.match?(line) }
-      cleaner
-    end
-  end
-end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spec_forge
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-28 00:00:00.000000000 Z
+date: 2025-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -163,6 +163,7 @@ files:
 - lib/spec_forge/attribute/chainable.rb
 - lib/spec_forge/attribute/factory.rb
 - lib/spec_forge/attribute/faker.rb
+- lib/spec_forge/attribute/global.rb
 - lib/spec_forge/attribute/literal.rb
 - lib/spec_forge/attribute/matcher.rb
 - lib/spec_forge/attribute/parameterized.rb
@@ -170,9 +171,11 @@ files:
 - lib/spec_forge/attribute/resolvable.rb
 - lib/spec_forge/attribute/resolvable_array.rb
 - lib/spec_forge/attribute/resolvable_hash.rb
+- lib/spec_forge/attribute/store.rb
 - lib/spec_forge/attribute/transform.rb
 - lib/spec_forge/attribute/variable.rb
 - lib/spec_forge/backtrace_formatter.rb
+- lib/spec_forge/callbacks.rb
 - lib/spec_forge/cli.rb
 - lib/spec_forge/cli/actions.rb
 - lib/spec_forge/cli/command.rb
@@ -180,23 +183,38 @@ files:
 - lib/spec_forge/cli/new.rb
 - lib/spec_forge/cli/run.rb
 - lib/spec_forge/configuration.rb
+- lib/spec_forge/context.rb
+- lib/spec_forge/context/callbacks.rb
+- lib/spec_forge/context/global.rb
+- lib/spec_forge/context/store.rb
+- lib/spec_forge/context/variables.rb
 - lib/spec_forge/core_ext.rb
 - lib/spec_forge/core_ext/rspec.rb
 - lib/spec_forge/error.rb
 - lib/spec_forge/factory.rb
+- lib/spec_forge/filter.rb
+- lib/spec_forge/forge.rb
 - lib/spec_forge/http.rb
 - lib/spec_forge/http/backend.rb
 - lib/spec_forge/http/client.rb
 - lib/spec_forge/http/request.rb
 - lib/spec_forge/http/verb.rb
+- lib/spec_forge/loader.rb
+- lib/spec_forge/matchers.rb
 - lib/spec_forge/normalizer.rb
 - lib/spec_forge/normalizer/configuration.rb
 - lib/spec_forge/normalizer/constraint.rb
 - lib/spec_forge/normalizer/expectation.rb
 - lib/spec_forge/normalizer/factory.rb
 - lib/spec_forge/normalizer/factory_reference.rb
+- lib/spec_forge/normalizer/global_context.rb
 - lib/spec_forge/normalizer/spec.rb
 - lib/spec_forge/runner.rb
+- lib/spec_forge/runner/callbacks.rb
+- lib/spec_forge/runner/debug_proxy.rb
+- lib/spec_forge/runner/listener.rb
+- lib/spec_forge/runner/metadata.rb
+- lib/spec_forge/runner/state.rb
 - lib/spec_forge/spec.rb
 - lib/spec_forge/spec/expectation.rb
 - lib/spec_forge/spec/expectation/constraint.rb
@@ -205,9 +223,6 @@ files:
 - lib/templates/forge_helper.tt
 - lib/templates/new_factory.tt
 - lib/templates/new_spec.tt
-- spec_forge/factories/user.yml
-- spec_forge/forge_helper.rb
-- spec_forge/specs/users.yml
 homepage: https://github.com/itsthedevman/spec_forge
 licenses:
 - MIT

data/spec_forge/factories/user.yml

@@ -1,4 +0,0 @@
-user:
-  class: User
-  attributes:
-    attribute: value

data/spec_forge/forge_helper.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-##########################################
-# Framework Integration
-##########################################
-
-# Rails Integration
-# require_relative "../config/environment"
-
-# RSpec Integration (includes your existing configurations)
-# require_relative "../spec/spec_helper"
-
-# Custom requires (models, libraries, etc)
-# Dir[File.join(__dir__, "..", "lib", "**", "*.rb")].sort.each { |f| require f }
-
-##########################################
-# Configuration
-##########################################
-
-SpecForge.configure do |config|
-  # Base configuration
-  config.base_url = "http://localhost:3000"
-
-  # Default request headers
-  config.headers = {
-    "Authorization" => "Bearer #{ENV.fetch("API_TOKEN", "")}"
-  }
-
-  # Optional: Default query parameters
-  # config.query = {api_key: ENV['API_KEY']}
-
-  # Factory configuration
-  # config.factories.auto_discover = false        # Default: true
-  # config.factories.paths += ["lib/factories"]   # Adds to default paths
-
-  # Debug configuration
-  # Available in specs with debug: true (aliases: breakpoint, pry)
-  # Defaults to printing state overview (-> { puts inspect })
-  # Available context: expectation, variables, request, response,
-  #                   expected_status, expected_json
-  # config.on_debug { binding.pry }
-
-  # Test Framework Configuration
-  # Useful for database cleaners, test data setup, etc
-  # config.specs.before(:suite) { }
-  # config.specs.around { |example| example.run }
-  # config.specs.formatter = :documentation
-end