api-testing-patterns

SKILL.md

API Testing Patterns

<default_to_action>
When testing APIs or designing API test strategy:

IDENTIFY testing level: contract, integration, or component

TEST the contract, not implementation (consumer perspective)

VALIDATE auth, input, errors, idempotency, concurrency

AUTOMATE in CI/CD with schema validation

MONITOR production APIs for contract drift

Quick Pattern Selection:

Microservices → Consumer-driven contracts (Pact)

REST APIs → CRUD + pagination + filtering tests

GraphQL → Query validation + complexity limits

External deps → Mock with component testing

Performance → Load test critical endpoints

Critical Success Factors:

APIs are contracts - test from consumer perspective

Always test error scenarios, not just happy paths

Version your API tests to prevent breaking changes
</default_to_action>

Quick Reference Card

When to Use

Testing REST or GraphQL APIs

Validating microservice contracts

Designing API test strategies

Preventing breaking API changes

Testing Levels

Level
Purpose
Dependencies
Speed

Contract
Provider-consumer agreement
None
Fast

Component
API in isolation
Mocked
Fast

Integration
Real dependencies
Database, services
Slower

Critical Test Scenarios

Scenario
Must Test
Example

Auth
401/403 handling
Expired token, wrong user

Input
400 validation
Missing fields, wrong types

Errors
500 graceful handling
DB down, timeout

Idempotency
Duplicate prevention
Same idempotency key

Concurrency
Race conditions
Parallel checkout

Tools

Contract: Pact, Spring Cloud Contract

REST: Supertest, REST-assured, Playwright

Load: k6, Artillery, JMeter

Agent Coordination

qe-api-contract-validator: Validate contracts, detect breaking changes

qe-test-generator: Generate tests from OpenAPI spec

qe-performance-tester: Load test endpoints

qe-security-scanner: API security testing

Contract Testing

Pattern: Consumer-Driven Contracts

// Consumer defines expectations
const contract = {
  request: { method: 'POST', path: '/orders', body: { productId: 'abc', quantity: 2 } },
  response: { status: 201, body: { orderId: 'string', total: 'number' } }
};

// Provider must fulfill
test('order API meets contract', async () => {
  const response = await api.post('/orders', { productId: 'abc', quantity: 2 });

  expect(response.status).toBe(201);
  expect(response.body).toMatchSchema({
    orderId: expect.any(String),
    total: expect.any(Number)
  });
});

When: Microservices, distributed systems, third-party integrations

Critical Test Patterns

Authentication & Authorization

describe('Auth', () => {
  it('rejects without token', async () => {
    expect((await api.get('/orders')).status).toBe(401);
  });

  it('rejects expired token', async () => {
    const expired = generateExpiredToken();
    expect((await api.get('/orders', { headers: { Authorization: `Bearer ${expired}` } })).status).toBe(401);
  });

  it('blocks cross-user access', async () => {
    const userAToken = generateToken({ userId: 'A' });
    expect((await api.get('/orders/user-B-order', { headers: { Authorization: `Bearer ${userAToken}` } })).status).toBe(403);
  });
});

Input Validation

describe('Validation', () => {
  it('validates required fields', async () => {
    const response = await api.post('/orders', { quantity: 2 }); // Missing productId
    expect(response.status).toBe(400);
    expect(response.body.errors).toContain('productId is required');
  });

  it('validates types', async () => {
    expect((await api.post('/orders', { productId: 'abc', quantity: 'two' })).status).toBe(400);
  });

  it('validates ranges', async () => {
    expect((await api.post('/orders', { productId: 'abc', quantity: -5 })).status).toBe(400);
  });
});

Idempotency

it('prevents duplicates with idempotency key', async () => {
  const key = 'unique-123';
  const data = { productId: 'abc', quantity: 2 };

  const r1 = await api.post('/orders', data, { headers: { 'Idempotency-Key': key } });
  const r2 = await api.post('/orders', data, { headers: { 'Idempotency-Key': key } });

  expect(r1.body.orderId).toBe(r2.body.orderId); // Same order
});

Concurrency

it('handles race condition on inventory', async () => {
  const promises = Array(10).fill().map(() =>
    api.post('/orders', { productId: 'abc', quantity: 1 })
  );
  const responses = await Promise.all(promises);
  const successful = responses.filter(r => r.status === 201);

  const inventory = await db.inventory.findById('abc');
  expect(inventory.quantity).toBe(initialQuantity - successful.length);
});

REST CRUD Pattern

describe('Product CRUD', () => {
  let productId;

  it('CREATE', async () => {
    const r = await api.post('/products', { name: 'Widget', price: 10 });
    expect(r.status).toBe(201);
    productId = r.body.id;
  });

  it('READ', async () => {
    const r = await api.get(`/products/${productId}`);
    expect(r.body.name).toBe('Widget');
  });

  it('UPDATE', async () => {
    const r = await api.put(`/products/${productId}`, { price: 12 });
    expect(r.body.price).toBe(12);
  });

  it('DELETE', async () => {
    expect((await api.delete(`/products/${productId}`)).status).toBe(204);
    expect((await api.get(`/products/${productId}`)).status).toBe(404);
  });
});

Best Practices

✅ Do This

Test from consumer perspective

Use schema validation (not exact values)

Test error scenarios extensively

Version API tests

Automate in CI/CD

❌ Avoid This

Testing implementation, not contract

Ignoring HTTP semantics (status codes)

No negative testing

Asserting on field order or extra fields

Slow tests (mock external services)

Agent-Assisted API Testing

// Validate contracts
await Task("Contract Validation", {
  spec: 'openapi.yaml',
  endpoint: '/orders',
  checkBreakingChanges: true
}, "qe-api-contract-validator");

// Generate tests from spec
await Task("Generate API Tests", {
  spec: 'openapi.yaml',
  coverage: 'comprehensive',
  include: ['happy-paths', 'input-validation', 'auth-scenarios', 'error-handling']
}, "qe-test-generator");

// Load test
await Task("API Load Test", {
  endpoint: '/orders',
  rps: 1000,
  duration: '5min'
}, "qe-performance-tester");

// Security scan
await Task("API Security Scan", {
  spec: 'openapi.yaml',
  checks: ['sql-injection', 'xss', 'broken-auth', 'rate-limiting']
}, "qe-security-scanner");

Agent Coordination Hints

Memory Namespace

aqe/api-testing/
├── contracts/*        - API contract definitions
├── generated-tests/*  - Generated test suites
├── validation/*       - Contract validation results
└── performance/*      - Load test results

Fleet Coordination

const apiFleet = await FleetManager.coordinate({
  strategy: 'contract-testing',
  agents: ['qe-api-contract-validator', 'qe-test-generator', 'qe-test-executor'],
  topology: 'mesh'
});

await apiFleet.execute({
  services: [
    { name: 'orders-api', consumers: ['checkout-ui', 'admin-api'] },
    { name: 'payment-api', consumers: ['orders-api'] }
  ]
});

Related Skills

agentic-quality-engineering - API testing with agents

tdd-london-chicago - London school for API testing

performance-testing - API load testing

security-testing - API security validation

contract-testing - Consumer-driven contracts deep dive

Remember

API testing = verifying contracts and behavior, not implementation. Focus on what matters to consumers: correct responses, proper error handling, acceptable performance.

With Agents: Agents automate contract validation, generate comprehensive test suites from specs, and monitor production APIs for drift. Use agents to maintain API quality at scale.

Gotchas

Agent generates tests against documented API, not actual API — always validate against running service first

Auth tokens expire between test runs — use fixtures with long-lived tokens or refresh before each suite

Rate limiting in CI causes intermittent failures — add retry with exponential backoff for 429 responses

GraphQL introspection may be disabled in production — test against staging schema, not production endpoint

Idempotency tests need unique request IDs per run — hardcoded IDs cause false passes on retry