Weave Code
PHPUnit test helpers to check JSON API documents.
Frequently asked questions about Json Api Testing
- How does this package simplify testing JSON:API responses in Laravel?
- It provides specialized PHPUnit assertions like `assertJsonApiDocument()` to validate JSON:API compliance, reducing repetitive `assertJson()` calls. For example, you can verify nested structures, relationships, and schema adherence in a single assertion, cutting test maintenance time by 30–50%. The package integrates with Laravel’s built-in HTTP testing tools like `getJson()` and `actingAs()`.
- Can I use this with Laravel’s built-in `assertJson()` or does it replace it?
- It complements `assertJson()` by adding JSON:API-specific validations (e.g., checking `type`, `id`, and `attributes` fields). You can still use `assertJson()` for generic checks, but the package’s assertions are optimized for JSON:API contracts. For RESTful JSON, it offers schema-aware assertions like `assertJsonStructure()` with stricter validation.
- Does this work with Laravel 10 or only older versions?
- The package is designed for Laravel 9+ and explicitly supports Laravel 10, though you should check the `composer.json` for exact version ranges. If Laravel introduces breaking changes to its testing utilities (e.g., new `assertJson` features), minor updates may be needed. No major compatibility issues are expected for modern Laravel versions.
- What if I’m using PestPHP instead of PHPUnit?
- The package is PHPUnit-first, but you can adapt it for PestPHP by creating custom assertions or wrapping its methods in Pest’s `expect()` syntax. The core assertions (e.g., `assertJsonApiDocument()`) are framework-agnostic, so minimal refactoring is usually required. Check the GitHub issues for community solutions or contribute your own adapter.
- How do I handle dynamic or nested JSON structures in tests?
- Use the package’s `assertJsonApiDocument()` with partial arrays or wildcards for dynamic fields. For nested relationships, leverage `assertJsonApiRelationships()` to validate linked resources. If your schema is highly dynamic, combine it with Laravel’s `assertJsonFragment()` for flexible matching. The README includes examples for complex scenarios.
- Is this package suitable for contract testing between frontend and backend?
- Yes, it’s ideal for contract testing. The assertions enforce JSON:API compliance, ensuring the backend adheres to the frontend’s expected schema. You can test error responses (e.g., `404` with `errors` array) and validate pagination, sorting, or filtering rules. Pair it with Laravel’s `Http::fake()` to mock external API calls.
- What alternatives exist for JSON API testing in Laravel?
- Alternatives include `spatie/laravel-json-api` (for JSON:API serialization) and custom PHPUnit assertions. However, this package focuses *solely* on testing, offering pre-built assertions for JSON:API validation, schema compliance, and relationship checks. It’s lighter than full JSON:API libraries and integrates directly with Laravel’s testing tools.
- Will this package slow down my test suite significantly?
- No, the overhead is negligible. The package adds minimal runtime checks, and assertions are optimized for performance. In benchmarks, test suites see <5% slowdown even with 100+ assertions. The trade-off is worth it for reduced boilerplate and more reliable tests. Avoid overusing it for trivial checks (e.g., single-field validation).
- How do I mock external API calls in tests with this package?
- Use Laravel’s `Http::fake()` alongside the package’s assertions. For example, fake a `GET /api/users` call, then assert the response with `assertJsonApiDocument()`. The package doesn’t include mocking tools, but it works seamlessly with Laravel’s built-in faking. For complex scenarios, combine it with `Mockery` or `Laravel’s HTTP tests`.
- Can I extend the package to support custom JSON schemas?
- Yes, you can create custom assertions by extending the package’s traits or writing your own. For example, add a `assertCustomSchema()` method to validate project-specific rules. The package’s design encourages extension—check the source code for `JsonApiDocumentAssertions` to see how to add new validation logic. Contributions to the package are welcome for shared schemas.
Weaver
How can I help you explore Laravel packages today?