Add “assert.throws” and “assert.rejects”.

In general, we only support a _strict_ subset of the `node:assert`
interface. We aim to support things that are genuinely tricky to encode
yourself or are genuinely annoying to write over-and-over in your own
test code (e.g., try-catch around throws / rejections).

This brings our assert interface to:

- `assert(value[, message])`
- `assert.deepEqual(actual, expected[, message])`
- `assert.rejects(asyncFn[, error][, message])`
- `assert.throws(fn[, error][, message])`

It’s not clear that we really need more than this. Everything else is
either esoteric (e.g., `ifError`), an inverse (e.g., `notDeepEqual`),
trivially implemented by other means (e.g., `match`), or literally just
an alias for something else (e.g., `ok`).

We may choose to flesh some more things out simply for agents trying to
do pattern matching… but it all ends up being surface area to maintain.

Author: theengineear

CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `assert.throws(fn, error, message?)` and `assert.rejects(fn, error, message?)`
+  for asserting that a function throws or an async function rejects. The `error`
+  argument is a `RegExp` tested against `String(thrown)` (consistent with
+  `node:assert`) (#99).
+
 ## [2.0.0-rc.10] - 2026-04-28
 
 ### Changed

README.md

@@ -19,6 +19,14 @@ suite('important feature', () => {
   test('should match interface', () => {
     assert.deepEqual(MyFeature.interface, { version: '123' }, 'does not match');
   });
+
+  test('should throw on bad input', () => {
+    assert.throws(() => MyFeature.doThing(null), /^Error: bad input$/);
+  });
+
+  test('should reject on bad async input', async () => {
+    await assert.rejects(() => MyFeature.doThingAsync(null), /^Error: bad input$/);
+  });
 });
 ```
 
@@ -47,6 +55,8 @@ The following are exposed in the testing interface:
 - `suite.todo`: Mark all `test` tests within this group as _todo_.
 - `assert`: Simple assertion call that throws if the boolean input is false-y.
 - `assert.deepEqual`: Strict deep-equality assertion for primitives, plain objects, and arrays.
+- `assert.throws`: Asserts that a function throws, matching the thrown value against a RegExp.
+- `assert.rejects`: Asserts that an async function rejects, matching the rejection against a RegExp.
 
 ### Parameters
 

test/shared.js

@@ -619,6 +619,79 @@ suite('deepEqual', () => {
   });
 });
 
+suite('throws', () => {
+  const makeContext = () => ({ state: { bailed: false } });
+  const expectFail = (fn) => {
+    let message;
+    try { fn(); } catch (error) { message = error.message; }
+    return message;
+  };
+
+  test('fails when function does not throw', () => {
+    const message = expectFail(() => XTestFrame.throws(makeContext(), null, () => {}, /foo/));
+    assert(message === 'expected function to throw');
+  });
+
+  test('passes when RegExp matches', () => {
+    XTestFrame.throws(makeContext(), null, () => { throw new Error('boom'); }, /boom/);
+  });
+
+  test('fails when RegExp does not match', () => {
+    const message = expectFail(() => XTestFrame.throws(makeContext(), null, () => { throw new Error('boom'); }, /nope/));
+    assert(message === 'expected thrown value to match "/nope/"');
+  });
+
+  test('uses custom message on failure', () => {
+    const message = expectFail(() => XTestFrame.throws(makeContext(), null, () => {}, /foo/, 'custom'));
+    assert(message === 'custom');
+  });
+
+  test('matches non-Error throws via String()', () => {
+    XTestFrame.throws(makeContext(), null, () => { throw 2; }, /2/);
+    XTestFrame.throws(makeContext(), null, () => { throw undefined; }, /undefined/);
+  });
+
+  test('is a no-op when context is bailed', () => {
+    XTestFrame.throws({ state: { bailed: true } }, null, () => {}, /anything/, 'should not throw');
+  });
+});
+
+suite('rejects', () => {
+  const makeContext = () => ({ state: { bailed: false } });
+  const expectFail = async (fn) => {
+    let message;
+    try { await fn(); } catch (error) { message = error.message; }
+    return message;
+  };
+
+  test('fails when function does not reject', async () => {
+    const message = await expectFail(() => XTestFrame.rejects(makeContext(), null, async () => {}, /foo/));
+    assert(message === 'expected function to reject');
+  });
+
+  test('passes when RegExp matches', async () => {
+    await XTestFrame.rejects(makeContext(), null, async () => { throw new Error('boom'); }, /boom/);
+  });
+
+  test('fails when RegExp does not match', async () => {
+    const message = await expectFail(() => XTestFrame.rejects(makeContext(), null, async () => { throw new Error('boom'); }, /nope/));
+    assert(message === 'expected rejection value to match "/nope/"');
+  });
+
+  test('uses custom message on failure', async () => {
+    const message = await expectFail(() => XTestFrame.rejects(makeContext(), null, async () => {}, /foo/, 'custom'));
+    assert(message === 'custom');
+  });
+
+  test('works with a function returning a rejected Promise', async () => {
+    await XTestFrame.rejects(makeContext(), null, () => Promise.reject(new Error('boom')), /boom/);
+  });
+
+  test('is a no-op when context is bailed', async () => {
+    await XTestFrame.rejects({ state: { bailed: true } }, null, async () => {}, /anything/, 'should not throw');
+  });
+});
+
 suite('bail', () => {
   test('marks state as ended', () => {
     const error = new Error('error test');

test/test-frame.js

@@ -1,6 +1,5 @@
 import { test, suite, assert } from '../x-test.js';
 import { XTestRoot } from '../x-test-root.js';
-import { assertThrows } from './shared.js';
 
 // Dependency injection.
 const getContext = () => {
@@ -170,7 +169,8 @@ suite('onDefer', () => {
   test('throws on unknown defer type', () => {
     const { context } = getContext();
     const event = { data: { data: { type: 'unknown' } } };
-    assertThrows(() => XTestRoot.onDefer(context, event), /Unexpected defer type "unknown"\./);
+    const fn = () => XTestRoot.onDefer(context, event);
+    assert.throws(fn, /Unexpected defer type "unknown"\./);
   });
 });
 
@@ -207,7 +207,8 @@ suite('handleEmptyPlan', () => {
   test('throws when no subtest line is in the queue', () => {
     const { context } = getContext();
     context.state.queue = [];
-    assertThrows(() => XTestRoot.handleEmptyPlan(context), /Expected to find matching subtest/);
+    const fn = () => XTestRoot.handleEmptyPlan(context);
+    assert.throws(fn, /Expected to find matching subtest/);
   });
 });
 
@@ -336,7 +337,8 @@ suite('handleFilteredOutput', () => {
     context.state.queue = [];
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.handleFilteredOutput(context, [], 's'), /Unexpected step type "unknown"/);
+    const fn = () => XTestRoot.handleFilteredOutput(context, [], 's');
+    assert.throws(fn, /Unexpected step type "unknown"/);
   });
 });
 
@@ -347,7 +349,8 @@ suite('onResult', () => {
     context.state.stepIds.push('ts');
     context.state.steps['ts'] = { type: 'test', testId: 't', status: 'waiting' };
     const event = { data: { data: { testId: 't' } } };
-    assertThrows(() => XTestRoot.onResult(context, event), /step to complete is not running/);
+    const fn = () => XTestRoot.onResult(context, event);
+    assert.throws(fn, /step to complete is not running/);
   });
 });
 
@@ -368,7 +371,8 @@ suite('onReady', () => {
     context.state.frames['f'] = { href: 'http://test.html', children: [] };
     context.state.stepIds.push('fs');
     context.state.steps['fs'] = { type: 'frame-start', frameId: 'f', status: 'waiting' };
-    assertThrows(() => XTestRoot.onReady(context, { data: { data: { frameId: 'f' } } }), /frame to ready is not running/);
+    const fn = () => XTestRoot.onReady(context, { data: { data: { frameId: 'f' } } });
+    assert.throws(fn, /frame to ready is not running/);
   });
 
   test('inherits suite directive onto tests without one', () => {
@@ -387,7 +391,8 @@ suite('onRegister', () => {
   test('throws on unknown registration type', () => {
     const { context } = getContext();
     const event = { data: { data: { type: 'unknown' } } };
-    assertThrows(() => XTestRoot.onRegister(context, event), /Unexpected registration type "unknown"\./);
+    const fn = () => XTestRoot.onRegister(context, event);
+    assert.throws(fn, /Unexpected registration type "unknown"\./);
   });
 });
 
@@ -470,7 +475,8 @@ suite('registerTest', () => {
 suite('childOk', () => {
   test('throws on unknown child type', () => {
     const { context } = getContext();
-    assertThrows(() => XTestRoot.childOk(context, { type: 'unknown' }), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.childOk(context, { type: 'unknown' });
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -479,7 +485,8 @@ suite('href', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.href(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.href(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -488,7 +495,8 @@ suite('directive', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.directive(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.directive(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -497,7 +505,8 @@ suite('level', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.level(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.level(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -506,7 +515,8 @@ suite('count', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.count(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.count(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -515,7 +525,8 @@ suite('yaml', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.yaml(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.yaml(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -524,7 +535,8 @@ suite('text', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.text(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.text(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -533,7 +545,8 @@ suite('number', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.number(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.number(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 
   test('returns position for a test whose direct parent is a frame', () => {
@@ -551,7 +564,8 @@ suite('ok', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown' };
-    assertThrows(() => XTestRoot.ok(context, 's'), /Unexpected type "unknown"/);
+    const fn = () => XTestRoot.ok(context, 's');
+    assert.throws(fn, /Unexpected type "unknown"/);
   });
 });
 
@@ -569,7 +583,8 @@ suite('check', () => {
     const { context } = getContext();
     context.state.stepIds.push('s');
     context.state.steps['s'] = { type: 'unknown', status: 'waiting' };
-    assertThrows(() => XTestRoot.check(context), /Unexpected step type "unknown"/);
+    const fn = () => XTestRoot.check(context);
+    assert.throws(fn, /Unexpected step type "unknown"/);
   });
 
   test('does not kick off the exit step once the run has ended (e.g. after a bail)', () => {

test/test-root.js

@@ -33,6 +33,18 @@ suite.only('assert.deepEqual', () => {
   });
 });
 
+suite.only('assert.throws', () => {
+  test('exercises the public assert.throws export', () => {
+    assert.throws(() => { throw new Error('boom'); }, /boom/);
+  });
+});
+
+suite.only('assert.rejects', () => {
+  test('exercises the public assert.rejects export', async () => {
+    await assert.rejects(async () => { throw new Error('boom'); }, /boom/);
+  });
+});
+
 suite.only('interval', () => {
   test.todo('times out after interval - this is supposed to fail', async () => {
     await new Promise(resolve => setTimeout(resolve, 1_000));

test/test-scratch.js

@@ -13,6 +13,28 @@ export namespace assert {
      * @returns {asserts actual is T} Throws if values are not deeply equal.
      */
     function deepEqual<T>(actual: unknown, expected: T, message?: string): asserts actual is T;
+    /**
+     * Asserts that a function throws, testing the thrown value against a RegExp via `String(thrown)`.
+     * @example
+     *   assert.throws(() => { throw new Error('boom'); }, /^Error: boom$/);
+     *   assert.throws(() => { throw new Error('boom'); }, new RegExp('.*')); // match anything — just assert it throws
+     * @param {() => void} fn - The function expected to throw
+     * @param {RegExp} error - Tested against `String(thrown)`
+     * @param {string} [message] - The assertion message
+     * @returns {void}
+     */
+    function throws(fn: () => void, error: RegExp, message?: string): void;
+    /**
+     * Asserts that an async function rejects, testing the rejection against a RegExp via `String(thrown)`.
+     * @example
+     *   await assert.rejects(async () => { throw new Error('boom'); }, /^Error: boom$/);
+     *   await assert.rejects(() => Promise.reject(new Error('boom')), new RegExp('.*')); // match anything — just assert it rejects
+     * @param {() => Promise<unknown>} fn - The function expected to reject
+     * @param {RegExp} error - Tested against `String(thrown)`
+     * @param {string} [message] - The assertion message
+     * @returns {Promise<void>}
+     */
+    function rejects(fn: () => Promise<unknown>, error: RegExp, message?: string): Promise<void>;
 }
 export function load(href: string): void;
 export function suite(text: string, callback: () => void): void;