spec_forge 0.5.0 → 0.7.0

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

@@ -4,44 +4,123 @@ module SpecForge
   class Spec
     class Expectation
       #
-      # Represents the "expect" hash
+      # Represents the expected response constraints for an expectation
       #
-      class Constraint < Data.define(:status, :json) # :xml, :html
+      # 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,
+      #     headers: {response_header: "kind_of.string"},
+      #     json: {name: {"matcher.eq" => "John"}}
+      #   )
+      #
+      class Constraint < Data.define(:status, :headers, :json) # :xml, :html
         #
-        # Creates a new Constraint
+        # Creates a new constraint
         #
-        # @param status [Integer] The expected HTTP status code
+        # @param status [Integer, String] The expected HTTP status code, or reference to one
+        # @param headers [Hash] The expected headers with matchers
         # @param json [Hash, Array] The expected JSON with matchers
         #
-        def initialize(status:, json:)
-          super(status:, json: convert_to_matchers(json))
+        # @return [Constraint] A new constraint instance
+        #
+        def initialize(status:, headers: {}, json: {})
+          super(
+            status: Attribute.from(status),
+            headers: Attribute.from(headers),
+            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
 
-        private
+        #
+        # 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,
+            headers: resolve_hash_matcher(headers)
+          }
+        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
 
-        def convert_to_matchers(value)
-          # This makes it easier to check if json was provided
-          return Attribute.from(nil) if value.blank?
+          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)
 
-          case value
+            description +=
+              " and a JSON object that contains #{"key".pluralize(size)}: #{keys}"
+          end
+
+          description
+        end
+
+        private
+
+        def resolve_json_matcher
+          case json
           when HashLike
-            value = value.transform_values { |i| convert_to_matchers(i) }
-            Attribute.from("matcher.include" => value)
-          when ArrayLike
-            value = value.map { |i| convert_to_matchers(i) }
-            Attribute.from("matcher.contain_exactly" => value)
-          when Attribute::Regex
-            Attribute.from("matcher.match" => value)
-          when Attribute::Literal
-            Attribute.from("matcher.eq" => value)
+            resolve_hash_matcher(json)
           else
-            value
+            json.resolve_as_matcher
           end
         end
+
+        def resolve_hash_matcher(hash)
+          hash.transform_values(&:resolve_as_matcher).stringify_keys
+        end
       end
     end
   end

data/lib/spec_forge/spec/expectation.rb

@@ -1,72 +1,68 @@
 # 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, :documentation, :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 documentation [Boolean] Whether to include in documentation generation
+      # @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:, documentation:)
+        constraints = Constraint.new(**expect)
 
-        # Must be after http_client
-        load_name(input)
+        super(id:, name:, line_number:, debug:, store_as:, documentation:, 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,68 @@
 # frozen_string_literal: true
 
-require_relative "spec/expectation"
-
 module SpecForge
-  class Spec
-    #
-    # Loads and defines specs with the runner. Specs can be filtered using the optional parameters
+  #
+  # 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 < Data.define(
+    :id, :name, :file_path, :file_name, :line_number,
+    :debug, :documentation, :expectations
+  )
     #
-    # @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.
+    # @return [Boolean] True if debugging is enabled
     #
-    # @return [Array<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
+    attr_predicate :debug
 
     #
-    # Loads any specs defined in the spec files. A single file can contain one or more specs
+    # Creates a new spec instance
     #
-    # @return [Array<Spec>] An array of specs that were loaded.
+    # @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 documentation [Boolean] Whether to include in documentation generation
+    # @param expectations [Array<Hash>] Expectation configurations
     #
-    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
-
-          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
+    # @return [Spec] A new spec instance
+    #
+    def initialize(
+      id:, name:, file_path:, file_name:, line_number:,
+      debug:, documentation:, expectations:
+    )
+      expectations = expectations.map { |e| Expectation.new(**e) }
 
-      specs
+      super
     end
 
-    ############################################################################
-
-    attr_predicate :debug
-
-    attr_reader :name, :file_path, :file_name, :line_number, :expectations
-
     #
-    # Creates a Spec based on the input
+    # Converts the spec to a hash representation
     #
-    # @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 [Hash] Hash representation
     #
-    def initialize(name:, file_path:, file_name:, line_number:, **input)
-      @name = name
-      @file_path = file_path
-      @file_name = file_name
-      @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)
-    end
-
-    private
-
-    def normalize_global_options(input)
-      config = SpecForge.configuration.to_h.slice(:base_url, :headers, :query)
-      Configuration.overlay_options(config, input.except(:expectations))
+    def to_h
+      {
+        name:,
+        file_path:,
+        file_name:,
+        debug:,
+        line_number:,
+        documentation:,
+        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.5.0"
+  #
+  # Current version of SpecForge
+  #
+  VERSION = "0.7.0"
 end