spec_forge 0.7.0 → 1.0.0

data/lib/spec_forge/factory.rb

@@ -25,6 +25,8 @@ module SpecForge
     # Loads factory definitions from YAML files
     # Creates Factory instances but doesn't register them with FactoryBot
     #
+    # Factory names are derived from the filename (e.g., user.yml -> :user)
+    #
     # @return [Array<Factory>] Array of loaded factory instances
     #
     def self.load_from_files
@@ -35,11 +37,11 @@ module SpecForge
       Dir[path].each do |file_path|
         hash = YAML.load_file(file_path, symbolize_names: true)
 
-        hash.each do |factory_name, factory_hash|
-          factory_hash[:name] = factory_name
+        # Extract factory name from filename (e.g., "user.yml" -> :user)
+        factory_name = File.basename(file_path, ".yml").to_sym
+        hash[:name] = factory_name
 
-          factories << new(**factory_hash)
-        end
+        factories << new(**hash)
       end
 
       factories
@@ -62,6 +64,9 @@ module SpecForge
     # @return [Hash<Symbol, Attribute>] The attributes that define this factory
     attr_reader :attributes
 
+    # @return [Hash<Symbol, Hash<Symbol, Attribute>>] Traits defined for this factory
+    attr_reader :traits
+
     #
     # Creates a new Factory instance
     #
@@ -77,8 +82,9 @@ module SpecForge
       @input = input
       @model_class = input[:model_class]
 
-      @variables = extract_variables(input)
-      @attributes = extract_attributes(input)
+      @variables = Attribute.from(input[:variables])
+      @attributes = Attribute.from(input[:attributes], context: @variables)
+      @traits = extract_traits(input[:traits], context: @variables)
     end
 
     #
@@ -91,13 +97,23 @@ module SpecForge
       dsl = FactoryBot::Syntax::Default::DSL.new
 
       options = {}
-      options[:class] = model_class if model_class
+      options[:class] = model_class if model_class.present?
 
       # This creates the factory in FactoryBot
       factory_forge = self
       dsl.factory(name, options) do
-        factory_forge.attributes.each do |name, attribute|
-          add_attribute(name) { attribute.resolve }
+        # Register base attributes
+        factory_forge.attributes.each do |attr_name, attribute|
+          add_attribute(attr_name) { attribute.resolve }
+        end
+
+        # Register traits
+        factory_forge.traits.each do |trait_name, trait_attributes|
+          trait(trait_name) do
+            trait_attributes.each do |attr_name, attribute|
+              add_attribute(attr_name) { attribute.resolve }
+            end
+          end
         end
       end
 
@@ -106,16 +122,20 @@ module SpecForge
 
     private
 
-    def extract_variables(input)
-      variables = Attribute.from(input[:variables])
-
-      # Update the variables that reference other variables lol
-      Attribute.bind_variables(variables, variables)
-    end
+    #
+    # Extracts and processes trait definitions from the input hash
+    # Trait definitions are flat hashes of attributes (no nested "attributes:" key)
+    #
+    # @param traits_hash [Hash] Raw trait definitions from YAML
+    # @param context [Hash] Variable context for attribute resolution
+    # @return [Hash<Symbol, Hash<Symbol, Attribute>>] Processed traits with Attribute values
+    #
+    def extract_traits(traits_hash, context: nil)
+      return {} if traits_hash.blank?
 
-    def extract_attributes(input)
-      attributes = Attribute.from(input[:attributes])
-      Attribute.bind_variables(attributes, variables)
+      traits_hash.transform_values do |trait_attributes|
+        Attribute.from(trait_attributes || {}, context:)
+      end
     end
   end
 end

data/lib/spec_forge/forge/action.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Base class for step actions
+    #
+    # Actions are the executable units within a step. Each action type
+    # (Call, Debug, Expect, Request, Store) inherits from this base class
+    # and implements the run method to perform its specific behavior.
+    #
+    class Action
+      # @return [Step] The step being executed
+      attr_reader :step
+
+      #
+      # Creates a new action for the given step
+      #
+      # @param step [Step] The step this action belongs to
+      #
+      # @return [Action] A new action instance
+      #
+      def initialize(step)
+        @step = step
+      end
+
+      #
+      # Executes the action
+      #
+      # @param _forge [Forge] The forge instance executing this action
+      #
+      # @return [void]
+      #
+      # @raise [RuntimeError] If not implemented by subclass
+      #
+      def run(_forge)
+        raise "not implemented"
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/actions/call.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Action for the `call:` step attribute
+    #
+    # Executes registered callbacks defined in forge_helper.rb during step processing.
+    # Callbacks can receive the current context and optional arguments.
+    #
+    class Call < Action
+      #
+      # Executes all callbacks defined in the step's call: attribute
+      #
+      # @param forge [Forge] The forge instance for accessing callbacks and display
+      #
+      # @return [void]
+      #
+      def run(forge)
+        context = SpecForge::Forge.context
+
+        step.calls.each do |call|
+          callback_name = call.callback_name
+          arguments = call.arguments
+
+          forge.display.action("Call #{callback_name}", symbol: :checkmark, symbol_styles: :yellow)
+
+          forge.callbacks.run(callback_name, context, arguments)
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/actions/debug.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Action for the `debug:` step attribute
+    #
+    # Triggers a debug breakpoint when a step has debug: true, invoking the
+    # configured debug handler (e.g., binding.pry) to allow interactive debugging.
+    #
+    class Debug < Action
+      #
+      # Triggers the debug breakpoint
+      #
+      # @param forge [Forge] The forge instance
+      #
+      # @return [void]
+      #
+      # @raise [Error] If no debug handler is configured
+      #
+      def run(forge, blueprint)
+        forge.display.action("Debug breakpoint triggered", symbol: :flag, symbol_styles: :yellow)
+
+        callback = SpecForge.configuration.on_debug_proc
+        if callback.nil?
+          raise Error, <<~STRING
+            Debug breakpoint triggered but no debug handler is configured.
+
+            Add a debug handler in your forge_helper.rb:
+
+              SpecForge.configure do |config|
+                config.on_debug { binding.pry }  # or byebug, debug, etc.
+              end
+
+          STRING
+        end
+
+        if callback.arity == 1
+          context = SpecForge::Forge.context.with(forge:, blueprint:, step:)
+          callback.call(context)
+        else
+          callback.call
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/actions/expect.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Action for the `expect:` step attribute
+    #
+    # Runs expectations against the current response, validating status codes,
+    # headers, and JSON body against expected values using RSpec matchers.
+    #
+    class Expect < Action
+      #
+      # Runs all expectations for the step against the current response
+      #
+      # @param forge [Forge] The forge instance containing response data
+      #
+      # @return [void]
+      #
+      # @raise [Error::ExpectationFailure] If any expectations fail
+      #
+      def run(forge)
+        show_expectation_count = step.expects.size > 1
+
+        failed_examples =
+          step.expects.flat_map.with_index do |expectation, index|
+            failed = forge.runner.run(forge, step, expectation)
+
+            forge.display.expectation_finished(
+              failed_examples: failed,
+              total_count: expectation.size,
+              index: index + 1,
+              show_index: show_expectation_count
+            )
+
+            failed
+          end
+
+        return if failed_examples.empty?
+
+        raise Error::ExpectationFailure.new(failed_examples)
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/actions/request.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Action for the `request:` step attribute
+    #
+    # Builds and executes an HTTP request based on the step's configuration,
+    # then stores both the request and response in the forge's variables for
+    # use by subsequent actions.
+    #
+    class Request < Action
+      #
+      # Executes the HTTP request and stores the response
+      #
+      # @param forge [Forge] The forge instance
+      #
+      # @return [void]
+      #
+      def run(forge)
+        sendable_request, resolved_request = build_requests
+
+        forge.display.action(
+          "#{sendable_request.http_verb} #{sendable_request.url}",
+          symbol: :right_arrow, symbol_styles: :yellow
+        )
+
+        response = forge.http_client.perform(sendable_request)
+        response = parse_response(response)
+
+        # Only store the original resolved request before we modify it
+        forge.variables[:request] = resolved_request
+        forge.variables[:response] = response
+      end
+
+      private
+
+      def build_requests
+        resolved_request = step.request.to_h.transform_values { |v| v.respond_to?(:resolved) ? v.resolved : v }
+        resolved_request[:base_url] = SpecForge.configuration.base_url if resolved_request[:base_url].blank?
+
+        request = resolved_request.deep_dup
+        request[:body] =
+          if step.request.json?
+            request[:body].to_json
+          else
+            request[:body].to_s
+          end
+
+        [HTTP::Request.new(**request), resolved_request]
+      end
+
+      def parse_response(response)
+        response.to_hash.tap do |response|
+          response[:headers] = response.delete(:response_headers)
+
+          case response[:headers]["content-type"]
+          when "application/json"
+            response[:body] = response[:body].to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/actions/store.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Action for the `store:` step attribute
+    #
+    # Resolves attribute values and stores them as variables for use by
+    # subsequent steps. Can store literal values or extract values from
+    # the response using template syntax.
+    #
+    class Store < Action
+      #
+      # Stores all configured values in the forge's variables
+      #
+      # @param forge [Forge] The forge instance
+      #
+      # @return [void]
+      #
+      def run(forge)
+        step.store.each do |name, value|
+          event = forge.variables.key?(name) ? "Update" : "Store"
+
+          forge.display.action("#{event} #{name.in_quotes}", symbol: :flag, symbol_styles: :bright_cyan)
+
+          forge.variables[name] = value.resolved
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/callbacks.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Manages registered callbacks that can be invoked from blueprints
+    #
+    # Callbacks are Ruby blocks registered in forge_helper.rb that can be
+    # called during step execution using the call: attribute.
+    #
+    class Callbacks
+      #
+      # Creates a new empty callback registry
+      #
+      # @return [Callbacks] A new callbacks instance
+      #
+      def initialize
+        @callbacks = {}
+      end
+
+      #
+      # Registers a callback with the given name
+      #
+      # @param name [String, Symbol] The name to register the callback under
+      #
+      # @yield The block to execute when the callback is invoked
+      #
+      # @raise [ArgumentError] If no block is provided
+      #
+      def register(name, &block)
+        raise ArgumentError, "A block must be provided" unless block.is_a?(Proc)
+
+        if registered?(name)
+          warn("Callback #{name.in_quotes} is already registered. It will be overwritten")
+        end
+
+        @callbacks[name.to_sym] = block
+      end
+
+      #
+      # Checks if a callback with the given name has been registered
+      #
+      # @param name [String, Symbol] The callback name to check
+      #
+      # @return [Boolean] Whether the callback is registered
+      #
+      def registered?(name)
+        @callbacks.key?(name.to_sym)
+      end
+
+      #
+      # Executes a registered callback by name
+      #
+      # @param name [String, Symbol] The callback name to execute
+      # @param context [Forge::Context, nil] The current execution context
+      # @param arguments [Array, Hash] Arguments to pass to the callback
+      #
+      # @return [Object] The return value of the callback
+      #
+      # @raise [Error::UndefinedCallbackError] If the callback is not registered
+      #
+      def run(name, context = nil, arguments = [])
+        raise Error::UndefinedCallbackError.new(name, @callbacks.keys) unless registered?(name)
+
+        callback = @callbacks[name.to_sym]
+
+        # No arguments? Just call
+        return callback.call if callback.arity == 0
+        return callback.call(context) if callback.arity == 1
+
+        case arguments
+        when Array
+          callback.call(context, *arguments)
+        when Hash
+          callback.call(context, **arguments)
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/forge/context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Forge
+    #
+    # Immutable execution context passed to callbacks and hooks
+    #
+    # Contains the current state during forge execution including
+    # variables, the current blueprint and step, and any error that occurred.
+    #
+    class Context < Data.define(:variables, :forge, :blueprint, :step, :error)
+      def initialize(**context)
+        context[:variables] ||= nil
+        context[:forge] ||= nil
+        context[:blueprint] ||= nil
+        context[:step] ||= nil
+        context[:error] ||= nil
+
+        super(context)
+      end
+
+      #
+      # Returns whether the context represents a successful state
+      #
+      # @return [Boolean] True if no error is present
+      #
+      def success?
+        error.nil?
+      end
+
+      #
+      # Returns whether the context represents a failed state
+      #
+      # @return [Boolean] True if an error is present
+      #
+      def failure?
+        !success?
+      end
+    end
+  end
+end