api-testing

# API Testing (Playwright + REST Assured) Comprehensive API testing skill covering both Playwright TypeScript (request fixture, Supertest, Zod) and Java (REST Assured, AssertJ, JSON Schema Validator). Provides deep domain expertise for the `api-tester-specialist` agent. ## When to Use This Skill - Create API tests for REST or GraphQL endpoints - Validate request/response schemas (Zod, JSON Schema) - Test authentication flows (OAuth2, JWT, API keys, Bearer tokens) - Verify error handling (400, 401, 403, 404, 409, 422, 500) - Test pagination, filtering, sorting edge cases - Validate idempotency for PUT/DELETE operations - Contract testing between services - Rate limiting validation ## Prerequisites | Stack | Requirements | | ---------- | --------------------------------------------------------------------- | | TypeScript | Node.js 18+, `@playwright/test` or `supertest`, `zod` | | Java | Java 21+, REST Assured 5.x, AssertJ, Jackson, `json-schema-validator` | ## Core Principles 1. **Schema validation on every response** — never trust an unvalidated response 2. **Test all HTTP status codes** — happy path AND error states 3. **Auth testing is mandatory** — verify 401/403 for protected endpoints 4. **Data-driven** — test with valid, invalid, boundary, and empty values 5. **Stateless where possible** — each test cleans up or uses unique data ## Quick Reference — Playwright ```typescript import { test, expect } from "@playwright/test"; test("GET /api/users returns 200 with valid schema", async ({ request }) => { const response = await request.get("/api/users"); expect(response.ok()).toBeTruthy(); const body = await response.json(); expect(body).toMatchObject({ data: expect.any(Array) }); }); ``` ## Quick Reference — REST Assured ```java import static io.restassured.RestAssured.*; import static org.hamcrest.Matchers.*; import java.util.List; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @Test @DisplayName("GET /api/users returns 200 with valid schema") void getUsers() { String token = "test-token"; given() .header("Authorization", "Bearer " + token) .when() .get("/api/users") .then() .statusCode(200) .body("data", is(instanceOf(List.class))) .body("data.size()", greaterThan(0)); } ``` ## Common Rationalizations > Common shortcuts and "good enough" excuses that erode test quality — and the reality behind each. | Rationalization | Reality | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | "Schema validation is overkill" | Without schema validation, a silent field rename becomes a production incident. Validate every response. | | "Happy path testing is enough" | Error states (400, 401, 403, 404, 409, 500) are where real failures happen. Test all status codes. | | "Auth tests can wait" | Unauthenticated access to protected endpoints is a security vulnerability, not a backlog item. | | "This endpoint won't change" | APIs evolve. Contract tests catch breaking changes before they reach production. | | "Manual API testing with Postman is sufficient" | Manual testing isn't repeatable, can't run in CI, and doesn't scale. Automate API tests. | | "Idempotency doesn't matter" | Duplicate requests happen in production. Without idempotency testing, you get duplicate records and charges. | --- ## References | Document | Content | | ---------------------------------------------------------------- | --------------------------------------------------- | | [REST API Patterns](./references/rest-api-patterns.md) | CRUD, pagination, filtering, error patterns | | [Playwright API Testing](./references/playwright-api-testing.md) | Request fixture, Supertest, TypeScript patterns | | [REST Assured Testing](./references/rest-assured-testing.md) | REST Assured, AssertJ, Java patterns | | [Schema Validation](./references/schema-validation.md) | Zod (TS), JSON Schema (Java), strict vs loose | | [Contract Testing](./references/contract-testing.md) | Request/response contracts, idempotency, versioning | ## Templates - [Playwright API Spec](./templates/playwright-api-spec.ts) — starter test file for API testing - [REST Assured Test](./templates/rest-assured-test.java) — starter Java test class ## Scripts - [API Health Check](./scripts/api-health-check.sh) — validate API endpoints respond correctly ## Troubleshooting | Issue | Solution | | ------------------------------ | ------------------------------------------------------------------------------ | | 401 on authenticated endpoints | Verify token is fresh; check expiry; re-authenticate | | Flaky API tests | Add retry logic; check for rate limiting; use unique test data | | Schema validation too strict | Use `.passthrough()` (Zod) or `additionalProperties: true` for flexible fields | | Timeout on slow endpoints | Increase `timeout` in request options; check for server load | --- ## Verification After completing this skill's workflow, confirm: - [ ] **All CRUD operations tested** — POST, GET, PUT, PATCH, DELETE covered for the resource - [ ] **Status codes verified** — Success (2xx) AND error codes (4xx, 5xx) tested - [ ] **Schema validation in place** — Every response validated against a schema (Zod or JSON Schema) - [ ] **Authentication tested** — 401 returned for protected endpoints without valid credentials - [ ] **Idempotency verified** — PUT/DELETE produce same result when called multiple times - [ ] **Edge cases covered** — Empty payloads, invalid types, boundary values, SQL injection attempts - [ ] **All tests pass** — Playwright API tests or REST Assured tests exit successfully