@jterrazz/test 3.0.0 → 3.2.0

package/README.md

@@ -1,96 +1,145 @@
-# Package Typescript Test
+# @jterrazz/test
 
-This package provides Vitest configuration and testing utilities for TypeScript projects, including MSW (Mock Service Worker) setup for API mocking.
+Testing framework for the @jterrazz ecosystem — declarative Docker infrastructure, specification runners, and conventions that all projects follow.
 
 ## Installation
 
-Install the package using npm:
-
 ```bash
-npm install -D @jterrazz/test
+npm install -D @jterrazz/test vitest
 ```
 
-## Usage
+Requires Docker.
 
-1. Set up MSW for API mocking:
+## Specification runners
 
-```typescript
-// handlers.ts
-import { http } from 'msw';
-import { setupServer } from '@jterrazz/test';
-
-// Define your API handlers
-const handlers = [
-  http.get('/api/example', () => {
-    return new Response(JSON.stringify({ data: 'example' }));
-  }),
-];
-
-// Setup MSW server
-export const server = setupServer(...handlers);
-```
+Declare services, provide an app factory, the framework starts containers and wires everything.
 
-2. You can now write your tests using Vitest and MSW!
+### Integration (testcontainers, in-process app)
 
 ```typescript
-import { describe, test, expect } from '@jterrazz/test';
-import { server } from './handlers';
+// tests/integration/integration.specification.ts
+import { afterAll } from "vitest";
+import { integration, postgres } from "@jterrazz/test";
+import { createApp } from "../../src/app.js";
 
-describe('API Tests', () => {
-  test('should handle API requests', async () => {
-    const response = await fetch('/api/example');
-    const data = await response.json();
+const db = postgres({ compose: "db" });
 
-    expect(data).toEqual({ data: 'example' });
-  });
+export const spec = await integration({
+  services: [db],
+  app: () => createApp({ databaseUrl: db.connectionString }),
+  root: "../../",
 });
+
+afterAll(() => spec.cleanup());
 ```
 
-3. Using Date Mocking:
+### E2E (docker compose up, real HTTP)
 
 ```typescript
-import { mockOfDate } from '@jterrazz/test';
+// tests/e2e/e2e.specification.ts
+import { afterAll } from "vitest";
+import { e2e } from "@jterrazz/test";
+
+export const spec = await e2e({
+  root: "../../",
+});
 
-describe('Date Tests', () => {
-  test('should mock dates', () => {
-    const fixedDate = new Date('2024-01-01');
-    mockOfDate.set(fixedDate);
+afterAll(() => spec.cleanup());
+```
 
-    expect(new Date()).toEqual(fixedDate);
+### Usage
 
-    // Reset the mock after your test
-    mockOfDate.reset();
+```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"]],
   });
 });
 ```
 
-4. Using Extended Mocking:
+## Service factories
 
 ```typescript
-import { mockOf } from '@jterrazz/test';
+import { postgres, redis } from "@jterrazz/test";
 
-interface UserService {
-  getUser: (id: string) => Promise<{ id: string; name: string }>;
-}
+const db = postgres({ compose: "db" }); // Reads config from docker/compose.test.yaml
+const cache = redis({ compose: "cache" });
+```
 
-describe('Mock Tests', () => {
-  test('should use extended mocks', async () => {
-    const mockUserService = mockOf<UserService>();
+After `await integration()`, service handles have `.connectionString` populated from running containers.
 
-    // Setup mock behavior
-    mockUserService.getUser.mockResolvedValue({ id: '1', name: 'John' });
+## Docker convention
 
-    const user = await mockUserService.getUser('1');
-    expect(user).toEqual({ id: '1', name: 'John' });
-  });
-});
 ```
+docker/
+├── compose.test.yaml           # Source of truth for test infrastructure
+├── postgres/
+│   └── init.sql                # Auto-run on container start
+```
+
+## Builder API
 
-## Features
+**Setup:** `.seed("file.sql")`, `.mock("file.json")`
 
-- Vitest configuration with TypeScript support
-- MSW integration for API mocking
-- Mock date utilities for time-based testing
-- Extended mocking capabilities with vitest-mock-extended
+**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";
+```
 
-Happy testing! 🚀
+| Export        | Description                              |
+| ------------- | ---------------------------------------- |
+| `mockOfDate`  | Date mocking — `set(date)` and `reset()` |
+| `mockOf<T>()` | Deep mock of any interface               |