zenspec 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7737ee41815ffc6e727f44826dda5052addaa5925860cd1421665ffed41e85e0
-  data.tar.gz: 37c0da188f214be5efe29ac58496a24b2831f2e076d4fb247a1bbbaaec57fa59
+  metadata.gz: 726804494431887d8cde8ded93f4e74a9a9613812adb1acc276765bbdc0ce5c5
+  data.tar.gz: 8f830f054711e25fcbe469ece0500168686af283a2ba2d1ebeb5895ef5d9b88c
 SHA512:
-  metadata.gz: cb5d249f606858f4f5835c7889cc6aeacc157ed30e79bac209758c42e5b8abb076e84afdb978ec1c0cbc537d4f1e6c6ba672d53fbcf2f87ae5faa8d3428cbe6b
-  data.tar.gz: 4796a8d28823742fa70c5417918d310f0ebfaed055a26cd7a8938919b35e2d5cc2de5d18b22622af4d46296d41ea861850b66bf28b76fb955243703f1f1f64e3
+  metadata.gz: 9c02f637bab3391379cc0d68e3a61db9759a7c4ffd6e4d956256332aa3723090a44509be9f22cb28e8dd103aa71f40502420740da0dd45c695e15cbc72e9276a
+  data.tar.gz: 50f5e33010455625a06c9fa9819969de3e25f9e39575eb4b3a4ce4bdc39304f8d4602b7280e92affecb526465e488007531507889f111679aa8a40002a3bb7a1

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.3.1] - 2025-11-16
+
+### Fixed
+- **Critical**: Fixed falsy value handling in `have_graphql_data` matcher - now correctly handles `false`, `0`, and empty string values
+- **Critical**: Fixed falsy data value bug in interactor `succeed` matcher - now correctly handles `false` and `0` as expected data
+- Improved snake_case to camelCase conversion to handle edge cases (leading/trailing underscores, consecutive underscores)
+
+### Changed
+- Extracted duplicated type conversion methods to shared `FieldNameHelper` module (reduces code duplication by ~120 lines)
+- Pre-compiled ANSI regex in `ProgressBarFormatter` for better performance
+- Made global `ProgressBarFormatter` constant conditional to prevent namespace conflicts
+- Added documentation comments to magic numbers explaining their values
+
+### Added
+- Support for error count validation in `have_graphql_errors` matcher: `expect(result).to have_graphql_errors(2)`
+- CI testing for Ruby 3.2, 3.3, and 3.4 (expanded from single version)
+
 ## [0.2.0] - 2025-11-16
 
 ### Changed

data/README.md

@@ -2,54 +2,269 @@
 
 A comprehensive RSpec matcher library for testing GraphQL APIs, Interactor service objects, and Rails applications.
 
-## Installation
+**Features:**
+- GraphQL schema type matchers with snake_case support
+- GraphQL response matchers for queries and mutations
+- Interactor/service object matchers
+- Shoulda matchers integration
+- Beautiful progress bar formatter
 
-Add this line to your application's Gemfile:
+---
+
+## 30-Second Quickstart
 
 ```ruby
+# 1. Add to Gemfile
 gem "zenspec"
-```
-
-And then execute:
 
-```bash
+# 2. Bundle install
 bundle install
+
+# 3. Start testing!
+RSpec.describe UserType do
+  # Test GraphQL types (supports snake_case!)
+  it { is_expected.to have_field(:id).of_type("ID!") }
+  it { is_expected.to have_field(:current_user).of_type("User") }
+end
+
+RSpec.describe "GraphQL Queries" do
+  subject(:result) { graphql_execute(query) }
+
+  let(:query) do
+    <<~GQL
+      query { user(id: "123") { id name } }
+    GQL
+  end
+
+  # Test responses
+  it { is_expected.to succeed_graphql }
+  it { is_expected.to have_graphql_data("user", "name").with_value("John") }
+end
+
+RSpec.describe CreateUser do
+  subject(:result) { described_class.call(name: "John") }
+
+  # Test interactors
+  it { is_expected.to succeed }
+  it { is_expected.to set_context(:user) }
+end
 ```
 
-## Quick Start
+---
+
+## Complete Matchers Reference
+
+### GraphQL Type Matchers
+
+Test your GraphQL schema types, fields, and structure.
 
-### 1. Add to your spec helper
+| Matcher | Usage | Description |
+|---------|-------|-------------|
+| `have_field(name)` | `have_field(:user)` | Check if type has a field (snake_case supported) |
+| `.of_type(type)` | `.of_type("User!")` | Verify field return type |
+| `.with_argument(name, type)` | `.with_argument(:id, "ID!")` | Check field has argument (snake_case supported) |
+| `have_argument(name)` | `have_argument(:limit)` | Check argument exists on field |
+| `.of_type(type)` | `.of_type("Int")` | Verify argument type |
+| `have_enum_values(*values)` | `have_enum_values("ACTIVE", "PENDING")` | Verify enum contains values |
+| `have_query(name)` | `have_query(:current_user)` | Check schema has query (snake_case supported) |
+| `have_mutation(name)` | `have_mutation(:create_user)` | Check schema has mutation (snake_case supported) |
+
+**Examples:**
 
 ```ruby
-# In your spec/rails_helper.rb or spec/spec_helper.rb
-require "zenspec"
+# Field testing (snake_case supported!)
+expect(UserType).to have_field(:id).of_type("ID!")
+expect(UserType).to have_field(:current_user).of_type("User")  # Works with snake_case!
+expect(UserType).to have_field(:posts).of_type("[Post!]!")
+
+# Fields with arguments (snake_case supported!)
+expect(UserType).to have_field(:posts)
+  .with_argument(:limit, "Int")
+  .with_argument(:include_archived, "Boolean")  # snake_case works!
 
-# Everything is automatically configured!
+# Enum testing
+expect(StatusEnum).to have_enum_values("ACTIVE", "INACTIVE", "PENDING")
+
+# Schema queries (snake_case supported!)
+expect(AppSchema).to have_query(:user).with_argument(:id, "ID!")
+expect(AppSchema).to have_query(:current_user).of_type("User")  # snake_case!
+
+# Schema mutations (snake_case supported!)
+expect(AppSchema).to have_mutation(:create_user).of_type("UserPayload!")
+expect(AppSchema).to have_mutation(:update_user_status)
+  .with_argument(:user_id, "ID!")           # snake_case arguments!
+  .with_argument(:new_status, "Status!")
 ```
 
-### 2. (Optional) Add progress bar formatter to `.rspec`
+### GraphQL Response Matchers
+
+Test GraphQL query and mutation responses.
+
+| Matcher | Usage | Description |
+|---------|-------|-------------|
+| `succeed_graphql` | `expect(result).to succeed_graphql` | Verify query/mutation succeeded (no errors) |
+| `have_graphql_data(path...)` | `have_graphql_data("user", "name")` | Check response data at path |
+| `.with_value(expected)` | `.with_value("John")` | Exact value match |
+| `.matching(hash)` | `.matching(id: "123", name: "John")` | Partial hash match |
+| `.that_includes(hash)` | `.that_includes(name: "John")` | Includes these key-value pairs |
+| `.that_is_present` | `.that_is_present` | Value exists and not null |
+| `.that_is_null` | `.that_is_null` | Value is explicitly null |
+| `.with_count(n)` | `.with_count(5)` | Array has exactly n items |
+| `have_graphql_error` | `have_graphql_error` | Has at least one error |
+| `.with_message(msg)` | `.with_message("Not found")` | Error message matches |
+| `.with_extensions(hash)` | `.with_extensions(code: "NOT_FOUND")` | Error extensions match |
+| `.at_path(array)` | `.at_path(["user", "email"])` | Error occurred at path |
+| `have_graphql_errors(n)` | `have_graphql_errors(2)` | Has exactly n errors |
+| `have_graphql_field(name)` | `have_graphql_field("user")` | Response has field |
+| `have_graphql_fields(hash)` | `have_graphql_fields("user" => true)` | Response has multiple fields |
+
+**Examples:**
 
+```ruby
+# Basic success check
+expect(result).to succeed_graphql
+
+# Data checks
+expect(result).to have_graphql_data("user")
+expect(result).to have_graphql_data("user", "name").with_value("John")
+expect(result).to have_graphql_data("user", "email").that_is_present
+
+# Hash matching
+expect(result).to have_graphql_data("user").matching(
+  id: "123",
+  name: "John Doe",
+  email: "john@example.com"
+)
+
+# Array checks
+expect(result).to have_graphql_data("users").with_count(5)
+expect(result).to have_graphql_data("users").that_is_present
+
+# Error handling
+expect(result).to have_graphql_error
+expect(result).to have_graphql_error.with_message("Not found")
+expect(result).to have_graphql_error.with_extensions(code: "NOT_FOUND")
+expect(result).to have_graphql_error.at_path(["user", "email"])
+expect(result).to have_graphql_errors(2)
 ```
---require zenspec/formatters/progress_bar_formatter
---format ProgressBarFormatter
---color
---require spec_helper
+
+### Interactor Matchers
+
+Test your Interactor service objects.
+
+| Matcher | Usage | Description |
+|---------|-------|-------------|
+| `succeed` | `expect(result).to succeed` | Interactor succeeded |
+| `.with_context(key, value)` | `.with_context(:user, user)` | Check context value |
+| `.with_data(value)` | `.with_data(user)` | Check context.data value |
+| `fail_interactor` | `expect(result).to fail_interactor` | Interactor failed |
+| `.with_error(code)` | `.with_error("not_found")` | Failed with specific error code |
+| `.with_errors(*codes)` | `.with_errors("invalid", "missing")` | Failed with multiple error codes |
+| `set_context(key)` | `set_context(:user)` | Context key was set |
+| `set_context(key, value)` | `set_context(:user, user)` | Context key set to value |
+| `have_error_code(code)` | `have_error_code("not_found")` | Has specific error code |
+| `have_error_codes(*codes)` | `have_error_codes("a", "b")` | Has multiple error codes |
+
+**Examples:**
+
+```ruby
+# Success checks
+expect(result).to succeed
+expect(result).to succeed.with_context(:user, kind_of(User))
+expect(result).to succeed.with_data(user)
+expect(result).to set_context(:user)
+
+# Failure checks
+expect(result).to fail_interactor
+expect(result).to fail_interactor.with_error("validation_failed")
+expect(result).to fail_interactor.with_errors("invalid_email", "missing_name")
+expect(result).to have_error_code("not_found")
+expect(result).to have_error_codes("invalid", "missing")
 ```
 
-That's it! You can now use all GraphQL and Interactor matchers in your tests.
+### GraphQL Helpers
+
+Helper methods for executing GraphQL queries and mutations in tests.
+
+| Helper | Usage | Description |
+|--------|-------|-------------|
+| `graphql_execute(query, **options)` | `graphql_execute(query, variables: {id: "123"})` | Execute GraphQL query |
+| `graphql_execute_as(user, query, **options)` | `graphql_execute_as(user, query)` | Execute query with user in context |
+| `graphql_mutate(mutation, **options)` | `graphql_mutate(mutation, input: {name: "John"})` | Execute GraphQL mutation |
+| `graphql_mutate_as(user, mutation, **options)` | `graphql_mutate_as(user, mutation, input: {})` | Execute mutation with user in context |
+
+**Examples:**
+
+```ruby
+# Execute query
+result = graphql_execute(query, variables: { id: "123" }, context: { current_user: user })
+
+# Execute as user (adds to context automatically)
+result = graphql_execute_as(user, query, variables: { id: "123" })
+
+# Execute mutation
+result = graphql_mutate(mutation, input: { name: "John" }, context: { current_user: user })
+
+# Execute mutation as user
+result = graphql_mutate_as(user, mutation, input: { name: "John" })
+```
 
 ---
 
-## GraphQL Testing
+## Detailed Usage Examples
+
+### Testing GraphQL Types
 
-### Response Matchers
+```ruby
+RSpec.describe UserType do
+  subject { described_class }
 
-Test GraphQL query and mutation responses with clean, expressive matchers.
+  # Basic fields (snake_case supported!)
+  it { is_expected.to have_field(:id).of_type("ID!") }
+  it { is_expected.to have_field(:name).of_type("String!") }
+  it { is_expected.to have_field(:email).of_type("String") }
+  it { is_expected.to have_field(:current_user).of_type("User") }  # snake_case!
+
+  # Array types
+  it { is_expected.to have_field(:posts).of_type("[Post!]!") }
+
+  # Fields with arguments (snake_case supported!)
+  it do
+    is_expected.to have_field(:posts)
+      .with_argument(:limit, "Int")
+      .with_argument(:offset, "Int")
+      .with_argument(:include_archived, "Boolean")  # snake_case works!
+  end
+end
+
+RSpec.describe StatusEnum do
+  subject { described_class }
+
+  it { is_expected.to have_enum_values("ACTIVE", "INACTIVE", "PENDING") }
+end
+
+RSpec.describe AppSchema do
+  subject { described_class }
+
+  # Queries (snake_case supported!)
+  it { is_expected.to have_query(:user).with_argument(:id, "ID!") }
+  it { is_expected.to have_query(:current_user).of_type("User") }
+
+  # Mutations (snake_case supported!)
+  it { is_expected.to have_mutation(:create_user).of_type("UserPayload!") }
+  it { is_expected.to have_mutation(:update_user_status)
+    .with_argument(:user_id, "ID!")
+    .with_argument(:new_status, "Status!") }
+end
+```
+
+### Testing GraphQL Queries
 
 ```ruby
 RSpec.describe "User Queries" do
   subject(:result) { graphql_execute_as(user, query, variables: { id: user.id }) }
 
+  let(:user) { create(:user, name: "John Doe", email: "john@example.com") }
   let(:query) do
     <<~GQL
       query GetUser($id: ID!) {
@@ -65,9 +280,11 @@ RSpec.describe "User Queries" do
   # Basic checks
   it { is_expected.to succeed_graphql }
   it { is_expected.to have_graphql_data("user") }
-  it { is_expected.to have_graphql_data("user", "name").with_value("John") }
+  it { is_expected.to have_graphql_data("user", "id").with_value(user.id) }
+  it { is_expected.to have_graphql_data("user", "name").with_value("John Doe") }
+  it { is_expected.to have_graphql_data("user", "email").that_is_present }
 
-  # Matching data
+  # Full object matching
   it "returns correct user data" do
     expect(result).to have_graphql_data("user").matching(
       id: user.id,
@@ -76,111 +293,113 @@ RSpec.describe "User Queries" do
     )
   end
 
-  # Array checks
-  it { is_expected.to have_graphql_data("users").with_count(5) }
-  it { is_expected.to have_graphql_data("users").that_is_present }
-
-  # Error handling
-  expect(result).to have_graphql_error.with_message("Not found")
-  expect(result).to have_graphql_error.with_extensions(code: "NOT_FOUND")
-  expect(result).to have_graphql_error.at_path(["user", "email"])
+  # Partial matching
+  it "includes user name" do
+    expect(result).to have_graphql_data("user").that_includes(name: "John Doe")
+  end
 end
-```
 
-**Available matchers:**
-- `succeed_graphql` - Verify successful query/mutation
-- `have_graphql_data(path...)` - Check response data
-- `have_graphql_error` / `have_graphql_errors` - Verify errors
-- `have_graphql_field(name)` / `have_graphql_fields(hash)` - Check field presence
+RSpec.describe "User List Query" do
+  subject(:result) { graphql_execute(query) }
 
-**Data matchers:**
-- `.with_value(expected)` - Exact value match
-- `.matching(hash)` - Partial hash match
-- `.that_includes(hash)` - Includes these values
-- `.that_is_present` / `.that_is_null` - Presence checks
-- `.with_count(n)` - Array size
+  let!(:users) { create_list(:user, 5) }
+  let(:query) do
+    <<~GQL
+      query { users { id name } }
+    GQL
+  end
 
-### Type Matchers
+  it { is_expected.to succeed_graphql }
+  it { is_expected.to have_graphql_data("users").with_count(5) }
+  it { is_expected.to have_graphql_data("users").that_is_present }
+end
+```
 
-Test your GraphQL schema types, fields, and arguments.
+### Testing GraphQL Mutations
 
 ```ruby
-RSpec.describe UserType do
-  subject { described_class }
-
-  # Field testing
-  it { is_expected.to have_field(:id).of_type("ID!") }
-  it { is_expected.to have_field(:name).of_type("String!") }
-  it { is_expected.to have_field(:email).of_type("String") }
-  it { is_expected.to have_field(:posts).of_type("[Post!]!") }
+RSpec.describe "Create User Mutation" do
+  subject(:result) do
+    graphql_mutate_as(admin, mutation, input: { name: "Jane", email: "jane@example.com" })
+  end
 
-  # Fields with arguments
-  it do
-    is_expected.to have_field(:posts)
-      .with_argument(:limit, "Int")
-      .with_argument(:offset, "Int")
+  let(:admin) { create(:user, :admin) }
+  let(:mutation) do
+    <<~GQL
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          user { id name email }
+          errors
+        }
+      }
+    GQL
   end
-end
 
-# Enum testing
-RSpec.describe StatusEnum do
-  subject { described_class }
+  context "with valid input" do
+    it { is_expected.to succeed_graphql }
+    it { is_expected.to have_graphql_data("createUser", "user", "name").with_value("Jane") }
+    it { is_expected.to have_graphql_data("createUser", "user", "email").with_value("jane@example.com") }
+    it { is_expected.to have_graphql_data("createUser", "errors").that_is_null }
 
-  it { is_expected.to have_enum_values("ACTIVE", "INACTIVE", "PENDING") }
-end
+    it "creates a new user" do
+      expect { result }.to change(User, :count).by(1)
+    end
+  end
 
-# Schema queries and mutations
-RSpec.describe AppSchema do
-  subject { described_class }
+  context "with invalid input" do
+    subject(:result) do
+      graphql_mutate_as(admin, mutation, input: { name: "", email: "invalid" })
+    end
 
-  it { is_expected.to have_query(:user).with_argument(:id, "ID!") }
-  it { is_expected.to have_mutation(:createUser).of_type("UserPayload!") }
+    it { is_expected.to have_graphql_data("createUser", "user").that_is_null }
+    it { is_expected.to have_graphql_data("createUser", "errors").that_is_present }
+  end
 end
 ```
 
-**Available matchers:**
-- `have_field(name)` - Check field exists
-- `of_type(type)` - Verify field type
-- `with_argument(name, type)` - Check field arguments
-- `have_argument(name)` - Check argument on field
-- `have_enum_values(*values)` - Verify enum values
-- `have_query(name)` / `have_mutation(name)` - Schema-level checks
-
-### GraphQL Helpers
-
-Execute queries and mutations easily in your tests.
+### Testing GraphQL Errors
 
 ```ruby
-# Execute query
-result = graphql_execute(query, variables: { id: "123" }, context: { current_user: user })
+RSpec.describe "User Query with errors" do
+  subject(:result) { graphql_execute(query, variables: { id: "999" }) }
 
-# Execute as user (automatically adds to context)
-result = graphql_execute_as(user, query, variables: { id: "123" })
+  let(:query) do
+    <<~GQL
+      query GetUser($id: ID!) {
+        user(id: $id) { id name }
+      }
+    GQL
+  end
 
-# Execute mutation
-result = graphql_mutate(mutation, input: { name: "John" }, context: { current_user: user })
+  it { is_expected.not_to succeed_graphql }
+  it { is_expected.to have_graphql_error }
+  it { is_expected.to have_graphql_error.with_message("User not found") }
+  it { is_expected.to have_graphql_error.with_extensions(code: "NOT_FOUND") }
+  it { is_expected.to have_graphql_error.at_path(["user"]) }
 
-# Execute mutation as user
-result = graphql_mutate_as(user, mutation, input: { name: "John" })
+  context "with multiple errors" do
+    it { is_expected.to have_graphql_errors(2) }
+  end
+end
 ```
 
----
-
-## Interactor Testing
-
-Test your Interactor service objects with clean, expressive matchers.
+### Testing Interactors
 
 ```ruby
 RSpec.describe CreateUser do
   subject(:result) { described_class.call(params) }
 
   context "with valid params" do
-    let(:params) { { name: "John", email: "john@example.com" } }
+    let(:params) { { name: "John Doe", email: "john@example.com" } }
 
-    # Basic checks
     it { is_expected.to succeed }
     it { is_expected.to set_context(:user) }
     it { is_expected.to succeed.with_context(:user, kind_of(User)) }
+
+    it "creates a user" do
+      expect(result.user).to be_persisted
+      expect(result.user.name).to eq("John Doe")
+    end
   end
 
   context "with invalid params" do
@@ -189,25 +408,39 @@ RSpec.describe CreateUser do
     it { is_expected.to fail_interactor }
     it { is_expected.to fail_interactor.with_error("validation_failed") }
     it { is_expected.to have_error_code("validation_failed") }
+
+    it "does not create a user" do
+      expect { result }.not_to change(User, :count)
+    end
+  end
+
+  context "with multiple errors" do
+    let(:params) { { name: "", email: "" } }
+
+    it { is_expected.to fail_interactor.with_errors("missing_name", "missing_email") }
+    it { is_expected.to have_error_codes("missing_name", "missing_email") }
   end
 end
-```
 
-**Available matchers:**
-- `succeed` - Verify interactor succeeded
-  - `.with_context(key, value)` - Check context value
-  - `.with_data(value)` - Check context.data value
-- `fail_interactor` - Verify interactor failed
-  - `.with_error(code)` - Check single error code
-  - `.with_errors(*codes)` - Check multiple error codes
-- `set_context(key, value)` - Check context was set
-- `have_error_code(code)` / `have_error_codes(*codes)` - Check error codes
+RSpec.describe UpdateUser do
+  subject(:result) { described_class.call(user: user, name: new_name) }
 
----
+  let(:user) { create(:user, name: "Old Name") }
+  let(:new_name) { "New Name" }
+
+  it { is_expected.to succeed }
+  it { is_expected.to succeed.with_context(:user, user) }
+  it { is_expected.to succeed.with_data(user) }
+
+  it "updates the user's name" do
+    expect { result }.to change { user.reload.name }.from("Old Name").to("New Name")
+  end
+end
+```
 
-## Shoulda Matchers
+### Testing with Shoulda Matchers
 
-Automatically includes and configures [Shoulda Matchers](https://github.com/thoughtbot/shoulda-matchers) for Rails projects.
+Shoulda matchers are automatically included for Rails projects.
 
 ```ruby
 RSpec.describe User do
@@ -216,26 +449,42 @@ RSpec.describe User do
   # Validations
   it { is_expected.to validate_presence_of(:email) }
   it { is_expected.to validate_uniqueness_of(:email).case_insensitive }
+  it { is_expected.to validate_length_of(:name).is_at_least(2).is_at_most(100) }
 
   # Associations
   it { is_expected.to have_many(:posts).dependent(:destroy) }
   it { is_expected.to belong_to(:organization) }
+  it { is_expected.to have_one(:profile) }
 end
 ```
 
 ---
 
-## Progress Bar Formatter
+## Installation
 
-Clean, colorful test output with status icons.
+Add this line to your application's Gemfile:
 
-### Setup
+```ruby
+gem "zenspec"
+```
 
-Add to your `.rspec` file:
+And then execute:
+
+```bash
+bundle install
+```
+
+That's it! All matchers and helpers are automatically available in your RSpec tests.
+
+### Optional: Progress Bar Formatter
+
+For a cleaner test output with a progress bar, add to your `.rspec` file:
 
 ```
 --require zenspec/formatters/progress_bar_formatter
 --format ProgressBarFormatter
+--color
+--require spec_helper
 ```
 
 Or use via command line:
@@ -244,25 +493,28 @@ Or use via command line:
 rspec --require zenspec/formatters/progress_bar_formatter --format ProgressBarFormatter
 ```
 
-### Output
+**Example output:**
 
 ```
-✔ user_spec.rb                                                [10% 1/10]
-✔ post_spec.rb                                                [20% 2/10]
-⠿ auth_spec.rb --> authenticates with OAuth                   [30% 3/10]
+✔ user_spec.rb                                                [10% 15/152]
+✔ post_spec.rb                                                [20% 30/152]
+⠿ auth_spec.rb --> authenticates with OAuth                   [30% 45/152]
 ```
 
 **Icons:**
 - ✔ Green - Passed
 - ✗ Red - Failed
-- ⠿ Yellow - Running (shows test description)
+- ⠿ Yellow - Running (shows current test description)
 - ⊘ Cyan - Pending
 
 ---
 
 ## Configuration
 
-Zenspec works out of the box with sensible defaults. For Rails applications, it automatically configures itself.
+Zenspec works out of the box with sensible defaults. For Rails applications, it automatically:
+- Includes all matchers in RSpec
+- Configures Shoulda Matchers
+- Sets up GraphQL helpers with your `AppSchema`
 
 ### Non-Rails Projects
 
@@ -270,21 +522,54 @@ Zenspec works out of the box with sensible defaults. For Rails applications, it
 # spec/spec_helper.rb
 require "zenspec"
 
-# That's it! All matchers and helpers are available
+# All matchers and helpers are now available!
+```
+
+### Custom GraphQL Schema
+
+If your schema is not named `AppSchema`, you can configure it:
+
+```ruby
+# spec/spec_helper.rb
+RSpec.configure do |config|
+  config.include Zenspec::Helpers::GraphQLHelpers
+
+  # Override the schema
+  config.before do
+    stub_const("AppSchema", YourCustomSchema)
+  end
+end
 ```
 
 ---
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+After checking out the repo, run `bin/setup` to install dependencies. Then run the tests:
+
+```bash
+bundle exec rspec
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+---
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/zyxzen/zenspec.
 
+Please ensure:
+1. All tests pass (`bundle exec rspec`)
+2. Code follows the existing style
+3. New features include tests and documentation
+
+---
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/zenspec/formatters/progress_bar_formatter.rb

@@ -56,15 +56,18 @@ module Zenspec
       # Spinner frames for animation
       SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"].freeze
 
-      # Spinner update interval in seconds
+      # Spinner update interval in seconds (80ms provides smooth 12.5 FPS animation)
       SPINNER_INTERVAL = 0.08
 
-      # Default terminal width if unable to detect
+      # Default terminal width if unable to detect (standard wide terminal)
       DEFAULT_TERMINAL_WIDTH = 120
 
-      # Minimum padding between left and right parts
+      # Minimum padding between left and right parts for readability
       MIN_PADDING = 2
 
+      # Pre-compiled regex for stripping ANSI color codes (performance optimization)
+      ANSI_REGEX = /\e\[[0-9;]*m/.freeze
+
       def initialize(output)
         super
         @current_count = 0
@@ -338,8 +341,9 @@ module Zenspec
       end
 
       # Strip ANSI color codes from text
+      # Uses pre-compiled regex for performance in hot path
       def strip_ansi(text)
-        text.gsub(/\e\[[0-9;]*m/, "")
+        text.gsub(ANSI_REGEX, "")
       end
 
       # Extract short filename from example
@@ -430,4 +434,10 @@ module Zenspec
 end
 
 # Register the formatter as ProgressBarFormatter for easier use
-ProgressBarFormatter = Zenspec::Formatters::ProgressBarFormatter
+# Users can use the short form by requiring this file directly:
+#   --require zenspec/formatters/progress_bar_formatter
+#   --format ProgressBarFormatter
+# Or use the full constant name: Zenspec::Formatters::ProgressBarFormatter
+unless Object.const_defined?(:ProgressBarFormatter)
+  ProgressBarFormatter = Zenspec::Formatters::ProgressBarFormatter
+end

data/lib/zenspec/matchers/graphql_matchers.rb

@@ -141,7 +141,7 @@ module Zenspec
           end
 
           # Check exact value
-          if @expected_value
+          unless @expected_value.nil?
             data == @expected_value
           else
             !data.nil?
@@ -210,13 +210,15 @@ module Zenspec
       #
       # @example
       #   expect(result).to have_graphql_errors
+      #   expect(result).to have_graphql_errors(2)  # Exactly 2 errors
       #   expect(result).to have_graphql_error.with_message("Not found")
       #   expect(result).to have_graphql_error.with_extensions(code: "NOT_FOUND")
       #   expect(result).to have_graphql_error.at_path(["user", "email"])
       #   expect { execute_query }.to have_graphql_errors
       #
-      RSpec::Matchers.define :have_graphql_errors do
+      RSpec::Matchers.define :have_graphql_errors do |expected_count = nil|
         match do |result_or_block|
+          @expected_count = expected_count
           if result_or_block.is_a?(Proc)
             begin
               result_or_block.call
@@ -232,6 +234,12 @@ module Zenspec
             errors = result_or_block["errors"]
             return false if errors.nil? || (errors.is_a?(Array) && errors.empty?)
 
+            # Check for exact error count if specified
+            if @expected_count
+              @actual_count = errors.is_a?(Array) ? errors.length : 0
+              return false unless @actual_count == @expected_count
+            end
+
             # Check for specific message
             if @expected_message
               return errors.any? { |error| error["message"]&.include?(@expected_message) }
@@ -269,6 +277,8 @@ module Zenspec
         failure_message do
           if @raised_error
             "expected no errors, but got: #{@error.message}"
+          elsif @expected_count
+            "expected exactly #{@expected_count} error(s), but got #{@actual_count}"
           elsif @expected_message
             errors = @result["errors"] || []
             messages = errors.map { |e| e["message"] }

data/lib/zenspec/matchers/graphql_type_matchers.rb

@@ -5,6 +5,118 @@ require "rspec/expectations"
 module Zenspec
   module Matchers
     module GraphQLTypeMatchers
+      # Helper module for field name conversion
+      module FieldNameHelper
+        # Convert snake_case to camelCase for GraphQL field lookup
+        # GraphQL-Ruby automatically converts snake_case field definitions to camelCase
+        #
+        # Handles edge cases:
+        # - Empty strings: "" -> ""
+        # - No underscores: "foo" -> "foo"
+        # - Leading underscores: "_foo_bar" -> "fooBar"
+        # - Trailing underscores: "foo_bar_" -> "fooBar"
+        # - Consecutive underscores: "foo__bar" -> "fooBar"
+        def camelize(name)
+          str = name.to_s
+          return str if str.empty? || !str.include?("_")
+
+          # Split on underscores and reject empty parts (handles consecutive underscores)
+          parts = str.split("_").reject(&:empty?)
+          return str if parts.empty?
+
+          parts.map.with_index { |word, i| i.zero? ? word : word.capitalize }.join
+        end
+
+        # Try to get a field by name, attempting both the original name and camelCase version
+        def get_field_with_conversion(type, field_name)
+          field_name_str = field_name.to_s
+
+          # Try the exact name first (for backward compatibility)
+          field = get_field_exact(type, field_name_str)
+          return field if field
+
+          # Try the camelCase version if the original name contains underscores
+          if field_name_str.include?("_")
+            camel_name = camelize(field_name_str)
+            field = get_field_exact(type, camel_name)
+            return field if field
+          end
+
+          nil
+        end
+
+        def get_field_exact(type, field_name)
+          if type.respond_to?(:fields)
+            type.fields[field_name]
+          elsif type.respond_to?(:get_field)
+            type.get_field(field_name)
+          end
+        end
+
+        # Try to get an argument by name, attempting both the original name and camelCase version
+        def get_argument_with_conversion(field, arg_name)
+          return nil unless field.respond_to?(:arguments)
+
+          arg_name_str = arg_name.to_s
+
+          # Try the exact name first (for backward compatibility)
+          arg = field.arguments[arg_name_str]
+          return arg if arg
+
+          # Try the camelCase version if the original name contains underscores
+          if arg_name_str.include?("_")
+            camel_name = camelize(arg_name_str)
+            arg = field.arguments[camel_name]
+            return arg if arg
+          end
+
+          nil
+        end
+
+        # Shared type conversion methods to avoid duplication across matchers
+
+        # Convert a GraphQL type object to its string representation
+        # Handles NonNull (!), List ([]), and nested types
+        def type_to_string(type)
+          case type
+          when GraphQL::Schema::NonNull
+            "#{type_to_string(type.of_type)}!"
+          when GraphQL::Schema::List
+            "[#{type_to_string(type.of_type)}]"
+          when GraphQL::Schema::Member
+            type.graphql_name
+          else
+            # Handle wrapped types from graphql-ruby
+            if type.respond_to?(:unwrap)
+              unwrapped = type.unwrap
+              base_name = unwrapped.respond_to?(:graphql_name) ? unwrapped.graphql_name : unwrapped.to_s
+
+              # Build the type string with wrappers
+              result = base_name
+              result = "[#{result}]" if list?(type)
+              result = "#{result}!" if non_null?(type)
+              result
+            elsif type.respond_to?(:graphql_name)
+              type.graphql_name
+            else
+              type.to_s
+            end
+          end
+        end
+
+        # Check if a type is a List type
+        def list?(type)
+          type.is_a?(GraphQL::Schema::List) ||
+            (type.respond_to?(:list?) && type.list?)
+        end
+
+        # Check if a type is a NonNull type
+        def non_null?(type)
+          type.is_a?(GraphQL::Schema::NonNull) ||
+            (type.respond_to?(:non_null?) && type.non_null?)
+        end
+      end
+
       # Matcher for checking if a GraphQL type has a specific field with type and arguments
       #
       # @example
@@ -14,12 +126,14 @@ module Zenspec
       #   expect(UserType).to have_field(:posts).with_argument(:limit, "Int")
       #
       RSpec::Matchers.define :have_field do |field_name|
+        include FieldNameHelper
+
         match do |type|
           @field_name = field_name.to_s
           @type = type
 
           # Get the field from the type
-          @field = get_field(type, @field_name)
+          @field = get_field_with_conversion(type, @field_name)
           return false unless @field
 
           # Check field type if specified
@@ -62,14 +176,6 @@ module Zenspec
 
         private
 
-        def get_field(type, field_name)
-          if type.respond_to?(:fields)
-            type.fields[field_name]
-          elsif type.respond_to?(:get_field)
-            type.get_field(field_name)
-          end
-        end
-
         def field_type_string(field)
           return nil unless field
 
@@ -77,47 +183,10 @@ module Zenspec
           type_to_string(type)
         end
 
-        def type_to_string(type)
-          case type
-          when GraphQL::Schema::NonNull
-            "#{type_to_string(type.of_type)}!"
-          when GraphQL::Schema::List
-            "[#{type_to_string(type.of_type)}]"
-          when GraphQL::Schema::Member
-            type.graphql_name
-          else
-            # Handle wrapped types from graphql-ruby
-            if type.respond_to?(:unwrap)
-              unwrapped = type.unwrap
-              base_name = unwrapped.respond_to?(:graphql_name) ? unwrapped.graphql_name : unwrapped.to_s
-
-              # Build the type string with wrappers
-              result = base_name
-              result = "[#{result}]" if list?(type)
-              result = "#{result}!" if non_null?(type)
-              result
-            elsif type.respond_to?(:graphql_name)
-              type.graphql_name
-            else
-              type.to_s
-            end
-          end
-        end
-
-        def list?(type)
-          type.is_a?(GraphQL::Schema::List) ||
-            (type.respond_to?(:list?) && type.list?)
-        end
-
-        def non_null?(type)
-          type.is_a?(GraphQL::Schema::NonNull) ||
-            (type.respond_to?(:non_null?) && type.non_null?)
-        end
-
         def check_argument(arg_name, expected_type)
           return false unless @field.respond_to?(:arguments)
 
-          arg = @field.arguments[arg_name]
+          arg = get_argument_with_conversion(@field, arg_name)
           return false unless arg
 
           if expected_type
@@ -206,12 +275,14 @@ module Zenspec
       #   expect(QueryType.fields["users"]).to have_argument(:filter).of_type("UserFilterInput")
       #
       RSpec::Matchers.define :have_argument do |arg_name|
+        include FieldNameHelper
+
         match do |field|
           @field = field
           @arg_name = arg_name.to_s
 
           # Get the argument
-          @argument = get_argument(field, @arg_name)
+          @argument = get_argument_with_conversion(field, @arg_name)
           return false unless @argument
 
           # Check argument type if specified
@@ -239,55 +310,12 @@ module Zenspec
 
         private
 
-        def get_argument(field, arg_name)
-          return nil unless field.respond_to?(:arguments)
-
-          field.arguments[arg_name]
-        end
-
         def argument_type_string(argument)
           return nil unless argument
 
           type = argument.type
           type_to_string(type)
         end
-
-        def type_to_string(type)
-          case type
-          when GraphQL::Schema::NonNull
-            "#{type_to_string(type.of_type)}!"
-          when GraphQL::Schema::List
-            "[#{type_to_string(type.of_type)}]"
-          when GraphQL::Schema::Member
-            type.graphql_name
-          else
-            # Handle wrapped types from graphql-ruby
-            if type.respond_to?(:unwrap)
-              unwrapped = type.unwrap
-              base_name = unwrapped.respond_to?(:graphql_name) ? unwrapped.graphql_name : unwrapped.to_s
-
-              # Build the type string with wrappers
-              result = base_name
-              result = "[#{result}]" if list?(type)
-              result = "#{result}!" if non_null?(type)
-              result
-            elsif type.respond_to?(:graphql_name)
-              type.graphql_name
-            else
-              type.to_s
-            end
-          end
-        end
-
-        def list?(type)
-          type.is_a?(GraphQL::Schema::List) ||
-            (type.respond_to?(:list?) && type.list?)
-        end
-
-        def non_null?(type)
-          type.is_a?(GraphQL::Schema::NonNull) ||
-            (type.respond_to?(:non_null?) && type.non_null?)
-        end
       end
 
       # Matcher for checking if a schema has a specific query field
@@ -297,6 +325,8 @@ module Zenspec
       #   expect(schema).to have_query(:users).of_type("[User!]!")
       #
       RSpec::Matchers.define :have_query do |query_name|
+        include FieldNameHelper
+
         match do |schema|
           @schema = schema
           @query_name = query_name.to_s
@@ -306,7 +336,7 @@ module Zenspec
           return false unless query_type
 
           # Get the field
-          @field = get_field(query_type, @query_name)
+          @field = get_field_with_conversion(query_type, @query_name)
           return false unless @field
 
           # Check field type if specified
@@ -353,14 +383,6 @@ module Zenspec
           schema.respond_to?(:query) ? schema.query : nil
         end
 
-        def get_field(type, field_name)
-          if type.respond_to?(:fields)
-            type.fields[field_name]
-          elsif type.respond_to?(:get_field)
-            type.get_field(field_name)
-          end
-        end
-
         def field_type_string(field)
           return nil unless field
 
@@ -368,45 +390,10 @@ module Zenspec
           type_to_string(type)
         end
 
-        def type_to_string(type)
-          case type
-          when GraphQL::Schema::NonNull
-            "#{type_to_string(type.of_type)}!"
-          when GraphQL::Schema::List
-            "[#{type_to_string(type.of_type)}]"
-          when GraphQL::Schema::Member
-            type.graphql_name
-          else
-            if type.respond_to?(:unwrap)
-              unwrapped = type.unwrap
-              base_name = unwrapped.respond_to?(:graphql_name) ? unwrapped.graphql_name : unwrapped.to_s
-
-              result = base_name
-              result = "[#{result}]" if list?(type)
-              result = "#{result}!" if non_null?(type)
-              result
-            elsif type.respond_to?(:graphql_name)
-              type.graphql_name
-            else
-              type.to_s
-            end
-          end
-        end
-
-        def list?(type)
-          type.is_a?(GraphQL::Schema::List) ||
-            (type.respond_to?(:list?) && type.list?)
-        end
-
-        def non_null?(type)
-          type.is_a?(GraphQL::Schema::NonNull) ||
-            (type.respond_to?(:non_null?) && type.non_null?)
-        end
-
         def check_argument(arg_name, expected_type)
           return false unless @field.respond_to?(:arguments)
 
-          arg = @field.arguments[arg_name]
+          arg = get_argument_with_conversion(@field, arg_name)
           return false unless arg
 
           if expected_type
@@ -425,6 +412,8 @@ module Zenspec
       #   expect(schema).to have_mutation(:deleteUser).of_type("DeleteUserPayload!")
       #
       RSpec::Matchers.define :have_mutation do |mutation_name|
+        include FieldNameHelper
+
         match do |schema|
           @schema = schema
           @mutation_name = mutation_name.to_s
@@ -434,7 +423,7 @@ module Zenspec
           return false unless mutation_type
 
           # Get the field
-          @field = get_field(mutation_type, @mutation_name)
+          @field = get_field_with_conversion(mutation_type, @mutation_name)
           return false unless @field
 
           # Check field type if specified
@@ -481,14 +470,6 @@ module Zenspec
           schema.respond_to?(:mutation) ? schema.mutation : nil
         end
 
-        def get_field(type, field_name)
-          if type.respond_to?(:fields)
-            type.fields[field_name]
-          elsif type.respond_to?(:get_field)
-            type.get_field(field_name)
-          end
-        end
-
         def field_type_string(field)
           return nil unless field
 
@@ -496,45 +477,10 @@ module Zenspec
           type_to_string(type)
         end
 
-        def type_to_string(type)
-          case type
-          when GraphQL::Schema::NonNull
-            "#{type_to_string(type.of_type)}!"
-          when GraphQL::Schema::List
-            "[#{type_to_string(type.of_type)}]"
-          when GraphQL::Schema::Member
-            type.graphql_name
-          else
-            if type.respond_to?(:unwrap)
-              unwrapped = type.unwrap
-              base_name = unwrapped.respond_to?(:graphql_name) ? unwrapped.graphql_name : unwrapped.to_s
-
-              result = base_name
-              result = "[#{result}]" if list?(type)
-              result = "#{result}!" if non_null?(type)
-              result
-            elsif type.respond_to?(:graphql_name)
-              type.graphql_name
-            else
-              type.to_s
-            end
-          end
-        end
-
-        def list?(type)
-          type.is_a?(GraphQL::Schema::List) ||
-            (type.respond_to?(:list?) && type.list?)
-        end
-
-        def non_null?(type)
-          type.is_a?(GraphQL::Schema::NonNull) ||
-            (type.respond_to?(:non_null?) && type.non_null?)
-        end
-
         def check_argument(arg_name, expected_type)
           return false unless @field.respond_to?(:arguments)
 
-          arg = @field.arguments[arg_name]
+          arg = get_argument_with_conversion(@field, arg_name)
           return false unless arg
 
           if expected_type

data/lib/zenspec/matchers/interactor_matchers.rb

@@ -18,7 +18,7 @@ module Zenspec
           @result = get_result(actual)
           return false if @result.failure?
 
-          return false if @expected_data && @result.data != @expected_data
+          return false if !@expected_data.nil? && @result.data != @expected_data
 
           if @context_checks
             @context_checks.all? do |key, value|

data/lib/zenspec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zenspec
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zenspec
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Wilson Anciro