You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+7-4Lines changed: 7 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -64,14 +64,17 @@ Drizzle ORM with SQLite (default) or Postgres. Tables: `request_usage`, `provide
64
64
## Development & Testing
65
65
66
66
-**Dev server:**`bun run dev` (backend port 4000 + frontend watcher)
67
-
-**Tests:**`bun test` from `packages/backend/`
67
+
-**Tests:**`bun run test` from the repo root or from `packages/backend/` (`bun test` is intentionally blocked both at repo root and in `packages/backend` with a guidance message)
68
68
-**Format:**`bun run format` / `bun run format:check`
69
69
70
70
### Test Isolation
71
71
72
-
-**Global setup:**`bunfig.toml` preloads `packages/backend/test/setup.ts` which mocks Logger and initializes in-memory DB.
73
-
-**Do NOT** use `mock.module` to globally mock `config.ts` — it pollutes other tests.
74
-
-**Use `registerSpy`** from `test/test-utils.ts` instead of raw `spyOn` — automatic cleanup after each test.
72
+
- Backend tests run on **Vitest** via `packages/backend/vitest.config.ts`.
73
+
-**Global setup:**`packages/backend/test/vitest.global-setup.ts` creates a temporary file-backed SQLite DB, runs migrations once, and cleans it up automatically after the run.
74
+
-**Per-worker setup:**`packages/backend/test/vitest.setup.ts` installs logger/debug test doubles.
75
+
-`packages/backend/bunfig.toml` intentionally blocks raw `bun test` in `packages/backend` and directs contributors to `bun run test` / `bun run test:watch`.
76
+
- Root `bunfig.toml` intentionally blocks raw `bun test` at the repo root and directs contributors to `cd packages/backend && bun run test`.
77
+
-**Use `registerSpy`** from `test/test-utils.ts` instead of raw `spyOn` when you want automatic cleanup after each test.
75
78
- If you must mock a module, implement its **full public interface**.
Copy file name to clipboardExpand all lines: docs/TESTING.md
+40-20Lines changed: 40 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,41 +18,67 @@ The E2E tests are split by API type:
18
18
19
19
## Global Test Setup
20
20
21
-
To ensure test isolation and prevent "mock pollution" in Bun's shared-worker environment, this project uses a global setup script.
21
+
Backend tests run on **Vitest**.
22
22
23
-
### `bunfig.toml`and `test/setup.ts`
23
+
### `vitest.config.ts`, `test/vitest.global-setup.ts`, and `test/vitest.setup.ts`
24
24
25
-
The root `bunfig.toml` is configured to preload `packages/backend/test/setup.ts` before any tests run. This script establishes "Gold Standard" mocks for global dependencies like the **Logger**.
25
+
-`packages/backend/vitest.config.ts` is the single backend test-runner config.
26
+
-`packages/backend/test/vitest.global-setup.ts` creates a temporary file-backed SQLite database, generates Drizzle metadata if needed, runs migrations once, and removes the temp directory after the run.
27
+
-`packages/backend/test/vitest.setup.ts` installs stable logger/debug test doubles for each worker.
28
+
- Root `bunfig.toml` intentionally blocks raw `bun test` at the repo root and points contributors to `cd packages/backend && bun run test`.
29
+
-`packages/backend/bunfig.toml` intentionally blocks raw `bun test` in `packages/backend` and points contributors to `bun run test`.
26
30
27
31
### Mocking Pattern: Shared Dependencies
28
32
29
-
Bun's `mock.module` is a process-global operation. Once a module is mocked, it remains mocked for the duration of that worker thread, and `mock.restore()` does **not** reset it.
33
+
Vitest restores mocks reliably, but shared dependencies should still follow these rules:
30
34
31
-
To prevent crashes in other tests (e.g., `TypeError: logger.info is not a function`), follow these rules:
32
-
33
-
1.**Use the Global Setup:** Common modules like `src/utils/logger` should be mocked once in `setup.ts`.
34
-
2.**Robust Mocking:** If you must mock a module in a specific test file, your mock **MUST** implement the entire public interface of that module (including all log levels like `silly`, `debug`, etc.).
35
-
3.**Prefer Spying:** If you need to assert that a global dependency was called, use `spyOn` on the already-mocked global instance rather than re-mocking the module.
35
+
1.**Use the shared setup:** Common modules like `src/utils/logger` are mocked once in `vitest.setup.ts`.
36
+
2.**Robust Mocking:** If you mock a module in a specific test file, your mock **MUST** implement the relevant public interface of that module.
37
+
3.**Prefer Spying:** If you need to assert that a shared dependency was called, use `vi.spyOn` or `registerSpy` rather than replacing the whole module repeatedly.
36
38
37
39
```typescript
38
40
import { logger } from"src/utils/logger";
39
-
import { spyOn, expect, test} from"bun:test";
41
+
import { expect, test, vi} from"vitest";
40
42
41
43
test("my test", () => {
42
-
const infoSpy =spyOn(logger, "info");
44
+
const infoSpy =vi.spyOn(logger, "info");
43
45
// ... run code ...
44
46
expect(infoSpy).toHaveBeenCalled();
45
47
});
46
48
```
47
49
48
50
## Running Tests
49
51
50
-
### 1. Standard Run (Replay Mode)
51
-
Uses existing cassettes. No API keys or network access are required.
52
+
### 1. Standard Run
53
+
54
+
From the repo root:
55
+
56
+
```bash
57
+
bun run test
58
+
```
59
+
60
+
Or from the backend package:
52
61
53
62
```bash
54
63
cd packages/backend
55
-
bun test
64
+
bun run test
65
+
```
66
+
67
+
> Note: `bun test` is intentionally blocked both at repo root and in `packages/backend`. Use `bun run test` instead.
68
+
69
+
### 2. Watch Mode
70
+
71
+
From the repo root:
72
+
73
+
```bash
74
+
bun run test:watch
75
+
```
76
+
77
+
Or from the backend package:
78
+
79
+
```bash
80
+
cd packages/backend
81
+
bun run test:watch
56
82
```
57
83
*Tip: You can also run this via the VS Code task `Bun: Backend Tests`.*
58
84
@@ -89,9 +115,3 @@ The following environment variables are used during **Record Mode**:
89
115
|`PLEXUS_TEST_BASE_URL`| Base URL for Chat provider. |`https://api.upstream.mock/openai/v1`|
90
116
|`PLEXUS_TEST_ANTHROPIC_BASE_URL`| Base URL for Messages provider. |`https://api.anthropic.com/v1`|
91
117
92
-
## Adding New Test Cases
93
-
94
-
1. Add a new JSON request body to `cases/chat/` (for Chat-like) or `cases/messages/` (for Messages-like).
95
-
2. Run the **Record Mode**command above to capture the network interaction.
96
-
3. Commit the new case and its corresponding cassette in`__cassettes__/`.
0 commit comments