spec_forge 0.6.0 → 0.7.1

data/lib/spec_forge/runner.rb

@@ -8,150 +8,66 @@ module SpecForge
   class Runner
     class << self
       #
-      # Defines RSpec examples for a collection of forges
-      # Creates the test structure that will be executed
+      # Prepares forge objects for test execution
       #
-      # @param forges [Array<Forge>] The forges to define as RSpec examples
+      # Loads the forge helper, registers factories, loads specs from files,
+      # applies filtering, and returns ready-to-run forge objects.
       #
-      def define(forges)
-        forges.each do |forge|
-          define_forge(forge)
-        end
-      end
-
-      #
-      # Runs the defined RSpec examples
-      # Executes the tests after they've been defined
-      #
-      def run
-        prepare_for_run
-
-        ARGV.clear
-        RSpec::Core::Runner.invoke
-      end
-
-      #
-      # Defines RSpec examples for a specific forge
-      # Creates the test structure for a single forge file
+      # @param file_name [String, nil] Optional file name filter
+      # @param spec_name [String, nil] Optional spec name filter
+      # @param expectation_name [String, nil] Optional expectation name filter
       #
-      # @param forge [Forge] The forge to define
+      # @return [Array<Forge>] Array of prepared forge objects
       #
-      def define_forge(forge)
-        # This is just like writing a normal RSpec test, except with loops ;)
-        RSpec.describe(forge.name) do
-          # Callback for the file
-          before(:context) { Callbacks.before_file(forge) }
-          after(:context) { Callbacks.after_file(forge) }
-
-          # Specs
-          forge.specs.each do |spec|
-            # Describe the spec
-            describe(spec.name) do
-              # Request data is for the spec and contains the base and overlays
-              let!(:request_data) { forge.request[spec.id] }
-
-              # The HTTP client for the spec
-              let!(:http_client) { HTTP::Client.new(**request_data[:base]) }
-
-              # Callback for the spec
-              before(:context) { Callbacks.before_spec(forge, spec) }
-              after(:context) { Callbacks.after_spec(forge, spec) }
-
-              # Expectations
-              spec.expectations.each do |expectation|
-                # Onto the actual expectation itself
-                describe(expectation.name) do
-                  # Set metadata for the example group for error reporting
-                  Metadata.set_for_group(spec, expectation, self)
+      def prepare(file_name: nil, spec_name: nil, expectation_name: nil)
+        load_forge_helper
 
-                  # Lazily load the constraints
-                  let(:constraints) { expectation.constraints.as_matchers }
+        # Load factories
+        Factory.load_and_register
 
-                  let(:match_status) { constraints[:status] }
-                  let(:match_json) { constraints[:json] }
-                  let(:match_json_class) { be_kind_of(match_json.class) }
+        # Load the specs from their files and create forges from them
+        forges = Loader.load_from_files.map { |f| Forge.new(*f) }
 
-                  # The request for the test itself. Overlays the expectation's data if it exists
-                  let(:request) do
-                    request = request_data[:base]
+        # Filter out the specs and expectations
+        forges = Filter.apply(forges, file_name:, spec_name:, expectation_name:)
 
-                    if (overlay = request_data[:overlay][expectation.id])
-                      request = request.deep_merge(overlay)
-                    end
+        # Tell the user that we filtered if we did
+        Filter.announce(forges, file_name:, spec_name:, expectation_name:)
 
-                    HTTP::Request.new(**request)
-                  end
-
-                  # The Faraday response
-                  subject(:response) { http_client.call(request) }
-
-                  # Callbacks for the expectation
-                  before :each do
-                    Callbacks.before_expectation(
-                      forge, spec, expectation, self, RSpec.current_example
-                    )
-                  end
-
-                  # The 'after_expectation' callback is handled by Listener due to RSpec not
-                  # reporting the example's status until after the describe block has finished.
-                  after :each do
-                    # However, the downside about having the callback triggered later is that RSpec
-                    # will have reset the memoized let variables back to nil.
-                    # This causes an issue when an expectation goes to store the state, it will end
-                    # up re-calling the various variables and triggering another HTTP request.
-                    # Since the variables are still memoized in this hook, it is the perfect
-                    # time to store the referenced to them.
-                    State.set(response:)
-                  end
-
-                  # The test itself
-                  it(expectation.constraints.description) do
-                    if spec.debug? || expectation.debug?
-                      Callbacks.on_debug(forge, spec, expectation, self)
-                    end
-
-                    # Status check
-                    expect(response.status).to match_status
-
-                    # JSON check
-                    if match_json.present?
-                      expect(response.body).to match_json_class
+        forges
+      end
 
-                      case match_json
-                      when Hash
-                        # Check per key for easier debugging
-                        match_json.each do |key, matcher|
-                          expect(response.body).to have_key(key)
-                          expect(response.body[key]).to matcher
-                        end
-                      else
-                        expect(response.body).to match_json
-                      end
-                    end
-                  end
-                end
-              end
-            end
-          end
-        end
+      #
+      # Runs the prepared forges through RSpec
+      #
+      # Sets up the RSpec adapter and executes all tests, with optional
+      # exit behavior for CLI usage.
+      #
+      # @param forges [Array<Forge>] The forge objects to run
+      # @param exit_on_finish [Boolean] Whether to exit the process when complete
+      # @param exit_on_failure [Boolean] Whether to exit the process if any test fails
+      #
+      # @return [Integer, nil] Exit status if exit_on_finish is false
+      #
+      def run(forges, **)
+        Adapter.setup(forges)
+        Adapter.run(**)
       end
 
       private
 
-      def prepare_for_run
-        # Allows modifying the error backtrace reporting within rspec
-        RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
+      def load_forge_helper
+        forge_helper = SpecForge.forge_path.join("forge_helper.rb")
+        require_relative forge_helper if File.exist?(forge_helper)
 
-        # Listen for passed/failed events to trigger the "after_each" callback
-        RSpec.configuration.reporter.register_listener(
-          Listener.instance,
-          :example_passed, :example_failed
-        )
+        # Validate in case anything was changed
+        SpecForge.configuration.validate
       end
     end
   end
 end
 
+require_relative "runner/adapter"
 require_relative "runner/callbacks"
 require_relative "runner/debug_proxy"
 require_relative "runner/listener"

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

@@ -12,21 +12,24 @@ module SpecForge
       # @example In code
       #   constraint = Constraint.new(
       #     status: 200,
-      #     json: {name: "matcher.eq" => "John"}
+      #     headers: {response_header: "kind_of.string"},
+      #     json: {name: {"matcher.eq" => "John"}}
       #   )
       #
-      class Constraint < Data.define(:status, :json) # :xml, :html
+      class Constraint < Data.define(:status, :headers, :json) # :xml, :html
         #
         # Creates a new constraint
         #
         # @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
         #
         # @return [Constraint] A new constraint instance
         #
-        def initialize(status:, json: {})
+        def initialize(status:, headers: {}, json: {})
           super(
             status: Attribute.from(status),
+            headers: Attribute.from(headers),
             json: Attribute.from(json)
           )
         end
@@ -58,7 +61,8 @@ module SpecForge
         def as_matchers
           {
             status: status.resolve_as_matcher,
-            json: resolve_json_matcher
+            json: resolve_json_matcher,
+            headers: resolve_hash_matcher(headers)
           }
         end
 
@@ -108,11 +112,15 @@ module SpecForge
         def resolve_json_matcher
           case json
           when HashLike
-            json.transform_values(&:resolve_as_matcher).stringify_keys
+            resolve_hash_matcher(json)
           else
             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

@@ -15,7 +15,10 @@ module SpecForge
     #       json:
     #         name: kind_of.string
     #
-    class Expectation < Data.define(:id, :name, :line_number, :debug, :store_as, :constraints)
+    class Expectation < Data.define(
+      :id, :name, :line_number,
+      :debug, :store_as, :documentation, :constraints
+    )
       #
       # @return [Boolean] True if debugging is enabled
       #
@@ -34,14 +37,15 @@ module SpecForge
       # @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
       #
       # @return [Expectation] A new expectation instance
       #
-      def initialize(id:, name:, line_number:, debug:, store_as:, expect:)
+      def initialize(id:, name:, line_number:, debug:, store_as:, expect:, documentation:)
         constraints = Constraint.new(**expect)
 
-        super(id:, name:, line_number:, debug:, store_as:, constraints:)
+        super(id:, name:, line_number:, debug:, store_as:, documentation:, constraints:)
       end
 
       #

data/lib/spec_forge/spec.rb

@@ -14,61 +14,15 @@ module SpecForge
   #     - expect:
   #         status: 200
   #
-  class Spec
+  class Spec < Data.define(
+    :id, :name, :file_path, :file_name, :line_number,
+    :debug, :documentation, :expectations
+  )
     #
     # @return [Boolean] True if debugging is enabled
     #
     attr_predicate :debug
 
-    #
-    # Unique identifier for this spec
-    #
-    # @return [String] The spec ID
-    #
-    attr_reader :id
-
-    #
-    # Human-readable name for this spec
-    #
-    # @return [String] The spec name
-    #
-    attr_reader :name
-
-    #
-    # Absolute path to the file containing this spec
-    #
-    # @return [String] The file path
-    #
-    attr_reader :file_path
-
-    #
-    # 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
-
-    #
-    # Line number in the source file where this spec is defined
-    #
-    # @return [Integer] The line number
-    #
-    attr_reader :line_number
-
-    #
-    # The expectations to test for this spec
-    #
-    # @return [Array<Expectation>] The expectations
-    #
-    attr_accessor :expectations
-
     #
     # Creates a new spec instance
     #
@@ -78,18 +32,18 @@ module SpecForge
     # @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
     #
     # @return [Spec] A new spec instance
     #
-    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
-      @expectations = expectations.map { |e| Expectation.new(**e) }
+    def initialize(
+      id:, name:, file_path:, file_name:, line_number:,
+      debug:, documentation:, expectations:
+    )
+      expectations = expectations.map { |e| Expectation.new(**e) }
+
+      super
     end
 
     #
@@ -104,6 +58,7 @@ module SpecForge
         file_name:,
         debug:,
         line_number:,
+        documentation:,
         expectations: expectations.map(&:to_h)
       }
     end

data/lib/spec_forge/version.rb

@@ -4,5 +4,5 @@ module SpecForge
   #
   # Current version of SpecForge
   #
-  VERSION = "0.6.0"
+  VERSION = "0.7.1"
 end

data/lib/spec_forge.rb

@@ -5,15 +5,19 @@ require "logger"
 require "active_support"
 require "active_support/core_ext"
 require "commander"
-require "everythingrb"
+require "everythingrb/prelude"
+require "everythingrb/all"
 require "factory_bot"
 require "faker"
 require "faraday"
 require "mime/types"
+require "openapi3_parser"
 require "pathname"
 require "rspec"
+require "sem_version"
 require "singleton"
 require "thor"
+require "webrick"
 require "yaml"
 
 #
@@ -57,28 +61,8 @@ module SpecForge
     # @param expectation_name [String, nil] Optional name of expectation to run
     #
     def run(file_name: nil, spec_name: nil, expectation_name: nil)
-      # Load spec_helper.rb
-      forge_helper = SpecForge.forge_path.join("forge_helper.rb")
-      require_relative forge_helper if File.exist?(forge_helper)
-
-      # Validate in case anything was changed
-      configuration.validate
-
-      # Load factories
-      Factory.load_and_register
-
-      # Load the specs from their files and create forges from them
-      forges = Loader.load_from_files.map { |f| Forge.new(*f) }
-
-      # Filter out the specs and expectations
-      forges = Filter.apply(forges, file_name:, spec_name:, expectation_name:)
-
-      # Tell the user that we filtered if we did
-      Filter.announce(forges, file_name:, spec_name:, expectation_name:)
-
-      # Define and run everything
-      Runner.define(forges)
-      Runner.run
+      forges = Runner.prepare(file_name:, spec_name:, expectation_name:)
+      Runner.run(forges, exit_on_finish: true)
     end
 
     #
@@ -99,6 +83,15 @@ module SpecForge
       @forge_path ||= root.join("spec_forge")
     end
 
+    #
+    # Returns SpecForge's openapi directory
+    #
+    # @return [Pathname] The spec_forge openapi directory path
+    #
+    def openapi_path
+      @openapi_path ||= forge_path.join("openapi")
+    end
+
     #
     # Returns SpecForge's configuration
     #
@@ -168,6 +161,19 @@ module SpecForge
     def register_callback(name, &)
       Callbacks.register(name, &)
     end
+
+    #
+    # Generates a unique ID for an object based on hash and object_id
+    #
+    # @param object [Object] The object to generate an ID for
+    #
+    # @return [String] A unique ID string
+    #
+    # @private
+    #
+    def generate_id(object)
+      "#{object.hash.abs.to_s(36)}_#{object.object_id.to_s(36)}"
+    end
   end
 end
 
@@ -178,6 +184,7 @@ require_relative "spec_forge/cli"
 require_relative "spec_forge/configuration"
 require_relative "spec_forge/context"
 require_relative "spec_forge/core_ext"
+require_relative "spec_forge/documentation"
 require_relative "spec_forge/error"
 require_relative "spec_forge/factory"
 require_relative "spec_forge/filter"

data/lib/templates/openapi.yml.tt

@@ -0,0 +1,22 @@
+info:
+  title: My API
+  version: 1.0.0
+  description: A description of My API
+  contact:
+    name: My API Team
+    email: api@example.com
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+# servers:
+# - url: https://api.example.com/v1
+#   description: Production
+# - url: https://staging-api.example.com/v1
+#   description: Staging
+#
+# tags:
+# - name: users
+#   description: User account management
+# - name: posts
+#   description: Blog post management

data/lib/templates/redoc.html.tt

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Redoc</title>
+  <!-- needed for adaptive design -->
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+
+  <!--
+    Redoc doesn't change outer page styles
+    -->
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+
+<body>
+  <redoc spec-url="<%= spec_url %>"></redoc>
+  <script src=" https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">
+  </script>
+</body>
+
+</html>

data/lib/templates/swagger.html.tt

@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>Swagger UI</title>
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+
+    *,
+    *:before,
+    *:after {
+      box-sizing: inherit;
+    }
+
+    body {
+      margin: 0;
+      background: #fafafa;
+    }
+  </style>
+
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.24.0/swagger-ui.min.css"
+    integrity="sha512-wWpxfn2bFvPwxuqDyiJbVB0WR3ffSqJNMMryNP07frPJ1h5Xg9HIDMV1wRr1rpxT5E+KTxDrKTuWfGb1RcV8SA=="
+    crossorigin="anonymous" referrerpolicy="no-referrer" />
+</head>
+
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.24.0/swagger-ui-bundle.min.js"
+    integrity="sha512-nEy/zRjIvuFMSr5ljsQUaUW4l7DoSHz8+SRybclmCjCh3MeF9UaooWYdr/SqjGCiyi4RIvBvn9DxCCV0ZDhiNA=="
+    crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.24.0/swagger-ui-standalone-preset.min.js"
+    integrity="sha512-yJlD9FXQ7YaxAKXhviHSt/0KqWDCkLFdCnk0Ti23HXDMEQtHLAAWMHZ+POglC1mx/MOUB//h8kci3U1JYrywpQ=="
+    crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+
+  <script>
+    window.onload = function () {
+      const ui = SwaggerUIBundle({
+        url: "<%= spec_url %>",
+        dom_id: "#swagger-ui",
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      });
+    };
+  </script>
+</body>
+
+</html>