# API Test Plan Template

Source: https://totalshiftleft.ai/blog/api-test-plan-template (Total Shift Left). Free to copy and adapt.

How to use: replace everything in [brackets], delete rows that don't apply, commit this file next to the API's OpenAPI spec and review it with development and product before testing starts.


Replace everything in `[brackets]`. Delete rows that don't apply rather than writing "N/A" everywhere.

## 1. Document control and objectives

| Field | Value |
|---|---|
| API and version | [Orders API v2.3] |
| Spec location | [repo/path/openapi.yaml @ commit or tag] |
| Release or milestone | [Release 2026.11] |
| Test lead | [Name] |
| Approvers | [Engineering lead, Product owner] |
| Objectives | [e.g. Verify new refund endpoints; no regression on v2.2 behaviour; p95 latency within SLO] |
| Plan version and date | [1.0, YYYY-MM-DD] |

## 2. Scope

| Item | In scope | Out of scope | Notes |
|---|---|---|---|
| Operations | [All operations tagged `orders`, `refunds`] | [`/admin/*`] | [Admin covered by separate plan] |
| API versions | [v2.3; v2.2 for backward compatibility] | [v1 (retired)] | |
| Protocols | [REST/JSON] | [Legacy SOAP endpoint] | |
| Consumers | [Web app, mobile app, partner X] | | [Partner contract tests required] |
| Integrations | [Payments provider sandbox, email service mock] | [Live payments] | |
| Test types | [Functional, contract, integration, regression, performance, security] | [Usability] | |

## 3. Test approach by level

| Level | What it checks | How (tool or method) | Owner | When it runs |
|---|---|---|---|---|
| Contract / schema | Responses match the OpenAPI spec; breaking changes blocked | [Generated from spec] | [Dev] | Every PR |
| Functional | Status codes, business rules, validation, errors, state changes | [pytest / REST Assured / generated suite] | [QA] | Every PR |
| Integration | Calls across services, databases, queues | [Docker Compose / staging] | [QA + Dev] | Merge to main |
| Regression | Previously working behaviour still works | [Full functional + contract suite] | [QA] | Nightly and pre-release |
| Performance | Latency, throughput, error rate under load | [k6 / JMeter / platform add-on] | [Perf engineer] | Pre-release |
| Security | OWASP API Top 10 risks, auth, rate limits | [DAST / security checks] | [AppSec] | Pre-release and weekly |
| Exploratory | Unscripted sessions on new features | [Charters, timeboxed] | [QA] | Per feature |

## 4. Environments

| Environment | URL | Data | Dependencies | Who can deploy | Use |
|---|---|---|---|---|---|
| Local | [localhost:8080] | Seeded fixtures | Mocks | Developer | Unit, contract, functional |
| CI ephemeral | [per-PR URL] | Seeded on start | Mocks + containers | Pipeline | PR gates |
| Staging | [https://staging.example.com] | Masked copy, refreshed [weekly] | Sandboxes | Release pipeline | Integration, regression, performance |
| Production | [https://api.example.com] | Real | Real | Release manager | Smoke and monitoring only |

## 5. Entry and exit criteria

| Type | Criterion | Measured by |
|---|---|---|
| Entry | Spec for the release merged and linted with no errors | Linter job |
| Entry | Build deployed to staging and smoke suite green | CI job |
| Entry | Test data and accounts for every role available | Checklist |
| Exit | 100% of planned critical and high-priority tests executed | Test report |
| Exit | No open critical or high defects, or each waived in writing by [approver] | Defect tracker |
| Exit | Every in-scope operation has at least one positive and one negative test | Coverage report |
| Exit | Contract tests green against the published spec | CI job |
| Exit | p95 latency ≤ [300 ms] and error rate ≤ [0.1%] at [200] requests per second | Performance report |
| Exit | No new high or critical security findings | Security report |
| Suspend | Smoke suite failing or environment down for more than [4 hours] | On-call |

## 6. Risk register

Score likelihood and impact from 1 to 3; multiply for priority. Test the highest scores first and deepest.

| ID | Risk | Likelihood | Impact | Score | Mitigation (tests) |
|---|---|---|---|---|---|
| R1 | Refund amount calculated wrongly | 2 | 3 | 6 | Decision-table tests on refund rules; reconciliation check |
| R2 | Breaking change for mobile app | 2 | 3 | 6 | Contract tests on every PR; consumer tests for mobile |
| R3 | Customer reads another customer's order | 1 | 3 | 3 | Two-user authorization tests on every `{id}` operation |
| R4 | Latency spike under month-end load | 2 | 2 | 4 | Load test at 2× expected peak |
| R5 | Payments sandbox unavailable | 3 | 1 | 3 | Mock payments provider for PR gates |

## 7. Coverage targets

| Dimension | Target | Notes |
|---|---|---|
| Operations with at least one test | 100% | From the spec |
| Operations with positive and negative tests | 100% | |
| Documented status codes asserted | [≥ 90%] | |
| Required fields with a "missing" test | 100% | |
| Field constraints (`min`/`max`, `pattern`, `enum`) with a boundary test | [≥ 80%] | |
| Requirements with at least one linked test | 100% | Traceability matrix |
| Risks scored 6 or more with a dedicated test | 100% | From section 6 |


## 8. Test data

| Data set | Source | Refresh | Owner | Sensitive data handling |
|---|---|---|---|---|
| Customer accounts for each role | Seed script | Every run | QA | Synthetic only |
| Product catalogue | Masked production subset | Weekly | Data team | Masked, no PII |
| Payment cards | Provider's published test numbers | Static | QA | Never real cards |
| Boundary and negative values | Generated from spec | Every run | QA | n/a |


## 9. Tools

| Purpose | Tool | Version or plan | Owner |
|---|---|---|---|
| Spec linting | [Spectral] | [x.y] | Dev |
| Functional and contract tests | [pytest / REST Assured / Shift-Left API] | | QA |
| Mocks | [WireMock / Prism / platform mock server] | | Dev |
| Performance | [k6 / JMeter] | | Perf |
| Security | [ZAP / security add-on] | | AppSec |
| Test management | [Jira + Xray / Azure Test Plans / TestRail] | | QA |
| CI | [GitHub Actions / Jenkins / Azure DevOps] | | DevOps |

## 10. CI quality gates

| Stage | Trigger | Jobs | Blocks | Time budget |
|---|---|---|---|---|
| Pull request | Every push | Lint spec, contract tests, functional smoke | Merge | [≤ 10 min] |
| Merge to main | Merge | Full functional, integration | Deploy to staging | [≤ 30 min] |
| Nightly | Schedule | Full regression, security checks | Next day's release | [≤ 2 h] |
| Pre-release | Release tag | Performance, security, exit-criteria report | Production deploy | [≤ 4 h] |

## 11. Reporting and defects

| Item | Value |
|---|---|
| Run results | [JUnit XML in CI; dashboard link] |
| Daily status | [Channel / time] |
| Defect tracker | [Jira project / board] |
| Severity definitions | Critical: data loss, security breach or outage. High: core flow broken, no workaround. Medium: workaround exists. Low: cosmetic. |
| Test summary report | At exit: scope tested, results, open defects, waivers, risks remaining |

## 12. Roles and schedule

| Role | Name | Responsibilities |
|---|---|---|
| Test lead | [Name] | Plan, report, sign-off recommendation |
| QA engineers | [Names] | Design, automate, execute |
| Developers | [Names] | Unit and contract tests, fixes |
| Product owner | [Name] | Accept risk waivers, approve exit |

| Milestone | Date |
|---|---|
| Plan approved | [YYYY-MM-DD] |
| Test complete | [YYYY-MM-DD] |
| Go/no-go | [YYYY-MM-DD] |

## Appendix: one-page API test strategy

| Area | Your standard |
|---|---|
| Source of truth | [Every API has an OpenAPI spec in its repo; tests are planned from it] |
| Test levels | [Contract, functional, integration, regression, performance, security] |
| Automation policy | [All functional and contract tests automated; manual only for exploratory] |
| Where tests run | [PR: contract + smoke; main: full; nightly: regression + security; release: performance] |
| Definition of done | [New operation ships with positive, negative and boundary tests and an updated spec] |
| Test data policy | [Synthetic by default; masked production data only in staging; no real PII in CI] |
| Environments | [Ephemeral per PR; shared staging; production smoke only] |
| Quality gates | [No merge on red contract tests; no release with open critical or high defects] |
| Metrics | [Operation coverage, escaped defects, flaky-test rate, time to feedback] |
| Tooling | [Approved tools per purpose] |
| Ownership | [Teams own tests for their APIs; QA owns standards and shared tooling] |


## Change log

| Version | Date | Author | Change |
|---|---|---|---|
| 1.0 | [YYYY-MM-DD] | [Name] | First version |