pgsql-test 5.18.0 → 5.19.0

package/README.md

@@ -131,6 +131,7 @@ The `PgTestClient` returned by `getConnections()` wraps a `pg.Client` and provid
 * `beforeEach()` – Begins a transaction and sets a savepoint (called at the start of each test)
 * `afterEach()` – Rolls back to the savepoint and commits the outer transaction (cleans up test state)
 * `setContext({ key: value })` – Sets PostgreSQL config variables (like `role`) to simulate RLS contexts
+* `expectError(run, expected?)` – Asserts `run` fails (message substring/RegExp, or `{ code, message }`) inside a savepoint, so the transaction stays usable afterwards; resolves to the caught error (see [Expected failures](#expected-failures))
 * `checkConstraints()` – Runs the commit-time checks for any pending deferred constraints now, without committing (see [Deferred constraints](#deferred-constraints-under-rollback-isolation))
 * `any`, `one`, `oneOrNone`, `many`, `manyOrNone`, `none`, `result` – Typed query helpers for specific result expectations
 
@@ -604,6 +605,26 @@ This table documents the available options for the `getConnections` function. Th
 | `db.prefix`              | `string`   | `'db-'`          | Prefix used when generating test database names                             |
 | `db.deferredConstraints` | `'off' \| 'check' \| 'immediate'` | `'off'` | How `DEFERRABLE INITIALLY DEFERRED` constraints are handled under rollback isolation (env: `DB_DEFERRED_CONSTRAINTS`). See below. |
 
+### Expected failures
+
+A failed statement aborts the surrounding transaction, so after a plain `expect(...).rejects` every later query in the test fails with `current transaction is aborted`. Use `expectError()` instead — it wraps the call in a savepoint, always rolls back to it, and throws if the call succeeds or fails differently:
+
+```ts
+it('anonymous users cannot write', async () => {
+  db.setContext({ role: 'anonymous' });
+  await db.expectError(() => db.query(`INSERT INTO app.posts (title) VALUES ('x')`), /permission denied/);
+  await db.expectError(() => db.query(`DELETE FROM app.posts`), { code: '42501' });
+
+  const err = await db.expectError(() => db.query(`SELECT app.transfer(-5)`));
+  expect(err.message).toMatch(/^INVALID_AMOUNT/);
+
+  // still usable
+  expect((await db.one(`SELECT count(*) FROM app.posts`)).count).toBe('1');
+});
+```
+
+`expected` is a message substring, a `RegExp`, or `{ code?: string; message?: string | RegExp }` (`code` is the SQLSTATE). Run the statement on the same client you call `expectError` on.
+
 ### Deferred constraints under rollback isolation
 
 `beforeEach()`/`afterEach()` isolate tests by rolling back instead of committing. Anything Postgres only does **at COMMIT** therefore never happens inside a test. The one that bites is `DEFERRABLE INITIALLY DEFERRED` constraints (FK / UNIQUE / EXCLUDE / `CONSTRAINT TRIGGER`): a test can leave a dangling deferred foreign key and still pass, because the check that would have failed the commit is discarded with the rollback. This is inherent to every rollback-based test harness, not specific to pgsql-test.

package/esm/test-client.js

@@ -5,6 +5,37 @@ import { loadSqlFiles } from 'pgsql-seed';
 import { deployPgpm } from 'pgsql-seed';
 import { formatPgError } from './utils';
 const IN_FAILED_SQL_TRANSACTION = '25P02';
+const EXPECT_ERROR_SAVEPOINT = 'pgsql_test_expect_error';
+const describeExpected = (expected) => {
+    if (expected === undefined)
+        return 'an error';
+    if (typeof expected === 'string' || expected instanceof RegExp)
+        return String(expected);
+    return JSON.stringify({
+        code: expected.code,
+        message: expected.message === undefined ? undefined : String(expected.message)
+    });
+};
+const matchesText = (text, pattern) => {
+    if (typeof pattern === 'string')
+        return text.includes(pattern);
+    pattern.lastIndex = 0;
+    return pattern.test(text);
+};
+const describeError = (err) => [err?.code, String(err?.message ?? err).split('\n')[0]].filter(Boolean).join(': ');
+const matchesExpected = (err, expected) => {
+    if (expected === undefined)
+        return true;
+    const message = String(err?.message ?? '');
+    if (typeof expected === 'string' || expected instanceof RegExp) {
+        return matchesText(message, expected);
+    }
+    if (expected.code !== undefined && err?.code !== expected.code)
+        return false;
+    if (expected.message !== undefined && !matchesText(message, expected.message))
+        return false;
+    return true;
+};
 export class PgTestClient extends PgClient {
     testOpts;
     constructor(config, opts = {}) {
@@ -61,6 +92,51 @@ export class PgTestClient extends PgClient {
         if (violation)
             throw violation;
     }
+    /**
+     * Assert that `run` fails, and keep the test transaction usable afterwards.
+     *
+     * Wraps `run` in a savepoint on this client, rolls back to it whatever happens
+     * (so the aborted statement, or an unexpected success, leaves no trace), then
+     * releases it. Throws if `run` succeeds or its error does not match `expected`;
+     * otherwise returns the caught error for further assertions.
+     *
+     * `run` must execute on this same client — a savepoint cannot rescue another
+     * connection's aborted transaction.
+     *
+     * @example
+     * await db.expectError(() => db.query('INSERT INTO app.secrets ...'), /permission denied/);
+     * const err = await db.expectError(() => db.query('...'), { code: '23505' });
+     */
+    async expectError(run, expected) {
+        await this.savepoint(EXPECT_ERROR_SAVEPOINT);
+        let caught;
+        let failed = false;
+        try {
+            await run();
+        }
+        catch (err) {
+            failed = true;
+            caught = err;
+        }
+        try {
+            await this.rollback(EXPECT_ERROR_SAVEPOINT);
+            await this.client.query(`RELEASE SAVEPOINT "${EXPECT_ERROR_SAVEPOINT}";`);
+        }
+        catch (cleanupError) {
+            const outcome = failed ? `run() failed with ${describeError(caught)}` : 'run() succeeded';
+            throw new Error(`[pgsql-test] expectError: could not roll back its savepoint (${describeError(cleanupError)}); ${outcome}. ` +
+                'Did run() end the transaction or run on another client?', { cause: failed ? caught : cleanupError });
+        }
+        if (!failed) {
+            throw new Error(`[pgsql-test] expectError: expected ${describeExpected(expected)}, but the statement succeeded`);
+        }
+        if (!matchesExpected(caught, expected)) {
+            throw new Error(`[pgsql-test] expectError: expected ${describeExpected(expected)}, got ${describeError(caught)}`, {
+                cause: caught
+            });
+        }
+        return caught;
+    }
     /**
      * Run the commit-time checks for every pending deferred constraint now, without committing.
      * Postgres checks all outstanding deferred constraint events when a constraint switches from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-test",
-  "version": "5.18.0",
+  "version": "5.19.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "pgsql-test offers isolated, role-aware, and rollback-friendly PostgreSQL environments for integration tests — giving developers realistic test coverage without external state pollution",
   "main": "index.js",
@@ -68,8 +68,8 @@
     "pg": "^8.21.0",
     "pg-cache": "^3.30.0",
     "pg-env": "^1.33.0",
-    "pgsql-client": "^4.17.0",
+    "pgsql-client": "^4.17.1",
     "pgsql-seed": "^3.16.0"
   },
-  "gitHead": "487c4ec9ee997d7da80584a3d41d7120d4354c54"
+  "gitHead": "0b8a4fa54f658bf3b3a8776b98cc5fb373103ce8"
 }

package/test-client.d.ts

@@ -17,6 +17,14 @@ export type PgTestClientOpts = PgClientOpts & {
      */
     deferredConstraints?: DeferredConstraintsMode;
 };
+/**
+ * What an expected error must match: a substring or RegExp of the message, or
+ * an object checking the SQLSTATE `code` and/or the `message`.
+ */
+export type ExpectedPgError = string | RegExp | {
+    code?: string;
+    message?: string | RegExp;
+};
 export declare class PgTestClient extends PgClient {
     protected testOpts: PgTestClientOpts;
     constructor(config: PgConfig, opts?: PgTestClientOpts);
@@ -33,6 +41,22 @@ export declare class PgTestClient extends PgClient {
     private get deferredConstraintsMode();
     beforeEach(): Promise<void>;
     afterEach(): Promise<void>;
+    /**
+     * Assert that `run` fails, and keep the test transaction usable afterwards.
+     *
+     * Wraps `run` in a savepoint on this client, rolls back to it whatever happens
+     * (so the aborted statement, or an unexpected success, leaves no trace), then
+     * releases it. Throws if `run` succeeds or its error does not match `expected`;
+     * otherwise returns the caught error for further assertions.
+     *
+     * `run` must execute on this same client — a savepoint cannot rescue another
+     * connection's aborted transaction.
+     *
+     * @example
+     * await db.expectError(() => db.query('INSERT INTO app.secrets ...'), /permission denied/);
+     * const err = await db.expectError(() => db.query('...'), { code: '23505' });
+     */
+    expectError<E = any>(run: () => Promise<unknown>, expected?: ExpectedPgError): Promise<E>;
     /**
      * Run the commit-time checks for every pending deferred constraint now, without committing.
      * Postgres checks all outstanding deferred constraint events when a constraint switches from

package/test-client.js

@@ -8,6 +8,37 @@ const pgsql_seed_3 = require("pgsql-seed");
 const pgsql_seed_4 = require("pgsql-seed");
 const utils_1 = require("./utils");
 const IN_FAILED_SQL_TRANSACTION = '25P02';
+const EXPECT_ERROR_SAVEPOINT = 'pgsql_test_expect_error';
+const describeExpected = (expected) => {
+    if (expected === undefined)
+        return 'an error';
+    if (typeof expected === 'string' || expected instanceof RegExp)
+        return String(expected);
+    return JSON.stringify({
+        code: expected.code,
+        message: expected.message === undefined ? undefined : String(expected.message)
+    });
+};
+const matchesText = (text, pattern) => {
+    if (typeof pattern === 'string')
+        return text.includes(pattern);
+    pattern.lastIndex = 0;
+    return pattern.test(text);
+};
+const describeError = (err) => [err?.code, String(err?.message ?? err).split('\n')[0]].filter(Boolean).join(': ');
+const matchesExpected = (err, expected) => {
+    if (expected === undefined)
+        return true;
+    const message = String(err?.message ?? '');
+    if (typeof expected === 'string' || expected instanceof RegExp) {
+        return matchesText(message, expected);
+    }
+    if (expected.code !== undefined && err?.code !== expected.code)
+        return false;
+    if (expected.message !== undefined && !matchesText(message, expected.message))
+        return false;
+    return true;
+};
 class PgTestClient extends pgsql_client_1.PgClient {
     testOpts;
     constructor(config, opts = {}) {
@@ -64,6 +95,51 @@ class PgTestClient extends pgsql_client_1.PgClient {
         if (violation)
             throw violation;
     }
+    /**
+     * Assert that `run` fails, and keep the test transaction usable afterwards.
+     *
+     * Wraps `run` in a savepoint on this client, rolls back to it whatever happens
+     * (so the aborted statement, or an unexpected success, leaves no trace), then
+     * releases it. Throws if `run` succeeds or its error does not match `expected`;
+     * otherwise returns the caught error for further assertions.
+     *
+     * `run` must execute on this same client — a savepoint cannot rescue another
+     * connection's aborted transaction.
+     *
+     * @example
+     * await db.expectError(() => db.query('INSERT INTO app.secrets ...'), /permission denied/);
+     * const err = await db.expectError(() => db.query('...'), { code: '23505' });
+     */
+    async expectError(run, expected) {
+        await this.savepoint(EXPECT_ERROR_SAVEPOINT);
+        let caught;
+        let failed = false;
+        try {
+            await run();
+        }
+        catch (err) {
+            failed = true;
+            caught = err;
+        }
+        try {
+            await this.rollback(EXPECT_ERROR_SAVEPOINT);
+            await this.client.query(`RELEASE SAVEPOINT "${EXPECT_ERROR_SAVEPOINT}";`);
+        }
+        catch (cleanupError) {
+            const outcome = failed ? `run() failed with ${describeError(caught)}` : 'run() succeeded';
+            throw new Error(`[pgsql-test] expectError: could not roll back its savepoint (${describeError(cleanupError)}); ${outcome}. ` +
+                'Did run() end the transaction or run on another client?', { cause: failed ? caught : cleanupError });
+        }
+        if (!failed) {
+            throw new Error(`[pgsql-test] expectError: expected ${describeExpected(expected)}, but the statement succeeded`);
+        }
+        if (!matchesExpected(caught, expected)) {
+            throw new Error(`[pgsql-test] expectError: expected ${describeExpected(expected)}, got ${describeError(caught)}`, {
+                cause: caught
+            });
+        }
+        return caught;
+    }
     /**
      * Run the commit-time checks for every pending deferred constraint now, without committing.
      * Postgres checks all outstanding deferred constraint events when a constraint switches from