spec_forge 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f51faa712bafdcb48e3940273ec494eb3f39e43c0d122ff0a6f97e425026438
-  data.tar.gz: fe5cf7dff0a44cf5cfc466189fb38c3ed66da21637e18ebcdb44e31f9f6a8b73
+  metadata.gz: 6b2d5790d4797a63b8fbad4dd296b9c9beb657b30a98bda5fab8ca7c635abd5a
+  data.tar.gz: b22a8f664dd676846e703f5312383c9c9b1b9cabab52b2cc3c8a8d28830490c0
 SHA512:
-  metadata.gz: be068681e3c2ce8b2f62fa21ae03281d40b34c19e190acce4f90796dd526197b6ae54cc6edaa04d6715e347a67e2c193e2b99b0e16e45b47b3183915001790f3
-  data.tar.gz: 644f2c1a49d3ed45a201cb53d731176a418c134679f324ef96f331427481643b2744bd6c27c0f326df32c1db751c412137ad209a3f0b0ce3add9cc68eb6a660e
+  metadata.gz: 858e7dfd4546bc34e7dd8f899d99b5cf03d26cfbe9042f238de44566e2981a82bcd06803a0319f6d937d7c509dc3c02e8a962415c8e6fbb8e3c515c693c5e176
+  data.tar.gz: 3b246fda2d4bbbc5ce12fa0f683e27e1cb0e2950fe3b7c03b978f6d88662d1b65b0037b00931fe598415ee3d3c8477f7f76fd3f523547e061f86ac000e617d52

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

@@ -19,9 +19,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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
 
-### Removed
+- 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
 

data/README.md

@@ -4,30 +4,50 @@
 ![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)
 
+> 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:
 
 ```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
+          - /@/
 ```
 
 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.
 
 ## Why SpecForge?
 
-SpecForge shines when you need:
+1. **Living Documentation**: Your tests should serve as clear, readable documentation of your API's behavior.
+2. **Reduce Boilerplate**: Write tests without repetitive setup code and HTTP configuration.
+3. **Quick Setup**: Start testing APIs in minutes instead of spending hours on test infrastructure.
+4. **Gradual Adoption**: Use alongside your existing test suite, introducing it incrementally where it makes sense.
+5. **Developer & QA Collaboration**: Create a testing format that everyone can understand and maintain, regardless of Ruby expertise.
+
+## Key Features
 
-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.
+- **YAML-Based Tests**: Write clear, declarative tests that read like documentation
+- **RSpec Integration**: Leverage all the power of RSpec matchers and expectations
+- **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!
 
 ## When Not to Use SpecForge
 
@@ -85,25 +105,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": 1742422364,
+        "narHash": "sha256-mNqIplmEohk5jRkqYqG19GA8MbQ/D4gQSK0Mu4LvfRQ=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9e4d5190a9482a1fb9d18adf0bdb83c6e506eaab",
+        "rev": "a84ebe20c6bc2ecbcfb000a50776219f48d134cc",
         "type": "github"
       },
       "original": {

data/flake.nix

@@ -6,8 +6,14 @@
     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

data/lib/spec_forge/attribute/chainable.rb

@@ -2,84 +2,272 @@
 
 module SpecForge
   class Attribute
+    #
+    # Adds support for an attribute to accept n-number of chained calls. It supports chaining
+    # methods, hash keys, and array indexes. It also works well alongside Parameterized attributes
+    #
+    # This module requires being included into a class first before it can be used
+    #
+    # @example Basic usage in YAML
+    #   my_variable: variable.users.first
+    #
+    # @example Advanced usage in YAML
+    #   my_variable: variable.users.0.posts.second.author.name
+    #
+    # @example Basic usage in code
+    #   faker = SpecForge::Attribute.from("faker.name.name.upcase")
+    #   faker.resolved #=> BENDING UNIT 22
+    #
     module Chainable
+      #
+      # Regular expression that matches pure numeric strings
+      # Used for detecting potential array index operations
+      #
+      # @return [Regexp] A case-insensitive regex matching strings containing only digits
+      #
       NUMBER_REGEX = /^\d+$/i
 
-      attr_reader :header, :invocation_chain, :base_object
+      #
+      # The first part of the chained attribute
+      #
+      # @return [Symbol] The first component of the chained attribute
+      #
+      attr_reader :keyword
+
+      #
+      # The second part of the chained attribute
+      #
+      # @return [Symbol] The second component of the chained attribute
+      #
+      attr_reader :header
+
+      #
+      # The remaining parts of the attribute chain after the header
+      #
+      # @return [Array<Symbol>] The remaining method/key invocations in the chain
+      #
+      attr_reader :invocation_chain
 
       #
-      # Represents any attribute that is a series of chained invocations:
+      # The initial object from which the chain will start traversing
+      #
+      # @return [Object] The base object that starts the method/attribute chain
       #
-      #   <keyword>.<header>.<segment(hash_key | method | index)>...
+      attr_reader :base_object
+
       #
-      # This module is not used as is, but is included in another class.
-      # Note: There can be any n number of segments.
+      # Initializes a new chainable attribute by parsing the input into components
       #
       def initialize(...)
         super
 
-        # Drop the keyword
-        sections = input.split(".")[1..]
+        sections = input.split(".")
 
-        @header = sections.first&.to_sym
-        @invocation_chain = sections[1..] || []
+        @keyword = sections.first.to_sym
+        @header = sections.second&.to_sym
+        @invocation_chain = sections[2..] || []
       end
 
+      #
+      # Returns the value of this attribute by resolving the chain
+      # Will return a new value on each call for dynamic attributes like Faker
+      #
+      # @return [Object] The result of invoking the chain on the base object
+      #
       def value
         invoke_chain
       end
 
-      def resolve
+      #
+      # Resolves the chain and stores the result
+      # The result is memoized, so subsequent calls return the same value
+      # even for dynamic attributes like Faker and Factory
+      #
+      # @return [Object] The fully resolved and memoized value
+      #
+      def resolved
         @resolved ||= resolve_chain
       end
 
       private
 
+      #
+      # Invokes the chain by calling #value on each object
+      #
+      # @return [Object] The result of invoking the chain
+      #
+      # @private
+      #
       def invoke_chain
         traverse_chain(resolve: false)
       end
 
+      #
+      # Resolves the chain by calling #resolve on each object
+      #
+      # @return [Object] The fully resolved result
+      #
+      # @private
+      #
       def resolve_chain
-        __resolve(traverse_chain(resolve: true))
+        traverse_chain(resolve: true)
       end
 
+      #
+      # Traverses the chain of invocations step by step
+      #
+      # @param resolve [Boolean] Whether to use resolve during traversal
+      #
+      # @return [Object] The result of the traversal
+      #
+      # @private
+      #
       def traverse_chain(resolve:)
-        result = invocation_chain.reduce(base_object) do |current_value, step|
-          next_value = retrieve_value(current_value, resolve:)
+        resolution_path = {}
+
+        current_path = "#{keyword}.#{header}"
+        current_object = base_object
+
+        invocation_chain.each do |step|
+          next_value = retrieve_value(current_object, resolve:)
+
+          # Store this step's resolution for error reporting
+          resolution_path[current_path] = describe_value(next_value)
+          current_path += ".#{step}"
+
+          # Try to invoke the next step
+          current_object = invoke(step, next_value)
+        rescue Error::InvalidInvocationError => e
+          resolution_path[current_path] = "Error: #{e.message}"
 
-          invoke(step, next_value)
+          raise e.with_resolution_path(resolution_path)
         end
 
-        retrieve_value(result, resolve:)
+        # Return final result
+        retrieve_value(current_object, resolve:)
       end
 
+      #
+      # Retrieves the value from an object, resolving it if needed
+      #
+      # @param object [Object] The object to retrieve a value from
+      # @param resolve [Boolean] Whether to resolve the object's value
+      #
+      # @return [Object] The retrieved value
+      #
+      # @private
+      #
       def retrieve_value(object, resolve:)
         return object unless object.is_a?(Attribute)
 
-        resolve ? object.resolve : object.value
+        resolve ? object.resolved : object.value
+      end
+
+      #
+      # Creates a description of a value for error messages
+      #
+      # @param value [Object] The value to describe
+      #
+      # @return [String] A description
+      #
+      # @private
+      #
+      def describe_value(value)
+        case value
+        when Context::Store::Entry
+          "Store with attributes: #{value.available_methods.join_map(", ", &:in_quotes)}"
+        when OpenStruct
+          "Object with attributes: #{value.table.keys.join_map(", ", &:in_quotes)}"
+        when Struct, Data
+          "Object with attributes: #{value.members.join_map(", ", &:in_quotes)}"
+        when ArrayLike
+          # Preview the first 5 value's classes
+          preview = value.take(5).map(&:class)
+          preview << "..." if value.size > 5
+
+          "Array with #{value.size} #{"element".pluralize(value.size)}: #{preview}"
+        when HashLike
+          # Preview the first 5 keys
+          keys = value.keys.take(5)
+
+          preview = keys.join_map(", ") { |key| "\"#{key}\"" }
+          preview += ", ..." if value.keys.size > 5
+
+          "Hash with #{"key".pluralize(keys.size)}: #{preview}"
+        when String
+          "\"#{value.truncate(50)}\""
+        when NilClass
+          "nil"
+        when Proc
+          "Proc defined at #{value.source_location.join(":")}"
+        else
+          "#{value.class}: #{value.inspect[0..50]}"
+        end
       end
 
+      #
+      # Invokes an operation on an object based on the step type (hash key, array index, or method)
+      #
+      # @param step [String] The step to invoke
+      # @param object [Object] The object to invoke the step on
+      #
+      # @return [Object] The result of the invocation
+      #
+      # @raise [Error::InvalidInvocationError] If the step cannot be invoked on the object
+      #
+      # @private
+      #
       def invoke(step, object)
         if hash_key?(object, step)
-          object[step.to_sym]
+          object[step.to_s] || object[step.to_sym]
         elsif index?(object, step)
           object[step.to_i]
         elsif method?(object, step)
           object.public_send(step)
         else
-          raise InvalidInvocationError.new(step, object)
+          raise Error::InvalidInvocationError.new(step, object)
         end
       end
 
+      #
+      # Checks if the object can be accessed with the given key
+      #
+      # @param object [Object] The object to check
+      # @param key [String] The key to check
+      #
+      # @return [Boolean] Whether the object supports hash-like access with the key
+      #
+      # @private
+      #
       def hash_key?(object, key)
-        # This is to support the silly delegator
-        method?(object, :key?) && object.key?(key.to_sym)
+        # This is to support the silly delegator and both symbol/string
+        method?(object, :key?) && (object.key?(key.to_s) || object.key?(key.to_sym))
       end
 
+      #
+      # Checks if the object responds to the given method
+      #
+      # @param object [Object] The object to check
+      # @param method_name [String, Symbol] The method name to check
+      #
+      # @return [Boolean] Whether the object responds to the method
+      #
+      # @private
+      #
       def method?(object, method_name)
         object.respond_to?(method_name)
       end
 
+      #
+      # Checks if the object supports array-like access with the given index
+      #
+      # @param object [Object] The object to check
+      # @param step [String] The potential index
+      #
+      # @return [Boolean] Whether the object supports array-like access with the step
+      #
+      # @private
+      #
       def index?(object, step)
         # This is to support the silly delegator
         method?(object, :index) && step.match?(NUMBER_REGEX)