api-testing

This skill complements testing-skill (code-based tests) and api-design-skill (API structure). Use this when you need to test existing APIs with dedicated tools rather than writing programmatic tests.

Key distinction:

• testing-skill: Code-based tests (supertest, MSW, pytest requests)
• api-testing-skill: Tool-based tests (Postman, Bruno collections)
• api-design-skill: How to design APIs (structure, conventions) </objective>

<quick_start> Postman Quick Test:

// Tests tab in Postman
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has user data", function () {
    const json = pm.response.json();
    pm.expect(json).to.have.property("id");
    pm.expect(json).to.have.property("email");
});

Bruno Quick Test:

// tests/get-user.bru
meta {
  name: Get User
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/api/users/{{userId}}
}

tests {
  test("should return 200", function() {
    expect(res.status).to.equal(200);
  });
}

Environment Setup:

{
  "baseUrl": "https://api.example.com",
  "apiKey": "test_key_xxx"
}

</quick_start>

<success_criteria> API testing is successful when:

• All endpoints have at least one happy path test
• Error cases tested (4xx, 5xx responses)
• Response schema validated (not just status codes)
• Environment variables used for all configurable values
• Collections organized by resource/domain
• Authentication flows tested end-to-end
• CI pipeline runs collections on every PR
• Test data is reproducible (fixtures or dynamic generation) </success_criteria>

<tool_comparison>

Postman vs Bruno

When to Use Each

Choose Postman when:

• Team needs real-time collaboration
• API documentation is primary output
• Mock servers needed for frontend dev
• Complex OAuth flows with token refresh

Choose Bruno when:

• Git-native workflow preferred
• Privacy/self-hosting required
• Simpler test scenarios
• Developers prefer code-like syntax </tool_comparison>

<collection_organization>

Collection Structure

Folder Hierarchy

my-api-tests/
├── auth/
│   ├── login.bru
│   ├── refresh-token.bru
│   └── logout.bru
├── users/
│   ├── create-user.bru
│   ├── get-user.bru
│   ├── update-user.bru
│   └── delete-user.bru
├── orders/
│   ├── create-order.bru
│   ├── get-orders.bru
│   └── cancel-order.bru
├── environments/
│   ├── local.bru
│   ├── staging.bru
│   └── production.bru
└── collection.bru

Naming Conventions

Request Ordering

Use sequence numbers for dependent requests:

1. auth/login.bru          (seq: 1)
2. users/create-user.bru   (seq: 2) - needs auth token
3. users/get-user.bru      (seq: 3) - uses created user ID

</collection_organization>

<test_patterns>

Test Assertion Patterns

See reference/test-design.md for full assertion patterns with Postman and Bruno examples. </test_patterns>

<environment_management>

Environment Management

Variable scope (Postman): Global → Collection → Environment → Data → Local (highest priority).

Use environment files for baseUrl, apiKey per env (local/staging/production). Chain requests by saving response values (pm.environment.set("authToken", json.accessToken)) for use in subsequent requests.

See reference/data-management.md for environment file formats, dynamic variables, and request chaining patterns. </environment_management>

<authentication_testing>

Authentication Testing

Always test: 401 without token, 403 with wrong role.

See reference/postman-patterns.md for OAuth 2.0 refresh flow and auth failure test patterns. </authentication_testing>

<error_testing>

Error Response Testing

Test each error class: 400 (validation errors with details array), 404 (not found), 429 (rate limit headers present), 5xx (has requestId).

See reference/test-design.md for error response assertion patterns. </error_testing>

<ci_integration>

CI/CD Integration

Integrate via GitHub Actions: install CLI, run collection, upload HTML report as artifact. Use ${{ secrets.* }} for sensitive env vars.

See reference/ci-integration.md for GitHub Actions workflow, reporters, and secrets handling. </ci_integration>

<data_management>

Test Data Management

Use data files (newman run -d test-data.json) for iteration-based testing. Postman has built-in dynamic variables ({{$guid}}, {{$randomEmail}}, {{$timestamp}}). Add cleanup scripts in post-request to delete created resources.

See reference/data-management.md for data file formats, dynamic generation, and cleanup patterns. </data_management>

Before creating collection:

• API documentation reviewed
• Authentication method identified
• Base URLs for all environments defined
• Test data strategy determined

For each endpoint:

• Happy path test (expected input, expected output)
• Required field validation (400 errors)
• Authentication test (401 without token)
• Authorization test (403 wrong permissions)
• Not found test (404 invalid ID)
• Response schema validated
• Response time asserted

Collection organization:

• Requests grouped by resource
• Sequence numbers for dependent requests
• Environments for local/staging/production
• Sensitive values marked as secrets

CI integration:

• Newman/Bruno CLI configured
• GitHub Actions workflow created
• Test reports uploaded as artifacts
• Secrets stored in CI environment </checklist>

To load: Ask for the specific topic or check if context suggests it. </references>

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-api-testing.json:

{"ts":"[UTC ISO8601]","skill":"api-testing","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"tests_created":[n],"endpoints_tested":[n],"assertions_written":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.