spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/spec/expectation/constraint.rb

@@ -4,39 +4,114 @@ module SpecForge
   class Spec
     class Expectation
       #
-      # Represents the "expect" hash
+      # Represents the expected response constraints for an expectation
+      #
+      # A Constraint defines what the API response should look like,
+      # including status code and body content with support for matchers.
+      #
+      # @example In code
+      #   constraint = Constraint.new(
+      #     status: 200,
+      #     json: {name: "matcher.eq" => "John"}
+      #   )
       #
       class Constraint < Data.define(:status, :json) # :xml, :html
         #
-        # Creates a new Constraint
+        # Creates a new constraint
         #
-        # @param status [Integer] The expected HTTP status code
-        # @param json [Hash] The expected JSON with matchers
+        # @param status [Integer, String] The expected HTTP status code, or reference to one
+        # @param json [Hash, Array] The expected JSON with matchers
         #
-        def initialize(status:, json:)
-          super(status:, json: normalize_hash(json))
+        # @return [Constraint] A new constraint instance
+        #
+        def initialize(status:, json: {})
+          super(
+            status: Attribute.from(status),
+            json: Attribute.from(json)
+          )
         end
 
+        #
+        # Converts the constraint to a hash with resolved values
+        #
+        # @return [Hash] Hash representation with resolved values
+        #
         def to_h
           super.transform_values(&:resolve)
         end
 
+        #
+        # Converts constraints to RSpec matchers for validation
+        #
+        # Transforms the defined constraints (status and JSON expectations) into
+        # appropriate RSpec matchers that can be used in test expectations.
+        # This method resolves all values and applies the appropriate matcher
+        # conversions to create a complete expectation structure.
+        #
+        # @return [Hash] A hash containing resolved matchers
+        #
+        # @example
+        #   constraint = Constraint.new(status: 200, json: {name: "John"})
+        #   matchers = constraint.as_matchers
+        #   # => {status: eq(200), json: include("name" => eq("John"))}
+        #
+        def as_matchers
+          {
+            status: status.resolve_as_matcher,
+            json: resolve_json_matcher
+          }
+        end
+
+        #
+        # Generates a human-readable description of what this constraint expects in the response
+        #
+        # Creates a description string for RSpec examples that clearly explains the expected
+        # status code and JSON structure. This makes test output more informative and helps
+        # developers understand what's being tested at a glance.
+        #
+        # @return [String] A human-readable description of the constraint expectations
+        #
+        # @example Status code with JSON object
+        #   constraint.description
+        #   # => "is expected to respond with \"200 OK\" and a JSON object that contains keys: \"id\", \"name\""
+        #
+        # @example Status code with JSON array
+        #   constraint.description
+        #   # => "is expected to respond with \"201 Created\" and a JSON array that contains 3 items"
+        #
+        def description
+          description = "is expected to respond with"
+
+          description += if status.is_a?(Attribute::Literal)
+            " #{HTTP.status_code_to_description(status.input).in_quotes}"
+          else
+            " the expected status code"
+          end
+
+          size = json.size
+
+          if Type.array?(json)
+            description +=
+              " and a JSON array that contains #{size} #{"item".pluralize(size)}"
+          elsif Type.hash?(json) && size > 0
+            keys = json.keys.join_map(", ", &:in_quotes)
+
+            description +=
+              " and a JSON object that contains #{"key".pluralize(size)}: #{keys}"
+          end
+
+          description
+        end
+
         private
 
-        def normalize_hash(hash)
-          hash =
-            hash.transform_values do |attribute|
-              case attribute
-              when Attribute::Regex
-                Attribute.from("matcher.match" => attribute.resolve)
-              when Attribute::Literal
-                Attribute.from("matcher.eq" => attribute.resolve)
-              else
-                attribute
-              end
-            end
-
-          Attribute.from(hash)
+        def resolve_json_matcher
+          case json
+          when HashLike
+            json.transform_values(&:resolve_as_matcher).stringify_keys
+          else
+            json.resolve_as_matcher
+          end
         end
       end
     end

data/lib/spec_forge/spec/expectation.rb

@@ -1,72 +1,64 @@
 # frozen_string_literal: true
 
-require_relative "expectation/constraint"
-
 module SpecForge
   class Spec
-    class Expectation
+    #
+    # Represents a single test expectation within a spec
+    #
+    # An Expectation defines what should be tested for a specific API request,
+    # including the expected status code and response structure.
+    #
+    # @example YAML representation
+    #   - name: "Get user successfully"
+    #     expect:
+    #       status: 200
+    #       json:
+    #         name: kind_of.string
+    #
+    class Expectation < Data.define(:id, :name, :line_number, :debug, :store_as, :constraints)
+      #
+      # @return [Boolean] True if debugging is enabled
+      #
       attr_predicate :debug
 
-      attr_reader :name, :variables, :constraints, :http_client
+      #
+      # @return [Boolean] True if store_as is set
+      #
+      attr_predicate :store_as
 
       #
-      # Creates a new Expectation
+      # Creates a new expectation with constraints
       #
-      # @param input [Hash] A hash containing the various attributes to control the expectation
-      # @param name [String] The name of the expectation
+      # @param id [String] Unique identifier
+      # @param name [String] Human-readable name
+      # @param line_number [Integer] Line number in source
+      # @param debug [Boolean] Whether to enable debugging
+      # @param store_as [String] Unique Context::Store identifier
+      # @param expect [Hash] Expected constraints
       #
-      def initialize(input, global_options: {})
-        # This allows defining spec level attributes that can be overwritten by the expectation
-        input = Attribute.from(Configuration.overlay_options(global_options, input))
-
-        load_debug(input)
-        load_variables(input)
-
-        # Must be after load_variables
-        load_constraints(input)
-
-        @http_client = HTTP::Client.new(
-          variables:, **input.except(:name, :variables, :expect, :debug)
-        )
+      # @return [Expectation] A new expectation instance
+      #
+      def initialize(id:, name:, line_number:, debug:, store_as:, expect:)
+        constraints = Constraint.new(**expect)
 
-        # Must be after http_client
-        load_name(input)
+        super(id:, name:, line_number:, debug:, store_as:, constraints:)
       end
 
+      #
+      # Converts the expectation to a hash representation
+      #
+      # @return [Hash] Hash representation
+      #
       def to_h
         {
           name:,
-          debug: debug?,
-          variables: variables.resolve,
-          request: http_client.request.to_h,
-          constraints: constraints.to_h
+          line_number:,
+          debug:,
+          expect: constraints.to_h
         }
       end
-
-      private
-
-      def load_name(input)
-        # GET /users
-        @name = "#{http_client.request.http_verb.upcase} #{http_client.request.url}"
-
-        # GET /users - Returns a 404
-        if (name = input[:name].resolve.presence)
-          @name += " - #{name}"
-        end
-      end
-
-      def load_variables(input)
-        @variables = Attribute.bind_variables(input[:variables], input[:variables])
-      end
-
-      def load_debug(input)
-        @debug = input[:debug].resolve
-      end
-
-      def load_constraints(input)
-        constraints = Attribute.bind_variables(input[:expect], variables)
-        @constraints = Constraint.new(**constraints)
-      end
     end
   end
 end
+
+require_relative "expectation/constraint"

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.4.0"
+  #
+  # Current version of SpecForge
+  #
+  VERSION = "0.6.0"
 end