A battle-tested API testing architecture built from experience managing 37+ enterprise-grade test suites.
This template distills enterprise-grade API testing patterns into a clean, reusable framework. It demonstrates advanced concepts like:
- Real JWT Authentication Flow: Using DummyJSON's
/auth/loginto show token caching and injection. - Enterprise Pagination: Handling
limit,skip, andtotalmetadata. - Data-Driven Testing: Dynamically generating tests from JSON fixtures.
- Performance SLAs: k6 benchmarks with automated pass/fail thresholds.
To run performance tests, you need k6 installed on your system:
- Windows:
winget install GrafanaLabs.k6 - macOS:
brew install k6 - Linux: See k6 docs
# 1. Install dependencies
npm install
# 2. Run all tests
npm test
# 3. Run specific suites
npm run test:smoke # Critical path only
npm run test:regression # Full CRUD coverage
npm run test:integration # End-to-end flows
npm run test:ddt # Data-driven testsZero external setup required — tests run against DummyJSON, a production-ready mock API.
enterprise-api-template/
├── config/ # Centralized env config (never read process.env directly)
├── helpers/ # ⭐ Reusable infrastructure layer
│ ├── auth.js # Token caching & login flows
│ ├── request.js # Generic HTTP wrapper (GET/POST/PUT/PATCH/DELETE)
│ ├── assertions.js # Status-code assertion helpers
│ ├── data-factory.js # Faker.js dynamic data generation
│ └── cleanup.js # Test teardown utilities
├── fixtures/ # Test data (JSON + YAML flows)
├── tests/
│ ├── smoke/ # Gatekeeper tests — run first in CI
│ ├── regression/ # Full feature coverage per module
│ ├── integration/ # Cross-module end-to-end flows
│ ├── data-driven/ # Fixture-driven parameterized tests
│ └── performance/ # k6 scripts (smoke/load/stress)
├── scripts/ # TestRail sync, Allure report generation
└── .github/workflows/ # CI/CD pipeline
graph LR
A[Test Suite] --> B[helpers/request.js]
A --> C[helpers/assertions.js]
A --> D[helpers/data-factory.js]
B --> E[supertest + config]
C --> E
D --> F[Faker.js]
A --> G[helpers/auth.js]
G --> E
Instead of writing raw supertest calls in every test file, the helper layer provides a consistent, documented API that scales to dozens of modules.
| Suite | File | Tests | What It Covers |
|---|---|---|---|
| 🚬 Smoke | health-check.test.js |
5 | API reachability, response shape |
| 🚬 Smoke | auth.test.js |
6 | Login/register critical paths |
| 🧪 Regression | users.test.js |
16 | Full CRUD lifecycle, edge cases |
| 🧪 Regression | users-search.test.js |
9 | Pagination, filtering, delayed response |
| 🧪 Regression | register.test.js |
8 | Registration validation scenarios |
| 🔗 Integration | user-lifecycle-flow.test.js |
6 | End-to-end multi-step flow |
| 📊 DDT | users-ddt.test.js |
14 | JSON/YAML fixture-driven tests |
| Total | ~64 |
Three profiles with automated SLA thresholds:
| Profile | VUs | Duration | p95 SLA | Error Rate | Use Case |
|---|---|---|---|---|---|
| Smoke | 1 | 30s | < 500ms | 0% | Sanity check |
| Load | 10 | 60s | < 1000ms | < 5% | Baseline capacity |
| Stress | 1→50 | 3.5min | < 2000ms | < 10% | Breaking point |
npm run perf:smoke # Quick sanity check
npm run perf:load # Baseline measurement
npm run perf:stress # Find the limitsRequires k6 installed locally.
npm test # Run tests (generates allure-results/)
npm run report:allure # Generate + open HTML reportnpm run push:testrail:dry # Preview what would be synced
npm run push:testrail # Push test cases to TestRailThis framework includes custom Claude Code Skills to accelerate test development using AI. These skills allow you to generate production-ready test files from OpenAPI specs or declarative flow definitions.
| Skill | Command | Purpose |
|---|---|---|
| Generate Tests | /generate-tests |
Creates tests/generated/*.js from an OpenAPI spec or flows.yaml. |
| Enhance Tests | /enhance-tests |
Adds business-rule coverage and negative scenarios to existing test files. |
| Generate Flows | /generate-flows |
(Optional) Scaffolds flow definitions from project requirements or tickets. |
- Define the Flow: Describe a multi-step user journey in
api/flows.yaml. - Generate Code: Run
/generate-tests --flows api/flows.yaml. - Refine: Run
/enhance-tests tests/generated/new-feature.jsto add edge cases. - Verify: Run the generated Mocha tests normally.
[!TIP] These skills are optimized for this framework's helper patterns (
helpers/request.js,helpers/assertions.js), ensuring that AI-generated code is indistinguishable from human-written code.
The GitHub Actions workflow implements a smoke-gated pipeline:
graph TD
A[Push / PR] --> B[🚬 Smoke Tests]
B -->|Pass| C[🧪 Regression]
B -->|Pass| D[🔗 Integration]
B -->|Pass| E[📊 Data-Driven]
C & D & E --> F[📊 Allure Report Upload]
B -->|Fail| G[❌ Pipeline Stops]
If smoke tests fail, the entire pipeline stops — no wasted CI minutes on tests that can't possibly pass.
| Pattern | Where | Why It Matters |
|---|---|---|
| Token Caching | helpers/auth.js |
Avoid 37+ redundant login calls per run |
| Centralized HTTP Wrapper | helpers/request.js |
One change = all suites updated |
| Assertion Library | helpers/assertions.js |
Consistent error validation across modules |
| Dynamic Data Factory | helpers/data-factory.js |
Zero hardcoded data, true test isolation |
| Data-Driven Testing | fixtures/*.json + tests/data-driven/ |
Scale to 100s of scenarios via config |
| YAML Flow Definitions | api/*.yaml |
Declarative multi-step test workflows |
| Smoke-Gated CI | .github/workflows/ |
Fast feedback, no wasted resources |
| Performance SLAs | tests/performance/lib/thresholds.js |
Automated pass/fail for latency budgets |
| TestRail Integration | scripts/push-to-testrail.js |
Automated test management sync |
Vidhya Sasidharan — Senior QA Engineer | AI Quality Specialist
- 🌍 Dubai, UAE
- 💼 10+ years in Quality Engineering
- 🧪 37+ enterprise API test suites managed
- 🤖 Pioneering AI-assisted QA workflows
MIT — Use this template as a foundation for your own API testing projects.