feat(test-utils): add custom response matchers for API error handling

[luxass]

🔗 Linked issue

📚 Description

This PR adds a few new matchers.

Helps closing #420

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2340ed9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@luxass has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 2 minutes and 51 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between b183271 and 2340ed9.

📒 Files selected for processing (4)

• packages/test-utils/src/matchers/response-matchers.ts
• packages/test-utils/src/matchers/schema-matchers.ts
• packages/test-utils/src/matchers/types.d.ts
• packages/test-utils/src/matchers/vitest-setup.ts

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🌏 Preview Deployments

Note

No deployable apps affected by changes in this PR.

Built from commit: 2340ed954e3c1b23051335eff1ca48495be49492

---

_{🤖 This comment will be updated automatically when you push new commits to this PR.}

[codecov]

Codecov Report

❌ Patch coverage is 3.12500% with 124 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...kages/test-utils/src/matchers/response-matchers.ts	2.75%	52 Missing and 54 partials ⚠️
...ackages/test-utils/src/matchers/schema-matchers.ts	5.26%	12 Missing and 6 partials ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

Added four custom Vitest matchers to @ucdjs/test-utils for API testing: toMatchResponse, toBeApiError, toBeHeadError, and toMatchSchema.

• toMatchResponse validates Response objects including status, headers, cache-control, and optional error structure checking
• toBeApiError checks API error responses match the ApiError schema with status/message/timestamp
• toBeHeadError validates HEAD request responses have correct status and empty body
• toMatchSchema validates data against Zod schemas with optional partial data matching

The matchers follow the existing pattern from error-matchers.ts and are properly registered in vitest-setup.ts.

Confidence Score: 3/5

• PR has two issues that will cause TypeScript compilation errors and one logic bug in regex matching
• The missing zod import in types.d.ts will cause TypeScript to fail compilation since z.ZodType is undefined. The regex matching bug in response-matchers.ts:266 will cause incorrect behavior when RegExp patterns are provided for error message validation. These must be fixed before merging.
• Pay close attention to packages/test-utils/src/matchers/types.d.ts (missing import) and packages/test-utils/src/matchers/response-matchers.ts (regex bug on line 266)

Important Files Changed

Filename	Overview
packages/test-utils/src/matchers/response-matchers.ts	Added three response matchers (toBeApiError, toBeHeadError, toMatchResponse) for API testing - found regex handling bug in line 266 and unused exported interface
packages/test-utils/src/matchers/types.d.ts	Added type declarations for new matchers - missing zod import causes z.ZodType to be undefined

Sequence Diagram

sequenceDiagram
    participant Test as Test Suite
    participant Matcher as Custom Matchers
    participant Response as Response Object
    participant Schema as Zod Schema
    participant Error as ApiError

    Note over Test,Matcher: Response Validation Flow
    Test->>Matcher: expect(response).toMatchResponse(options)
    Matcher->>Response: Check status code
    Matcher->>Response: Check content-type header
    Matcher->>Response: Validate cache-control
    Matcher->>Response: Check custom headers
    alt Error validation requested
        Matcher->>Response: response.json()
        Response-->>Matcher: ApiError object
        Matcher->>Error: Validate status, message, timestamp
        Matcher-->>Test: Pass/Fail with message
    else Standard response
        Matcher-->>Test: Pass/Fail with message
    end

    Note over Test,Matcher: Schema Validation Flow
    Test->>Matcher: expect(data).toMatchSchema(options)
    Matcher->>Schema: schema.safeParse(data)
    Schema-->>Matcher: Validation result
    alt Partial data check
        Matcher->>Matcher: Compare expected properties
    end
    Matcher-->>Test: Pass/Fail with message

    Note over Test,Matcher: API Error Validation Flow
    Test->>Matcher: expect(response).toBeApiError(options)
    Matcher->>Response: Verify status matches
    Matcher->>Response: Check JSON content-type
    Matcher->>Response: response.json()
    Response-->>Matcher: ApiError object
    Matcher->>Error: Validate structure
    alt Message pattern provided
        Matcher->>Error: Test message against pattern
    end
    Matcher-->>Test: Pass/Fail with message

Loading

[greptile-apps]

_{4 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[Copilot]

Pull request overview

This PR introduces custom Vitest matchers for API response and schema validation testing, enhancing the test-utils package with three new matchers: toBeApiError, toBeHeadError, and toMatchResponse, along with a schema validation matcher toMatchSchema.

Key changes:

• Added schema validation matcher with support for partial data matching
• Added API error validation matchers with status code, content-type, and message verification
• Added HEAD request error matcher for validating error responses with proper content-length

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 6 comments.

File	Description
packages/test-utils/src/matchers/vitest-setup.ts	Registers the new matchers (toMatchSchema, toBeApiError, toBeHeadError, toMatchResponse) with Vitest
packages/test-utils/src/matchers/types.d.ts	Adds TypeScript type definitions for the new matchers to the Vitest Matchers interface
packages/test-utils/src/matchers/schema-matchers.ts	Implements toMatchSchema matcher for validating data against Zod schemas with optional partial data checking
packages/test-utils/src/matchers/response-matchers.ts	Implements three response validation matchers for API error handling, HEAD requests, and general response matching

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.