spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/cli/run.rb

@@ -2,12 +2,37 @@
 
 module SpecForge
   class CLI
+    #
+    # Command for running SpecForge tests with filtering options
+    #
+    # @example Running all specs
+    #   spec_forge run
+    #
+    # @example Running specific file
+    #   spec_forge run users
+    #
+    # @example Running specific spec
+    #   spec_forge run users:create_user
+    #
+    # @example Running specific expectation
+    #   spec_forge run users:create_user:"POST /users"
+    #
     class Run < Command
       command_name "run"
       syntax "run [target]"
 
-      summary "Runs specs loaded from spec_forge/specs/"
-      description "Runs specs loaded from spec_forge/specs/. The optional target argument allows running specific files, specs, or expectations."
+      summary "Execute your API tests with smart filtering options"
+
+      description <<~DESC
+        Execute API tests with filtering options.
+
+        Target formats:
+          • file_name - Run all specs in a file
+          • file:spec - Run specific spec
+          • file:spec:"expectation" - Run individual expectation
+
+        Uses RSpec for execution with detailed error reporting.
+      DESC
 
       example "spec_forge run",
         "Run all specs in spec_forge/specs/"
@@ -24,8 +49,9 @@ module SpecForge
       example "spec_forge run users:create_user:\"POST /users - Create Admin\"",
         "Run the specific expectation named \"Create Admin\""
 
-      # option "-n", "--no-docs", "Do not generate OpenAPI documentation on completion"
-
+      #
+      # Loads and runs all specs, or a subset of specs based on the provided arguments
+      #
       def call
         return SpecForge.run if arguments.blank?
 
@@ -53,6 +79,8 @@ module SpecForge
       #     Example with name:
       #       "users:show_user:'GET /users/:id - Returns 404 due to missing user'"
       #
+      # @private
+      #
       def extract_filter(input)
         # Note: Only split 3 because the expectation name can have colons in them.
         file_name, spec_name, expectation_name = input.split(":", 3).map(&:strip)

data/lib/spec_forge/cli/serve.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class CLI
+    #
+    # Command for generating and serving API documentation
+    #
+    # Combines documentation generation with a local web server to provide
+    # an easy way to view and interact with generated API documentation.
+    # Supports both Swagger UI and Redoc interfaces.
+    #
+    # @example Start documentation server
+    #   spec_forge serve
+    #
+    # @example Serve with Redoc UI
+    #   spec_forge serve --ui redoc
+    #
+    class Serve < Command
+      include Docs::Generate
+      #
+      # Valid file formats for documentation output
+      #
+      # Supported formats include YAML variants (yml, yaml) and JSON.
+      # Used for validation when users specify the --format option.
+      #
+      # @api private
+      #
+      VALID_FORMATS = %w[yml yaml json].freeze
+
+      command_name "serve"
+      syntax "serve"
+      summary "Start a local server to preview your API documentation"
+      description <<~DESC
+        Generate documentation and start a local preview server.
+
+        Combines docs generation with a web interface. Choose between
+        Swagger UI or Redoc for viewing the documentation.
+      DESC
+
+      example "serve",
+        "Generates docs (if needed) and starts documentation server at localhost:8080"
+
+      example "serve --fresh",
+        "Re-runs tests, regenerates docs, and starts the documentation server"
+
+      example "serve --ui redoc",
+        "Starts server with Redoc interface instead of Swagger UI"
+
+      example "serve --port 3001",
+        "Starts documentation server on port 3001"
+
+      example "serve --fresh --ui redoc --port 3001",
+        "Re-runs tests and serves fresh docs with Redoc on custom port"
+
+      # Generation options
+      option "--fresh", "Re-run all tests before starting server"
+      option "--format=FORMAT", "Output format: yml/yaml or json (default: yml)"
+      option "--skip-validation", "Skip OpenAPI specification validation during generation"
+
+      # Server options
+      option "--ui=UI", "Documentation interface: swagger or redoc (default: swagger)"
+      option "--port=PORT", "Port to serve documentation on (default: 8080)"
+
+      aliases :s
+
+      #
+      # Generates documentation and starts a local web server
+      #
+      # Creates OpenAPI documentation from tests and serves it through a local
+      # HTTP server with either Swagger UI or Redoc interface for easy viewing.
+      #
+      # @return [void]
+      #
+      def call
+        server_path = SpecForge.openapi_path.join("server")
+        actions.empty_directory(server_path, verbose: false) # spec_forge/openapi/server
+
+        # Generate and copy the OpenAPI spec file
+        file_name = generate_and_copy_openapi_spec
+
+        # Determine which template file to use
+        template_name =
+          if options.ui == "redoc"
+            "redoc.html.tt"
+          else
+            "swagger.html.tt"
+          end
+
+        # Remove the index if it exists
+        index_path = server_path.join("index.html")
+        index_path.delete if index_path.exist?
+
+        # Generate index.html
+        actions.template(
+          template_name,
+          index_path,
+          context: Proxy.new(spec_url: file_name).call,
+          verbose: false
+        )
+
+        # And serve it!
+        port = options.port || 8080
+        server = WEBrick::HTTPServer.new(
+          Port: port,
+          DocumentRoot: server_path
+        )
+
+        puts <<~STRING
+          ========================================
+          🚀 SpecForge Documentation Server
+          ========================================
+          Server running at: http://localhost:#{port}
+          Press Ctrl+C to stop
+          ========================================
+        STRING
+
+        trap("INT") { server.shutdown }
+        server.start
+      end
+
+      private
+
+      def generate_and_copy_openapi_spec
+        server_path = SpecForge.openapi_path.join("server")
+
+        file_path = generate_documentation
+
+        file_name = file_path.basename
+        path = server_path.join(file_name)
+
+        # If the file already exists, delete it
+        # This ensures we always have the latest spec
+        path.delete if path.exist?
+
+        actions.copy_file(file_path, path, verbose: false)
+
+        file_name
+      end
+
+      #
+      # Helper class for passing template variables to Thor templates
+      #
+      class Proxy < Struct.new(:spec_url)
+        #
+        # Returns a binding for use in templates
+        #
+        # @return [Binding] A binding containing template variables
+        #
+        def call
+          binding
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/cli.rb

@@ -2,35 +2,54 @@
 
 require_relative "cli/actions"
 require_relative "cli/command"
+require_relative "cli/docs"
 require_relative "cli/init"
 require_relative "cli/new"
 require_relative "cli/run"
+require_relative "cli/serve"
 
 module SpecForge
+  #
+  # Command-line interface for SpecForge that provides the overall command structure
+  # and entry point for the CLI functionality.
+  #
+  # @example Running a specific command
+  #   # From command line: spec_forge init
+  #
   class CLI
     include Commander::Methods
 
-    COMMANDS = [Init, New, Run]
-
     #
-    # Runs the CLI
+    # @return [Array<SpecForge::CLI::Command>] All available commands
     #
-    # @private
+    COMMANDS = [Docs, Init, New, Run, Serve].freeze
+
+    #
+    # Runs the CLI application, setting up program information and registering commands
     #
     def run
       program :name, "SpecForge"
       program :version, SpecForge::VERSION
-      program :description, "Write expressive API tests in YAML with the power of RSpec matchers"
+      program :description, <<~DESC.strip
+        Write expressive API tests in YAML with the power of RSpec matchers.
+
+        Quick Start:
+          spec_forge init              # Set up your project
+          spec_forge new spec users    # Create your first test
+          spec_forge run               # Execute tests
+          spec_forge docs              # Generate API docs
+          spec_forge serve             # Serve API docs locally
+      DESC
 
       register_commands
 
-      default_command :run
+      default_command :help
 
       run!
     end
 
     #
-    # Registers the commands with Commander
+    # Registers the command classes with Commander
     #
     # @private
     #

data/lib/spec_forge/configuration.rb

@@ -1,45 +1,64 @@
 # frozen_string_literal: true
 
 module SpecForge
-  class Configuration < Struct.new(:base_url, :headers, :query, :factories, :specs, :on_debug)
-    ############################################################################
-
+  #
+  # Configuration container for SpecForge settings
+  # Defines default values and validation for all configuration options
+  #
+  class Configuration < Struct.new(:base_url, :headers, :query, :factories, :on_debug)
+    #
+    # Manages factory configuration settings
+    # Controls auto-discovery behavior and custom factory paths
+    #
+    # @example
+    #   config.factories.auto_discover = false
+    #   config.factories.paths += ["lib/factories"]
+    #
     class Factories < Struct.new(:auto_discover, :paths)
+      #
+      # Creates reader methods that return boolean values
+      # Allows for checking configuration with predicate methods
+      #
       attr_predicate :auto_discover, :paths
 
+      #
+      # Initializes a new Factories configuration
+      # Sets default values for auto-discovery and paths
+      #
+      # @param auto_discover [Boolean] Whether to auto-discover factories (default: true)
+      # @param paths [Array<String>] Additional paths to look for factories (default: [])
+      #
+      # @return [Factories] A new factories configuration instance
+      #
       def initialize(auto_discover: true, paths: []) = super
     end
 
-    ############################################################################
-
-    def self.overlay_options(source, overlay)
-      source.deep_merge(overlay) do |key, source_value, overlay_value|
-        # If overlay has a populated value, use it
-        if overlay_value.present? || overlay_value == false
-          overlay_value
-        # If source is nil and overlay exists (but wasn't "present"), use overlay
-        elsif source_value.nil? && !overlay_value.nil?
-          overlay_value
-        # Otherwise keep source value
-        else
-          source_value
-        end
-      end
-    end
-
+    #
+    # Initializes a new Configuration with default values
+    # Sets up the configuration structure including factory settings and debug proxy
+    #
+    # @return [Configuration] A new configuration instance with defaults
+    #
     def initialize
-      config = Normalizer.default_configuration
+      config = Normalizer.default(:configuration)
 
       config[:base_url] = "http://localhost:3000"
       config[:factories] = Factories.new
-      config[:specs] = RSpec.configuration
       config[:on_debug] = Runner::DebugProxy.default
 
       super(**config)
     end
 
+    #
+    # Validates the configuration and applies normalization
+    # Ensures all required fields have values and applies defaults when needed
+    #
+    # @return [self] Returns self for method chaining
+    #
+    # @api private
+    #
     def validate
-      output = Normalizer.normalize_configuration!(to_h)
+      output = Normalizer.normalize!(to_h, using: :configuration)
 
       # In case any value was set to `nil`
       self.base_url = output[:base_url] if base_url.blank?
@@ -49,10 +68,63 @@ module SpecForge
       self
     end
 
+    #
+    # Recursively converts the configuration to a hash representation
+    #
+    # @return [Hash] Hash representation of the configuration
+    #
     def to_h
-      hash = super.except(:specs)
+      hash = super
       hash[:factories] = hash[:factories].to_h
       hash
     end
+
+    #
+    # Returns the RSpec configuration object
+    # Provides access to RSpec's internal configuration for test customization
+    #
+    # @return [RSpec::Core::Configuration] RSpec's configuration object
+    #
+    # @example Setting formatter options
+    #   SpecForge.configure do |config|
+    #     config.specs.formatter = :documentation
+    #   end
+    #
+    def specs
+      RSpec.configuration
+    end
+
+    alias_method :rspec, :specs
+
+    #
+    # Registers a callback for a specific test lifecycle event
+    # Allows custom code execution at specific points during test execution
+    #
+    # @param name [Symbol, String] The callback point to register for
+    #   (:before_file, :after_expectation, etc.)
+    # @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.configure do |config|
+    #     config.register_callback(:on_debug) { binding.pry }
+    #   end
+    #
+    # @example Cleaning database after each test
+    #   SpecForge.configure do |config|
+    #     config.register_callback(:after_expectation) do
+    #       DatabaseCleaner.clean
+    #     end
+    #   end
+    #
+    def register_callback(name, &)
+      Callbacks.register(name, &)
+    end
+
+    alias_method :define_callback, :register_callback
+    alias_method :callback, :register_callback
   end
 end

data/lib/spec_forge/context/callbacks.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages user-defined callbacks grouped by lifecycle hook
+    #
+    # This class collects and organizes callbacks by their hook type
+    # (before_file, after_each, etc.) to support the test lifecycle.
+    # It ensures callbacks are properly categorized for execution.
+    #
+    # @example Creating callback groups
+    #   callbacks = Context::Callbacks.new([
+    #     {before_file: "setup_environment"},
+    #     {after_each: "log_test_result"}
+    #   ])
+    #
+    class Callbacks
+      #
+      # Creates a new callbacks collection
+      #
+      # @param callback_array [Array] Optional initial callbacks to register
+      #
+      # @return [Callbacks] A new callbacks collection
+      #
+      def initialize(callback_array = [])
+        set(callback_array)
+      end
+
+      #
+      # Updates the callbacks collection
+      #
+      # @param callback_array [Array] New callbacks to register
+      #
+      # @return [self]
+      #
+      def set(callback_array)
+        @inner = organize_callbacks_by_hook(callback_array)
+        self
+      end
+
+      #
+      # Returns the hash representation of callbacks
+      #
+      # @return [Hash] Callbacks organized by hook type
+      #
+      def to_h
+        @inner
+      end
+
+      #
+      # Executes all registered callbacks for a specific lifecycle hook
+      #
+      # @param hook_name [String, Symbol] The lifecycle hook (before_file, after_each, etc.)
+      # @param context [Hash] State data that will be converted to a structured object
+      #   and passed to callbacks
+      #
+      def run(hook_name, context = {})
+        context = context.to_struct
+
+        @inner[hook_name].each do |callback_name|
+          SpecForge::Callbacks.run(callback_name, context)
+        end
+      end
+
+      private
+
+      #
+      # Organizes callbacks from an array to hash structure by hook type
+      # Groups callbacks like before_file, after_each, etc. for easier lookup
+      #
+      # @param callback_array [Array] The array of callbacks
+      #
+      # @return [Hash] Callbacks indexed by hook type
+      #
+      # @private
+      #
+      def organize_callbacks_by_hook(callback_array)
+        groups = Hash.new { |h, k| h[k] = Set.new }
+
+        callback_array.each_with_object(groups) do |callbacks, groups|
+          callbacks.each do |hook, name|
+            next if name.blank?
+
+            groups[hook].add(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/context/global.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages global state and variables at the spec file level.
+    #
+    # The Global class provides access to variables that are defined at the global level
+    # in a spec file and are accessible across all specs and expectations in a file.
+    # Unlike regular variables, global variables do not support overlaying - they maintain
+    # consistent values throughout test execution.
+    #
+    # @example Basic usage
+    #   global = Global.new(variables: {api_version: "v2", environment: "test"})
+    #
+    #   global.variables[:api_version] #=> "v2"
+    #   global.variables[:environment] #=> "test"
+    #
+    #   # Update global variables
+    #   global.set(variables: {environment: "staging"})
+    #   global.variables[:environment] #=> "staging"
+    #   global.variables[:api_version] #=> nil
+    #
+    class Global
+      # @return [Context::Variables] The container for global variables
+      attr_reader :variables
+
+      # @return [Context::Callbacks] The container for callbacks
+      attr_reader :callbacks
+
+      #
+      # Creates a new Global context instance
+      #
+      # @param variables [Hash<Symbol, Object>] A hash of variable names and values
+      # @param callbacks [Array<Hash<Symbol, String>>] An array of callback hooks
+      #
+      # @return [Global] The new Global instance
+      #
+      def initialize(variables: {}, callbacks: [])
+        @variables = Variables.new(base: variables)
+        @callbacks = Callbacks.new(callbacks)
+      end
+
+      #
+      # Sets the global variables
+      #
+      # @param variables [Hash<Symbol, Object>] A hash of variable names and values
+      # @param callbacks [Array<Hash<Symbol, String>>] An array of callback hooks
+      #
+      # @return [self]
+      #
+      def set(variables: {}, callbacks: [])
+        @variables.set(base: variables)
+        @callbacks.set(callbacks)
+
+        self
+      end
+
+      #
+      # Returns a hash representation of the global context
+      #
+      # @return [Hash]
+      #
+      def to_h
+        {
+          variables: variables.to_h,
+          callbacks: callbacks.to_h
+        }
+      end
+    end
+  end
+end