spec_forge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 588d2718c1fbacbfd1505a216f4b324c1ba83f12363a740f09cbd0f494595caa
+  data.tar.gz: 54dc440972584290ec208b60d0c22a0ebedb8c186fd90479b688f451281a7db0
+SHA512:
+  metadata.gz: d6e2030a3d788df3ca19c3193f37d78cc0a7b0b6f641ac5e07ec15c5386807b231eb5bb052265b12389e0cc5c95ca950a7703889ae1bfe3441bc13793a45495b
+  data.tar.gz: '0581cfbf2db39d3a30b2698e22e9f74c65229004269c49efb656e4cc169473273ddaf366250447ea9d9633d4007eb379bbce65bc4f3d5920cd63fa62bfb20c9a'

data/.envrc

@@ -0,0 +1 @@
+use flake

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.3

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-01-22
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Bryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,426 @@
+# SpecForge
+
+**Please note: This gem is under active development and isn't quite ready for use**
+
+I have 98% of the first release done, but I still have a lot of testing and polishing to ensure it works as expected.
+
+---
+
+Write API tests in YAML that read like documentation:
+
+```yaml
+user_profile:
+  path: /users/1
+  expect:
+    status: 200
+    json:
+      name: kind_of.string
+      email: /@/
+```
+
+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.
+
+But that's just scratching the surface.
+
+## Table of Contents
+
+- [Features](#features)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Writing Your First Test](#writing-your-first-test)
+- [Configuration](#configuration)
+  - [Base URL](#base-url)
+  - [Authorization](#authorization)
+- [The Spec Structure](#the-spec-structure)
+  - [Basic Structure](#basic-structure)
+  - [Testing Response Data](#testing-response-data)
+  - [Multiple Expectations](#multiple-expectations)
+  - [Request Data](#request-data)
+- [Dynamic Features](#dynamic-features)
+  - [Variables](#variables)
+  - [Transformations](#transformations)
+  - [Factory Integration](#factory-integration)
+- [RSpec Matchers](#rspec-matchers)
+  - ["be" namespace](#be-namespace)
+  - ["kind_of" namespace](#kind_of-namespace)
+  - ["matchers" namespace](#matchers-namespace)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+- [Looking for a Software Engineer?](#looking-for-a-software-engineer)
+
+## Features
+
+- **Write Tests in YAML**: Create clear, maintainable API tests using a declarative YAML syntax
+- **RSpec Integration**: Harness RSpec's powerful matcher system and reporting through an intuitive interface
+- **Dynamic Test Data**: Generate realistic test data using Faker, transformations, and a flexible variable system
+- **Factory Integration**: Seamless integration with FactoryBot for test data generation
+
+## Compatibility
+
+Currently tested on:
+- MRI Ruby 3.0+
+- NixOS (see `flake.nix` for details)
+
+## 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
+gem install spec_forge
+```
+
+## Getting Started
+
+Initialize the required directory structure:
+
+```bash
+spec_forge init
+```
+
+Or with bundle:
+```bash
+bundle exec spec_forge init
+```
+
+This creates the `spec_forge` directory with the following structure:
+```
+spec_forge/
+  config.yml      # Global configuration
+  factories/      # Your factory definitions
+  specs/          # Your test specifications
+```
+
+## Writing Your First Test
+
+Let's write a simple test to verify a user endpoint. Create a new spec file:
+
+```bash
+spec_forge new spec users
+```
+
+This creates `spec_forge/specs/users.yml`. Here's a basic example:
+
+```yaml
+get_user:
+  path: /users/1
+  method: GET
+  expectations:
+  - name: "Retrieves a user successfully"
+    expect:
+      status: 200
+      json:
+        id: 1
+        name: kind_of.string
+        email: /@/
+```
+
+Run your tests with:
+
+```bash
+spec_forge run
+```
+
+## Configuration
+
+The configuration file (`spec_forge/config.yml`) supports ERB and allows you to set global options for your test suite.
+
+### Base URL
+
+The base URL can be specified at three levels (in order of precedence):
+1. Expectation level
+2. Spec level
+3. Config level (`config.yml`)
+
+```yaml
+# config.yml
+base_url: https://api.example.com
+
+# specs/users.yml
+get_user:
+  base_url: https://staging.example.com  # Overrides config.yml
+  path: /users/1
+  expectations:
+  - name: "Production check"
+    base_url: https://prod.example.com  # Overrides spec level
+    expect:
+      status: 200
+```
+
+### Authorization
+
+SpecForge currently supports header-based authorization. Configure it in your `config.yml`:
+
+```yaml
+authorization:
+  default:
+    header: Authorization
+    value: Bearer <%= ENV['API_TOKEN'] %>  # ERB is supported!
+```
+
+## The Spec Structure
+
+### Basic Structure
+
+Every spec needs a path, HTTP method, and at least one expectation to be useful:
+
+```yaml
+show_user:
+  path: /users/1
+  method: GET # Optional for GET requests, can be lowercase too if that's your style
+  expectations:
+  - name: "Retrieves a User"  # Recommended. May be required in future versions for OpenAPI generation
+    expect:
+      status: 200
+```
+
+### Testing Response Data
+
+Let's verify the response JSON:
+
+```yaml
+show_user:
+  path: /users/1
+  method: GET
+  expectations:
+  - name: "Retrieves a User"
+    expect:
+      status: 200
+      json:
+        id: 1
+        name: kind_of.string
+        role: admin
+```
+
+### Multiple Expectations
+
+Each expectation can override any spec-level setting. This is useful for testing different scenarios:
+
+```yaml
+show_user:
+  path: /users/1
+  method: GET
+  expectations:
+  - name: "Retrieves a User"
+    expect:
+      status: 200
+      json:
+        id: 1
+        role: admin
+  - name: "Invalid User ID"
+    path: /users/999  # Overrides spec-level path
+    expect:
+      status: 404
+```
+
+### Request Data
+
+For POST/PUT/PATCH requests, you can include query parameters and body data:
+
+```yaml
+create_user:
+  path: /users
+  method: POST
+  query:  # or 'params' if you prefer
+    team_id: 123
+  body:   # or 'data' if you prefer
+    name: John Doe
+    email: john@example.com
+    role: admin
+  expectations:
+  - expect:
+      status: 201
+      json:
+        id: kind_of.integer
+        name: John Doe
+```
+
+## Dynamic Features
+
+SpecForge provides powerful features for generating and manipulating test data dynamically.
+
+### Variables
+
+Variables let you define and reuse values across your tests. They support complex chaining and can reference generated data:
+
+```yaml
+list_posts:
+  path: /posts
+  variables:
+    author: factories.user
+    category_name: faker.lorem.word
+  query:
+    author_id: variables.author.id
+    category: variables.category_name
+  expectations:
+  - name: "Lists user's posts"
+    expect:
+      status: 200
+      json:
+        posts:
+          matcher.include:
+          - author:
+              id: variables.author.id
+              name: variables.author.name
+            category: variables.category_name
+```
+
+Variables support deep traversal:
+```yaml
+variables:
+  user: factories.user
+  first_post: variables.user.posts.last
+  author: variables.first_post.comments.2.author.name
+```
+
+### Transformations
+
+Transform data using built-in helpers:
+
+```yaml
+create_user:
+  variables:
+    first_name: faker.name.first_name
+    last_name: faker.name.last_name
+    full_name:
+      transform.join:
+      - variables.first_name
+      - " "
+      - variables.last_name
+  body:
+    name: variables.full_name
+    email: faker.internet.email
+```
+
+### Factory Integration
+
+SpecForge provides a YAML interface to FactoryBot, making it easy to define and use factories in your tests:
+
+1. **Existing FactoryBot Factories**: Out of the box, SpecForge automatically discovers your existing Ruby-defined factories from:
+   - Standard paths (`spec/factories` and `test/factories`)
+   - Any custom paths you configure via your `config.yml`:
+     ```yaml
+     factories:
+       # Override default FactoryBot factory paths
+       paths:
+       - custom/factories/path
+
+       # Disable automatic factory discovery if needed (default: true)
+       auto_discover: false
+     ```
+
+2. **YAML Factory Definitions**: Define factories using YAML in `spec_forge/factories/`:
+   ```yaml
+   # spec_forge/factories/user.yml
+   user:
+     class: User  # Optional model class name
+     attributes:
+       name: faker.name.name
+       email: faker.internet.email
+       role: admin
+   ```
+   SpecForge registers these YAML definitions with FactoryBot, making them work exactly like Ruby-defined factories.
+
+Use factories in your tests:
+```yaml
+create_post:
+  variables:
+    author: factories.user  # Works with both YAML and Ruby-defined factories
+```
+
+## RSpec Matchers
+
+SpecForge provides access to RSpec's powerful matcher system through an intuitive dot notation syntax. The matcher system dynamically integrates with RSpec's matchers through three main namespaces:
+
+#### "be" namespace
+```yaml
+expect:
+  json:
+    # Simple predicates
+    active: be.true
+    deleted: be.false
+    description: be.nil
+    tags: be.empty
+    email: be.present
+
+    # Comparisons (aliases available)
+    price:
+      be.greater_than: 18            # be.greater also works
+    stock:
+      be.less_than_or_equal: 100     # be.less_or_equal also works
+    rating:
+      be.between:
+      - 1
+      - 5
+
+    # Dynamic predicate methods
+    published: be.published          # Maps to be_published
+    admin: be.admin                  # Maps to be_admin
+```
+
+#### "kind_of" namespace
+```yaml
+expect:
+  json:
+    id: kind_of.integer
+    name: kind_of.string
+    metadata: kind_of.hash
+    scores: kind_of.array
+```
+
+#### "matchers" namespace
+```yaml
+expect:
+  json:
+    # Direct RSpec matcher usage
+    tags:
+      matcher.include:
+      - featured
+      - published
+
+    slug: /^[a-z0-9-]+$/    # Shorthand for matching regexes
+
+    # Any RSpec matcher can be used
+    config:
+      matcher.have_key: api_version
+```
+
+Note: Matchers that require Ruby blocks (like `change`) are not supported.
+
+## Roadmap
+
+- [ ] Negated matchers
+- [ ] OpenAPI generation from your tests
+- [ ] Support for XML/HTML response handling
+- [ ] Support for running individual specs
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create new Pull Request
+
+Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Looking for a Software Engineer?
+
+I'm looking for work! Please send serious enquiries to bryan@itsthedevman.com

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "standard/rake"
+
+task default: %i[standard]

data/bin/spec_forge

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

data/flake.lock

@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "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": 1737469691,
+        "narHash": "sha256-nmKOgAU48S41dTPIXAq0AHZSehWUn6ZPrUKijHAMmIk=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "9e4d5190a9482a1fb9d18adf0bdb83c6e506eaab",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "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",
+  "version": 7
+}