@jterrazz/test 3.1.0 → 3.2.0

package/README.md

@@ -1,8 +1,6 @@
-*Hey there – I’m Jean-Baptiste, just another developer doing weird things with code. All my projects live on [jterrazz.com](https://jterrazz.com) – complete with backstories and lessons learned. Feel free to poke around – you might just find something useful!*
-
 # @jterrazz/test
 
-Mocking utilities for TypeScript testing.
+Testing framework for the @jterrazz ecosystem — declarative Docker infrastructure, specification runners, and conventions that all projects follow.
 
 ## Installation
 
@@ -10,66 +8,138 @@ Mocking utilities for TypeScript testing.
 npm install -D @jterrazz/test vitest
 ```
 
-**Optional:** For API mocking with MSW:
+Requires Docker.
 
-```bash
-npm install -D msw
-```
+## Specification runners
 
-## Usage
+Declare services, provide an app factory, the framework starts containers and wires everything.
 
-### Date Mocking
+### Integration (testcontainers, in-process app)
 
 ```typescript
-import { describe, test, expect, afterEach } from 'vitest';
-import { mockOfDate } from '@jterrazz/test';
-
-describe('Date Tests', () => {
-  afterEach(() => {
-    mockOfDate.reset();
-  });
+// tests/integration/integration.specification.ts
+import { afterAll } from "vitest";
+import { integration, postgres } from "@jterrazz/test";
+import { createApp } from "../../src/app.js";
 
-  test('should mock dates', () => {
-    const fixedDate = new Date('2024-01-01');
-    mockOfDate.set(fixedDate);
+const db = postgres({ compose: "db" });
 
-    expect(new Date()).toEqual(fixedDate);
-  });
+export const spec = await integration({
+  services: [db],
+  app: () => createApp({ databaseUrl: db.connectionString }),
+  root: "../../",
 });
+
+afterAll(() => spec.cleanup());
 ```
 
-### Deep Mocking
+### E2E (docker compose up, real HTTP)
 
 ```typescript
-import { describe, test, expect } from 'vitest';
-import { mockOf } from '@jterrazz/test';
+// tests/e2e/e2e.specification.ts
+import { afterAll } from "vitest";
+import { e2e } from "@jterrazz/test";
 
-interface UserService {
-  getUser: (id: string) => Promise<{ id: string; name: string }>;
-}
+export const spec = await e2e({
+  root: "../../",
+});
 
-describe('Mock Tests', () => {
-  test('should use deep mocks', async () => {
-    const mockUserService = mockOf<UserService>();
+afterAll(() => spec.cleanup());
+```
 
-    mockUserService.getUser.mockResolvedValue({ id: '1', name: 'John' });
+### Usage
 
-    const user = await mockUserService.getUser('1');
-    expect(user).toEqual({ id: '1', name: 'John' });
+```typescript
+import { spec } from "../integration.specification.js";
+
+test("creates company", async () => {
+  const result = await spec("creates company")
+    .seed("transactions.sql")
+    .post("/api/analyze", "request.json")
+    .run();
+
+  result.expectStatus(201);
+  result.expectResponse("created.response.json");
+  await result.expectTable("company_profile", {
+    columns: ["name"],
+    rows: [["TEST COMPANY"]],
   });
 });
 ```
 
-## API
+## Service factories
+
+```typescript
+import { postgres, redis } from "@jterrazz/test";
+
+const db = postgres({ compose: "db" }); // Reads config from docker/compose.test.yaml
+const cache = redis({ compose: "cache" });
+```
+
+After `await integration()`, service handles have `.connectionString` populated from running containers.
 
-| Export | Description |
-|--------|-------------|
-| `mockOfDate` | Date mocking utilities (`set`, `reset`) |
-| `mockOf<T>()` | Create deep mock of any interface |
-| `MockDatePort` | Type interface for date mocking |
-| `MockPort` | Type interface for deep mocking |
+## Docker convention
 
-## Peer Dependencies
+```
+docker/
+├── compose.test.yaml           # Source of truth for test infrastructure
+├── postgres/
+│   └── init.sql                # Auto-run on container start
+```
+
+## Builder API
+
+**Setup:** `.seed("file.sql")`, `.mock("file.json")`
+
+**Action:** `.get(path)`, `.post(path, "body.json")`, `.put(path, "body.json")`, `.delete(path)`
+
+**Assertions:** `.expectStatus(code)`, `.expectResponse("file.json")`, `.expectTable(table, { columns, rows })`
+
+## Test structure
+
+```
+tests/
+├── setup/                      # Infrastructure (DB init, Docker config)
+├── fixtures/                   # Shared fake things to test against
+├── helpers/                    # Shared test utilities
+├── integration/
+│   ├── integration.specification.ts
+│   └── api/
+│       └── {feature}/
+│           ├── {feature}.integration.test.ts
+│           ├── seeds/
+│           ├── requests/
+│           └── responses/
+└── e2e/
+    ├── e2e.specification.ts
+    └── api/...
+```
+
+## Test data (colocated per test)
+
+| Folder       | Purpose                            |
+| ------------ | ---------------------------------- |
+| `seeds/`     | Database state setup               |
+| `mock/`      | Mocked external API responses      |
+| `requests/`  | Request bodies                     |
+| `responses/` | Expected API responses             |
+| `expected/`  | Expected output to compare against |
+
+## File naming
+
+| Type        | Suffix                 | Location              |
+| ----------- | ---------------------- | --------------------- |
+| Unit        | `.test.ts`             | Colocated with source |
+| Integration | `.integration.test.ts` | `tests/integration/`  |
+| E2E         | `.e2e.test.ts`         | `tests/e2e/`          |
+
+## Mocking utilities
+
+```typescript
+import { mockOf, mockOfDate } from "@jterrazz/test";
+```
 
-- `vitest` (required)
-- `msw` (optional)
+| Export        | Description                              |
+| ------------- | ---------------------------------------- |
+| `mockOfDate`  | Date mocking — `set(date)` and `reset()` |
+| `mockOf<T>()` | Deep mock of any interface               |