fast-api-tester 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-api-tester",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Ultra-fast, connection-pooled API testing library for Node.js",
   "type": "module",
   "main": "./dist/index.js",

package/readme

@@ -0,0 +1,166 @@
+# ⚡ fast-api-tester
+
+> A lightweight, zero-overhead API testing engine built for high-performance Node.js environments.
+
+[![npm version](https://img.shields.io/npm/v/fast-api-tester.svg)](https://www.npmjs.com/package/fast-api-tester)
+[![license](https://img.shields.io/npm/l/fast-api-tester.svg)](https://github.com/your-username/fast-api-tester/blob/main/LICENSE)
+
+`fast-api-tester` provides a clean, framework-agnostic client to run fast HTTP assertions against REST APIs. Designed with connection pooling and low-latency execution in mind, it works seamlessly with **Vitest**, **Jest**, or Node's native **`node:assert`**.
+
+---
+
+## 📦 Installation
+
+Install `fast-api-tester` using your preferred package manager:
+
+```bash
+# npm
+npm install fast-api-tester
+
+# pnpm
+pnpm add fast-api-tester
+
+# yarn
+yarn add fast-api-tester
+```
+
+For TypeScript projects, also install execution tools or test runners as development dependencies:
+
+```bash
+npm install -D vitest typescript @types/node
+```
+
+---
+
+## 🚀 Quick Start
+
+### Option A: Using Vitest (Recommended)
+
+1. Ensure `"type": "module"` is in your `package.json`:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "test": "vitest run"
+  }
+}
+```
+
+2. Create a test file at `tests/api.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { ApiEngine } from 'fast-api-tester';
+
+describe('JSONPlaceholder API Test Suite', () => {
+  let api: ApiEngine;
+
+  beforeAll(() => {
+    api = new ApiEngine();
+    api.setBaseUrl('https://jsonplaceholder.typicode.com');
+  });
+
+  afterAll(async () => {
+    // Clean up socket connection pools
+    await api.destroy();
+  });
+
+  it('GET /posts/1 - should fetch post details', async () => {
+    const res = await api.get('/posts/1');
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toHaveProperty('id', 1);
+    expect(res.latencyMs).toBeGreaterThan(0);
+  });
+
+  it('POST /posts - should create a new post', async () => {
+    const payload = {
+      title: 'Fast API Testing',
+      body: 'Testing with fast-api-tester',
+      userId: 1,
+    };
+
+    const res = await api.post('/posts', payload);
+
+    expect(res.statusCode).toBe(201);
+    expect(res.body).toMatchObject(payload);
+  });
+});
+```
+
+3. Run your tests:
+
+```bash
+npm test
+```
+
+### Option B: Standalone Script (Zero Runner Setup)
+
+If you don't want to use a runner like Vitest or Jest, run a script directly using `tsx` and Node's native `assert`:
+
+```typescript
+// run-tests.ts
+import assert from 'node:assert/strict';
+import { ApiEngine } from 'fast-api-tester';
+
+const api = new ApiEngine();
+api.setBaseUrl('https://jsonplaceholder.typicode.com');
+
+async function run() {
+  try {
+    console.log('⚡ Running API assertions...');
+
+    const res = await api.get('/posts/1');
+    assert.equal(res.statusCode, 200, 'Expected status code 200');
+
+    console.log(`✅ Success! Response status: ${res.statusCode} (${res.latencyMs}ms)`);
+  } catch (err) {
+    console.error('❌ Test failed:', err);
+  } finally {
+    await api.destroy();
+  }
+}
+
+run();
+```
+
+Run it instantly:
+
+```bash
+npx tsx run-tests.ts
+```
+
+---
+
+## 🛠️ API Reference
+
+### `new ApiEngine(options?)`
+
+Creates a new instance of the HTTP engine.
+
+- `setBaseUrl(url: string)`: Sets the default host URL for all relative request paths.
+- `get(path, headers?)`: Executes an HTTP `GET` request.
+- `post(path, body?, headers?)`: Executes an HTTP `POST` request.
+- `put(path, body?, headers?)`: Executes an HTTP `PUT` request.
+- `delete(path, headers?)`: Executes an HTTP `DELETE` request.
+- `destroy()`: Gracefully closes active network sockets and releases resources.
+
+### Response Object Structure
+
+All HTTP methods return a uniform response structure:
+
+```typescript
+{
+  statusCode: number;   // e.g., 200, 201, 404
+  body: any;            // Parsed JSON response payload
+  headers: Record<string, string | string[]>; // Response headers
+  latencyMs: number;    // Round-trip duration in milliseconds
+}
+```
+
+---
+
+## 📜 License
+
+[MIT](./LICENSE) © Kushan Amarasiri