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

``bash
npm install apit-core
`

If using the CLI (coming soon):

`bash
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

$3

`ts
export const serviceSignUp = APIT.createService({
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,
});
`

$3

`ts
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

`ts
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:

`mermaid
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

$3

`ts
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");
},
});
`

$3

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

$3

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

$3

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

---

💪 CLI (Planned)

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

---

🚧 License

MIT © 2024