spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/normalizer.rb

@@ -1,54 +1,121 @@
 # frozen_string_literal: true
 
 module SpecForge
+  #
+  # Base class for normalizing various data structures in SpecForge
+  #
+  # The Normalizer validates and standardizes user input from YAML files,
+  # ensuring it meets the expected structure and types before processing.
+  # It supports default values, type checking, aliases, and nested structures.
+  #
+  # @example Normalizing a hash
+  #   normalizer = Normalizer.new("spec", input_hash)
+  #   output, errors = normalizer.normalize
+  #
   class Normalizer
+    #
+    # Shared attributes used by the various normalizers
+    #
+    # @return [Hash<Symbol, Hash>]
+    #
     SHARED_ATTRIBUTES = {
+      id: {type: String},
+      name: {type: String},
+      line_number: {type: Integer},
       base_url: {
         type: String,
-        default: ""
+        default: nil
       },
       url: {
         type: String,
         aliases: %i[path],
-        default: ""
+        default: nil
       },
-      http_method: {
+      http_verb: {
         type: String,
-        aliases: %i[method],
-        default: ""
+        aliases: %i[method http_method],
+        default: nil, # Do not default this to "GET". Leave it nil. Seriously.
+        validator: lambda do |value|
+          valid_verbs = HTTP::Verb::VERBS.values
+          return if value.blank? || valid_verbs.include?(value.to_s.upcase)
+
+          raise Error, "Invalid HTTP verb: #{value}. Valid values are: #{valid_verbs.join(", ")}"
+        end
       },
       headers: {
         type: Hash,
         default: {}
       },
       query: {
-        type: Hash,
+        type: [Hash, String],
         aliases: %i[params],
         default: {}
       },
       body: {
-        type: Hash,
+        type: [Hash, String],
         aliases: %i[data],
         default: {}
       },
       variables: {
-        type: Hash,
+        type: [Hash, String],
         default: {}
       },
       debug: {
         type: [TrueClass, FalseClass],
         default: false,
         aliases: %i[pry breakpoint]
+      },
+      callback: {
+        type: [String, NilClass],
+        validator: lambda do |value|
+          return if value.blank?
+          return if SpecForge::Callbacks.registered?(value)
+
+          raise Error::UndefinedCallbackError.new(value, SpecForge::Callbacks.registered_names)
+        end
       }
     }.freeze
 
+    #
+    # Defines the normalized structure for validating and parsing input data
+    #
+    # Each key represents an attribute with its validation and transformation rules.
+    # The structure supports defining:
+    # - Expected data type(s)
+    # - Default values
+    # - Aliases for alternative key names
+    # - Optional validation logic
+    # - Nested sub-structures
+    #
+    # @return [Hash] A configuration hash defining attribute validation rules
+    #
+    # @example Basic structure definition
+    #   STRUCTURE = {
+    #     name: {
+    #       type: String,              # Must be a String
+    #       default: "",               # Default to empty string if not provided
+    #       aliases: [:title]          # Allows using 'title' as an alternative key
+    #     },
+    #     age: {
+    #       type: Integer,             # Must be an Integer
+    #       default: 0                 # Default to 0 if not provided
+    #     }
+    #   }
+    #
+    # @see Normalizer
+    #
     STRUCTURE = {}
 
     class << self
       #
       # Raises any errors collected by the block
       #
-      # @raises InvalidStructureError
+      # @yield Block that returns [output, errors]
+      # @yieldreturn [Array<Object, Set>] The result and any errors
+      #
+      # @return [Object] The normalized output if successful
+      #
+      # @raise [Error::InvalidStructureError] If any errors were encountered
       #
       # @private
       #
@@ -62,7 +129,7 @@ module SpecForge
           errors << e
         end
 
-        raise InvalidStructureError.new(errors) if errors.size > 0
+        raise Error::InvalidStructureError.new(errors) if errors.size > 0
 
         output
       end
@@ -70,6 +137,8 @@ module SpecForge
       #
       # Returns a default version of this normalizer
       #
+      # @return [Hash] Default structure with default values
+      #
       # @private
       #
       def default
@@ -77,7 +146,14 @@ module SpecForge
       end
     end
 
-    attr_reader :label, :input, :structure
+    # @return [String] A label that describes the data itself
+    attr_reader :label
+
+    # @return [Hash] The data to normalize
+    attr_reader :input
+
+    # @return [Hash] The structure to normalize the data to
+    attr_reader :structure
 
     #
     # Creates a normalizer for normalizing Hash data based on a structure
@@ -86,6 +162,8 @@ module SpecForge
     # @param input [Hash] The data to normalize
     # @param structure [Hash] The structure to normalize the data to
     #
+    # @return [Normalizer] A new normalizer instance
+    #
     def initialize(label, input, structure: self.class::STRUCTURE)
       @label = label
       @input = input
@@ -93,68 +171,88 @@ module SpecForge
     end
 
     #
-    # Normalizes the data and returns the result
+    # Normalizes the data according to the defined structure
     #
-    # @return [Hash] The normalized data
+    # @return [Array<Hash, Set>] The normalized data and any errors
     #
     def normalize
-      normalize_to_structure
+      case input
+      when Hash
+        normalize_hash
+      when Array
+        normalize_array
+      end
     end
 
     #
     # Returns a hash with the default structure
     #
-    # @return [Hash]
+    # @return [Hash] A hash with default values for all structure keys
     #
     def default
-      structure.transform_values do |value|
-        if value.key?(:default)
-          value[:default].dup
-        elsif value[:type] == Integer # Can't call new on int
-          0
-        elsif value[:type] == Proc # Sameeee
-          -> {}
-        else
-          value[:type].new
-        end
+      structure.each_with_object({}) do |(key, value), hash|
+        hash[key] =
+          if value.key?(:default)
+            default = value[:default]
+            next if default.nil?
+
+            default.dup
+          elsif value[:type] == Integer # Can't call new on int
+            0
+          elsif value[:type] == Proc # Sameeee
+            -> {}
+          else
+            value[:type].new
+          end
       end
     end
 
     protected
 
-    def normalize_to_structure
+    #
+    # Normalizes the input hash according to the structure definition
+    #
+    # @return [Array<Hash, Set>] Normalized hash and any errors
+    #
+    # @private
+    #
+    def normalize_hash
       output, errors = {}, Set.new
 
       structure.each do |key, attribute|
         type_class = attribute[:type]
         aliases = attribute[:aliases] || []
-        sub_structure = attribute[:structure]
         default = attribute[:default]
-        required = !attribute.key?(:default)
+
+        has_default = attribute.key?(:default)
+        nilable = has_default && default.nil?
 
         # Get the value
         value = value_from_keys(input, [key] + aliases)
+        next if nilable && value.nil?
 
         # Default the value if needed
-        value = default.dup if !required && value.nil?
+        value = default.dup if has_default && value.nil?
 
         # Type + existence check
         if !valid_class?(value, type_class)
-          raise InvalidTypeError.new(value, type_class, for: "\"#{key}\" on #{label}")
+          for_context = generate_error_label(key, aliases)
+
+          if (line_number = input[:line_number])
+            for_context += " (line #{line_number})"
+          end
+
+          raise Error::InvalidTypeError.new(value, type_class, for: for_context)
         end
 
-        value =
-          case [value.class, sub_structure.class]
-          when [Hash, Hash]
-            new_value, new_errors = self.class
-              .new(label, value, structure: sub_structure)
-              .normalize
+        # Call the validator if it has one
+        attribute[:validator]&.call(value)
 
-            errors += new_errors if new_errors.size > 0
-            new_value
-          else
-            value
-          end
+        # Normalize any sub structures
+        if (substructure = attribute[:structure])
+          new_label = generate_error_label(key, aliases)
+          value = normalize_substructure(new_label, value, substructure, errors)
+        end
 
         # Store
         output[key] = value
@@ -165,10 +263,30 @@ module SpecForge
       [output, errors]
     end
 
+    #
+    # Extracts a value from a hash checking multiple keys
+    #
+    # @param hash [Hash] The hash to extract from
+    # @param keys [Array<Symbol, String>] The keys to check
+    #
+    # @return [Object, nil] The value if found, nil otherwise
+    #
+    # @private
+    #
     def value_from_keys(hash, keys)
       hash.find { |k, v| keys.include?(k) }&.second
     end
 
+    #
+    # Checks if a value is of the expected type
+    #
+    # @param value [Object] The value to check
+    # @param expected_type [Class, Array<Class>] The expected type(s)
+    #
+    # @return [Boolean] Whether the value is of the expected type
+    #
+    # @private
+    #
     def valid_class?(value, expected_type)
       if expected_type.instance_of?(Array)
         expected_type.any? { |type| value.is_a?(type) }
@@ -176,6 +294,102 @@ module SpecForge
         value.is_a?(expected_type)
       end
     end
+
+    #
+    # Generates an error label with information about the key and its aliases
+    #
+    # Creates a descriptive label for error messages that includes the key name,
+    # any aliases it may have, and the context in which it appears.
+    #
+    # @param key [Symbol, String] The key that caused the error
+    # @param aliases [Array<Symbol, String>] Any aliases for the key
+    #
+    # @return [String] A formatted error label
+    #
+    # @example
+    #   generate_error_label(:user_id, [:id, :uid])
+    #   # => "\"user_id\" (aliases \"id\", \"uid\") in user config"
+    #
+    def generate_error_label(key, aliases)
+      error_label = key.to_s.in_quotes
+
+      if aliases.size > 0
+        aliases = aliases.join_map(", ") { |a| a.to_s.in_quotes }
+        error_label += " (aliases #{aliases})"
+      end
+
+      error_label + " in #{label}"
+    end
+
+    #
+    # Normalizes a nested substructure within a parent structure
+    #
+    # Recursively processes nested Hash or Array structures according to
+    # their structure definitions, collecting any validation errors.
+    #
+    # @param new_label [String] The label to use for error messages
+    # @param value [Hash, Array] The nested structure to normalize
+    # @param substructure [Hash] The structure definition for validation
+    # @param errors [Set] A set to collect any encountered errors
+    #
+    # @return [Hash, Array] The normalized substructure
+    #
+    # @example
+    #   value = {name: "Test", age: "25"}
+    #   substructure = {name: {type: String}, age: {type: Integer}}
+    #   normalize_substructure("user", value, substructure, Set.new)
+    #   # => {name: "Test", age: 25}
+    #
+    def normalize_substructure(new_label, value, substructure, errors)
+      return value unless value.is_a?(Hash) || value.is_a?(Array)
+
+      new_value, new_errors = self.class
+        .new(new_label, value, structure: substructure)
+        .normalize
+
+      errors.merge(new_errors) if new_errors.size > 0
+      new_value
+    end
+
+    #
+    # Normalizes an array according to its structure definition
+    #
+    # Processes each element in the input array, validating its type and
+    # recursively normalizing any nested structures.
+    #
+    # @return [Array<Object, Set>] A two-element array containing:
+    #   1. The normalized array
+    #   2. A set of any errors encountered during normalization
+    #
+    # @example
+    #   input = [1, "string", 3]
+    #   structure = {type: Numeric}
+    #   normalize_array # => [[1, 3], #<Set: {Error}>]
+    #
+    def normalize_array
+      output, errors = [], Set.new
+
+      input.each_with_index do |value, index|
+        type_class = structure[:type]
+
+        if !valid_class?(value, type_class)
+          raise Error::InvalidTypeError.new(value, type_class, for: "index #{index} of #{label}")
+        end
+
+        # Call the validator if it has one
+        structure[:validator]&.call(value)
+
+        if (substructure = structure[:structure])
+          value = normalize_substructure("index #{index} of #{label}", value, substructure, errors)
+        end
+
+        output << value
+      rescue => e
+        errors << e
+      end
+
+      [output, errors]
+    end
   end
 end
 

data/lib/spec_forge/runner/callbacks.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Runner
+    #
+    # Manages lifecycle hooks for test execution
+    #
+    # This class provides callback methods that run at specific points during test execution
+    # to prepare the test environment, manage state, and perform cleanup operations. These
+    # callbacks integrate with RSpec's test lifecycle and maintain the SpecForge context.
+    #
+    # @example Running before file callback
+    #   Callbacks.before_file(forge)
+    #
+    class Callbacks
+      class << self
+        #
+        # Callback executed before a file's specs are run
+        #
+        # Initializes global context and sets up any file-level state needed
+        # for all specs in the file.
+        #
+        # @param forge [SpecForge::Forge] The forge representing the current file
+        #
+        def before_file(forge)
+          # Set the global variables
+          SpecForge.context.global.set(**forge.global)
+
+          # Clear the store for this file
+          SpecForge.context.store.clear
+
+          # Start fresh
+          State.clear
+
+          # Run the user's before_file callbacks
+          run_user_callbacks(:before_file, file_context(forge))
+        end
+
+        #
+        # Callback executed before each spec is run
+        #
+        # Prepares the context for a specific spec, including loading
+        # spec-level variables and configuration.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec about to be executed
+        #
+        def before_spec(forge, spec)
+          # Prepare the variables for this spec
+          SpecForge.context.variables.set(**forge.variables_for_spec(spec))
+
+          # Clear any "spec" level stored data
+          SpecForge.context.store.clear_specs
+
+          # Run the user's before_spec callbacks
+          run_user_callbacks(:before_spec, spec_context(forge, spec))
+        end
+
+        #
+        # Callback executed before each expectation is run
+        #
+        # Prepares variables for the specific expectation and sets up
+        # example metadata for error reporting.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation about to be evaluated
+        # @param example_group [RSpec::Core::ExampleGroup] The current running example group
+        # @param example [RSpec::Core::Example] The current example
+        #
+        def before_expectation(forge, spec, expectation, example_group, example)
+          # Store metadata to failure/error messages display the correct information
+          Metadata.set_for_example(spec, expectation)
+
+          # Store state data for callbacks and persisting data into the store
+          State.set(
+            forge:, spec:, expectation:, example_group:, example:,
+            request: example_group.request
+          )
+
+          # Load the variable overlay for this expectation (if one exists)
+          SpecForge.context.variables.use_overlay(expectation.id)
+
+          # Run the user's before_each callbacks
+          run_user_callbacks(:before_each, expectation_context(forge, spec, expectation, example))
+        end
+
+        #
+        # Handles debug mode for an expectation
+        #
+        # When debugging is enabled for a spec or expectation, this method
+        # creates a debugging environment for inspecting test state.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation being evaluated
+        # @param example_group [RSpec::Core::ExampleGroup] The current running example group
+        #
+        def on_debug(forge, spec, expectation, example_group)
+          DebugProxy.new(forge, spec, expectation, example_group).call
+        end
+
+        #
+        # Callback executed after each expectation is run
+        #
+        # Performs cleanup and stores results if needed for future reference.
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation that was evaluated
+        # @param example_group [RSpec::Core::ExampleGroup] The current running example group
+        # @param example [RSpec::Core::Example] The current example
+        #
+        def after_expectation(forge, spec, expectation, example_group, example)
+          # Note: Let variables on `example_group` have been reset by RSpec at this point.
+          # Calling them will result in a new value being returned and memoized.
+          # In other words, do not call `example_group.response` in here unless you
+          # like potentially duplicating data ;)
+          State.persist
+
+          # Run the user's after_each callbacks
+          run_user_callbacks(:after_each, expectation_context(forge, spec, expectation, example))
+
+          # Clear the state for the next expectation
+          State.clear
+        end
+
+        #
+        # Callback executed after each spec is ran
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec that was executed
+        #
+        def after_spec(forge, spec)
+          # Run the user's after_spec callbacks
+          run_user_callbacks(:after_spec, spec_context(forge, spec))
+        end
+
+        #
+        # Callback executed after a file's specs have been ran
+        #
+        # @param forge [SpecForge::Forge] The forge representing the current file
+        #
+        def after_file(forge)
+          # Run the user's after_file callbacks
+          run_user_callbacks(:after_file, file_context(forge))
+        end
+
+        private
+
+        #
+        # Executes user-defined callbacks for a specific lifecycle point
+        #
+        # Processes the callback_type to extract timing and scope information,
+        # adds this metadata to the context, and then triggers all registered
+        # callbacks for that type.
+        #
+        # @param callback_type [Symbol, String] The type of callback to run
+        #   (:before_file, :after_spec, etc.)
+        # @param context [Hash] Context data containing state information for the callback
+        #
+        # @private
+        #
+        def run_user_callbacks(callback_type, context)
+          callback_timing, callback_scope = callback_type.to_s.split("_")
+
+          # Adds "before_each", "before", and "each" into the context so callbacks
+          # can build logic off of them
+          context.merge!(
+            callback_type: callback_type.to_s,
+            callback_timing:, callback_scope:
+          )
+
+          # Run the callbacks for this type
+          SpecForge.context.global.callbacks.run(callback_type, context)
+        end
+
+        #
+        # Builds the base context for file-level callbacks
+        #
+        # @param forge [SpecForge::Forge] The forge representing the file
+        #
+        # @return [Hash] Basic file context
+        #
+        # @private
+        #
+        def file_context(forge)
+          {
+            forge: forge,
+            file_path: forge.metadata[:file_path],
+            file_name: forge.metadata[:file_name]
+          }
+        end
+
+        #
+        # Builds context for spec-level callbacks
+        # Includes file context plus spec information
+        #
+        # @param forge [SpecForge::Forge] The forge representing the file
+        # @param spec [SpecForge::Spec] The spec being executed
+        #
+        # @return [Hash] Context with file and spec information
+        #
+        # @private
+        #
+        def spec_context(forge, spec)
+          file_context(forge).merge(
+            spec: spec,
+            spec_name: spec.name,
+            variables: SpecForge.context.variables
+          )
+        end
+
+        #
+        # Builds context for expectation-level callbacks
+        # Includes spec context plus expectation information
+        #
+        # @param forge [SpecForge::Forge] The forge being tested
+        # @param spec [SpecForge::Spec] The spec being tested
+        # @param expectation [SpecForge::Spec::Expectation] The expectation being evaluated
+        # @param example [RSpec::Core::Example] The current example
+        #
+        # @return [Hash] Context with file, spec and expectation information
+        #
+        # @private
+        #
+        def expectation_context(forge, spec, expectation, example)
+          example_group = State.current.example_group
+
+          # Pull this data from the State instead of example group to avoid creating a new value
+          request = State.current.request
+          response = State.current.response
+
+          spec_context(forge, spec).merge(
+            expectation:,
+            expectation_name: expectation.name,
+            request:,
+            response:,
+            example_group:,
+            example:
+          )
+        end
+      end
+    end
+  end
+end