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 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.5.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.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.6.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.23.3",
97
- "hazo_connect": "^4.3.2",
98
- "hazo_core": "^2.4.0",
99
- "hazo_i18n": "^0.9.0",
100
- "hazo_jobs": "^0.19.0",
101
- "hazo_llm_api": "^2.6.0",
102
- "hazo_notify": "^6.7.0",
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",