Json Api Testing Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev cloudcreativity/json-api-testing
   

   No additional configuration is required—it works out-of-the-box with PHPUnit.

2. First Use Case: Basic JSON API Assertion Use the JsonApiTestCase trait in your test class to validate JSON:API responses:

   use CloudCreativity\JsonApiTesting\JsonApiTestCase;
   
   class UserApiTest extends JsonApiTestCase
   {
       public function test_user_response()
       {
           $response = $this->get('/api/users/1');
   
           $this->assertJsonApiResponse($response)
               ->hasData('users', 1)
               ->hasAttributes('users.0', ['name', 'email'])
               ->isValid();
       }
   }
   

3. Key Methods to Explore First

   • assertJsonApiResponse(): Entry point for assertions.
   • hasData(): Verify resource count.
   • hasAttributes(): Check for required fields.
   • isValid(): Ensure the response adheres to JSON:API spec.

Implementation Patterns

Common Workflows

1. Testing API Endpoints Chain assertions for comprehensive validation:

   $this->assertJsonApiResponse($response)
       ->hasData('articles', 2)
       ->hasRelationships('articles.0', ['author'])
       ->hasMeta('pagination', ['total', 'limit'])
       ->isValid();
   

2. Dynamic Data Validation Use closures for conditional checks:

   $this->assertJsonApiResponse($response)
       ->hasAttributes('users.0', function ($attributes) {
           return $attributes['email'] === '[email protected]';
       });
   

3. Testing Error Responses Validate error formats (e.g., 404, 422):

   $response = $this->get('/api/nonexistent');
   $this->assertJsonApiResponse($response)
       ->hasErrors(['detail' => 'Not Found'])
       ->isInvalid();
   

4. Integration with Laravel HTTP Tests Combine with Laravel’s Http\TestResponse for seamless testing:

   $response = $this->actingAs($user)->post('/api/posts', ['title' => 'Test']);
   $this->assertJsonApiResponse($response)
       ->hasData('posts', 1)
       ->hasAttribute('posts.0', 'title', 'Test');
   

5. Custom Assertions Extend the package for domain-specific rules:

   $this->assertJsonApiResponse($response)
       ->hasCustomValidation('posts.0', function ($post) {
           $this->assertTrue(str_contains($post['title'], 'Laravel'));
       });
   

Gotchas and Tips

Pitfalls

1. Strict JSON:API Compliance The package enforces JSON:API spec rules (e.g., data root key, type/id fields). If your API deviates, assertions may fail unexpectedly. Fix: Use isValid(false) to skip spec validation.

2. Nested Resource Traversal Incorrect path syntax (e.g., users.0.author) will throw errors. Tip: Use hasRelationships() for nested resources and verify paths carefully.

3. Case Sensitivity Attribute names in hasAttributes() are case-sensitive. Tip: Normalize keys (e.g., snake_case) in tests if your API uses them.

4. Meta/Data Confusion Mixing meta and data assertions can lead to false positives. Tip: Explicitly scope checks (e.g., hasMeta(), hasData()).

Debugging Tips

• Inspect Raw Response Use $response->getContent() to debug unexpected JSON structures.
• Disable Strict Mode Temporarily set isValid(false) to isolate issues.
• Check for Typos Attribute/relationship paths are zero-indexed (e.g., users.0).

Extension Points

1. Custom Validators Override JsonApiTestCase to add domain logic:

   protected function customValidations()
   {
       return [
           'posts.0' => function ($post) {
               $this->assertTrue($post['published_at'] > now());
           }
       ];
   }
   

2. Mocking Responses Use Laravel’s JsonResponse for unit tests:

   $mockResponse = new JsonResponse(['data' => [...]]);
   $this->assertJsonApiResponse($mockResponse)->isValid();
   

3. Performance For large datasets, cache responses or use only() to limit assertions:

   $this->assertJsonApiResponse($response)
       ->only(['data', 'meta'])
       ->isValid();