@dever-labs/mockly-testcontainers 0.12.0

package/README.md

@@ -0,0 +1,98 @@
+# @dever-labs/mockly-testcontainers
+
+Run Mockly in Docker-backed Node.js and TypeScript tests with `testcontainers`.
+
+The package starts `ghcr.io/dever-labs/mockly:latest`, waits for the management API to be ready, and exposes helper methods for mocks, scenarios, faults, and logs.
+
+## Requirements
+
+- Node 18+
+- Docker
+- `testcontainers` 10+
+
+## Install
+
+```sh
+npm i -D @dever-labs/mockly-testcontainers testcontainers
+```
+
+## Quickstart
+
+```ts
+import assert from 'node:assert/strict'
+import { MocklyContainerBuilder } from '@dever-labs/mockly-testcontainers'
+
+const container = await new MocklyContainerBuilder().start()
+
+try {
+  await container.addMock({
+    id: 'get-user',
+    request: { method: 'GET', path: '/users/1' },
+    response: { status: 200, body: '{"id":1}' },
+  })
+
+  const response = await fetch(`${container.getHttpBase()}/users/1`)
+  assert.equal(response.status, 200)
+  assert.equal(await response.text(), '{"id":1}')
+} finally {
+  await container.stop()
+}
+```
+
+## When to use the testcontainers module
+
+Use `@dever-labs/mockly-testcontainers` when you want Docker-managed lifecycle, no native binary download, or a consistent Mockly environment across laptops and CI.
+
+Use `@dever-labs/mockly-driver` when you want to run the Mockly binary directly in the test process instead.
+
+## Builder API
+
+`MocklyContainerBuilder` configures the container before startup.
+
+| Method | Description |
+|---|---|
+| `new MocklyContainerBuilder()` | Create a builder with the default image and default config. |
+| `withImage(image)` | Override the Docker image. |
+| `withInlineConfig(yaml)` | Replace `/config/mockly.yaml` with inline YAML. |
+| `start()` | Start the container and return a `StartedMocklyContainer`. |
+
+### Custom YAML config
+
+```ts
+const container = await new MocklyContainerBuilder()
+  .withInlineConfig(`mockly:
+  api:
+    port: 9091
+protocols:
+  http:
+    enabled: true
+    port: 8090
+`)
+  .start()
+```
+
+## Started container API
+
+| Method | Description |
+|---|---|
+| `getHttpBase()` | Base URL of the mock HTTP server. |
+| `getApiBase()` | Base URL of the management API. |
+| `stop()` | Stop and remove the container. |
+| `addMock(mock)` | Register a dynamic HTTP mock. |
+| `deleteMock(id)` | Delete a mock by ID. |
+| `reset()` | Remove dynamic mocks, deactivate scenarios, and clear faults. |
+| `activateScenario(id)` | Activate a configured scenario. |
+| `deactivateScenario(id)` | Deactivate a configured scenario. |
+| `setFault(config)` | Apply a global HTTP fault. |
+| `clearFault()` | Remove the active fault. |
+| `getLogs()` | Read request logs as JSON. |
+| `clearLogs()` | Clear stored request logs. |
+
+## Exported types
+
+The package also exports these TypeScript types:
+
+- `HttpMock`
+- `MockRequest`
+- `MockResponse`
+- `FaultConfig`

package/dist/MocklyContainer.d.ts

@@ -0,0 +1,33 @@
+import type { StartedTestContainer } from 'testcontainers';
+import type { HttpMock, FaultConfig } from './types.js';
+export declare const DEFAULT_IMAGE = "ghcr.io/dever-labs/mockly:latest";
+export declare const HTTP_PORT = 8090;
+export declare const API_PORT = 9091;
+export declare const CONTAINER_CONFIG_PATH = "/config/mockly.yaml";
+export declare class MocklyContainerBuilder {
+    private image;
+    private inlineConfig;
+    withImage(image: string): this;
+    withInlineConfig(yaml: string): this;
+    start(): Promise<StartedMocklyContainer>;
+}
+export declare class StartedMocklyContainer {
+    private readonly container;
+    constructor(container: StartedTestContainer);
+    getHttpBase(): string;
+    getApiBase(): string;
+    stop(): Promise<void>;
+    addMock(mock: HttpMock): Promise<void>;
+    deleteMock(id: string): Promise<void>;
+    reset(): Promise<void>;
+    activateScenario(id: string): Promise<void>;
+    deactivateScenario(id: string): Promise<void>;
+    setFault(config: FaultConfig): Promise<void>;
+    clearFault(): Promise<void>;
+    getLogs(): Promise<string>;
+    clearLogs(): Promise<void>;
+    private assertOk;
+    private get;
+    private post;
+    private delete;
+}

package/dist/MocklyContainer.js

@@ -0,0 +1,112 @@
+import { GenericContainer, Wait } from 'testcontainers';
+export const DEFAULT_IMAGE = 'ghcr.io/dever-labs/mockly:latest';
+export const HTTP_PORT = 8090;
+export const API_PORT = 9091;
+export const CONTAINER_CONFIG_PATH = '/config/mockly.yaml';
+const DEFAULT_CONFIG = `mockly:
+  api:
+    port: 9091
+protocols:
+  http:
+    enabled: true
+    port: 8090
+`;
+export class MocklyContainerBuilder {
+    image = DEFAULT_IMAGE;
+    inlineConfig;
+    withImage(image) {
+        this.image = image;
+        return this;
+    }
+    withInlineConfig(yaml) {
+        this.inlineConfig = yaml;
+        return this;
+    }
+    async start() {
+        const configYaml = this.inlineConfig ?? DEFAULT_CONFIG;
+        const cmd = ['start', '-c', CONTAINER_CONFIG_PATH];
+        const container = await new GenericContainer(this.image)
+            .withExposedPorts(HTTP_PORT, API_PORT)
+            .withCommand(cmd)
+            .withCopyContentToContainer([
+            {
+                content: Buffer.from(configYaml),
+                target: CONTAINER_CONFIG_PATH,
+                mode: 0o644,
+            },
+        ])
+            .withWaitStrategy(Wait.forHttp('/api/protocols', API_PORT).withStartupTimeout(60_000))
+            .start();
+        return new StartedMocklyContainer(container);
+    }
+}
+export class StartedMocklyContainer {
+    container;
+    constructor(container) {
+        this.container = container;
+    }
+    getHttpBase() {
+        return `http://${this.container.getHost()}:${this.container.getMappedPort(HTTP_PORT)}`;
+    }
+    getApiBase() {
+        return `http://${this.container.getHost()}:${this.container.getMappedPort(API_PORT)}`;
+    }
+    async stop() {
+        await this.container.stop();
+    }
+    async addMock(mock) {
+        const res = await this.post('/api/mocks/http', mock);
+        this.assertOk(res, `addMock(${mock.id})`);
+    }
+    async deleteMock(id) {
+        const res = await this.delete(`/api/mocks/http/${id}`);
+        this.assertOk(res, `deleteMock(${id})`);
+    }
+    async reset() {
+        const res = await this.post('/api/reset', null);
+        this.assertOk(res, 'reset');
+    }
+    async activateScenario(id) {
+        const res = await this.post(`/api/scenarios/${id}/activate`, null);
+        this.assertOk(res, `activateScenario(${id})`);
+    }
+    async deactivateScenario(id) {
+        const res = await this.post(`/api/scenarios/${id}/deactivate`, null);
+        this.assertOk(res, `deactivateScenario(${id})`);
+    }
+    async setFault(config) {
+        const res = await this.post('/api/fault', config);
+        this.assertOk(res, 'setFault');
+    }
+    async clearFault() {
+        const res = await this.delete('/api/fault');
+        this.assertOk(res, 'clearFault');
+    }
+    async getLogs() {
+        const res = await this.get('/api/logs');
+        this.assertOk(res, 'getLogs');
+        return await res.text();
+    }
+    async clearLogs() {
+        const res = await this.delete('/api/logs');
+        this.assertOk(res, 'clearLogs');
+    }
+    assertOk(res, operation) {
+        if (!res.ok) {
+            throw new Error(`${operation} failed: HTTP ${res.status}`);
+        }
+    }
+    async get(path) {
+        return fetch(`${this.getApiBase()}${path}`);
+    }
+    async post(path, body) {
+        return fetch(`${this.getApiBase()}${path}`, {
+            method: 'POST',
+            headers: body !== null ? { 'Content-Type': 'application/json' } : {},
+            body: body !== null ? JSON.stringify(body) : undefined,
+        });
+    }
+    async delete(path) {
+        return fetch(`${this.getApiBase()}${path}`, { method: 'DELETE' });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CONTAINER_CONFIG_PATH, MocklyContainerBuilder, StartedMocklyContainer, DEFAULT_IMAGE, HTTP_PORT, API_PORT, } from './MocklyContainer.js';
+export type { MockRequest, MockResponse, HttpMock, FaultConfig } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { CONTAINER_CONFIG_PATH, MocklyContainerBuilder, StartedMocklyContainer, DEFAULT_IMAGE, HTTP_PORT, API_PORT, } from './MocklyContainer.js';

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface MockRequest {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+}
+export interface MockResponse {
+    status: number;
+    body?: string;
+    headers?: Record<string, string>;
+    delay?: string;
+}
+export interface HttpMock {
+    id: string;
+    request: MockRequest;
+    response: MockResponse;
+}
+export interface FaultConfig {
+    enabled: boolean;
+    delay?: string;
+    status_override?: number;
+    error_rate?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dever-labs/mockly-testcontainers",
+  "version": "0.12.0",
+  "description": "Testcontainers module for Mockly — run Mockly as a Docker container in tests",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dever-labs/mockly.git",
+    "directory": "clients/node-testcontainers"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:integration": "INTEGRATION=1 vitest run --config vitest.integration.config.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "testcontainers": ">=10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "testcontainers": "^12.0.3",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
+  },
+  "keywords": [
+    "mock",
+    "testing",
+    "http",
+    "integration-test",
+    "mockly",
+    "testcontainers",
+    "docker"
+  ]
+}