spec_forge 0.4.0 → 0.6.0

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.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-23 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,37 +0,0 @@
-# frozen_string_literal: true
-
-## Using Rails? Uncomment to load your app
-# ENV["RAILS_ENV"] ||= "test"
-# require_relative "../config/environment"
-
-## Not using Rails? Load anything you need here
-# Dir[SpecForge.root.join("lib", "my_api", "models", "**/*.rb")].sort.each { |path| require path }
-
-## Using RSpec? Uncomment to use your existing configurations
-# require_relative "../spec/spec_helper"
-
-SpecForge.configure do |config|
-  ## Base URL prefix for all API requests. All test paths will be appended to this URL
-  config.base_url = "http://localhost:3000"
-
-  ## Default request headers - commonly used for authentication and content negotiation
-  api_token = ENV.fetch("API_TOKEN", "")
-  config.headers = {
-    "Authorization" => "Bearer #{api_token}"
-  }
-
-  ## Default query parameters - useful for API keys or additional request context
-  # config.query = {api_token:}
-
-  ## Factory configuration options
-  ##
-  ## Enable/disable automatic factory discovery. When enabled, SpecForge will automatically
-  ## load factories from FactoryBot's default paths. Note: Factories defined in
-  ## "spec_forge/factories" are always loaded regardless of this setting.
-  # config.factories.auto_discover = false  # Default: true
-
-  ##
-  ## Additional paths, relative to the project folder, for discovering FactoryBot factories
-  ## By default, FactoryBot looks in "spec/factories" and "test/factories"
-  # config.factories.paths += ["custom/factories/path"]
-end

data/spec_forge/specs/users.yml

@@ -1,65 +0,0 @@
-index_users:
-  url: /users
-  expectations:
-  - expect:
-      status: 200
-
-show_user:
-  url: /users/{id}
-  expectations:
-  - query:
-      id: -1
-    expect:
-      status: 404
-  - query:
-      id: 1
-    expect:
-      status: 200
-      json:
-        name: kind_of.string
-        email: /\w+@example\.com/i
-
-create_user:
-  url: /users
-  method: post
-  expectations:
-  - expect:
-      status: 400
-  - expect:
-      status: 200
-      json:
-        name: variables.name
-        role: variables.role
-    variables:
-      name: faker.name.name
-      role: user
-    body:
-      name: variables.name
-
-update_user:
-  url: /users/{id}
-  method: patch
-  query:
-    id: 1
-  variables:
-    number:
-      faker.number.between:
-        from: 100000
-        to: 999999
-  expectations:
-  - expect:
-      status: 200
-      json:
-        name: kind_of.string
-        number: kind_of.integer
-    body:
-      number: variables.number
-
-destroy_user:
-  url: /users/{id}
-  method: delete
-  query:
-    id: 1
-  expectations:
-  - expect:
-      status: 200