api-testing

name	api-testing
description	Test REST and GraphQL endpoint contracts using Playwright request fixture (TypeScript) or REST Assured (Java). Use for standalone API tests covering schemas, auth, status/error handling, pagination, idempotency, rate limits, or contract checks; not for browser E2E specs. Keywords: REST, GraphQL, API contract, schema validation, REST Assured.
license	Complete terms in LICENSE.txt

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).

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

Do NOT Use For

• Browser-driven UI flows (use playwright-e2e-testing for Playwright specs, or webapp-selenium-testing for Selenium)
• Live interactive browser sessions or snapshots (use playwright-cli)
• Visual/layout regression (out of scope — no DOM)
• End-to-end journeys that must drive a real browser across pages

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

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

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));
}

---

Red Flags

Stop and reconsider if you see any of these in generated API tests:

• Assertions only on status code with no body/schema validation — an unvalidated response hides contract drift.
• Hardcoded secrets/tokens committed to the test file — read from env or a secrets manager.
• Tests sharing mutable state with no cleanup — flaky and order-dependent.
• Skipping auth tests (no 401/403 assertions on protected endpoints) — security regression risk.
• No coverage of error states (only happy-path 200s) — error handling is untested.

---

References

Document	Content
REST API Patterns	CRUD, pagination, filtering, error patterns
Playwright API Testing	Request fixture, Supertest, TypeScript patterns
REST Assured Testing	REST Assured, AssertJ, Java patterns
Schema Validation	Zod (TS), JSON Schema (Java), strict vs loose
Contract Testing	Request/response contracts, idempotency, versioning

Templates

• Playwright API Spec — starter test file for API testing
• REST Assured Test — starter Java test class

Scripts

• API Health Check — 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

• 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