REST API testing suite built with SuperTest, Jest and Zod schema validation. Targets the DummyJSON API as a reference implementation.
- Why?
- Demo
- Quick Start
- Architecture
- Stack
- Test Coverage
- Key Patterns
- CI/CD Integration
- Project Structure
- Development
API testing requires more than just status code checks. This suite demonstrates:
- Schema validation via Zod — catch contract breaks before they hit production
- Contract tests — headers, schemas, and response time SLOs in one suite
- Data-driven tests —
it.eachfor parameterized scenarios - Full CRUD coverage — GET, POST, PUT, PATCH, DELETE
- Auth flow — token extraction and reuse across test suites
- Reusable assertion helpers with descriptive error messages
$ npm test
PASS tests/users.test.ts
PASS tests/products.test.ts
PASS tests/edge-cases.test.ts
PASS tests/contracts.test.ts
PASS tests/search.test.ts
PASS tests/auth.test.ts
PASS tests/client.test.ts
PASS tests/schemas.test.ts
Test Suites: 8 passed, 8 total
Tests: 88 passed, 88 total
88 tests: 75 live tests against DummyJSON (auth, users and products CRUD, search, edge cases, contracts, headers, SLOs, client behaviour) plus 13 offline tests that prove the schemas and assertion helpers reject bad data.
git clone https://github.com/mustafaautomation/api-testing-suite.git
cd api-testing-suite
npm install
cp .env.example .env
# Run all tests
npm test
# Run specific suite
npm run test:auth
npm run test:users
npm run test:contracts
# With coverage
npm run test:coverage┌─────────────────────────────────────────────────────┐
│ Test Suites │
│ auth │ users │ contracts │ client (unit) │
├─────────────────────────────────────────────────────┤
│ Shared Layer │
│ ApiClient │ Assertions │ Schemas │ Test Data │
├─────────────────────────────────────────────────────┤
│ SuperTest + Zod │
│ HTTP assertions + schema validation │
├─────────────────────────────────────────────────────┤
│ Target API │
│ DummyJSON (https://dummyjson.com) │
└─────────────────────────────────────────────────────┘
| Tool | Purpose |
|---|---|
| SuperTest | HTTP assertions |
| Jest 30 | Test runner + HTML/JUnit reporters |
| Zod 4 | Schema validation |
| TypeScript 6.0 on Node.js 24 | Type safety |
| GitHub Actions | CI pipeline with nightly schedule |
| DummyJSON | Target REST API |
| Suite | Tests | What it covers |
|---|---|---|
auth.test.ts |
4 | Login, error states, missing fields |
users.test.ts |
15 | CRUD, pagination, data-driven, 404 handling |
products.test.ts |
15 | Products CRUD, categories, pagination |
search.test.ts |
8 | User and product search and filters |
edge-cases.test.ts |
11 | Pagination boundaries, invalid endpoints, concurrent requests, body validation |
contracts.test.ts |
15 | Schemas, headers, SLOs, status codes |
client.test.ts |
7 | ApiClient factory, chaining, retry, logging |
schemas.test.ts |
13 | Offline: schemas and helpers reject malformed payloads, name the failing field |
| Total | 88 |
const UserSchema = z.object({
id: z.number().positive(),
firstName: z.string().min(1),
email: z.string().email(),
image: z.string().url(),
});
assertSchema(UserSchema, res.body); // throws with descriptive error on failureit.each(VALID_USER_IDS)('should return user %i', async (id) => {
const res = await apiClient.get(`/users/${id}`);
expect(res.status).toBe(200);
});const apiClient = createApiClient(); // each test suite gets its own isolated client
apiClient.withToken(token).enableRetry().enableLogging();const client = createApiClient().enableRetry({ attempts: 3, baseDelay: 500 });
// Retries on 5xx and network errors; never retries 4xx (expected in tests)const client = createApiClient().enableLogging();
// Logs to stderr: [API] GET /users → 200 (142ms)const start = Date.now();
await apiClient.get('/users');
assertResponseTime(start, 500); // fails if > 500msThe GitHub Actions workflow:
- Runs lint, format, type check on every push/PR
- Executes all 88 tests on Node 24
- Uploads HTML + JUnit reports as artifacts
- Nightly scheduled run at 1 AM UTC
Set credentials as repository secrets:
TEST_PASSWORD
api-testing-suite/
├── .github/
│ ├── workflows/api-tests.yml # CI pipeline with nightly schedule
│ ├── dependabot.yml # Automated dependency updates
│ ├── CODEOWNERS # Review ownership
│ └── pull_request_template.md # PR checklist
├── src/
│ ├── client/
│ │ └── ApiClient.ts # Reusable HTTP client with auth
│ ├── config/
│ │ └── env.ts # Centralized environment config
│ ├── schemas/
│ │ ├── user.schema.ts # Zod schemas for user endpoints
│ │ └── auth.schema.ts # Zod schemas for auth endpoints
│ ├── data/
│ │ └── testData.ts # Test credentials and payloads
│ └── utils/
│ └── assertions.ts # Schema, SLO, header assertions
├── tests/
│ ├── auth.test.ts # Login, register, error handling
│ ├── users.test.ts # Full CRUD + data-driven tests
│ ├── products.test.ts # Products CRUD and categories
│ ├── search.test.ts # Search and filters
│ ├── edge-cases.test.ts # Boundaries and error handling
│ ├── contracts.test.ts # Schema, headers, SLO validation
│ ├── client.test.ts # ApiClient unit tests
│ └── schemas.test.ts # Offline negative schema/helper tests
├── CONTRIBUTING.md
├── SECURITY.md
├── Dockerfile
└── .dockerignore
git clone https://github.com/mustafaautomation/api-testing-suite.git
cd api-testing-suite
npm install
cp .env.example .env
npm test # Run all API tests
npm run test:ci # Run tests in CI mode (--runInBand --forceExit)
npm run typecheck # Type checking
npm run lint # ESLint
npm run format:check # PrettierMIT
Built by Quvantic