spec_forge 0.7.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9891353d8acd7d64ec4b2690e4e91d68c0d455913b8ca81c7f9e410859f51774
-  data.tar.gz: 7ff9aa712f7d21a75ae8a383175702ed8973b25e2935458bd75dd713f59b6fb3
+  metadata.gz: 2a63a7870c53ed507204c4848b271094c53a5be8d2925e7b04b359f6885b61cc
+  data.tar.gz: 12684cb3c690072fe1ead4c4ef5d4e9b2fb13d2e40f27c5eeea75fba9cdbff0e
 SHA512:
-  metadata.gz: 0637e96a8739579015af17ee0a6c8442b51c9fd189b2a220b7828ae68f0784760aad4d5312eabf450f18ee7e6db2789dad3fb55327cee0aa19f3a8e9b88be243
-  data.tar.gz: 3d10cc2cafb76d2d14b42e104fba62a5e8ec35d70cb92f6769e3fcde9611d9949d707fdc287caae52454e04d6542c507274e357bb38f41090792efa40e5d6436
+  metadata.gz: f656557492767c8f2391f334461ee4efbcad40118f7608b9d26ba6e5ee1492c3adddce4d76565a79b145b4d2f017de9f43aabbdfdf7e9e837fc71c77b54a4555
+  data.tar.gz: dbaf154a1d50d7399d7c25d5655ad9809185dd410de71d3f2b62809435dfdf75b1d0948ddcc848059c2ee0b7053fc31c148dac164c63636edf2b823c5562a963

data/CHANGELOG.md

@@ -15,6 +15,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 -->
 
+## [1.0.0] - 12026-01-29
+
+### ⚠️ Breaking Changes
+
+This release is a complete architectural redesign. See the [Migration Guide](https://github.com/itsthedevman/spec_forge/wiki/Migration-Guide) for detailed upgrade instructions.
+
+**Core changes:**
+- Directory renamed: `spec_forge/specs/` → `spec_forge/blueprints/`
+- CLI renamed: `spec_forge new spec` → `spec_forge new blueprint`
+- YAML structure rewritten from spec-based to sequential step-based workflows
+- Variable syntax changed: `variables.name` → `{{ name }}` template syntax
+- Execution architecture changed: Forge now orchestrates workflows and delegates validation to RSpec, replacing the previous fully RSpec-driven approach
+
+**Configuration:**
+- Removed: `config.headers`, `config.query` (use explicit inheritance instead)
+- Changed: `config.specs` → `config.rspec`
+- Changed: `config.on_debug = proc` → `config.on_debug { block }`
+
+### Added
+
+- **Step-based workflows**: Tests execute as sequential steps with explicit data flow between them. See [Writing Tests](https://github.com/itsthedevman/spec_forge/wiki/Writing-Tests).
+
+  ```yaml
+  - name: "Create user"
+    request:
+      url: /users
+      http_verb: POST
+      json:
+        email: "{{ faker.internet.email }}"
+    expect:
+    - status: 201
+    store:
+      user_id: "{{ response.body.id }}"
+
+  - name: "Fetch created user"
+    request:
+      url: "/users/{{ user_id }}"
+    expect:
+    - status: 200
+  ```
+
+- **Template variable system**: New `{{ }}` syntax for dynamic values—supports variables, Faker, factories, and environment variables. See [Dynamic Features](https://github.com/itsthedevman/spec_forge/wiki/Dynamic-Features).
+
+- **JSON validation modes**: Three modes for response validation—`shape:` for type checking with nullable/optional flags, `content:` for value matching, and `schema:` for explicit structure control. See [Validating Responses](https://github.com/itsthedevman/spec_forge/wiki/Validating-Responses).
+
+- **Configuration inheritance**: The `shared:` wrapper applies request configuration and hooks to nested steps, making auth flows and grouped operations cleaner.
+
+- **Lifecycle hooks**: Register callbacks for `before`/`after` events at forge, blueprint, and step levels. See [Callbacks](https://github.com/itsthedevman/spec_forge/wiki/Callbacks).
+
+- **Tag-based filtering**: Organize steps with tags and run subsets via `--tags` and `--skip-tags` CLI options. See [Running Tests](https://github.com/itsthedevman/spec_forge/wiki/Running-Tests).
+
+- **Improved output display**: Verbosity levels (`--verbose`, `--debug`, `--trace`) with colorized terminal output, detailed failure context, and YAML line number tracking in error messages.
+
+- **File includes**: Extract common workflows into separate files and inject them with `include:`.
+
+### Changed
+
+- Request options now nested under `request:` key
+- Expectations simplified from `expectations: [{ expect: ... }]` to `expect: [...]`
+- Error messages now include YAML line numbers and source file context
+- Factory references now support traits and attribute overrides via expanded syntax
+- Global variables defined in `forge_helper.rb` via `config.global_variables` instead of YAML
+
+### Removed
+
+- Global context system (`Context::Global`, `Context::Store`, `Context::Variables`)
+- Spec and Expectation classes (replaced with Step-based architecture)
+- Global headers/query configuration (use `shared:` inheritance instead)
+
+**[Full documentation](https://github.com/itsthedevman/spec_forge/wiki)** ｜ **[Migration Guide](https://github.com/itsthedevman/spec_forge/wiki/Migration-Guide)**
+
+---
+
 ## [0.7.1] - 12025-10-08
 
 ### Added
@@ -394,7 +467,8 @@ 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.7.1...HEAD
+[unreleased]: https://github.com/itsthedevman/spec_forge/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/itsthedevman/spec_forge/compare/v0.7.1...v1.0.0
 [0.7.1]: https://github.com/itsthedevman/spec_forge/compare/v0.7.0...v0.7.1
 [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

data/README.md

@@ -4,254 +4,176 @@
 ![Ruby Version](https://img.shields.io/badge/ruby-3.2+-ruby)
 [![Tests](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml/badge.svg)](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml)
 
-> 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.7.1](https://github.com/itsthedevman/spec_forge/releases/tag/v0.7.1) on GitHub releases.
-
-Write API tests in YAML that read like documentation and generate OpenAPI specifications:
+Write API tests as sequential workflows in YAML. Generate OpenAPI documentation automatically.
 
 ```yaml
-show_user:
-  path: /users/{id}
-  variables:
-    expected_status: 200
-    user_id: 1
-  query:
-    id: variables.user_id
-  expectations:
-  - expect:
-      status: variables.expected_status
-      json:
-        name: kind_of.string
-        email:
-          matcher.and:
-          - kind_of.string
-          - /@/
-      headers:
-        Content-Type: "application/json"
-        X-Request-ID: /^[0-9a-f-]{36}$/
+# spec_forge/blueprints/users.yml
+- name: "Create and verify user"
+  request:
+    url: /users
+    http_verb: POST
+    json:
+      name: "Jane Smith"
+      email: "jane@example.com"
+  expect:
+  - status: 201
+    json:
+      shape:
+        id: integer
+        name: string
+        email: string
+  store:
+    user_id: "{{ response.body.id }}"
+
+- name: "Fetch created user"
+  request:
+    url: "/users/{{ user_id }}"
+  expect:
+  - status: 200
+    json:
+      content:
+        name: "Jane Smith"
 ```
 
-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.
+Two steps. One workflow. No Ruby code required.
 
 ## Why SpecForge?
 
-**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
+**For Testing**
+- Write tests the way you think about APIs - as sequences of actions
+- Zero boilerplate: no HTTP client setup, no configuration objects
+- Full access to RSpec matchers, Faker, and FactoryBot without writing Ruby
 
-## Key Features
+**For Documentation**
+- Auto-generate OpenAPI specs from your workflows
+- Tests ensure documentation always matches your actual API
+- View in Swagger UI or Redoc with one command
 
-- **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!
+**For Teams**
+- YAML workflows are easier to review than Ruby test code
+- QA, developers, and product can all read and contribute
+- Version-controlled specifications that live with your code
 
 ## 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
-
-Consider alternatives when you need:
-
-1. **Complex Ruby Logic**: If your tests require custom Ruby code for data transformations or validations.
-2. **Complex Test Setup**: When you need intricate database states or specific service mocks.
-3. **Custom Response Validation**: For validation logic beyond what matchers provide.
-4. **Complex Non-JSON Testing**: While SpecForge handles basic XML/HTML responses (coming soon), complex validation might need specialized tools.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem "spec_forge"
-```
-
-And then execute:
-
-```bash
-bundle install
-```
-
-Or install it yourself as:
-
 ```bash
+# Install
 gem install spec_forge
-```
-
-## Getting Started
 
-Initialize the required directory structure:
-
-```bash
+# Initialize project structure
 spec_forge init
-```
-
-Create your first test:
-
-```bash
-spec_forge new spec users
-```
-
-Generate documentation (default command):
 
-```bash
-spec_forge
-```
+# Create your first workflow
+spec_forge new blueprint users
 
-Or start the live documentation server:
+# Run it
+spec_forge run
 
-```bash
+# Generate and view documentation
 spec_forge serve
 ```
 
-Run tests only (no documentation):
-
-```bash
-spec_forge run
-```
-
-## Documentation Workflow
+Visit `http://localhost:8080` to see your API documentation!
 
-SpecForge provides multiple ways to work with your API documentation:
+## Key Features
 
-```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
-```
+- **Step-based workflows**: Tests execute sequentially with explicit variable flow
+- **Variable storage**: Capture response values with `store:`, reference them with `{{ variable }}`
+- **Validation modes**: Simple `shape:` matching for structure, `schema:` for precise control
+- **Tag filtering**: Run subsets with `--tags smoke` or `--skip-tags slow`
+- **Lifecycle hooks**: Execute Ruby code at forge, blueprint, or step boundaries
+- **Dynamic data**: Built-in Faker and FactoryBot integration
+- **Nesting**: Group steps and share configuration with the `shared:` wrapper
 
-## Example: Complete User API
+## Example: Authentication Flow
 
 ```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
+- name: "Login"
+  request:
+    url: /auth/login
+    http_verb: POST
+    json:
+      email: "{{ faker.internet.email }}"
+      password: "testpass123"
+  expect:
+  - status: 200
+    json:
+      shape:
+        token: string
+  store:
+    auth_token: "{{ response.body.token }}"
+
+- name: "Authenticated requests"
+  shared:
+    request:
       headers:
-        Location: /\/users\/\d+/
+        Authorization: "Bearer {{ auth_token }}"
+  steps:
+  - name: "Get profile"
+    request:
+      url: /me
+    expect:
+    - status: 200
+
+  - name: "Update profile"
+    request:
+      url: /me
+      http_verb: PUT
       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
+        name: "Updated Name"
+    expect:
+    - status: 200
 ```
 
-This automatically generates a complete OpenAPI specification with all endpoints, request/response schemas, and examples!
+## When Not to Use SpecForge
+
+Consider alternatives when you need:
+
+1. **Complex Ruby logic** in tests - custom transformations, calculations, or validation beyond matchers
+2. **Intricate test setup** - complex database states, multiple service mocks, elaborate fixtures
+3. **Non-REST APIs** - GraphQL, gRPC, or WebSocket testing may need specialized tools
+4. **Heavy computational testing** - load testing, performance benchmarks, parallel execution
+
+You can use SpecForge alongside traditional RSpec tests. Use SpecForge for standard REST workflows and RSpec for complex scenarios.
 
 ## Documentation
 
-For comprehensive documentation, visit the [SpecForge Wiki](https://github.com/itsthedevman/spec_forge/wiki) which includes:
+For comprehensive guides and reference:
+
+- **[Getting Started](https://github.com/itsthedevman/spec_forge/wiki/Getting-Started)** - Installation and your first workflow
+- **[Writing Tests](https://github.com/itsthedevman/spec_forge/wiki/Writing-Tests)** - Complete syntax reference
+- **[Configuration](https://github.com/itsthedevman/spec_forge/wiki/Configuration)** - Setup and framework integration
+- **[Running Tests](https://github.com/itsthedevman/spec_forge/wiki/Running-Tests)** - CLI commands and filtering
+- **[Dynamic Features](https://github.com/itsthedevman/spec_forge/wiki/Dynamic-Features)** - Variables, Faker, FactoryBot
+- **[Documentation Generation](https://github.com/itsthedevman/spec_forge/wiki/Documentation-Generation)** - OpenAPI customization
+
+**Upgrading from 0.7?** See the **[Migration Guide](https://github.com/itsthedevman/spec_forge/wiki/Migration-Guide)**.
 
-- [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)
+**API Reference:** [itsthedevman.com/docs/spec_forge](https://itsthedevman.com/docs/spec_forge)
 
-Also see the [API Documentation](https://itsthedevman.com/docs/spec_forge).
+## CLI Reference
 
-## Future Development
+| Command | Description |
+|---------|-------------|
+| `spec_forge init` | Initialize project structure |
+| `spec_forge new blueprint <name>` | Create a workflow file |
+| `spec_forge new factory <name>` | Create a factory file |
+| `spec_forge run` | Execute workflows |
+| `spec_forge docs` | Generate OpenAPI specs |
+| `spec_forge serve` | Generate and serve documentation |
 
-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!
+Run `spec_forge help <command>` for detailed options.
 
 ## Contributing
 
-Contributions are welcome! See the [Contributing Guide](https://github.com/itsthedevman/spec_forge/wiki/Contributing) for details on how to get started.
+Contributions welcome! See the [Contributing Guide](https://github.com/itsthedevman/spec_forge/wiki/Contributing).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+Available as open source under the [MIT License](LICENSE.txt).
 
 ## Looking for a Software Engineer?
 
 I'm currently looking for opportunities where I can tackle meaningful problems and help build reliable software while mentoring the next generation of developers. If you're looking for a senior engineer with full-stack Rails expertise and a passion for clean, maintainable code, let's talk!
 
-[bryan@itsthedevman.com](mailto:bryan@itsthedevman.com)
+[bryan@itsthedevman.com](mailto:bryan@itsthedevman.com)

data/bin/spec_forge

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "spec_forge"
+require_relative "../lib/spec_forge"
 SpecForge::CLI.new.run

data/flake.lock

@@ -1,5 +1,21 @@
 {
   "nodes": {
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "narHash": "sha256-CIVLLkVgvHYbgI2UpXvIIBJ12HWgX+fjA8Xf8PUmqCY=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
@@ -18,13 +34,31 @@
         "type": "github"
       }
     },
+    "flake-utils_2": {
+      "inputs": {
+        "systems": "systems_2"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1750365781,
-        "narHash": "sha256-XE/lFNhz5lsriMm/yjXkvSZz5DfvKJLUjsS6pP8EC50=",
+        "lastModified": 1767379071,
+        "narHash": "sha256-EgE0pxsrW9jp9YFMkHL9JMXxcqi/OoumPJYwf+Okucw=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "08f22084e6085d19bcfb4be30d1ca76ecb96fe54",
+        "rev": "fb7944c166a3b630f177938e478f0378e64ce108",
         "type": "github"
       },
       "original": {
@@ -34,10 +68,33 @@
         "type": "github"
       }
     },
+    "nixpkgs-ruby": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1766728475,
+        "narHash": "sha256-9y9WBiQONK9TgD4lu8SW6TpcfEaJTxEs1HjhC4s4vnY=",
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "rev": "f167828eab19c3a7e3faa066a140d92e307f7b16",
+        "type": "github"
+      },
+      "original": {
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "flake-utils": "flake-utils",
-        "nixpkgs": "nixpkgs"
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-ruby": "nixpkgs-ruby"
       }
     },
     "systems": {
@@ -54,6 +111,21 @@
         "repo": "default",
         "type": "github"
       }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
     }
   },
   "root": "root",

data/flake.nix

@@ -4,6 +4,8 @@
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     flake-utils.url = "github:numtide/flake-utils";
+    nixpkgs-ruby.url = "github:bobvanderlinden/nixpkgs-ruby";
+    nixpkgs-ruby.inputs.nixpkgs.follows = "nixpkgs";
   };
 
   outputs =
@@ -11,19 +13,18 @@
       self,
       nixpkgs,
       flake-utils,
+      nixpkgs-ruby,
     }:
     flake-utils.lib.eachDefaultSystem (
       system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
+        ruby = nixpkgs-ruby.packages.${system}."ruby-3.2.9";
       in
       {
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
-            (ruby_3_2.override {
-              jemallocSupport = false;
-              docSupport = false;
-            })
+            ruby
 
             # Dependencies for native gems
             pkg-config