spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge.rb

@@ -5,103 +5,195 @@ 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"
 
-require_relative "spec_forge/attribute"
-require_relative "spec_forge/backtrace_formatter"
-require_relative "spec_forge/cli"
-require_relative "spec_forge/configuration"
-require_relative "spec_forge/core_ext"
-require_relative "spec_forge/error"
-require_relative "spec_forge/factory"
-require_relative "spec_forge/http"
-require_relative "spec_forge/normalizer"
-require_relative "spec_forge/runner"
-require_relative "spec_forge/spec"
-require_relative "spec_forge/type"
-require_relative "spec_forge/version"
-
+#
+# SpecForge: Write expressive API tests in YAML with the power of RSpec matchers
+#
+# SpecForge is a testing framework that allows writing API tests in a YAML format
+# that reads like documentation. It combines the readability of YAML with the
+# power of RSpec matchers, Faker data generation, and FactoryBot test objects.
+#
+# @example Basic spec in YAML
+#   get_user:
+#     path: /users/1
+#     expectations:
+#     - expect:
+#         status: 200
+#         json:
+#           name: kind_of.string
+#           email: /@/
+#
+# @example Running specs
+#   # Run all specs
+#   SpecForge.run
+#
+#   # Run specific file
+#   SpecForge.run(file_name: "users")
+#
+#   # Run specific spec
+#   SpecForge.run(file_name: "users", spec_name: "create_user")
+#
 module SpecForge
-  #
-  # Loads all factories and specs located in "path", then runs all of the specs
-  #
-  # @param path [String] The file path that contains factories and specs
-  #
-  def self.run(file_name: nil, spec_name: nil, expectation_name: nil)
-    path = SpecForge.forge
+  class << self
+    #
+    # Loads all factories and specs and runs the tests with optional filtering
+    #
+    # This is the main entry point for running SpecForge tests. It loads the
+    # forge_helper.rb file if it exists, configures the environment, loads
+    # factories and specs, and runs the tests through RSpec.
+    #
+    # @param file_name [String, nil] Optional name of spec file to run
+    # @param spec_name [String, nil] Optional name of spec to run
+    # @param expectation_name [String, nil] Optional name of expectation to run
+    #
+    def run(file_name: nil, spec_name: nil, expectation_name: nil)
+      forges = Runner.prepare(file_name:, spec_name:, expectation_name:)
+      Runner.run(forges, exit_on_finish: true)
+    end
 
-    # Initialize
-    forge_helper = path.join("forge_helper.rb")
-    require_relative forge_helper if File.exist?(forge_helper)
+    #
+    # Returns the directory root for the working directory
+    #
+    # @return [Pathname] The root directory path
+    #
+    def root
+      @root ||= Pathname.pwd
+    end
 
-    # Validate
-    configuration.validate
+    #
+    # Returns SpecForge's working directory
+    #
+    # @return [Pathname] The spec_forge directory path
+    #
+    def forge_path
+      @forge_path ||= root.join("spec_forge")
+    end
 
-    # Prepare
-    Factory.load_and_register
-    Spec.load_and_define(file_name:, spec_name:, expectation_name:)
+    #
+    # Returns SpecForge's openapi directory
+    #
+    # @return [Pathname] The spec_forge openapi directory path
+    #
+    def openapi_path
+      @openapi_path ||= forge_path.join("openapi")
+    end
 
-    # Run
-    Runner.run
-  end
+    #
+    # Returns SpecForge's configuration
+    #
+    # @return [Configuration] The current configuration
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
 
-  #
-  # Returns the directory root for the working directory
-  #
-  # @return [Pathname]
-  #
-  def self.root
-    @root ||= Pathname.pwd
-  end
+    #
+    # Yields SpecForge's configuration to a block for modification
+    #
+    # @yield [config] Block that receives the configuration object
+    # @yieldparam config [Configuration] The configuration to modify
+    #
+    # @return [Configuration] The updated configuration
+    #
+    def configure(&block)
+      block&.call(configuration)
+      configuration
+    end
 
-  #
-  # Returns SpecForge's working directory
-  #
-  # @return [Pathname]
-  #
-  def self.forge
-    @forge ||= root.join("spec_forge")
-  end
+    #
+    # Returns a backtrace cleaner configured for SpecForge
+    #
+    # Creates and configures an ActiveSupport::BacktraceCleaner to improve
+    # error messages by removing unnecessary lines and root paths.
+    #
+    # @return [ActiveSupport::BacktraceCleaner] The configured backtrace cleaner
+    #
+    def backtrace_cleaner
+      @backtrace_cleaner ||= begin
+        root = "#{SpecForge.root}/"
 
-  #
-  # Returns SpecForge's configuration
-  #
-  # @return [Config]
-  #
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
+        cleaner = ActiveSupport::BacktraceCleaner.new
+        cleaner.add_filter { |line| line.delete_prefix(root) }
+        cleaner.add_silencer { |line| /rubygems|backtrace_cleaner/.match?(line) }
+        cleaner
+      end
+    end
 
-  #
-  # Yields SpecForge's configuration to a block
-  #
-  def self.configure(&block)
-    block&.call(configuration)
-    configuration
-  end
+    #
+    # Returns the current execution context
+    #
+    # @return [Context] The current context object
+    #
+    def context
+      @context ||= Context.new
+    end
 
-  #
-  # Returns a backtrace cleaner configured for SpecForge
-  #
-  # @return [ActiveSupport::BacktraceCleaner]
-  #
-  def self.backtrace_cleaner
-    @backtrace_cleaner ||= begin
-      root = "#{SpecForge.root}/"
+    #
+    # Registers a callback for a specific test lifecycle event
+    # Allows custom code execution at specific points during test execution
+    #
+    # @param name [Symbol, String] A unique identifier for this callback
+    # @yield A block to execute when the callback is triggered
+    # @yieldparam context [Object] An object containing context-specific state data, depending
+    #   on which hook the callback is triggered from.
+    #
+    # @return [Proc] The registered callback
+    #
+    # @example Registering a custom debug handler
+    #   SpecForge.register_callback(:clean_database) do |context|
+    #     DatabaseCleaner.clean
+    #   end
+    #
+    def register_callback(name, &)
+      Callbacks.register(name, &)
+    end
 
-      cleaner = ActiveSupport::BacktraceCleaner.new
-      cleaner.add_filter { |line| line.delete_prefix(root) }
-      cleaner.add_silencer { |line| /rubygems|backtrace_cleaner/.match?(line) }
-      cleaner
+    #
+    # 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
+
+require_relative "spec_forge/attribute"
+require_relative "spec_forge/backtrace_formatter"
+require_relative "spec_forge/callbacks"
+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"
+require_relative "spec_forge/forge"
+require_relative "spec_forge/http"
+require_relative "spec_forge/loader"
+require_relative "spec_forge/matchers"
+require_relative "spec_forge/normalizer"
+require_relative "spec_forge/runner"
+require_relative "spec_forge/spec"
+require_relative "spec_forge/type"
+require_relative "spec_forge/version"

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>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spec_forge
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-28 00:00:00.000000000 Z
+date: 2025-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: factory_bot
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: openapi3_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: sem_version
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +164,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
 description: Write API tests in YAML without sacrificing power. SpecForge combines
   RSpec's matcher system, Faker's data generation, and factory patterns into a clean,
   declarative syntax that eliminates boilerplate while preserving control over your
@@ -163,6 +205,7 @@ files:
 - lib/spec_forge/attribute/chainable.rb
 - lib/spec_forge/attribute/factory.rb
 - lib/spec_forge/attribute/faker.rb
+- lib/spec_forge/attribute/global.rb
 - lib/spec_forge/attribute/literal.rb
 - lib/spec_forge/attribute/matcher.rb
 - lib/spec_forge/attribute/parameterized.rb
@@ -170,44 +213,94 @@ files:
 - lib/spec_forge/attribute/resolvable.rb
 - lib/spec_forge/attribute/resolvable_array.rb
 - lib/spec_forge/attribute/resolvable_hash.rb
+- lib/spec_forge/attribute/store.rb
 - lib/spec_forge/attribute/transform.rb
 - lib/spec_forge/attribute/variable.rb
 - lib/spec_forge/backtrace_formatter.rb
+- lib/spec_forge/callbacks.rb
 - lib/spec_forge/cli.rb
 - lib/spec_forge/cli/actions.rb
 - lib/spec_forge/cli/command.rb
+- lib/spec_forge/cli/docs.rb
+- lib/spec_forge/cli/docs/generate.rb
 - lib/spec_forge/cli/init.rb
 - lib/spec_forge/cli/new.rb
 - lib/spec_forge/cli/run.rb
+- lib/spec_forge/cli/serve.rb
 - lib/spec_forge/configuration.rb
+- lib/spec_forge/context.rb
+- lib/spec_forge/context/callbacks.rb
+- lib/spec_forge/context/global.rb
+- lib/spec_forge/context/store.rb
+- lib/spec_forge/context/variables.rb
 - lib/spec_forge/core_ext.rb
+- lib/spec_forge/core_ext/array.rb
 - lib/spec_forge/core_ext/rspec.rb
+- lib/spec_forge/documentation.rb
+- lib/spec_forge/documentation/builder.rb
+- lib/spec_forge/documentation/document.rb
+- lib/spec_forge/documentation/document/operation.rb
+- lib/spec_forge/documentation/document/parameter.rb
+- lib/spec_forge/documentation/document/request_body.rb
+- lib/spec_forge/documentation/document/response.rb
+- lib/spec_forge/documentation/document/response_body.rb
+- lib/spec_forge/documentation/generators.rb
+- lib/spec_forge/documentation/generators/base.rb
+- lib/spec_forge/documentation/generators/openapi.rb
+- lib/spec_forge/documentation/generators/openapi/base.rb
+- lib/spec_forge/documentation/generators/openapi/error_formatter.rb
+- lib/spec_forge/documentation/generators/openapi/v3_0.rb
+- lib/spec_forge/documentation/loader.rb
+- lib/spec_forge/documentation/loader/cache.rb
+- lib/spec_forge/documentation/openapi.rb
+- lib/spec_forge/documentation/openapi/base.rb
+- lib/spec_forge/documentation/openapi/v3_0/example.rb
+- lib/spec_forge/documentation/openapi/v3_0/media_type.rb
+- lib/spec_forge/documentation/openapi/v3_0/operation.rb
+- lib/spec_forge/documentation/openapi/v3_0/response.rb
+- lib/spec_forge/documentation/openapi/v3_0/schema.rb
+- lib/spec_forge/documentation/openapi/v3_0/tag.rb
 - lib/spec_forge/error.rb
 - lib/spec_forge/factory.rb
+- lib/spec_forge/filter.rb
+- lib/spec_forge/forge.rb
 - lib/spec_forge/http.rb
 - lib/spec_forge/http/backend.rb
 - lib/spec_forge/http/client.rb
 - lib/spec_forge/http/request.rb
 - lib/spec_forge/http/verb.rb
+- lib/spec_forge/loader.rb
+- lib/spec_forge/matchers.rb
 - lib/spec_forge/normalizer.rb
-- lib/spec_forge/normalizer/configuration.rb
-- lib/spec_forge/normalizer/constraint.rb
-- lib/spec_forge/normalizer/expectation.rb
-- lib/spec_forge/normalizer/factory.rb
-- lib/spec_forge/normalizer/factory_reference.rb
-- lib/spec_forge/normalizer/spec.rb
+- lib/spec_forge/normalizer/default.rb
+- lib/spec_forge/normalizer/definition.rb
+- lib/spec_forge/normalizer/validators.rb
+- lib/spec_forge/normalizers/_shared.yml
+- lib/spec_forge/normalizers/configuration.yml
+- lib/spec_forge/normalizers/constraint.yml
+- lib/spec_forge/normalizers/expectation.yml
+- lib/spec_forge/normalizers/factory.yml
+- lib/spec_forge/normalizers/factory_reference.yml
+- lib/spec_forge/normalizers/global_context.yml
+- lib/spec_forge/normalizers/spec.yml
 - lib/spec_forge/runner.rb
+- lib/spec_forge/runner/adapter.rb
+- lib/spec_forge/runner/callbacks.rb
+- lib/spec_forge/runner/debug_proxy.rb
+- lib/spec_forge/runner/listener.rb
+- lib/spec_forge/runner/metadata.rb
+- lib/spec_forge/runner/state.rb
 - lib/spec_forge/spec.rb
 - lib/spec_forge/spec/expectation.rb
 - lib/spec_forge/spec/expectation/constraint.rb
 - lib/spec_forge/type.rb
 - lib/spec_forge/version.rb
-- lib/templates/forge_helper.tt
-- lib/templates/new_factory.tt
-- lib/templates/new_spec.tt
-- spec_forge/factories/user.yml
-- spec_forge/forge_helper.rb
-- spec_forge/specs/users.yml
+- lib/templates/forge_helper.rb.tt
+- lib/templates/new_factory.yml.tt
+- lib/templates/new_spec.yml.tt
+- lib/templates/openapi.yml.tt
+- lib/templates/redoc.html.tt
+- lib/templates/swagger.html.tt
 homepage: https://github.com/itsthedevman/spec_forge
 licenses:
 - MIT

data/lib/spec_forge/normalizer/configuration.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-module SpecForge
-  class Normalizer
-    class Configuration < Normalizer
-      STRUCTURE = {
-        base_url: SHARED_ATTRIBUTES[:base_url].except(:default), # Make it required
-        headers: SHARED_ATTRIBUTES[:headers],
-        query: SHARED_ATTRIBUTES[:query],
-        factories: {
-          type: Hash,
-          default: {},
-          structure: {
-            auto_discover: {
-              type: [TrueClass, FalseClass],
-              default: true
-            },
-            paths: {
-              type: Array,
-              default: []
-            }
-          }
-        },
-        on_debug: {
-          type: Proc
-        }
-      }.freeze
-    end
-
-    # On Normalizer
-    class << self
-      #
-      # Generates an empty configuration hash
-      #
-      # @return [Hash]
-      #
-      def default_configuration
-        Configuration.default
-      end
-
-      #
-      # Normalizes a configuration hash by standardizing its keys while ensuring the required data
-      # is provided or defaulted.
-      # Raises InvalidStructureError if anything is missing/invalid type
-      #
-      # @param input [Hash] The hash to normalize
-      #
-      # @return [Hash] A normalized hash as a new instance
-      #
-      def normalize_configuration!(input)
-        raise_errors! do
-          normalize_configuration(input)
-        end
-      end
-
-      #
-      # Normalize a configuration hash
-      # Used internally by .normalize_configuration!, but is available for utility
-      #
-      # @param configuration [Hash] Configuration representation as a Hash
-      #
-      # @return [Array] Two item array
-      #   First - The normalized hash
-      #   Second - Array of errors, if any
-      #
-      # @private
-      #
-      def normalize_configuration(configuration)
-        if !Type.hash?(configuration)
-          raise InvalidTypeError.new(configuration, Hash, for: "configuration")
-        end
-
-        Normalizer::Configuration.new("configuration", configuration).normalize
-      end
-    end
-  end
-end