@thalorlabs/api-test-suite 1.0.0

package/.prettierrc

@@ -0,0 +1 @@
+"@thalorlabs/eslint-plugin-dev-config/prettier"

package/CLAUDE.md

@@ -0,0 +1,22 @@
+# @thalorlabs/api-test-suite
+
+## What this repo is
+
+Standardised integration test suite for ThalorLabs microservices. Provides `runStandardApiTests()` which generates the 90% of tests every MS needs — routing, auth, health, error contract.
+
+## Build & publish
+
+```bash
+npm run build      # tsc → dist/
+npm version patch  # or minor/major
+npm publish --access public
+```
+
+## What it tests
+
+- Route exists and returns expected status with valid auth
+- Unknown routes return 404
+- Missing/wrong/empty API key returns 401
+- GET /health and GET /alive return 200 without auth
+- Error responses include status field, no stack traces leaked
+- Response is JSON

package/README.md

@@ -0,0 +1,43 @@
+# @thalorlabs/api-test-suite
+
+Standardised integration tests for ThalorLabs microservices. One function call gives you the 90% of tests every MS needs.
+
+## Installation
+
+```bash
+npm install -D @thalorlabs/api-test-suite
+```
+
+## Usage
+
+```typescript
+import { runStandardApiTests } from '@thalorlabs/api-test-suite';
+import { app } from '../src/index';
+
+runStandardApiTests({
+  app,
+  route: '/api/v1/jokes',
+  method: 'GET',
+  validApiKey: 'test-api-key',
+});
+```
+
+## What it tests
+
+| Category | Tests |
+|----------|-------|
+| **Routing** | Route returns expected status, unknown routes return 404, response is JSON |
+| **Authentication** | Missing key → 401, wrong key → 401, empty key → 401 |
+| **Health** | GET /health returns 200 without auth, GET /alive returns 200 |
+| **Error contract** | Error responses include status field, no stack traces leaked |
+
+## Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `app` | Express | required | The Express app instance |
+| `route` | string | required | Route to test (e.g. '/api/v1/jokes') |
+| `method` | string | 'GET' | HTTP method |
+| `validApiKey` | string | required | Valid API key for auth tests |
+| `requiresAuth` | boolean | true | Whether the route requires auth |
+| `expectedStatus` | number | 200 | Expected success status code |

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { runStandardApiTests } from './standardTests';
+export type { StandardApiTestConfig } from './standardTests';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStandardApiTests = void 0;
+var standardTests_1 = require("./standardTests");
+Object.defineProperty(exports, "runStandardApiTests", { enumerable: true, get: function () { return standardTests_1.runStandardApiTests; } });

package/dist/standardTests.d.ts

@@ -0,0 +1,40 @@
+import { Express } from 'express';
+export interface StandardApiTestConfig {
+    /** The Express app instance */
+    app: Express;
+    /** The route to test (e.g. '/api/v1/jokes') */
+    route: string;
+    /** HTTP method (default: 'GET') */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Valid API key for auth tests */
+    validApiKey: string;
+    /** Whether the route requires auth (default: true) */
+    requiresAuth?: boolean;
+    /** Expected success status code (default: 200) */
+    expectedStatus?: number;
+}
+/**
+ * Runs standardised integration tests for a ThalorLabs microservice route.
+ *
+ * Covers:
+ * - Route exists and returns expected status
+ * - Authentication (missing key, wrong key)
+ * - Unknown routes return 404
+ * - Health endpoint returns 200 without auth
+ * - Response is JSON
+ * - Error responses don't leak stack traces
+ *
+ * @example
+ * ```typescript
+ * import { runStandardApiTests } from '@thalorlabs/api-test-suite';
+ * import { app } from '../src/index';
+ *
+ * runStandardApiTests({
+ *   app,
+ *   route: '/api/v1/jokes',
+ *   method: 'GET',
+ *   validApiKey: 'test-key',
+ * });
+ * ```
+ */
+export declare function runStandardApiTests(config: StandardApiTestConfig): void;

package/dist/standardTests.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStandardApiTests = runStandardApiTests;
+const supertest_1 = __importDefault(require("supertest"));
+function makeRequest(app, method, route) {
+    switch (method) {
+        case 'POST':
+            return (0, supertest_1.default)(app).post(route);
+        case 'PUT':
+            return (0, supertest_1.default)(app).put(route);
+        case 'PATCH':
+            return (0, supertest_1.default)(app).patch(route);
+        case 'DELETE':
+            return (0, supertest_1.default)(app).delete(route);
+        default:
+            return (0, supertest_1.default)(app).get(route);
+    }
+}
+/**
+ * Runs standardised integration tests for a ThalorLabs microservice route.
+ *
+ * Covers:
+ * - Route exists and returns expected status
+ * - Authentication (missing key, wrong key)
+ * - Unknown routes return 404
+ * - Health endpoint returns 200 without auth
+ * - Response is JSON
+ * - Error responses don't leak stack traces
+ *
+ * @example
+ * ```typescript
+ * import { runStandardApiTests } from '@thalorlabs/api-test-suite';
+ * import { app } from '../src/index';
+ *
+ * runStandardApiTests({
+ *   app,
+ *   route: '/api/v1/jokes',
+ *   method: 'GET',
+ *   validApiKey: 'test-key',
+ * });
+ * ```
+ */
+function runStandardApiTests(config) {
+    const { app, route, method = 'GET', validApiKey, requiresAuth = true, expectedStatus = 200, } = config;
+    describe(`Standard API Tests — ${method} ${route}`, () => {
+        // Routing
+        describe('Routing', () => {
+            it(`${method} ${route} returns ${expectedStatus} with valid auth`, async () => {
+                const res = await makeRequest(app, method, route).set('x-api-key', validApiKey);
+                expect(res.status).toBe(expectedStatus);
+            });
+            it('unknown route returns 404', async () => {
+                const res = await (0, supertest_1.default)(app)
+                    .get('/api/v1/this-route-does-not-exist')
+                    .set('x-api-key', validApiKey);
+                expect(res.status).toBe(404);
+            });
+            it('response is JSON', async () => {
+                const res = await makeRequest(app, method, route).set('x-api-key', validApiKey);
+                expect(res.headers['content-type']).toMatch(/json/);
+            });
+        });
+        // Authentication
+        if (requiresAuth) {
+            describe('Authentication', () => {
+                it('returns 401 without API key', async () => {
+                    const res = await makeRequest(app, method, route);
+                    expect(res.status).toBe(401);
+                });
+                it('returns 401 with wrong API key', async () => {
+                    const res = await makeRequest(app, method, route).set('x-api-key', 'wrong-key-that-should-fail');
+                    expect(res.status).toBe(401);
+                });
+                it('returns 401 with empty API key', async () => {
+                    const res = await makeRequest(app, method, route).set('x-api-key', '');
+                    expect(res.status).toBe(401);
+                });
+            });
+        }
+        // Health endpoint
+        describe('Health', () => {
+            it('GET /health returns 200 without auth', async () => {
+                const res = await (0, supertest_1.default)(app).get('/health');
+                expect(res.status).toBe(200);
+                expect(res.body).toHaveProperty('status');
+            });
+            it('GET /alive returns 200 without auth', async () => {
+                const res = await (0, supertest_1.default)(app).get('/alive');
+                expect(res.status).toBe(200);
+                expect(res.body).toHaveProperty('status', 'alive');
+            });
+        });
+        // Error response contract
+        describe('Error response contract', () => {
+            it('error responses include status field', async () => {
+                const res = await makeRequest(app, method, route);
+                if (res.status >= 400) {
+                    expect(res.body).toHaveProperty('status');
+                }
+            });
+            it('error responses do not leak stack traces', async () => {
+                const res = await makeRequest(app, method, route);
+                if (res.status >= 400) {
+                    const body = JSON.stringify(res.body);
+                    expect(body).not.toContain('at Object.');
+                    expect(body).not.toContain('at Module.');
+                    expect(body).not.toContain('node_modules');
+                    expect(body).not.toContain('.ts:');
+                }
+            });
+        });
+    });
+}

package/eslint.config.mjs

@@ -0,0 +1,3 @@
+import { backend } from '@thalorlabs/eslint-plugin-dev-config';
+
+export default backend;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@thalorlabs/api-test-suite",
+  "author": "ThalorLabs",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Standardised integration test suite for ThalorLabs microservices",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prebuild": "npm run clean",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\""
+  },
+  "devDependencies": {
+    "@thalorlabs/eslint-plugin-dev-config": "^2.1.3",
+    "@types/express": "^5.0.0",
+    "@types/node": "^25.0.0",
+    "@types/supertest": "^6.0.0",
+    "express": "^4.21.0",
+    "prettier": "^3.0.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "supertest": "^7.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0"
+  },
+  "prettier": "@thalorlabs/eslint-plugin-dev-config/prettier",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { runStandardApiTests } from './standardTests';
+export type { StandardApiTestConfig } from './standardTests';

package/src/standardTests.ts

@@ -0,0 +1,177 @@
+import { Express } from 'express';
+import request from 'supertest';
+
+// vitest globals (describe, it, expect) are injected by the test runner.
+// This package is consumed inside vitest test files — no explicit import needed.
+declare const describe: (name: string, fn: () => void) => void;
+declare const it: (name: string, fn: () => Promise<void> | void) => void;
+declare const expect: (value: unknown) => any;
+
+export interface StandardApiTestConfig {
+  /** The Express app instance */
+  app: Express;
+  /** The route to test (e.g. '/api/v1/jokes') */
+  route: string;
+  /** HTTP method (default: 'GET') */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Valid API key for auth tests */
+  validApiKey: string;
+  /** Whether the route requires auth (default: true) */
+  requiresAuth?: boolean;
+  /** Expected success status code (default: 200) */
+  expectedStatus?: number;
+}
+
+function makeRequest(
+  app: Express,
+  method: string,
+  route: string
+): request.Test {
+  switch (method) {
+    case 'POST':
+      return request(app).post(route);
+    case 'PUT':
+      return request(app).put(route);
+    case 'PATCH':
+      return request(app).patch(route);
+    case 'DELETE':
+      return request(app).delete(route);
+    default:
+      return request(app).get(route);
+  }
+}
+
+/**
+ * Runs standardised integration tests for a ThalorLabs microservice route.
+ *
+ * Covers:
+ * - Route exists and returns expected status
+ * - Authentication (missing key, wrong key)
+ * - Unknown routes return 404
+ * - Health endpoint returns 200 without auth
+ * - Response is JSON
+ * - Error responses don't leak stack traces
+ *
+ * @example
+ * ```typescript
+ * import { runStandardApiTests } from '@thalorlabs/api-test-suite';
+ * import { app } from '../src/index';
+ *
+ * runStandardApiTests({
+ *   app,
+ *   route: '/api/v1/jokes',
+ *   method: 'GET',
+ *   validApiKey: 'test-key',
+ * });
+ * ```
+ */
+export function runStandardApiTests(config: StandardApiTestConfig): void {
+  const {
+    app,
+    route,
+    method = 'GET',
+    validApiKey,
+    requiresAuth = true,
+    expectedStatus = 200,
+  } = config;
+
+  describe(`Standard API Tests — ${method} ${route}`, () => {
+    // Routing
+    describe('Routing', () => {
+      it(`${method} ${route} returns ${expectedStatus} with valid auth`, async () => {
+        const res = await makeRequest(app, method, route).set(
+          'x-api-key',
+          validApiKey
+        );
+
+        expect(res.status).toBe(expectedStatus);
+      });
+
+      it('unknown route returns 404', async () => {
+        const res = await request(app)
+          .get('/api/v1/this-route-does-not-exist')
+          .set('x-api-key', validApiKey);
+
+        expect(res.status).toBe(404);
+      });
+
+      it('response is JSON', async () => {
+        const res = await makeRequest(app, method, route).set(
+          'x-api-key',
+          validApiKey
+        );
+
+        expect(res.headers['content-type']).toMatch(/json/);
+      });
+    });
+
+    // Authentication
+    if (requiresAuth) {
+      describe('Authentication', () => {
+        it('returns 401 without API key', async () => {
+          const res = await makeRequest(app, method, route);
+
+          expect(res.status).toBe(401);
+        });
+
+        it('returns 401 with wrong API key', async () => {
+          const res = await makeRequest(app, method, route).set(
+            'x-api-key',
+            'wrong-key-that-should-fail'
+          );
+
+          expect(res.status).toBe(401);
+        });
+
+        it('returns 401 with empty API key', async () => {
+          const res = await makeRequest(app, method, route).set(
+            'x-api-key',
+            ''
+          );
+
+          expect(res.status).toBe(401);
+        });
+      });
+    }
+
+    // Health endpoint
+    describe('Health', () => {
+      it('GET /health returns 200 without auth', async () => {
+        const res = await request(app).get('/health');
+
+        expect(res.status).toBe(200);
+        expect(res.body).toHaveProperty('status');
+      });
+
+      it('GET /alive returns 200 without auth', async () => {
+        const res = await request(app).get('/alive');
+
+        expect(res.status).toBe(200);
+        expect(res.body).toHaveProperty('status', 'alive');
+      });
+    });
+
+    // Error response contract
+    describe('Error response contract', () => {
+      it('error responses include status field', async () => {
+        const res = await makeRequest(app, method, route);
+
+        if (res.status >= 400) {
+          expect(res.body).toHaveProperty('status');
+        }
+      });
+
+      it('error responses do not leak stack traces', async () => {
+        const res = await makeRequest(app, method, route);
+
+        if (res.status >= 400) {
+          const body = JSON.stringify(res.body);
+          expect(body).not.toContain('at Object.');
+          expect(body).not.toContain('at Module.');
+          expect(body).not.toContain('node_modules');
+          expect(body).not.toContain('.ts:');
+        }
+      });
+    });
+  });
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@thalorlabs/eslint-plugin-dev-config/tsconfig/backend.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}