fast-api-tester 1.0.12 → 1.0.14

package/package.json

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

package/readme

@@ -187,8 +187,78 @@ Every execution run updates `test-report.html` and persists historical execution
 - **Historical Execution Trend**: Stacked bar chart visualizing test pass/fail trends over time across consecutive heartbeats.
 - **Detailed Table View**: Complete summary including HTTP Method, Endpoint, Status Code, Measured Latency, SLA Target, and exact error stack/messages for failing requests.
 
+### 🐌 Bandwidth Throttling Simulator
+
+Test your API's resilience and SLA assertions under real-world network conditions. The bandwidth simulator introduces precise artificial latency to mimic poor connections, ensuring your timeouts and SLA limits are truly battle-tested before hitting production.
+
+**Available Profiles:**
+
+- `Slow-3G`: 500ms delay
+- `3G`: 300ms delay
+- `4G`: 100ms delay
+- `None`: 0ms delay (Default)
+- Custom: Pass any raw `number` to simulate exact millisecond latency.
+
+**Example Usage:**
+
+```typescript
+import { ApiEngine } from './index';
+
+// Initialize the engine with a 3G network profile (adds 300ms artificial delay)
+const api = new ApiEngine()
+  .setBaseUrl('https://api.example.com')
+  .simulateNetwork('3G');
+
+api.startHeartbeat(async () => {
+  const res = await api.get('/health');
+
+  // If the server takes 250ms to respond, total measured latency will be 550ms.
+  // This helps ensure your application handles degraded network states gracefully.
+  res.expectLatencyUnder(500);
+});
+```
+
+### ⚖️ Assertion Modes (Hard vs. Soft)
+
+The framework supports two distinct validation behaviors to give you maximum flexibility when testing APIs:
+
+- **Hard Assertions (Default)**: Designed for strict control flows where subsequent steps depend entirely on the success of the current step. When a hard assertion fails (e.g., unexpected status code or SLA violation), it immediately records the failure, updates the test execution record, and throws a fatal `Error` that aborts the test suite execution instantly.
+- **Soft Assertions**: Designed for comprehensive test reporting where you want to execute an entire suite or multiple checks without stopping at the first error. When a soft assertion fails, it logs a warning, flags the failure in the test record, and continues test execution. This ensures all endpoints are tested and included in the final HTML report and telemetry history, rather than failing fast.
+
+#### How the Implementation Works
+
+**1. Configuration & Mode State (`AssertionMode`)**
+
+- **Global Level**: You can configure the engine-wide default behavior using `engine.setAssertionMode('soft')` or `'hard'`. Every request made through the engine inherits this baseline mode.
+- **Inline Level**: You can override the mode on a per-response chain using `.soft()` or `.hard()` right before your assertions.
+
+**2. Centralized Error Handling (`handleAssertionFailure`)**
+
+Instead of directly throwing errors inside every expectation method, assertions pass their failure message to a centralized handler:
+
+- It updates the `TestExecutionRecord` by setting `passed = false` and appends the error message.
+- If the mode is `'hard'`, it throws an `Error` immediately.
+- If the mode is `'soft'`, it catches/bypasses the throw, logs a warning message to the console (`console.warn`), and allows the script execution to proceed normally.
+
+```typescript
+const engine = new ApiEngine()
+  .setBaseUrl('https://api.example.com')
+  .setAssertionMode('soft'); // Make all requests log failures but continue
+
+await engine.startHeartbeat(async () => {
+  // Even if this fails (e.g., latency > 50ms), execution continues!
+  await engine.get('/users').then(res => res.expectStatusOk().expectLatencyUnder(50));
+
+  // This request STILL executes and gets recorded in the HTML report
+  await engine.get('/orders').then(res => res.expectStatus(200));
+
+  // Abort suite hard AT THE END if any soft assertions failed above
+  engine.assertAll();
+});
+```
+
 ---
 
 ## 📜 License
 
-[MIT](./LICENSE) © Kushan Amarasiri
+[MIT](./LICENSE) © Kushan Amarasiri