APIT - API Testing Framework for TypeScript

APIT is a lightweight, fully-typed API testing framework built with TypeScript. It allows you to define API services, write tests with dynamic data flows, and generate test reports including Mermaid diagrams.

🚀 Installation

npm install apit-core

If using the CLI (coming soon):

npm install -g apitcli

💼 Features

• Define reusable services for any API endpoint
• Write tests with dynamic param injection and assertions
• Create flows of test cases for end-to-end scenarios
• Generate Markdown and Mermaid diagrams for reports
• Full TypeScript support for request/response types

⚡ Quick Start

1. Define API services

export const serviceSignUp = APIT.createService<SignUpRequest, SignUpResponse>({
  id: "SIGN_UP",
  endpoint: "http://localhost:4000/auth/sign-up",
  method: HttpMethod.POST,
});

export const serviceVerifyEmail = APIT.createService<
  void,
  void,
  { tokenVerification: string }
>({
  id: "VERIFY_EMAIL",
  endpoint: "http://localhost:4000/auth/verify-user-email/{tokenVerification}",
  method: HttpMethod.GET,
});

2. Create test cases

export const signUpTestService = APIT.createTest({
  id: "SIGN_UP",
  service: serviceSignUp,
  body: { email, password, username },
  expects: (res) => {
    expect(res).toHaveProperty("tokenVerification");
    expect(res).toHaveProperty("id");
  },
});

export const verifyEmailTestService = APIT.createTest({
  id: "VERIFY_EMAIL",
  service: serviceVerifyEmail,
  params: {
    tokenVerification: () =>
      signUpTestService.response?.tokenVerification || "",
  },
  expects: () => {},
});

3. Execute a flow

const apit = new APITCore();
const flow = APIT.createFlow("FULL_FLOW", [
  signUpTestService,
  verifyEmailTestService,
]);

apit.add(flow);
await apit.run();
await apit.generateReportMermaid();

📁 Project Structure

apit-tests/
├── src/
│   └── services.ts       # Your API service definitions
├── tests/
│   ├── specs.ts          # Reusable test cases
│   └── flows.ts          # Combine test cases into flows
└── test-report.md        # Markdown execution report (autogenerated)

📊 Reports

After running, APIT will generate:

• test-report.md – Full request/response logs
• mermaid-test-report.md – Execution flow diagram in Mermaid

Example:

graph LR
SIGN_UP --> VERIFY_EMAIL
style SIGN_UP fill:#389B35
style VERIFY_EMAIL fill:#389B35

✅ Why APIT?

• 🔐 Full TypeScript type safety
• 🔀 Reuse services across tests
• 🤪 Clear test structure with expectations
• ⚡ Dynamic params from previous tests
• 📄 Mermaid + Markdown reports out of the box

💼 More Examples

Using dynamic values from prior tests in path, body or headers:

export const signInTestService = APIT.createTest({
  id: "SIGN_IN",
  service: serviceSignIn,
  body: {
    email,
    password,
    mfaCode: "{mfaCode}",
  },
  params: {
    mfaCode: () => getMfaCodeTestService.response?.tokenMfa || "",
  },
  expects: (result) => {
    expect(result).toHaveProperty("credentials");
    expect(result.credentials).toHaveProperty("token");
  },
});

Replacing headers dynamically:

headers: {
  Authorization: "Bearer {token}"
},
params: {
  token: () => signInTestService.response?.credentials.token || "",
},

Interpolating values from arrays:

params: {
  id: () => getListItems.response?.[0].id || ""
},
endpoint: "http://localhost:4000/items/{id}"

No-body request:

export const healthCheck = APIT.createTest({
  id: "HEALTH_CHECK",
  service: APIT.createService<void, { status: string }>({
    id: "HEALTH",
    endpoint: "http://localhost:4000/health",
    method: HttpMethod.GET,
  }),
  expects: (res) => {
    expect(res.status).toBe("ok");
  },
});

💪 CLI (Planned)

apitcli start   # Create starter files
apitcli run     # Run all test flows

🚧 License

MIT © 2024