ometere123/the-skills-bible/api-testing-engineer

API Testing Engineer

Purpose

Verify API behaviour beyond schema validity, including durable outcomes, permissions, retries, and consumer expectations.

Use this skill when

• An API needs functional and negative testing.
• Schema checks pass but semantic defects remain.
• Authentication, pagination, concurrency, or error behaviour needs validation.
• API versions and consumers must remain compatible.

Do not use this skill as the primary workflow when

• The task is API design.
• The primary need is performance load testing.
• The request seeks unauthorised testing of third-party APIs.

Required inputs

• API specification and business semantics.
• Identity, roles, tenants, and resources.
• State model and persistence.
• Consumer and version compatibility.
• Rate, timeout, and dependency requirements.

Classify missing information as blocking, important, or optional. Inspect the actual requirements, risks, architecture, code, test suites, environments, data, telemetry, defect history, release process, and supported platforms before asking for information that can be verified directly.

Core operating principles

• Test risks and user outcomes, not implementation details alone.
• Choose the cheapest test level that can provide trustworthy evidence, then retain a small number of realistic end-to-end checks.
• Keep tests deterministic, isolated, observable, maintainable, and proportional to failure consequence.
• Use representative data, environments, concurrency, timing, permissions, devices, and dependency behaviour.
• Verify durable state, externally visible outcomes, and side effects rather than status codes or UI text alone.
• Treat failures, retries, cancellation, partial completion, race conditions, recovery, and degraded operation as normal test scenarios.
• Distinguish product defects, test defects, environment defects, data defects, and expected variation.
• Preserve accessibility, privacy, security, performance, and compatibility while creating test coverage.
• Make quality evidence traceable to requirements, risks, changes, incidents, and release decisions.
• Remove flaky, redundant, low-value, and obsolete tests instead of growing suites without control.

Workflow

1. Define API oracle

• Map operations to business outcomes, state transitions, permissions, and errors.
• Do not rely on schema alone.

2. Test request structure

• Cover methods, paths, headers, content types, encodings, required fields, limits, and malformed payloads.

3. Test response semantics

• Verify status, headers, body, ordering, pagination, links, errors, and side effects.
• Check durable state.

4. Test identity and access

• Exercise unauthenticated, expired, wrong audience, forbidden, cross-tenant, ownership, and role-change cases.

5. Test state transitions

• Cover create, update, delete, duplicate, stale version, invalid sequence, cancellation, and idempotent retry.

6. Test query behaviour

• Verify filtering, sorting, cursor pagination, field selection, search, empty results, and bounded complexity.

7. Test concurrency

• Exercise simultaneous updates, retries, duplicate requests, optimistic conflicts, and rate controls.
• Verify invariants.

8. Test dependency failure

• Inject timeout, partial response, unavailable service, queue delay, and uncertain remote outcome.
• Check retry guidance.

9. Test compatibility

• Validate supported versions, optional and unknown fields, deprecation, and contract consumers.
• Prevent accidental breaking change.

10. Automate and diagnose

• Run at service and deployed levels, capture requests, responses, correlation, traces, and state while redacting secrets.

Decision rules

Required outputs

• API oracle.
• Request tests.
• Response and state tests.
• Identity tests.
• State-transition tests.
• Query tests.
• Concurrency tests.
• Dependency-failure tests.
• Compatibility evidence.
• Automation and diagnostics.

Testing and quality gates

• Risk gate: Test scope maps to credible user, business, data, safety, security, and operational risks.
• Coverage gate: Important rules, workflows, boundaries, platforms, failures, and regressions have evidence.
• Fidelity gate: Test doubles, data, environments, devices, and dependencies are realistic enough for the decision.
• Determinism gate: Time, randomness, identity, concurrency, and external state are controlled where required.
• Isolation gate: Tests do not depend on undocumented order, shared mutable state, or production data.
• Diagnostics gate: A failure identifies the tested outcome, relevant state, environment, release, and evidence.
• Maintenance gate: Duplicated, flaky, obsolete, and low-value tests are removed or repaired.
• Accessibility gate: Testing tools and evidence do not exclude users or ignore assistive technology.
• Release gate: Quality decisions include known gaps, residual risk, rollback, and production monitoring.
• Learning gate: Escaped defects and incidents improve tests, requirements, observability, and design.

Evidence standard

For consequential quality claims, identify the exact requirement or risk, build or release, environment, data, identity, platform, dependency state, test version, and time window. Include repeatable procedures, assertions, logs, traces, screenshots or recordings where appropriate, and known fidelity gaps. Do not claim a feature tested because a script completed without proving the intended outcome.

Failure handling and escalation

Pause or escalate when:

• The expected behaviour, authoritative requirement, or risk acceptance is unclear.
• Testing could alter production data, send real communications, charge money, affect users, or create safety or privacy harm.
• Test environments, identities, or data are not isolated sufficiently.
• A failure may indicate security compromise, data corruption, or active customer impact.
• Release evidence is missing for a critical path.
• Reproduction requires prohibited access, real personal data, or unsafe load.
• Residual quality risk exceeds delegated release authority.

Report the exact blocker, verified state, affected outcomes, evidence, safe options, and smallest required decision.

Common anti-patterns

• Checking status code only.
• Happy-path authenticated admin tests.
• Offset pagination tested with tiny data.
• Raw secrets in test reports.
• Assuming idempotency from repeated success status.
• Ignoring content negotiation.
• Mock server as sole provider evidence.
• Breaking error semantics unnoticed.

Completion checklist

• [ ] Structure and semantics are tested.
• [ ] Permissions cover object and tenant scope.
• [ ] Durable state is asserted.
• [ ] Retries and concurrency are safe.
• [ ] Versions remain compatible.
• [ ] Failures include useful correlation.

Quality evidence record

# Quality Evidence Record
 
## Outcome under test
[Requirement, risk, workflow, or quality attribute]
 
## Scope
[Components, platforms, environments, identities, data, and exclusions]
 
## Test design
[Technique, levels, coverage, oracle, and representative conditions]
 
## Preconditions
[Build, configuration, fixtures, dependencies, permissions, and clocks]
 
## Execution
[Steps, automation, runs, seeds, load, devices, and timing]
 
## Evidence
[Assertions, state, logs, traces, screenshots, recordings, and reports]
 
## Findings
[Defects, test issues, environment issues, and uncertainty]
 
## Residual risk
[Untested areas, fidelity gaps, severity, owner, and acceptance]
 
## Release recommendation
[Proceed, conditionally proceed, block, or monitor]
 
## Follow-up
[Regression tests, fixes, observability, cleanup, and review triggers]

Related skills

• contract-testing-engineer
• integration-testing-specialist
• performance-testing-engineer
• security-testing-engineer

Maintenance rules

Review this skill when product risk, architecture, platforms, test tools, or release processes change; escaped defects reveal a coverage gap; the workflow becomes tied to one vendor; the file approaches 500 lines; or reusable fixtures, generators, models, or validators would improve execution.