spec_forge 0.7.1 → 1.0.0

data/lib/spec_forge/forge.rb

@@ -2,170 +2,244 @@
 
 module SpecForge
   #
-  # Represents a collection of related specs loaded from a single YAML file
+  # The main execution engine for running blueprints
   #
-  # A Forge contains multiple specs with their expectations, global variables,
-  # and request configuration. It acts as the container for all tests defined
-  # in a single file and manages their shared context.
-  #
-  # @example Creating a forge
-  #   global = {variables: {api_key: "123"}}
-  #   metadata = {file_name: "users", file_path: "/path/to/users.yml"}
-  #   specs = [{name: "list_users", url: "/users", expectations: [...]}]
-  #   forge = Forge.new(global, metadata, specs)
+  # Forge orchestrates the execution of blueprints by managing the execution
+  # context, HTTP client, variable storage, and display output. It processes
+  # each step sequentially and tracks statistics across the run.
   #
   class Forge
-    #
-    # The name of this forge from the relative path
-    #
-    # @return [String] The name derived from the file path
-    #
-    attr_reader :name
+    class << self
+      #
+      # Initializes SpecForge by loading the forge_helper and factories
+      #
+      # @return [Class] self for chaining
+      #
+      def ignite
+        load_forge_helper
+        Factory.load_and_register
 
-    #
-    # Global variables and configuration shared across all specs
-    #
-    # @return [Hash] The global variables and configuration
-    #
-    attr_reader :global
+        # Return for chaining
+        self
+      end
 
-    #
-    # Metadata about the spec file
-    #
-    # @return [Hash] File information such as path and name
-    #
-    attr_reader :metadata
+      #
+      # Creates and runs a new Forge instance with the given blueprints
+      #
+      # @param blueprints [Array<Blueprint>] The blueprints to execute
+      # @option verbosity_level [Integer] Output verbosity (0-3)
+      # @option hooks [Hash] Forge-level event hooks
+      #
+      # @return [void]
+      #
+      def run(blueprints, **)
+        new(blueprints, **).run
+      end
 
-    #
-    # Variables defined at the spec and expectation levels
-    #
-    # @return [Hash] Variable definitions organized by spec
-    #
-    attr_reader :variables
+      #
+      # Returns the current execution context for the current thread
+      #
+      # @return [Context, nil] The current context or nil if not executing
+      #
+      def context
+        Thread.current[:spec_forge_context]
+      end
 
-    #
-    # Request configuration for the specs
-    #
-    # @return [Hash] HTTP request configuration by spec
-    #
-    attr_reader :request
+      #
+      # Executes a block with a given context
+      #
+      # @param context [Context] The context to use during execution
+      #
+      # @yield Block to execute with the context
+      #
+      # @return [Object] The result of the block
+      #
+      def with_context(context)
+        old_context = Thread.current[:spec_forge_context]
+        Thread.current[:spec_forge_context] = context
+        yield
+      ensure
+        Thread.current[:spec_forge_context] = old_context
+      end
 
-    #
-    # Collection of specs contained in this forge
-    #
-    # @return [Array<Spec>] The specs defined in this file
-    #
-    attr_accessor :specs
+      private
 
-    #
-    # Creates a new Forge instance containing specs from a YAML file
-    #
-    # @param global [Hash] Global variables shared across all specs in the file
-    # @param metadata [Hash] Information about the spec file
-    # @param specs [Array<Hash>] Array of spec definitions from the file
-    #
-    # @return [Forge] A new forge instance with the processed specs
-    #
-    def initialize(global, metadata, specs)
-      @name = metadata[:relative_path]
+      def load_forge_helper
+        forge_helper = SpecForge.forge_path.join("forge_helper.rb")
+        return unless File.exist?(forge_helper)
 
-      @global = global
-      @metadata = metadata
+        require_relative forge_helper
 
-      @variables = extract_variables!(specs)
-      @request = extract_request!(specs)
-      @specs = specs.map { |spec| Spec.new(**spec) }
+        # Revalidate in case anything was changed
+        SpecForge.configuration.validate
+      end
     end
 
-    #
-    # Retrieves variables for a specific spec
-    #
-    # Returns the variables defined for a specific spec, including
-    # both base variables and any overlay variables for its expectations.
-    #
-    # @param spec [Spec] The spec to get variables for
-    #
-    # @return [Hash] The variables for the spec
-    #
-    def variables_for_spec(spec)
-      @variables[spec.id]
-    end
+    # @return [Array<Blueprint>] The blueprints being executed
+    attr_reader :blueprints
 
-    private
+    # @return [Callbacks] Callback registry for this forge run
+    attr_reader :callbacks
+
+    # @return [Display] Display handler for output formatting
+    attr_reader :display
+
+    # @return [Array<Hash>] List of failed expectations
+    attr_reader :failures
+
+    # @return [Hash{Symbol => Array<Step::Call>}] Forge-level before and after hooks
+    attr_reader :hooks
+
+    # @return [HTTP::Client] HTTP client for making requests
+    attr_reader :http_client
+
+    # @return [Runner] RSpec runner for executing expectations
+    attr_reader :runner
+
+    # @return [Hash] Statistics about the current run
+    attr_reader :stats
+
+    # @return [Timer] Timer for tracking execution duration
+    attr_reader :timer
+
+    # @return [Variables] Variable storage for the current run
+    attr_reader :variables
 
     #
-    # Extracts variables from specs and organizes them into base and overlay variables
-    #
-    # @param specs [Array<Hash>] Array of spec definitions
+    # Creates a new Forge instance with the specified blueprints
     #
-    # @return [Hash] A hash mapping spec IDs to their variables
+    # @param blueprints [Array<Blueprint>] The blueprints to execute
+    # @param verbosity_level [Integer] Output verbosity (0-3)
+    # @param hooks [Hash] Forge-level event hooks
     #
-    # @private
+    # @return [Forge] A new forge instance
     #
-    def extract_variables!(specs)
-      #
-      # Creates a hash that looks like this:
-      #
-      # {
-      #   spec_1: {
-      #     base: {var_1: true, var_2: false},
-      #     overlay: {
-      #       expectation: {var_1: false}
-      #     }
-      #   },
-      #   spec_2: ...
-      # }
-      #
-      specs.each_with_object({}) do |spec, hash|
-        overlay = spec[:expectations].to_h { |e| [e[:id], e.delete(:variables)] }.compact_blank
+    def initialize(blueprints, verbosity_level: 0, hooks: {})
+      @blueprints = blueprints
+      @callbacks = Callbacks.new
+      @display = Display.new(verbosity_level:)
+      @failures = []
+      @hooks = Step::Call.wrap_hooks(hooks)
+      @http_client = HTTP::Client.new
+      @runner = Runner.new
+      @stats = {}
+      @timer = Timer.new
+      @variables = Variables.new(static: SpecForge.configuration.global_variables)
 
-        hash[spec[:id]] = {base: spec.delete(:variables), overlay:}
-      end
+      reset_stats
     end
 
     #
-    # Extracts request configuration from specs and organizes them into base and overlay configs
+    # Executes all blueprints and their steps
     #
-    # @param specs [Array<Hash>] Array of spec definitions
+    # @return [void]
     #
-    # @return [Hash] A hash mapping spec IDs to their request configurations
-    #
-    # @private
-    #
-    def extract_request!(specs)
-      #
-      # Creates a hash that looks like this:
-      #
-      # {
-      #   spec_1: {
-      #     base: {base_url: "https://foo.bar", url: "", ...},
-      #     overlay: {
-      #       expectation: {base_url: "https://bar.baz", ...}
-      #     }
-      #   },
-      #   spec_2: ...
-      # }
-      #
-      config = SpecForge.configuration.to_h.slice(:base_url, :headers, :query)
-
-      specs.each_with_object({}) do |spec, hash|
-        overlay = spec[:expectations].to_h do |expectation|
-          [
-            expectation[:id],
-            expectation.extract!(*HTTP::REQUEST_ATTRIBUTES).compact_blank
-          ]
+    def run
+      context = Context.new(variables:)
+
+      Forge.with_context(context) do
+        forge_start
+
+        @blueprints.each do |blueprint|
+          blueprint_start(blueprint)
+
+          blueprint.steps.each do |step|
+            step_start(blueprint, step)
+            step_action(blueprint, step)
+            step_end(blueprint, step)
+          rescue => e
+            step_end(blueprint, step, error: e)
+            break
+          end
+
+          blueprint_end(blueprint)
         end
+      ensure
+        forge_end
+      end
+    end
 
-        overlay.compact_blank!
+    private
 
-        base = spec.extract!(*HTTP::REQUEST_ATTRIBUTES)
-        base.compact_blank!
+    def reset_stats
+      @stats = {
+        blueprints: 0,
+        steps: 0,
+        passed: 0,
+        failed: 0
+      }
+    end
 
-        base = config.deep_merge(base)
-        base[:http_verb] ||= "GET"
+    def forge_start
+      reset_stats
 
-        hash[spec[:id]] = {base:, overlay:}
+      # Load the callbacks from the configuration
+      SpecForge.configuration.callbacks.each { |name, block| @callbacks.register(name, &block) }
+
+      @display.forge_start(self)
+      @timer.start
+
+      Hooks.before_forge(self)
+    end
+
+    def blueprint_start(blueprint)
+      @variables.clear
+      @failures.clear
+
+      @display.blueprint_start(blueprint)
+
+      Hooks.before_blueprint(self, blueprint)
+    end
+
+    def step_start(blueprint, step)
+      @display.step_start(step)
+
+      Hooks.before_step(self, blueprint, step)
+    end
+
+    def step_action(blueprint, step)
+      # HEY! LISTEN: These read and write to the forge's state
+      Call.new(step).run(self) if step.calls?
+      Request.new(step).run(self) if step.request?
+      Debug.new(step).run(self, blueprint) if step.debug?
+      Expect.new(step).run(self) if step.expects?
+      Store.new(step).run(self) if step.store?
+    end
+
+    def step_end(blueprint, step, error: nil)
+      @stats[:steps] += 1
+
+      if error.is_a?(Error::ExpectationFailure)
+        @failures += error.failed_examples.map { |example| {step:, example:} }
       end
+
+      Hooks.after_step(self, blueprint, step, error:)
+
+      @display.step_end(self, step, error:)
+
+      # Bubble up only AFTER display has been updated
+      raise error if error && !error.is_a?(Error::ExpectationFailure)
+    ensure
+      # Drop the request/response data from scope
+      # Do this after everything is done so variables can be printed out if needed
+      @variables.except!(:request, :response)
+    end
+
+    def blueprint_end(blueprint)
+      @stats[:blueprints] += 1
+
+      @display.blueprint_end(blueprint, success: @failures.empty?)
+
+      Hooks.after_blueprint(self, blueprint)
+    end
+
+    def forge_end
+      @timer.stop
+
+      @display.forge_end(self)
+      Hooks.after_forge(self)
+
+      @display.stats(self)
     end
   end
 end

data/lib/spec_forge/http/backend.rb

@@ -3,30 +3,12 @@
 module SpecForge
   module HTTP
     #
-    # Handles the low-level HTTP operations using Faraday
+    # Low-level HTTP client wrapper around Faraday
     #
-    # This class is responsible for creating and configuring the Faraday connection,
-    # executing the actual HTTP requests, and handling URL path parameter substitution.
-    #
-    # @example Basic usage
-    #   backend = Backend.new(request)
-    #   response = backend.get("/users")
+    # Backend provides methods for each HTTP verb and handles the actual
+    # communication with the server. It's used internally by HTTP::Client.
     #
     class Backend
-      #
-      # Regular expression to match { placeholder } style URL parameters
-      #
-      # @return [Regexp]
-      #
-      CURLY_PLACEHOLDER = /\{(\w+)\}/
-
-      #
-      # Regular expression to match :placeholder style URL parameters
-      #
-      # @return [Regexp]
-      #
-      COLON_PLACEHOLDER = /:(\w+)/
-
       #
       # The configured Faraday connection
       #
@@ -35,180 +17,101 @@ module SpecForge
       attr_reader :connection
 
       #
-      # Configures a new Faraday connection based on the request configuration
+      # Creates a new HTTP backend with a Faraday connection
       #
-      # @param request [HTTP::Request] The request configuration to use
+      # @return [Backend] A new backend instance
       #
-      # @return [Backend] A new backend instance with a configured connection
-      #
-      def initialize(request)
-        @connection =
-          Faraday.new(url: request.base_url) do |builder|
-            # Content-Type
-            if !request.headers.key?("Content-Type")
-              builder.request :json
-              builder.response :json
-            end
-
-            # Headers
-            builder.headers.merge!(request.headers.resolved)
-          end
+      def initialize
+        @connection = Faraday.new
       end
 
       #
       # Executes a DELETE request to <base_url>/<provided_url>
       #
-      # @param url [String] The URL path to DELETE
-      # @param headers [Hash] HTTP headers to add
-      # @param query [Hash] Any query parameters to send
-      # @param body [Hash] Any body data to send
+      # @option options [String] :url The URL path to DELETE
+      # @option options [String] :base_url The base URL to use for the request
+      # @option options [Hash] :headers HTTP headers to add
+      # @option options [Hash] :query Any query parameters to send
+      # @option options [Hash] :body Any body data to send
       #
       # @return [Faraday::Response] The HTTP response
       #
-      def delete(url, headers: {}, query: {}, body: {})
-        url = normalize_url(url, query)
-        connection.delete(url) { |request| update_request(request, headers, query, body) }
+      def delete(**)
+        run_http_method(:delete, **)
       end
 
       #
       # Executes a GET request to <base_url>/<provided_url>
       #
-      # @param url [String] The URL path to GET
-      # @param headers [Hash] HTTP headers to add
-      # @param query [Hash] Any query parameters to send
-      # @param body [Hash] Any body data to send
+      # @option options [String] :url The URL path to GET
+      # @option options [String] :base_url The base URL to use for the request
+      # @option options [Hash] :headers HTTP headers to add
+      # @option options [Hash] :query Any query parameters to send
+      # @option options [Hash] :body Any body data to send
       #
       # @return [Faraday::Response] The HTTP response
       #
-      def get(url, headers: {}, query: {}, body: {})
-        url = normalize_url(url, query)
-        connection.get(url) { |request| update_request(request, headers, query, body) }
+      def get(**)
+        run_http_method(:get, **)
       end
 
       #
       # Executes a PATCH request to <base_url>/<provided_url>
       #
-      # @param url [String] The URL path to PATCH
-      # @param headers [Hash] HTTP headers to add
-      # @param query [Hash] Any query parameters to send
-      # @param body [Hash] Any body data to send
+      # @option options [String] :url The URL path to PATCH
+      # @option options [String] :base_url The base URL to use for the request
+      # @option options [Hash] :headers HTTP headers to add
+      # @option options [Hash] :query Any query parameters to send
+      # @option options [Hash] :body Any body data to send
       #
       # @return [Faraday::Response] The HTTP response
       #
-      def patch(url, headers: {}, query: {}, body: {})
-        url = normalize_url(url, query)
-        connection.patch(url) { |request| update_request(request, headers, query, body) }
+      def patch(**)
+        run_http_method(:patch, **)
       end
 
       #
       # Executes a POST request to <base_url>/<provided_url>
       #
-      # @param url [String] The URL path to POST
-      # @param headers [Hash] HTTP headers to add
-      # @param query [Hash] Any query parameters to send
-      # @param body [Hash] Any body data to send
+      # @option options [String] :url The URL path to POST
+      # @option options [String] :base_url The base URL to use for the request
+      # @option options [Hash] :headers HTTP headers to add
+      # @option options [Hash] :query Any query parameters to send
+      # @option options [Hash] :body Any body data to send
       #
       # @return [Faraday::Response] The HTTP response
       #
-      def post(url, headers: {}, query: {}, body: {})
-        url = normalize_url(url, query)
-        connection.post(url) { |request| update_request(request, headers, query, body) }
+      def post(**)
+        run_http_method(:post, **)
       end
 
       #
       # Executes a PUT request to <base_url>/<provided_url>
       #
-      # @param url [String] The URL path to PUT
-      # @param headers [Hash] HTTP headers to add
-      # @param query [Hash] Any query parameters to send
-      # @param body [Hash] Any body data to send
+      # @option options [String] :url The URL path to PUT
+      # @option options [String] :base_url The base URL to use for the request
+      # @option options [Hash] :headers HTTP headers to add
+      # @option options [Hash] :query Any query parameters to send
+      # @option options [Hash] :body Any body data to send
       #
       # @return [Faraday::Response] The HTTP response
       #
-      def put(url, headers: {}, query: {}, body: {})
-        url = normalize_url(url, query)
-        connection.put(url) { |request| update_request(request, headers, query, body) }
+      def put(**)
+        run_http_method(:put, **)
       end
 
       private
 
-      #
-      # Updates the request with query parameters and body
-      #
-      # @param request [Faraday::Request] The request to update
-      # @param headers [Hash] HTTP headers to add
-      # @param query [Hash] Query parameters to add
-      # @param body [Hash] Body data to add
-      #
-      # @private
-      #
-      def update_request(request, headers, query, body)
-        request.headers.merge!(headers)
-        request.headers.transform_values!(&:to_s)
-
-        request.params.merge!(query)
-        request.body = body.to_json
-      end
-
-      #
-      # Normalizes a URL by replacing path parameters with their values
-      #
-      # Handles both curly brace style {param} and colon style :param
-      # Parameters are extracted from the query hash and removed after substitution
-      #
-      # @param url [String] The URL pattern with potential placeholders
-      # @param query [Hash] Query parameters that may contain values for placeholders
-      #
-      # @return [String] The URL with placeholders replaced by actual values
-      #
-      # @raise [URI::InvalidURIError] If the resulting URL is invalid
-      #
-      # @private
-      #
-      def normalize_url(url, query)
-        # Strip leading slash so paths properly append to base URL
-        url = url.delete_prefix("/")
+      def run_http_method(method, url:, base_url:, headers: {}, query: {}, body: {})
+        connection.url_prefix = base_url
 
-        # /users/<user_id>
-        url = replace_url_placeholder(url, query, CURLY_PLACEHOLDER)
+        connection.public_send(method, url) do |request|
+          request.headers.merge!(headers)
+          request.headers.transform_values!(&:to_s)
 
-        # /users/:user_id
-        url = replace_url_placeholder(url, query, COLON_PLACEHOLDER)
-
-        # Attempt to validate (the colon style is considered valid apparently)
-        begin
-          URI.parse(url)
-        rescue URI::InvalidURIError
-          raise URI::InvalidURIError,
-            "#{url.inspect} is not a valid URI. If you're using path parameters (like ':id' or '{id}'), ensure they are defined in the 'query' section."
+          request.params.merge!(query)
+          request.body = body
         end
-
-        url
-      end
-
-      #
-      # Replaces URL placeholders with values from the query hash
-      #
-      # @param url [String] The URL with placeholders
-      # @param query [Hash] The query parameters containing values
-      # @param regex [Regexp] The pattern to match (curly or colon style)
-      #
-      # @return [String] The URL with placeholders replaced
-      #
-      # @private
-      #
-      def replace_url_placeholder(url, query, regex)
-        match = url.match(regex)
-        return url if match.nil?
-
-        key = match[1].to_sym
-        return url unless query.key?(key)
-
-        value = query.delete(key)
-        url.gsub(
-          match[0],
-          URI.encode_uri_component(value.to_s)
-        )
       end
     end
   end