hazo_testing 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGE_LOG.md +49 -0
- package/README.md +106 -0
- package/dist/db/create_test_postgrest_adapter.d.ts +18 -0
- package/dist/db/create_test_postgrest_adapter.js +33 -0
- package/dist/db/postgrest_guard.d.ts +25 -0
- package/dist/db/postgrest_guard.js +37 -0
- package/dist/db/postgrest_seed.d.ts +17 -0
- package/dist/db/postgrest_seed.js +29 -0
- package/dist/db/postgrest_truncate.d.ts +22 -0
- package/dist/db/postgrest_truncate.js +27 -0
- package/dist/errors.d.ts +18 -0
- package/dist/errors.js +30 -0
- package/dist/index.d.ts +10 -2
- package/dist/index.js +6 -2
- package/package.json +8 -8
package/CHANGE_LOG.md
CHANGED
|
@@ -1,5 +1,54 @@
|
|
|
1
1
|
# hazo_testing changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.0 — 2026-11-22
|
|
4
|
+
|
|
5
|
+
### Added — PostgREST test-database helpers (seed, truncate, factory)
|
|
6
|
+
|
|
7
|
+
Supports writing integration tests against a **remote** PostgREST-backed test
|
|
8
|
+
database (e.g. Faraday's `faraday_test`), as opposed to the in-memory SQLite
|
|
9
|
+
DB `createTestDatabase` provides. Three new exports, all delegating row I/O
|
|
10
|
+
to `hazo_connect`'s own `createCrudService`/`createTableQuery` (no hand-built
|
|
11
|
+
PostgREST requests):
|
|
12
|
+
|
|
13
|
+
- `createTestPostgrestAdapter(opts?)` — returns a `hazo_connect`
|
|
14
|
+
`HazoConnectAdapter` (`type: "postgrest"`) configured from `POSTGREST_URL` /
|
|
15
|
+
`POSTGREST_API_KEY` (env or explicit options). Throws
|
|
16
|
+
`MissingPostgrestTestConfig` if either is missing.
|
|
17
|
+
- `seedPostgrestRows(adapter, { [table]: rows[] })` — inserts fixture rows
|
|
18
|
+
into one or more tables (one POST per non-empty table; `insert()` already
|
|
19
|
+
accepts an array). Returns the inserted rows as reported by PostgREST.
|
|
20
|
+
- `truncatePostgrestTables(adapter, tables[], opts?)` — clears a named set of
|
|
21
|
+
tables between tests. **Safety-gated**: refuses synchronously, before any
|
|
22
|
+
request is made, unless BOTH an explicit opt-in
|
|
23
|
+
(`HAZO_TESTING_ALLOW_TRUNCATE=true` / `{ allowTruncate: true }`) AND a
|
|
24
|
+
test-identity check (`HAZO_TESTING_DB_NAME` or the PostgREST URL contains
|
|
25
|
+
`"test"`, case-insensitive) pass — neither alone is sufficient, by design
|
|
26
|
+
(e.g. the opt-in flag set against a `-prod` host still refuses). Not gated
|
|
27
|
+
on `NODE_ENV` (see `CLAUDE.md`). PostgREST has no native `TRUNCATE`
|
|
28
|
+
endpoint, so each table is cleared via `DELETE` filtered on
|
|
29
|
+
`<idColumn>=not.is.null` (default `idColumn: "id"`, overridable), which
|
|
30
|
+
matches every row since every row has a non-null primary key.
|
|
31
|
+
- `assertSafeToTruncate(opts?)` — the guard check alone, for callers who want
|
|
32
|
+
to fail fast without the delete side effect.
|
|
33
|
+
- New error classes `UnsafeTruncateTarget` and `MissingPostgrestTestConfig`
|
|
34
|
+
(both extend `HazoError`, `HAZO_TESTING_*` codes).
|
|
35
|
+
|
|
36
|
+
19 new unit tests (guard: 15, factory: 6, seed: 4, truncate: 7 — some
|
|
37
|
+
overlap across files) prove the guard refuses on every ambiguous
|
|
38
|
+
combination (neither flag, only the opt-in, only the identity match, both
|
|
39
|
+
flags but a non-test-identified target) and proceeds only when both
|
|
40
|
+
conditions hold. All new tests mock `global.fetch`; a
|
|
41
|
+
`postgrest_live.integration.test.ts` round-trip test is gated on
|
|
42
|
+
`POSTGREST_URL`/`POSTGREST_API_KEY` presence and skips cleanly with neither
|
|
43
|
+
set (confirmed: `npm test` stays green, 0 env vars required).
|
|
44
|
+
|
|
45
|
+
Also corrected a stale `HAZO_TESTING_VERSION` constant in `src/index.ts`
|
|
46
|
+
(read `"0.5.0"`, two releases behind; now matches `package.json`).
|
|
47
|
+
|
|
48
|
+
See README.md's "PostgREST test-database helpers" section for env vars, the
|
|
49
|
+
full safety-guard rationale, a Faraday `faraday_test` setup example, and CI
|
|
50
|
+
notes.
|
|
51
|
+
|
|
3
52
|
## 0.6.0 — 2026-10-19
|
|
4
53
|
|
|
5
54
|
### Added — vitest 4 support
|
package/README.md
CHANGED
|
@@ -7,6 +7,7 @@ Shared test infrastructure for hazo apps. Gives a consumer's Jest suite:
|
|
|
7
7
|
3. **Real-package wiring helpers** that stand up `hazo_jobs`, `hazo_notify`, and `hazo_llm_api` against the test DB — no fakes.
|
|
8
8
|
4. An `apiTestClient`, seed fixtures, a Jest preset, and in-process reset hooks.
|
|
9
9
|
5. Optional sub-exports for Playwright and Next.js integration testing.
|
|
10
|
+
6. PostgREST test-database helpers — seed/truncate/factory for integration tests against a **remote** PostgREST-backed test database (e.g. Faraday's `faraday_test`), with a safety-gated truncate (see below).
|
|
10
11
|
|
|
11
12
|
---
|
|
12
13
|
|
|
@@ -15,6 +16,7 @@ Shared test infrastructure for hazo apps. Gives a consumer's Jest suite:
|
|
|
15
16
|
> - `wireHazoNotify` with `channels: ["email"]` or `["telegram"]` **will send real email and real Telegram messages** through ZeptoMail / Telegram Bot API. Tests that enable those channels are skip-gated on the presence of `ZEPTOMAIL_API_KEY` / telegram credentials.
|
|
16
17
|
> - `wireHazoLlmApi` **makes real, billed API calls** to Gemini / Qwen. Tests that call `llm.run(...)` are skip-gated on `GEMINI_API_KEY` / `QWEN_API_KEY`.
|
|
17
18
|
> - The inbox-only notify path and all jobs/fixture/factory tests need no credentials and run fully offline.
|
|
19
|
+
> - `truncatePostgrestTables` **deletes rows from a real database** when its safety guard passes. It refuses unless both an explicit opt-in and a test-identity check pass — see "PostgREST test-database helpers" below.
|
|
18
20
|
|
|
19
21
|
---
|
|
20
22
|
|
|
@@ -98,6 +100,110 @@ These are thin shims over `createCrudService` from `hazo_connect`. They handle U
|
|
|
98
100
|
|
|
99
101
|
---
|
|
100
102
|
|
|
103
|
+
## PostgREST test-database helpers (0.7.0)
|
|
104
|
+
|
|
105
|
+
Integration tests against a **remote PostgREST-backed test database** (e.g. Faraday's `faraday_test`) — as opposed to the in-memory SQLite DB above. Three pieces: a factory, a seed helper, and a truncate helper. All three delegate row I/O to `hazo_connect`'s own `createCrudService`/`createTableQuery` — nothing here hand-builds PostgREST requests.
|
|
106
|
+
|
|
107
|
+
### Env vars
|
|
108
|
+
|
|
109
|
+
| Var | Required for | Purpose |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| `POSTGREST_URL` | `createTestPostgrestAdapter` | Base URL of the PostgREST instance fronting the test database. |
|
|
112
|
+
| `POSTGREST_API_KEY` | `createTestPostgrestAdapter` | API key / JWT sent as `Authorization: Bearer <key>`. |
|
|
113
|
+
| `HAZO_TESTING_ALLOW_TRUNCATE` | `truncatePostgrestTables` | Must be exactly `"true"`. Explicit opt-in for the destructive operation. |
|
|
114
|
+
| `HAZO_TESTING_DB_NAME` | `truncatePostgrestTables` | DB/schema name, checked for a `"test"` substring. Optional if `POSTGREST_URL` itself contains `"test"` (e.g. a `faraday-test` host). |
|
|
115
|
+
|
|
116
|
+
All four can instead be passed as explicit options to the corresponding function — options always take precedence over the env var.
|
|
117
|
+
|
|
118
|
+
### `createTestPostgrestAdapter`
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
import { createTestPostgrestAdapter } from "hazo_testing";
|
|
122
|
+
|
|
123
|
+
const adapter = createTestPostgrestAdapter();
|
|
124
|
+
// reads POSTGREST_URL / POSTGREST_API_KEY from env; throws
|
|
125
|
+
// MissingPostgrestTestConfig if either is unset and not passed explicitly.
|
|
126
|
+
|
|
127
|
+
// or pass config directly (overrides env):
|
|
128
|
+
const adapter2 = createTestPostgrestAdapter({
|
|
129
|
+
base_url: "https://faraday-test.example.com/rest/v1",
|
|
130
|
+
api_key: "...",
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Returns a plain `hazo_connect` `HazoConnectAdapter` (`createHazoConnect({ type: "postgrest", ... })`) — use it with `createCrudService`, `createTableQuery`, or any other `hazo_connect` helper exactly as you would any other adapter.
|
|
135
|
+
|
|
136
|
+
### `seedPostgrestRows` — insert fixture rows
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
import { seedPostgrestRows } from "hazo_testing";
|
|
140
|
+
|
|
141
|
+
const inserted = await seedPostgrestRows(adapter, {
|
|
142
|
+
providers: [{ name: "Acme Energy" }],
|
|
143
|
+
plans: [{ provider_id: inserted.providers[0].id, name: "Basic" }],
|
|
144
|
+
});
|
|
145
|
+
// inserted.providers, inserted.plans — rows as returned by PostgREST (ids, defaults, etc)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
One `createCrudService(adapter, table).insert(rows)` call per table (an `insert()` with multiple rows is still a single POST); tables with an empty row array are skipped with no request made.
|
|
149
|
+
|
|
150
|
+
### `truncatePostgrestTables` — the safety guard
|
|
151
|
+
|
|
152
|
+
**This is a destructive operation and is safety-gated.** It refuses to run — synchronously, before any request is made — unless **both** of the following are true:
|
|
153
|
+
|
|
154
|
+
1. **Explicit opt-in**: `HAZO_TESTING_ALLOW_TRUNCATE=true` (or `{ allowTruncate: true }`).
|
|
155
|
+
2. **Test-identity check**: `HAZO_TESTING_DB_NAME` *or* the PostgREST URL contains the substring `"test"` (case-insensitive).
|
|
156
|
+
|
|
157
|
+
Either condition alone is not enough — this is deliberate defense in depth. A URL pointing at something that merely isn't flagged as test (e.g. a `-prod` host) refuses even with the opt-in flag set. Per this package's `CLAUDE.md`, the guard is never gated on `NODE_ENV` — only on the real identity of the target.
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
import { truncatePostgrestTables } from "hazo_testing";
|
|
161
|
+
|
|
162
|
+
await truncatePostgrestTables(adapter, ["plans", "providers"], {
|
|
163
|
+
allowTruncate: true, // or set HAZO_TESTING_ALLOW_TRUNCATE=true
|
|
164
|
+
dbName: "faraday_test", // or set HAZO_TESTING_DB_NAME / point POSTGREST_URL at a "test" host
|
|
165
|
+
});
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
PostgREST has no native `TRUNCATE` endpoint, so this issues one `DELETE` per table filtered on `<idColumn>=not.is.null` (default `idColumn: "id"`, overridable per call) — every row has a non-null primary key, so this matches and deletes all of them.
|
|
169
|
+
|
|
170
|
+
A refusal throws `UnsafeTruncateTarget` (exported from `hazo_testing`). Call `assertSafeToTruncate(opts)` directly if you want the same check without the delete side effect (e.g. to fail fast in a `beforeAll`).
|
|
171
|
+
|
|
172
|
+
### Typical Jest setup (Faraday `faraday_test`)
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
// jest.setup.integration.ts, or inline in a describe block
|
|
176
|
+
import { createTestPostgrestAdapter, seedPostgrestRows, truncatePostgrestTables } from "hazo_testing";
|
|
177
|
+
|
|
178
|
+
const HAS_TEST_DB = Boolean(process.env.POSTGREST_URL && process.env.POSTGREST_API_KEY);
|
|
179
|
+
describe.skip.if(!HAS_TEST_DB)("plan comparison (faraday_test)", () => {
|
|
180
|
+
const adapter = createTestPostgrestAdapter();
|
|
181
|
+
|
|
182
|
+
afterEach(async () => {
|
|
183
|
+
await truncatePostgrestTables(adapter, ["plans", "providers"], {
|
|
184
|
+
allowTruncate: true,
|
|
185
|
+
dbName: "faraday_test",
|
|
186
|
+
});
|
|
187
|
+
});
|
|
188
|
+
|
|
189
|
+
it("ranks plans by estimated cost", async () => {
|
|
190
|
+
await seedPostgrestRows(adapter, { providers: [{ name: "Acme Energy" }] });
|
|
191
|
+
// ...
|
|
192
|
+
});
|
|
193
|
+
});
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Gate the whole suite on env-var presence (`describe.skip.if(!HAS_TEST_DB)`, matching this package's own `CLAUDE.md` convention) rather than `NODE_ENV` — the suite must stay green with no env set.
|
|
197
|
+
|
|
198
|
+
### CI notes
|
|
199
|
+
|
|
200
|
+
- CI needs `POSTGREST_URL` and `POSTGREST_API_KEY` pointed at the PostgREST instance fronting `faraday_test` to run these integration tests at all; without them the gated suites skip cleanly (0 failures).
|
|
201
|
+
- To let CI truncate between runs, also set `HAZO_TESTING_ALLOW_TRUNCATE=true` and either `HAZO_TESTING_DB_NAME=faraday_test` or use a `POSTGREST_URL` whose host already contains `test` (e.g. `faraday-test.example.com`) — the guard checks both independently.
|
|
202
|
+
- A production-looking URL (no `"test"` substring anywhere in the name/host) is refused by design, even with `HAZO_TESTING_ALLOW_TRUNCATE=true` set — this is intentional and is not a bug to work around. Point CI secrets at a URL/DB name that is unambiguously a test database.
|
|
203
|
+
- This package's own suite never requires these vars — `npm test` stays green with none of them set (see `src/db/__tests__/postgrest_live.integration.test.ts`).
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
101
207
|
## Auth factories
|
|
102
208
|
|
|
103
209
|
### `createTestUser`
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { HazoConnectAdapter, Logger } from "hazo_connect";
|
|
2
|
+
export interface CreateTestPostgrestAdapterOptions {
|
|
3
|
+
/** Defaults to `process.env.POSTGREST_URL`. */
|
|
4
|
+
base_url?: string;
|
|
5
|
+
/** Defaults to `process.env.POSTGREST_API_KEY`. */
|
|
6
|
+
api_key?: string;
|
|
7
|
+
logger?: Logger;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Returns a hazo_connect PostgREST adapter pointed at the test database
|
|
11
|
+
* identified by `POSTGREST_URL` / `POSTGREST_API_KEY` (or the equivalent
|
|
12
|
+
* options, which take precedence over the env vars).
|
|
13
|
+
*
|
|
14
|
+
* This factory does NOT perform the truncate safety check — it just builds
|
|
15
|
+
* a connection. Combine with `assertSafeToTruncate` / `truncatePostgrestTables`
|
|
16
|
+
* before running any destructive operation.
|
|
17
|
+
*/
|
|
18
|
+
export declare function createTestPostgrestAdapter(opts?: CreateTestPostgrestAdapterOptions): HazoConnectAdapter;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
// src/db/create_test_postgrest_adapter.ts
|
|
2
|
+
// Purpose: factory for a hazo_connect PostgREST adapter configured for
|
|
3
|
+
// integration tests against a remote test database (e.g. Faraday's
|
|
4
|
+
// `faraday_test`), read from env vars. Mirrors the env-reading style of
|
|
5
|
+
// hazo_connect's own `createHazoConnectFromEnv` (hazo_connect/nextjs/setup)
|
|
6
|
+
// but is PostgREST-only and lives here so hazo_testing consumers don't need
|
|
7
|
+
// to depend on the nextjs sub-export just to stand up a test adapter.
|
|
8
|
+
import { createHazoConnect } from "hazo_connect/server";
|
|
9
|
+
import { MissingPostgrestTestConfig } from "../errors.js";
|
|
10
|
+
/**
|
|
11
|
+
* Returns a hazo_connect PostgREST adapter pointed at the test database
|
|
12
|
+
* identified by `POSTGREST_URL` / `POSTGREST_API_KEY` (or the equivalent
|
|
13
|
+
* options, which take precedence over the env vars).
|
|
14
|
+
*
|
|
15
|
+
* This factory does NOT perform the truncate safety check — it just builds
|
|
16
|
+
* a connection. Combine with `assertSafeToTruncate` / `truncatePostgrestTables`
|
|
17
|
+
* before running any destructive operation.
|
|
18
|
+
*/
|
|
19
|
+
export function createTestPostgrestAdapter(opts = {}) {
|
|
20
|
+
const base_url = opts.base_url ?? process.env.POSTGREST_URL ?? "";
|
|
21
|
+
const api_key = opts.api_key ?? process.env.POSTGREST_API_KEY ?? "";
|
|
22
|
+
if (!base_url) {
|
|
23
|
+
throw new MissingPostgrestTestConfig("POSTGREST_URL");
|
|
24
|
+
}
|
|
25
|
+
if (!api_key) {
|
|
26
|
+
throw new MissingPostgrestTestConfig("POSTGREST_API_KEY");
|
|
27
|
+
}
|
|
28
|
+
return createHazoConnect({
|
|
29
|
+
type: "postgrest",
|
|
30
|
+
postgrest: { base_url, api_key },
|
|
31
|
+
logger: opts.logger,
|
|
32
|
+
});
|
|
33
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export interface TruncateGuardOptions {
|
|
2
|
+
/**
|
|
3
|
+
* Explicit opt-in. Defaults to `process.env.HAZO_TESTING_ALLOW_TRUNCATE === "true"`
|
|
4
|
+
* when not passed. Passing this overrides the env var entirely (does not merge).
|
|
5
|
+
*/
|
|
6
|
+
allowTruncate?: boolean;
|
|
7
|
+
/**
|
|
8
|
+
* Explicit PostgREST base URL to check for a "test" substring. Defaults to
|
|
9
|
+
* `process.env.POSTGREST_URL` when not passed.
|
|
10
|
+
*/
|
|
11
|
+
postgrestUrl?: string;
|
|
12
|
+
/**
|
|
13
|
+
* Explicit DB/schema name to check for a "test" substring. Defaults to
|
|
14
|
+
* `process.env.HAZO_TESTING_DB_NAME` when not passed.
|
|
15
|
+
*/
|
|
16
|
+
dbName?: string;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Throws `UnsafeTruncateTarget` unless BOTH:
|
|
20
|
+
* - an explicit opt-in is set (option or env var), AND
|
|
21
|
+
* - the db name and/or PostgREST URL identify the target as a test database.
|
|
22
|
+
* Synchronous, side-effect free besides throwing — safe to call before any
|
|
23
|
+
* adapter/network call.
|
|
24
|
+
*/
|
|
25
|
+
export declare function assertSafeToTruncate(opts?: TruncateGuardOptions): void;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// src/db/postgrest_guard.ts
|
|
2
|
+
// Purpose: safety-critical guard for destructive PostgREST test-db operations
|
|
3
|
+
// (currently: truncatePostgrestTables). Deliberately NOT gated on NODE_ENV
|
|
4
|
+
// (see CLAUDE.md) — NODE_ENV is set to "test" by test runners but says
|
|
5
|
+
// nothing about which *database* a PostgREST URL actually points at.
|
|
6
|
+
//
|
|
7
|
+
// Two independent conditions are both required (defense in depth):
|
|
8
|
+
// 1. An explicit opt-in: HAZO_TESTING_ALLOW_TRUNCATE=true (or
|
|
9
|
+
// { allowTruncate: true } passed directly).
|
|
10
|
+
// 2. A test-identity check: HAZO_TESTING_DB_NAME or the PostgREST URL
|
|
11
|
+
// (POSTGREST_URL, or { dbName } / { postgrestUrl } passed directly)
|
|
12
|
+
// must contain "test" (case-insensitive substring match).
|
|
13
|
+
// Either condition missing — or satisfied by only one of the two — refuses.
|
|
14
|
+
// The check runs synchronously and throws before any request is made.
|
|
15
|
+
import { UnsafeTruncateTarget } from "../errors.js";
|
|
16
|
+
function containsTest(value) {
|
|
17
|
+
return value.toLowerCase().includes("test");
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Throws `UnsafeTruncateTarget` unless BOTH:
|
|
21
|
+
* - an explicit opt-in is set (option or env var), AND
|
|
22
|
+
* - the db name and/or PostgREST URL identify the target as a test database.
|
|
23
|
+
* Synchronous, side-effect free besides throwing — safe to call before any
|
|
24
|
+
* adapter/network call.
|
|
25
|
+
*/
|
|
26
|
+
export function assertSafeToTruncate(opts = {}) {
|
|
27
|
+
const allowTruncate = opts.allowTruncate ?? process.env.HAZO_TESTING_ALLOW_TRUNCATE === "true";
|
|
28
|
+
if (!allowTruncate) {
|
|
29
|
+
throw new UnsafeTruncateTarget('Refusing to truncate: HAZO_TESTING_ALLOW_TRUNCATE is not set to "true" (and allowTruncate: true was not passed explicitly). This guard requires an explicit opt-in before running any destructive operation against a PostgREST database.');
|
|
30
|
+
}
|
|
31
|
+
const dbName = opts.dbName ?? process.env.HAZO_TESTING_DB_NAME ?? "";
|
|
32
|
+
const postgrestUrl = opts.postgrestUrl ?? process.env.POSTGREST_URL ?? "";
|
|
33
|
+
const looksLikeTestDatabase = containsTest(dbName) || containsTest(postgrestUrl);
|
|
34
|
+
if (!looksLikeTestDatabase) {
|
|
35
|
+
throw new UnsafeTruncateTarget(`Refusing to truncate: neither HAZO_TESTING_DB_NAME ("${dbName || "(unset)"}") nor the PostgREST URL ("${postgrestUrl || "(unset)"}") contains "test". Point this at a database whose name or URL unambiguously identifies it as a test database — the opt-in flag alone is not enough.`);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { HazoConnectAdapter } from "hazo_connect";
|
|
2
|
+
/** Map of table name -> rows to insert into that table. */
|
|
3
|
+
export type PostgrestSeedRows = Record<string, Array<Record<string, unknown>>>;
|
|
4
|
+
/** Map of table name -> the rows hazo_connect reports as inserted (with generated ids, defaults, etc). */
|
|
5
|
+
export type PostgrestSeedResult = Record<string, Array<Record<string, unknown>>>;
|
|
6
|
+
/**
|
|
7
|
+
* Insert fixture rows into one or more tables via `adapter`, one request per
|
|
8
|
+
* non-empty table (hazo_connect's `insert()` accepts an array, so a table
|
|
9
|
+
* with multiple rows is still a single POST). Tables with an empty row array
|
|
10
|
+
* are skipped without making any request.
|
|
11
|
+
*
|
|
12
|
+
* @param adapter - A hazo_connect adapter configured for the target database
|
|
13
|
+
* (typically from `createTestPostgrestAdapter`).
|
|
14
|
+
* @param rows - `{ [table]: rows[] }` — rows to insert per table.
|
|
15
|
+
* @returns `{ [table]: insertedRows[] }` as reported back by PostgREST.
|
|
16
|
+
*/
|
|
17
|
+
export declare function seedPostgrestRows(adapter: HazoConnectAdapter, rows: PostgrestSeedRows): Promise<PostgrestSeedResult>;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// src/db/postgrest_seed.ts
|
|
2
|
+
// Purpose: seed fixture rows into named tables via a hazo_connect PostgREST
|
|
3
|
+
// adapter. Delegates row insertion entirely to hazo_connect's own
|
|
4
|
+
// createCrudService().insert() (POST with Prefer: return=representation) —
|
|
5
|
+
// no hand-rolled request building here.
|
|
6
|
+
import { createCrudService } from "hazo_connect/server";
|
|
7
|
+
/**
|
|
8
|
+
* Insert fixture rows into one or more tables via `adapter`, one request per
|
|
9
|
+
* non-empty table (hazo_connect's `insert()` accepts an array, so a table
|
|
10
|
+
* with multiple rows is still a single POST). Tables with an empty row array
|
|
11
|
+
* are skipped without making any request.
|
|
12
|
+
*
|
|
13
|
+
* @param adapter - A hazo_connect adapter configured for the target database
|
|
14
|
+
* (typically from `createTestPostgrestAdapter`).
|
|
15
|
+
* @param rows - `{ [table]: rows[] }` — rows to insert per table.
|
|
16
|
+
* @returns `{ [table]: insertedRows[] }` as reported back by PostgREST.
|
|
17
|
+
*/
|
|
18
|
+
export async function seedPostgrestRows(adapter, rows) {
|
|
19
|
+
const inserted = {};
|
|
20
|
+
for (const [table, tableRows] of Object.entries(rows)) {
|
|
21
|
+
if (!tableRows || tableRows.length === 0) {
|
|
22
|
+
inserted[table] = [];
|
|
23
|
+
continue;
|
|
24
|
+
}
|
|
25
|
+
const svc = createCrudService(adapter, table);
|
|
26
|
+
inserted[table] = await svc.insert(tableRows);
|
|
27
|
+
}
|
|
28
|
+
return inserted;
|
|
29
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { HazoConnectAdapter } from "hazo_connect";
|
|
2
|
+
import { type TruncateGuardOptions } from "./postgrest_guard.js";
|
|
3
|
+
export interface TruncatePostgrestTablesOptions extends TruncateGuardOptions {
|
|
4
|
+
/**
|
|
5
|
+
* Primary-key column used to build the delete-all filter
|
|
6
|
+
* (`<idColumn>=not.is.null`). Defaults to `"id"`, matching the hazo_*
|
|
7
|
+
* convention (every hazo_* DDL table has an `id` primary key). Override
|
|
8
|
+
* for a table with a differently-named primary key.
|
|
9
|
+
*/
|
|
10
|
+
idColumn?: string;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Deletes every row from each named table via `adapter`, refusing to run
|
|
14
|
+
* unless `assertSafeToTruncate` passes (checked once, before any table is
|
|
15
|
+
* touched — a later table's delete never starts if the guard would have
|
|
16
|
+
* refused).
|
|
17
|
+
*
|
|
18
|
+
* @param adapter - A hazo_connect adapter configured for the target database.
|
|
19
|
+
* @param tables - Table names to truncate, in order.
|
|
20
|
+
* @param opts - Guard options (`allowTruncate`, `dbName`, `postgrestUrl`) plus `idColumn`.
|
|
21
|
+
*/
|
|
22
|
+
export declare function truncatePostgrestTables(adapter: HazoConnectAdapter, tables: string[], opts?: TruncatePostgrestTablesOptions): Promise<void>;
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// src/db/postgrest_truncate.ts
|
|
2
|
+
// Purpose: clear a named set of tables between integration tests, via a
|
|
3
|
+
// hazo_connect PostgREST adapter. Gated by assertSafeToTruncate() — see
|
|
4
|
+
// postgrest_guard.ts for the safety design. PostgREST has no native TRUNCATE
|
|
5
|
+
// endpoint, so this issues one DELETE per table with an `<idColumn>=not.is.null`
|
|
6
|
+
// filter (every row has a non-null primary key, so this matches all rows).
|
|
7
|
+
// hazo_connect's QueryBuilder 'is' operator with a non-null value already
|
|
8
|
+
// serializes to exactly that filter (see postgrest-adapter.ts buildPostgrestUrl).
|
|
9
|
+
import { createTableQuery } from "hazo_connect/server";
|
|
10
|
+
import { assertSafeToTruncate } from "./postgrest_guard.js";
|
|
11
|
+
/**
|
|
12
|
+
* Deletes every row from each named table via `adapter`, refusing to run
|
|
13
|
+
* unless `assertSafeToTruncate` passes (checked once, before any table is
|
|
14
|
+
* touched — a later table's delete never starts if the guard would have
|
|
15
|
+
* refused).
|
|
16
|
+
*
|
|
17
|
+
* @param adapter - A hazo_connect adapter configured for the target database.
|
|
18
|
+
* @param tables - Table names to truncate, in order.
|
|
19
|
+
* @param opts - Guard options (`allowTruncate`, `dbName`, `postgrestUrl`) plus `idColumn`.
|
|
20
|
+
*/
|
|
21
|
+
export async function truncatePostgrestTables(adapter, tables, opts = {}) {
|
|
22
|
+
assertSafeToTruncate(opts);
|
|
23
|
+
const idColumn = opts.idColumn ?? "id";
|
|
24
|
+
for (const table of tables) {
|
|
25
|
+
await createTableQuery(adapter, table).where(idColumn, "is", true).execute("DELETE");
|
|
26
|
+
}
|
|
27
|
+
}
|
package/dist/errors.d.ts
CHANGED
|
@@ -5,3 +5,21 @@ export declare class DockerNotSupported extends HazoError {
|
|
|
5
5
|
export declare class UnmappedLlmCall extends HazoError {
|
|
6
6
|
constructor(template: string);
|
|
7
7
|
}
|
|
8
|
+
/**
|
|
9
|
+
* Thrown by `truncatePostgrestTables` (via `assertSafeToTruncate`) whenever
|
|
10
|
+
* the destructive-operation guard refuses to run — either the explicit
|
|
11
|
+
* opt-in env var / option is missing, or the target's db-name/URL does not
|
|
12
|
+
* identify it as a test database. Thrown synchronously, before any network
|
|
13
|
+
* request is made.
|
|
14
|
+
*/
|
|
15
|
+
export declare class UnsafeTruncateTarget extends HazoError {
|
|
16
|
+
constructor(message: string);
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Thrown by `createTestPostgrestAdapter` when neither an explicit option nor
|
|
20
|
+
* the corresponding env var (`POSTGREST_URL` / `POSTGREST_API_KEY`) supplies
|
|
21
|
+
* required PostgREST connection config.
|
|
22
|
+
*/
|
|
23
|
+
export declare class MissingPostgrestTestConfig extends HazoError {
|
|
24
|
+
constructor(envVar: string);
|
|
25
|
+
}
|
package/dist/errors.js
CHANGED
|
@@ -20,3 +20,33 @@ export class UnmappedLlmCall extends HazoError {
|
|
|
20
20
|
});
|
|
21
21
|
}
|
|
22
22
|
}
|
|
23
|
+
/**
|
|
24
|
+
* Thrown by `truncatePostgrestTables` (via `assertSafeToTruncate`) whenever
|
|
25
|
+
* the destructive-operation guard refuses to run — either the explicit
|
|
26
|
+
* opt-in env var / option is missing, or the target's db-name/URL does not
|
|
27
|
+
* identify it as a test database. Thrown synchronously, before any network
|
|
28
|
+
* request is made.
|
|
29
|
+
*/
|
|
30
|
+
export class UnsafeTruncateTarget extends HazoError {
|
|
31
|
+
constructor(message) {
|
|
32
|
+
super({
|
|
33
|
+
code: "HAZO_TESTING_UNSAFE_TRUNCATE_TARGET",
|
|
34
|
+
pkg: "hazo_testing",
|
|
35
|
+
message,
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Thrown by `createTestPostgrestAdapter` when neither an explicit option nor
|
|
41
|
+
* the corresponding env var (`POSTGREST_URL` / `POSTGREST_API_KEY`) supplies
|
|
42
|
+
* required PostgREST connection config.
|
|
43
|
+
*/
|
|
44
|
+
export class MissingPostgrestTestConfig extends HazoError {
|
|
45
|
+
constructor(envVar) {
|
|
46
|
+
super({
|
|
47
|
+
code: "HAZO_TESTING_MISSING_POSTGREST_CONFIG",
|
|
48
|
+
pkg: "hazo_testing",
|
|
49
|
+
message: `createTestPostgrestAdapter: ${envVar} is not set and was not passed as an option. Set it in the environment or pass it explicitly.`,
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,18 @@
|
|
|
1
|
-
export declare const HAZO_TESTING_VERSION = "0.
|
|
1
|
+
export declare const HAZO_TESTING_VERSION = "0.7.0";
|
|
2
2
|
export declare const t: import("hazo_core/i18n").TFunc;
|
|
3
|
-
export { DockerNotSupported, UnmappedLlmCall } from "./errors.js";
|
|
3
|
+
export { DockerNotSupported, UnmappedLlmCall, UnsafeTruncateTarget, MissingPostgrestTestConfig } from "./errors.js";
|
|
4
4
|
export { augmentAdapter } from "./db/augmented_adapter.js";
|
|
5
5
|
export type { AugmentedAdapter } from "./db/augmented_adapter.js";
|
|
6
6
|
export { createTestDatabase, createTestDatabaseSqlite, createTestDatabaseDocker, } from "./db/test_database.js";
|
|
7
7
|
export type { CreateTestDatabaseOptions, TestDatabase } from "./db/test_database.js";
|
|
8
|
+
export { createTestPostgrestAdapter } from "./db/create_test_postgrest_adapter.js";
|
|
9
|
+
export type { CreateTestPostgrestAdapterOptions } from "./db/create_test_postgrest_adapter.js";
|
|
10
|
+
export { seedPostgrestRows } from "./db/postgrest_seed.js";
|
|
11
|
+
export type { PostgrestSeedRows, PostgrestSeedResult } from "./db/postgrest_seed.js";
|
|
12
|
+
export { truncatePostgrestTables } from "./db/postgrest_truncate.js";
|
|
13
|
+
export type { TruncatePostgrestTablesOptions } from "./db/postgrest_truncate.js";
|
|
14
|
+
export { assertSafeToTruncate } from "./db/postgrest_guard.js";
|
|
15
|
+
export type { TruncateGuardOptions } from "./db/postgrest_guard.js";
|
|
8
16
|
export { createTestUser } from "./factories/users.js";
|
|
9
17
|
export type { CreateTestUserOptions, TestUser } from "./factories/users.js";
|
|
10
18
|
export { createTestScope } from "./factories/scopes.js";
|
package/dist/index.js
CHANGED
|
@@ -2,16 +2,20 @@
|
|
|
2
2
|
// hazo_testing public server barrel.
|
|
3
3
|
import en from "./locales/en.json" with { type: "json" };
|
|
4
4
|
import { createPackageT } from "hazo_core/i18n";
|
|
5
|
-
export const HAZO_TESTING_VERSION = "0.
|
|
5
|
+
export const HAZO_TESTING_VERSION = "0.7.0";
|
|
6
6
|
// Module-scope translator — see hazo_core/i18n's createPackageT. hazo_testing
|
|
7
7
|
// is a zero-string package today (dev/test infra, no rendered UI text); this
|
|
8
8
|
// is future-proofing plumbing so a real catalog can be dropped in later
|
|
9
9
|
// without touching call sites. English-only consumers (no hazo_i18n
|
|
10
10
|
// installed) see no behavior change.
|
|
11
11
|
export const t = createPackageT("hazo_testing", en);
|
|
12
|
-
export { DockerNotSupported, UnmappedLlmCall } from "./errors.js";
|
|
12
|
+
export { DockerNotSupported, UnmappedLlmCall, UnsafeTruncateTarget, MissingPostgrestTestConfig } from "./errors.js";
|
|
13
13
|
export { augmentAdapter } from "./db/augmented_adapter.js";
|
|
14
14
|
export { createTestDatabase, createTestDatabaseSqlite, createTestDatabaseDocker, } from "./db/test_database.js";
|
|
15
|
+
export { createTestPostgrestAdapter } from "./db/create_test_postgrest_adapter.js";
|
|
16
|
+
export { seedPostgrestRows } from "./db/postgrest_seed.js";
|
|
17
|
+
export { truncatePostgrestTables } from "./db/postgrest_truncate.js";
|
|
18
|
+
export { assertSafeToTruncate } from "./db/postgrest_guard.js";
|
|
15
19
|
export { createTestUser } from "./factories/users.js";
|
|
16
20
|
export { createTestScope } from "./factories/scopes.js";
|
|
17
21
|
export { wireHazoJobs } from "./wiring/jobs.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hazo_testing",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Shared test infrastructure for hazo apps: SQLite test DB, real-package wiring, auth factories, apiTestClient, fixtures, Jest + Vitest presets.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -93,13 +93,13 @@
|
|
|
93
93
|
"peerDependencies": {
|
|
94
94
|
"@playwright/test": "^1.0.0",
|
|
95
95
|
"@testing-library/react": "^16.0.0",
|
|
96
|
-
"hazo_auth": "^10.
|
|
97
|
-
"hazo_connect": "^4.3.
|
|
98
|
-
"hazo_core": "^2.
|
|
99
|
-
"hazo_i18n": "^0.
|
|
100
|
-
"hazo_jobs": "^0.
|
|
101
|
-
"hazo_llm_api": "^2.
|
|
102
|
-
"hazo_notify": "^
|
|
96
|
+
"hazo_auth": "^10.32.0",
|
|
97
|
+
"hazo_connect": "^4.3.5",
|
|
98
|
+
"hazo_core": "^2.5.0",
|
|
99
|
+
"hazo_i18n": "^0.17.0",
|
|
100
|
+
"hazo_jobs": "^0.21.0",
|
|
101
|
+
"hazo_llm_api": "^2.9.0",
|
|
102
|
+
"hazo_notify": "^7.1.0",
|
|
103
103
|
"next": "^14.0.0 || ^16.0.0",
|
|
104
104
|
"next-intl": "^4.13.0",
|
|
105
105
|
"react": "^18.0.0 || ^19.0.0",
|