Skip to content

About

REST API test suite in TypeScript with Jest, SuperTest and Zod schema checks, JUnit/HTML reports and nightly CI

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

API Testing Suite

API Tests License: MIT Node.js TypeScript Docker

REST API testing suite built with SuperTest, Jest and Zod schema validation. Targets the DummyJSON API as a reference implementation.


Table of Contents


Why?

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.each for 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

Demo

$ 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.


Quick Start

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

Architecture

┌─────────────────────────────────────────────────────┐
│                   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)       │
└─────────────────────────────────────────────────────┘

Stack

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

Test Coverage

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

Key Patterns

Schema Validation with Zod

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 failure

Data-Driven Tests

it.each(VALID_USER_IDS)('should return user %i', async (id) => {
  const res = await apiClient.get(`/users/${id}`);
  expect(res.status).toBe(200);
});

Factory Pattern with createApiClient()

const apiClient = createApiClient(); // each test suite gets its own isolated client
apiClient.withToken(token).enableRetry().enableLogging();

Retry with Exponential Backoff

const client = createApiClient().enableRetry({ attempts: 3, baseDelay: 500 });
// Retries on 5xx and network errors; never retries 4xx (expected in tests)

Request Logging

const client = createApiClient().enableLogging();
// Logs to stderr: [API] GET /users → 200 (142ms)

Response Time SLOs

const start = Date.now();
await apiClient.get('/users');
assertResponseTime(start, 500); // fails if > 500ms

CI/CD Integration

The GitHub Actions workflow:

  1. Runs lint, format, type check on every push/PR
  2. Executes all 88 tests on Node 24
  3. Uploads HTML + JUnit reports as artifacts
  4. Nightly scheduled run at 1 AM UTC

Set credentials as repository secrets:

  • TEST_PASSWORD

Project Structure

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

Development

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  # Prettier

License

MIT


Built by Quvantic

About

REST API test suite in TypeScript with Jest, SuperTest and Zod schema checks, JUnit/HTML reports and nightly CI

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages