spec_forge 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f51faa712bafdcb48e3940273ec494eb3f39e43c0d122ff0a6f97e425026438
-  data.tar.gz: fe5cf7dff0a44cf5cfc466189fb38c3ed66da21637e18ebcdb44e31f9f6a8b73
+  metadata.gz: 7f8c38cb9ff50cb02ee74171a4d571ac411807b1dcce43edab0f28a757269b2f
+  data.tar.gz: 1595911a7a84d7712ddcc5bf0e2a08c0c30afce995ac02bb1372c1ae29ca7db0
 SHA512:
-  metadata.gz: be068681e3c2ce8b2f62fa21ae03281d40b34c19e190acce4f90796dd526197b6ae54cc6edaa04d6715e347a67e2c193e2b99b0e16e45b47b3183915001790f3
-  data.tar.gz: 644f2c1a49d3ed45a201cb53d731176a418c134679f324ef96f331427481643b2744bd6c27c0f326df32c1db751c412137ad209a3f0b0ce3add9cc68eb6a660e
+  metadata.gz: 731ff8f0cc847010f38caab823c7d30c0d3d7083d4ea53de6ac46c19929c2c31ce698db787303c706ae6ee517dea396ef5ceb220732dd172050967404dd102af
+  data.tar.gz: 1a24dd8f84528427e30d105c4e358ca226b699e79a68a9ac2eb5385a974abb2acb27f8c8a3751e8c69a70001ef8d2ef3938ab06f9c81f1f041325b1b038923e1

data/.standard.yml

@@ -2,6 +2,6 @@
 #   https://github.com/standardrb/standard
 ruby_version: 3.3
 ignore:
-  - ".direnv/**/*"
-  - "vendor/**/*"
-  - "spec/integration/**/*"
+- ".direnv/**/*"
+- "vendor/**/*"
+- "spec/integration/vendor/**/*"

data/CHANGELOG.md

@@ -15,14 +15,227 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 -->
 
-## [Unreleased]
+## [0.7.0] - 12025-06-22
 
 ### Added
 
+#### 🚀 Documentation-First Architecture
+**The Big Picture**: SpecForge now generates OpenAPI documentation from your tests automatically!
+
+- **Primary Documentation Workflow**: New `docs` command (now the default!) generates OpenAPI specs from test execution
+  - Smart caching system with `--fresh` flag for forced regeneration
+  - Multiple output formats: YAML (default) or JSON via `--format`
+  - Custom output paths with `--output` option
+  - Built-in OpenAPI 3.0.4 validation with detailed, helpful error messages
+  - Optional validation skip with `--skip-validation` for faster iterations
+
+- **Live Documentation Server**: `spec_forge serve` command for immediate feedback
+  - Local web server with Swagger UI (default) or Redoc (`--ui redoc`)
+  - Configurable port with `--port` (defaults to 8080)
+  - Auto-generated HTML templates for both UI options
+  - Perfect for development and API review workflows
+
+- **Flexible Configuration System**:
+  - Directory-based config: `config/components/`, `config/paths/`, etc.
+  - Template-based initialization with sensible defaults
+  - Enhanced YAML merging with `$ref` support
+  - Full OpenAPI customization through configuration files
+
+#### 🧪 Enhanced Testing Capabilities
+
+- **HTTP Header Testing**: Comprehensive header validation
+  ```yaml
+  headers:
+    Content-Type: "application/json"
+    X-Request-ID: /^[0-9a-f-]{36}$/
+    Cache-Control:
+      matcher.and:
+      - matcher.include: "max-age="
+      - matcher.include: "private"
+  ```
+
+- **Flexible Store System**: Store anything, access everything
+  - OpenStruct-based entries for maximum flexibility
+  - Custom data via callbacks (config, metadata, computed values)
+  - Same familiar `store.id.attribute` syntax
+  - Perfect for complex test scenarios and feature flags
+
+- **Documentation Control**: Fine-grained control over what gets documented
+  - New `documentation: true/false` attribute for specs and expectations
+  - Exclude test-only scenarios from API docs while keeping functionality
+
+#### ⚙️ Architecture Improvements
+
+- **YAML-Driven Normalizers**: Configuration over code
+  - Structure definitions in `lib/spec_forge/normalizers/*.yml`
+  - Powerful `reference:` system for reusable components
+  - Wildcard support (`*`) for catch-all schemas
+  - Centralized validation logic in dedicated module
+
+- **Enhanced CLI Experience**:
+  - Improved `init` command with `--skip-openapi` and `--skip-factories` flags
+  - Better help text and examples throughout
+  - Clearer error messages with actionable context
+
+- **Developer Utilities**:
+  - `Array#to_merged_h` for cleaner hash merging
+  - Unified `.normalize!(input, using:)` API across normalizers
+  - Separated test preparation (`Runner.prepare`) from execution
+
 ### Changed
 
+#### 🎯 User Experience Overhaul
+
+- **New Default Behavior**: `spec_forge` without arguments now shows help instead of running tests
+  - **Breaking Change**: Use `spec_forge docs` for documentation or `spec_forge run` for test-only execution
+  - Safer default that guides users to the right command for their needs
+
+- **Streamlined Commands**:
+  - Better command organization and help text
+  - Consistent flag naming across commands
+  - Enhanced error handling with helpful suggestions
+
+#### 🏗️ Internal Refactoring
+
+- **Normalizer Architecture**: YAML-based instead of class-heavy approach
+  - Consolidated shared definitions in `_shared.yml`
+  - Easier maintenance and extension
+  - Better error context with attribute path tracking
+
+- **Test Execution Pipeline**:
+  - Clean separation between test preparation and execution
+  - Enhanced RSpec adapter pattern
+  - Better reusability for documentation generation
+
+- **HTTP & Store Improvements**:
+  - Automatic header value string conversion
+  - Simplified store entry structure with OpenStruct flexibility
+  - Enhanced request/response handling
+
 ### Removed
 
+- **Legacy Architecture**: Individual normalizer class files (replaced with YAML config)
+
+---
+
+**Migration Notes**:
+- Update any scripts using bare `spec_forge` - now shows help instead of running tests
+- Use `spec_forge docs` for documentation generation or `spec_forge run` for testing
+- Store access patterns remain the same, but internal structure is more flexible
+
+## [0.6.0] - 12025-03-25
+
+### Added
+
+- Added new context system for managing shared state between tests
+  - Introduced `SpecForge.context` global accessor for accessing test context
+  - Created `Context` class with modular components:
+    - `Context::Global` for file-level shared variables
+    - `Context::Variables` for managing variables with overlay support
+    - `Context::Store` for storing the results of the tests
+- Added support for defining and referencing global variables
+  ```yaml
+  global:
+    variables:
+      api_version: "v2"
+      environment: "test"
+
+  index_user:
+    path: "/{api_version}/users"
+    query:
+      api_version: "global.variables.api_version"
+  ```
+- Added compound matcher support via `matcher.and` for combining multiple matchers
+  ```yaml
+  email:
+    matcher.and:
+    - kind_of.string
+    - /@/
+    - matcher.end_with: ".com"
+  ```
+- Added custom RSpec matcher `have_size` for checking an object's size via `matcher.have_size`
+- Added new `Loader` class for improved spec file processing
+- Added new `Filter` class for more flexible test filtering
+- Added normalizer for global context validation
+- Added line number tracking for specs and expectations
+- Added support for defining and referencing callbacks
+  ```ruby
+  # Configuration level
+  SpecForge.configure do |config|
+    config.register_callback("callback_name") { |context| }
+    # These are aliases
+    # config.define_callback("callback_name") { |context| }
+    # config.callback("callback_name") { |context| }
+  end
+
+  # Module level (no aliases)
+  SpecForge.register_callback("callback_name") { |context| }
+  ```
+  Once defined, callbacks can be referenced in spec files via the global context
+  ```yaml
+  global:
+    callbacks:
+    - before: callback_name
+      after: cleanup_database_state
+  ```
+- Added support for storing and retrieving test data via the `store_as` directive and `store` attribute
+  ```yaml
+  create_user:
+    path: "/users"
+    method: "post"
+    expectations:
+    - variables:
+        name: "John"
+        email: "john@example.com"
+      store_as: "created_user"
+      expect:
+        status: 200
+
+  show_user:
+    path: "/users/:id"
+    query:
+      id: store.created_user.response.id
+    - expect:
+        status: 200
+  ```
+- Added `UndefinedMatcherError` for clearer error messaging when invalid matchers are used
+- Enhanced debugging capabilities with improved DebugProxy methods and store access
+- Added HTTP status descriptions for better error messages
+- Added support for string values in `query`, `body`, and `variables` attributes
+- Added print statement when filtering tests for better visibility
+
+### Changed
+
+- Renamed `SpecForge.forge` to `SpecForge.forge_path`
+- Renamed attribute `http_method` to `http_verb` (`http_method` is now an alias)
+- Refactored attribute resolution methods:
+  - Renamed `Attribute#resolve` to `#resolved` (memoized version)
+  - Renamed `Attribute#resolve_value` to `#resolve` (immediate resolution)
+  - Added `Attribute#resolve_as_matcher` for resolving attributes into RSpec matchers
+- Refactored variable resolution to use the new context system
+- Updated `Runner` to properly initialize and manage context between tests
+- Improved error messages with more contextual information about the execution environment
+- Updated YARD comments with better API descriptions and examples
+- Restructured internal architecture for better separation of concerns
+- Moved all error classes under `SpecForge::Error`
+- Fixed issue where nesting expanded matchers (such as `matcher.include`) would cause an error
+- Improved response body validation for hash expectations:
+  - Each root-level key is now checked individually for more precise error messages
+  - Nested hashes still use the `include` matcher for flexibility
+- Adjusted `Attribute::Matcher` to accept either `matcher` or `matchers` namespace
+- Changed empty array matcher from using `contain_exactly` to `eq([])`
+- Changed empty hash matcher from using `include` to `eq({})`
+- Changed `forge_and` description from "matches all of:" to "match all:"
+- Improved error handling for chainable attributes with better descriptions for various object types
+- Limited error backtrace to 50 lines for cleaner output
+- Enhanced spec loading error messages with more detailed information
+- Improved RSpec example descriptions for better test output
+- Added support for overwriting headers at the request level
+
+## Removed
+
+- Removed `Configuration.overlay_options`
+
 ## [0.5.0] - 12025-02-28
 
 ### Added
@@ -126,7 +339,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial commit
 
-[unreleased]: https://github.com/itsthedevman/spec_forge/compare/v0.5.0...HEAD
+[unreleased]: https://github.com/itsthedevman/spec_forge/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/itsthedevman/spec_forge/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/itsthedevman/spec_forge/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/itsthedevman/spec_forge/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/itsthedevman/spec_forge/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/itsthedevman/spec_forge/compare/v0.3.0...v0.3.2

data/README.md

@@ -4,30 +4,84 @@
 ![Ruby Version](https://img.shields.io/badge/ruby-3.3.7-ruby)
 [![Tests](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml/badge.svg)](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml)
 
-Write API tests in YAML that read like documentation:
+> Note: The code in this repository represents the latest development version with new features and improvements that are being prepared for future releases. For the current stable version, check out [v0.6.0](https://github.com/itsthedevman/spec_forge/releases/tag/v0.6.0) on GitHub releases.
+
+Write API tests in YAML that read like documentation and generate OpenAPI specifications:
 
 ```yaml
-user_profile:
-  path: /users/1
+show_user:
+  path: /users/{id}
+  variables:
+    expected_status: 200
+    user_id: 1
+  query:
+    id: variables.user_id
   expectations:
   - expect:
-      status: 200
+      status: variables.expected_status
       json:
         name: kind_of.string
-        email: /@/
+        email:
+          matcher.and:
+          - kind_of.string
+          - /@/
+      headers:
+        Content-Type: "application/json"
+        X-Request-ID: /^[0-9a-f-]{36}$/
 ```
 
-That's a complete test. No Ruby code, no configuration files, no HTTP client setup - just a clear description of what you're testing. Under the hood, you get all the power of RSpec's matchers, Faker's data generation, and FactoryBot's test objects.
+That's a complete test that validates your API and creates OpenAPI documentation. No Ruby code, no configuration files, no HTTP client setup - just clear, executable specifications.
 
 ## Why SpecForge?
 
-SpecForge shines when you need:
+**For Testing:**
+
+- **Reduce Boilerplate**: Write tests without repetitive setup code and HTTP configuration
+- **Quick Setup**: Start testing APIs in minutes instead of spending hours on test infrastructure
+- **Clear Syntax**: Tests that everyone can read and understand, regardless of Ruby expertise
+
+**For Documentation:**
+
+- **OpenAPI Generation**: Generate OpenAPI specifications from your test structure, with full customization through configuration files
+- **Living Documentation**: Your tests ensure the documentation always matches your actual API behavior
+- **Professional Output**: View your API docs in Swagger UI or Redoc with minimal setup
+
+**For Teams:**
+
+- **Developer & QA Collaboration**: Create specifications that both developers and QA can maintain
+- **Gradual Adoption**: Use alongside your existing test suite, introducing it incrementally where it makes sense
 
-1. **Living Documentation**: Tests serve as clear, maintainable documentation of your API's expected behavior.
-2. **Power Without Complexity**: Get the benefits of Ruby-based tests (dynamic data, factories, matchers) without writing Ruby code.
-3. **Quick Setup**: Start testing APIs without configuring HTTP clients or writing boilerplate code.
-4. **Gradual Adoption**: Use alongside your existing test suite. Keep complex tests in RSpec while making simple API tests more accessible.
-5. **Accessible API Testing**: Non-developers can write and maintain tests without Ruby knowledge. The YAML syntax reads like documentation.
+## Key Features
+
+- **Automatic Documentation Generation**: Transform tests into OpenAPI specifications with customizable configuration
+- **Live Documentation Server**: Local development server for viewing generated documentation
+- **YAML-Based Tests**: Write clear, declarative tests that read like documentation
+- **RSpec Integration**: Leverage all the power of RSpec matchers and expectations
+- **Header Testing**: Comprehensive HTTP header validation with compound matchers
+- **FactoryBot Integration**: Generate test data with FactoryBot integration
+- **Faker Integration**: Create realistic test data with Faker
+- **Variable System**: Define and reference variables for dynamic test data
+- **Context Storage**: Store API responses and reference them in subsequent tests
+- **Compound Matchers**: Combine multiple validations with `matcher.and` for precise expectations
+- **Global Variables**: Define shared configuration at the file level
+- **Callback System**: Hook into the test lifecycle using Ruby for setup, teardown, and much more!
+
+## Quick Start
+
+Get started with SpecForge in 3 commands:
+
+```bash
+# 1. Initialize SpecForge
+spec_forge init
+
+# 2. Create your first test
+spec_forge new spec users
+
+# 3. View your documentation
+spec_forge serve
+```
+
+Then visit `http://localhost:8080` to see your API documentation!
 
 ## When Not to Use SpecForge
 
@@ -72,12 +126,103 @@ Create your first test:
 spec_forge new spec users
 ```
 
-Run your tests:
+Generate documentation (default command):
+
+```bash
+spec_forge
+```
+
+Or start the live documentation server:
+
+```bash
+spec_forge serve
+```
+
+Run tests only (no documentation):
 
 ```bash
 spec_forge run
 ```
 
+## Documentation Workflow
+
+SpecForge provides multiple ways to work with your API documentation:
+
+```bash
+# Generate OpenAPI specifications
+spec_forge docs                    # Smart caching
+spec_forge docs --fresh            # Force regeneration
+spec_forge docs --format json      # Output as JSON instead of YAML
+
+# View documentation in browser
+spec_forge serve                   # Generate if needed + serve
+spec_forge serve --fresh           # Force regeneration + serve
+spec_forge serve --ui redoc        # Use Redoc instead
+spec_forge serve --port 3001       # Custom port
+
+# Traditional testing
+spec_forge run                     # Pure testing mode
+spec_forge run users:show_user     # Run specific tests
+```
+
+## Example: Complete User API
+
+```yaml
+# spec_forge/specs/users.yml
+global:
+  variables:
+    admin_role: "admin"
+
+list_users:
+  path: /users
+  expectations:
+  - expect:
+      status: 200
+      headers:
+        Content-Type: "application/json"
+      json:
+        users:
+          matcher.have_size:
+            be.greater_than: 0
+
+create_user:
+  path: /users
+  method: POST
+  variables:
+    username: faker.internet.username
+    email: faker.internet.email
+  body:
+    name: variables.username
+    email: variables.email
+    role: global.variables.admin_role
+  store_as: new_user
+  expectations:
+  - expect:
+      status: 201
+      headers:
+        Location: /\/users\/\d+/
+      json:
+        id: kind_of.integer
+        name: variables.username
+        email: variables.email
+        role: global.variables.admin_role
+
+show_user:
+  path: /users/{id}
+  query:
+    id: store.new_user.body.id
+  expectations:
+  - expect:
+      status: 200
+      json:
+        id: store.new_user.body.id
+        name: store.new_user.body.name
+        email: store.new_user.body.email
+        role: global.variables.admin_role
+```
+
+This automatically generates a complete OpenAPI specification with all endpoints, request/response schemas, and examples!
+
 ## Documentation
 
 For comprehensive documentation, visit the [SpecForge Wiki](https://github.com/itsthedevman/spec_forge/wiki) which includes:
@@ -85,25 +230,17 @@ For comprehensive documentation, visit the [SpecForge Wiki](https://github.com/i
 - [Getting Started Guide](https://github.com/itsthedevman/spec_forge/wiki/Getting-Started)
 - [Configuration Options](https://github.com/itsthedevman/spec_forge/wiki/Configuration)
 - [Writing Tests](https://github.com/itsthedevman/spec_forge/wiki/Writing-Tests)
+- [Running Tests](https://github.com/itsthedevman/spec_forge/wiki/Running-Tests)
+- [Debugging Guide](https://github.com/itsthedevman/spec_forge/wiki/Debugging)
 - [Dynamic Features](https://github.com/itsthedevman/spec_forge/wiki/Dynamic-Features)
 - [Factory Support](https://github.com/itsthedevman/spec_forge/wiki/Factory-Support)
 - [RSpec Matchers](https://github.com/itsthedevman/spec_forge/wiki/RSpec-Matchers)
 
 Also see the [API Documentation](https://itsthedevman.com/docs/spec_forge).
 
-## Roadmap
-
-Current development priorities:
-- [ ] Negated matchers: `matcher.not`
-- [ ] `create_list/build_list` factory strategies
-- [ ] `transform.map` support
-- [ ] XML/HTML response handling
-- [ ] OpenAPI generation from tests
-- [x] Array support for `json` expectations
-- [x] Support for running individual specs
-- [x] Improved error handling
+## Future Development
 
-Have a feature request? Open an issue on GitHub!
+For the latest development priorities and feature ideas, check out our [Github Project](https://github.com/itsthedevman/spec_forge/projects?query=is%3Aopen). Have a feature request? Open an issue on GitHub!
 
 ## Contributing
 

data/flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1737469691,
-        "narHash": "sha256-nmKOgAU48S41dTPIXAq0AHZSehWUn6ZPrUKijHAMmIk=",
+        "lastModified": 1750365781,
+        "narHash": "sha256-XE/lFNhz5lsriMm/yjXkvSZz5DfvKJLUjsS6pP8EC50=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9e4d5190a9482a1fb9d18adf0bdb83c6e506eaab",
+        "rev": "08f22084e6085d19bcfb4be30d1ca76ecb96fe54",
         "type": "github"
       },
       "original": {

data/flake.nix

@@ -1,21 +1,27 @@
 {
-  description = "Ruby 3.4.2 development environment";
+  description = "Ruby 3.2 development environment";
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     flake-utils.url = "github:numtide/flake-utils";
   };
 
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system:
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
       in
       {
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
-            (ruby_3_4.override {
-              jemallocSupport = true;
+            (ruby_3_2.override {
+              jemallocSupport = false;
               docSupport = false;
             })