jaktestowac/awesome-copilot-for-testers / plugins/api-playwright-test-developer/skills/api-playwright-test-developer
api-playwright-test-developer
VerifiedWrites and reviews API automation tests with Playwright Test, covering setup/teardown, assertions, data management, and hybrid API+UI flows. Use when creating backend API tests, contract checks, data-driven API coverage, API+UI hybrid workflows, or reviewing existing Playwright API suites.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
SKILL.md
View on GitHub---
name: api-playwright-test-developer
description: 'Writes and reviews API automation tests with Playwright Test, covering setup/teardown, assertions, data management, and hybrid API+UI flows. Use when creating backend API tests, contract checks, data-driven API coverage, API+UI hybrid workflows, or reviewing existing Playwright API suites.'
argument-hint: 'Endpoint or OpenAPI spec, expected behaviors, auth details, and any existing fixtures or helpers'
user-invocable: true
---
# API Playwright Test Developer
This skill defines the standard approach for writing and maintaining Playwright-based API tests. It is optimized for robust, repeatable automated validation of REST/GraphQL services, readable test design, and minimal flakiness.
## When to Use
- API endpoint functional testing (status, schema, body values)
- Data-driven regression coverage across all environments
- Contract checks (OpenAPI/JSON Schema) for service evolution
- End-to-end test flows mixing UI and API interactions (hybrid tests)
- CI pipeline smoke tests and API health checks
## Core Principles
1. Explicit setup/teardown
- Use `test.beforeEach` and `test.afterEach` for consistent test state management (e.g., create/delete test data).
- Clean up created test data in `test.afterEach` by default. Skip cleanup only temporarily when debugging a failure, and never commit that state.
- Avoid shared mutable state across tests to prevent flakiness.
- Use unique identifiers in test data to avoid collisions and ensure idempotency.
2. Single responsibility per test case
- Each test should target one behavior (e.g., 200 vs 401, field validation, paginated listing).
- Use descriptive test titles to clarify the intent and expected outcome.
- For complex scenarios, break down into multiple focused tests rather than one large test with many assertions.
- When testing e2e flows, consider using `test.step` to logically group related API calls and assertions within a single test case.
3. Assertions
- Avoid brittle tests that rely on dynamic timestamps or ordering unless controlled.
- Add descriptive messages to assertions for easier debugging.
- Use soft assertions `expect.soft` for multiple checks in a single test without stopping at the first failure.
4. Clear data management
- Use fixtures/config to store base URL, auth tokens, test payload templates.
- Use factory functions to generate test data with unique identifiers.
- Avoid hardcoding environment-specific values in tests; use environment variables or config files.
- For complex data setup, consider using API calls in `beforeEach` to create necessary resources instead of relying on static test data.
5. Patterns and best practices
- Use `request` fixture for API calls.
- Use AAA pattern (Arrange-Act-Assert) for test structure.
- Use builders or factories for constructing request payloads to improve readability and maintainability.
- Use Simple Request Object Pattern to encapsulate API interactions and reduce duplication across tests.
- Use `test.describe` to group related tests and share setup/teardown logic.
## Recommended Folder Layout
```
.
├── tests/
│ ├── api/
│ │ ├── users.spec.ts
│ │ ├── auth.spec.ts
│ │ ├── orders.spec.ts
│ │ └── contracts.spec.ts
│ ├── e2e/
│ │ ├── signup-and-purchase.spec.ts
│ │ └── checkout-api-ui.spec.ts
│ └── fixtures/
│ ├── api-fixtures.ts
│ ├── data-fixtures.ts
│ └── auth-fixtures.ts
├── helpers/
│ ├── api-helpers.ts
│ ├── schema-validators.ts
│ └── retry-utils.ts
├── data/
│ └── payloads/
│ ├── create-user.json
│ ├── update-order.json
│ └── login.json
├── docs/
│ └── api-test-guidelines.md
├── .github/
│ └── workflows/
│ └── api-tests.yml
├── playwright.config.ts
└── .env.example
```
- `tests/api/`: dedicated API service tests and contract/spec tests.
- `tests/e2e/`: hybrid scenarios that combine UI and API flows.
- `tests/fixtures/`: setup data and auth fixtures for Playwright Test.
- `helpers/`: reusable request builders, response assertions, schema validators.
- `data/payloads/`: canonical test payloads to avoid inline duplication.
- `.env.example`: environment abstraction for endpoints and tokens.
- `.github/workflows/api-tests.yml`: CI pipeline orchestration with separate API test job.
## Playwright Test Example (TypeScript)
```ts
import { test, expect } from '@playwright/test';
test.describe('API: /users', () => {
test('GET /users returns 200 and JSON schema', async ({ request }) => {
const response = await request.get('/api/users', {
headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
});
expect(response.status()).toBe(200);
expect(response.headers()['content-type']).toContain('application/json');
const body = await response.json();
expect(Array.isArray(body)).toBeTruthy();
expect(body.length).toBeGreaterThanOrEqual(0);
});
});
```
## Common Patterns
- `request.get`, `request.post`, `request.put`, `request.delete`
- HTTP retries for transient 5xx responses (in test infrastructure, not per-test)
- Data-driven tests: Playwright Test has no `test.each` - loop over a test-case array instead, so each case registers as its own test:
```ts
const cases = [
{ name: 'admin', role: 'admin', expectedStatus: 200 },
{ name: 'guest', role: 'guest', expectedStatus: 403 },
];
for (const data of cases) {
test(`GET /reports as ${data.name} returns ${data.expectedStatus}`, async ({ request }) => {
const response = await request.get('/api/reports', {
headers: { Authorization: `Bearer ${tokenFor(data.role)}` },
});
expect(response.status()).toBe(data.expectedStatus);
});
}
```
See the parameterize guide: https://playwright.dev/docs/test-parameterize
- Auth token refresh helpers and failures when invalid credentials are used
- Validate headers `cache-control`, `strict-transport-security`, etc. for security tests
## Hybrid API+UI Scenario
1. Authenticate with API: `POST /auth/login` → token
2. Set browser storage/cookie in Playwright page context
3. Visit protected UI page to assert data mirrored from API
4. Modify resource via API, then confirm UI updates (or vice versa)
## Troubleshooting Guide
- 401/403: verify token scope, environment URL, and clock skew
- 404: confirm route path and version (`/v1`, `/v2`), check mock intercepts
- Timeout: increase `timeout` in `request` and `page.waitForResponse` with precise matcher
- Flakiness: isolate side effects, use dedicated test data, run service health checks before suite
## Best Practices Checklist
- [ ] Leverage shared fixtures for base URL and authentication
- [ ] Keep request payloads small and reproducible
- [ ] Assert exact response fields and types
- [ ] Log request/response on failure with contextual messages
- [ ] Use `test.step` for complex flows to improve readability
- [ ] Clean up created test data in `afterEach`
- [ ] Regularly review and refactor tests to remove redundancy and improve clarity
## Related Skills
- `designing-test-data` - when the test data strategy needs dedicated design
- `verifying-acceptance-criteria` - when API behavior must be checked against stated acceptance criteria
- `code-review-advanced` - when an existing API suite needs a structured review
## Definition of Done
This skill is complete when:
- each test targets one behavior with a descriptive title
- setup and teardown are explicit, and created data is cleaned up in `afterEach`
- assertions check status, content type, and exact response fields
- data-driven cases use the loop-over-cases pattern, not a nonexistent `test.each`
- environment-specific values come from config or environment variables, not hardcoded literals
## References
- Playwright REST API request docs: https://playwright.dev/docs/api-testing
- Parameterized tests: https://playwright.dev/docs/test-parameterize
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |