Make assertion validation stricter.

We can always loosen this over time, but trying to reclaim strictness
would cause a major version bump. I think it’s nice when low-level
libraries like a _testing library_ are exceedingly strict / clear about
call site expectations. In my experience, this kind of strictness
typically helps to _catch bugs_.

Author: theengineear

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- All `assert.*` functions now validate their arguments strictly: wrong argument
+  count, wrong types, or a non-string `message` throw immediately with a
+  descriptive error pointing at the call site (#99).
 - `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

test/test-assert.js

@@ -16,6 +16,18 @@ suite('assert', () => {
   test('uses custom message on failure', () => {
     assert.throws(() => assert(false, 'custom'), /^Error: custom$/);
   });
+
+  test('throws if message is not a string', () => {
+    assert.throws(() => assert(false, 42), /^Error: unexpected message, expected string but got "42"$/);
+  });
+
+  test('throws with no arguments', () => {
+    assert.throws(() => assert(), /^Error: expected value to assert, but got none$/);
+  });
+
+  test('throws on extra arguments', () => {
+    assert.throws(() => assert(false, 'msg', 'extra'), /^Error: unexpected extra arguments$/);
+  });
 });
 
 suite('assert.deepEqual', () => {
@@ -41,34 +53,91 @@ suite('assert.deepEqual', () => {
     const sym = Symbol('x');
     assert.throws(() => assert.deepEqual({ [sym]: 1 }, {}), /^Error: deepEqual does not support symbol-keyed properties\.$/);
   });
+
+  test('throws with too few arguments', () => {
+    assert.throws(() => assert.deepEqual(), /^Error: expected actual and expected values, but got too few arguments$/);
+    assert.throws(() => assert.deepEqual(1), /^Error: expected actual and expected values, but got too few arguments$/);
+  });
+
+  test('throws if message is not a string', () => {
+    assert.throws(() => assert.deepEqual(1, 2, 42), /^Error: unexpected message, expected string but got "42"$/);
+  });
+
+  test('throws on extra arguments', () => {
+    assert.throws(() => assert.deepEqual(1, 1, 'msg', 'extra'), /^Error: unexpected extra arguments$/);
+  });
 });
 
 suite('assert.throws', () => {
   test('exercises the public assert.throws export', () => {
     assert.throws(() => { throw new Error('boom'); }, /boom/);
     assert.throws(() => { throw new Error('boom'); }, /^Error: boom$/);
+    assert.throws(() => { throw new Error('boom'); }, /boom/, 'with message');
+  });
+
+  test('throws with too few arguments', () => {
+    assert.throws(() => assert.throws(), /^Error: expected fn and error arguments, but got too few arguments$/);
+    assert.throws(() => assert.throws(() => {}), /^Error: expected fn and error arguments, but got too few arguments$/);
   });
 
   test('throws early if fn is not a function', () => {
-    assert.throws(() => assert.throws('not a function', /boom/), /^Error: unexpected fn value "not a function"$/);
+    assert.throws(() => assert.throws('not a function', /boom/), /^Error: unexpected fn, expected Function but got "not a function"$/);
   });
 
   test('throws early if error is not a RegExp', () => {
-    assert.throws(() => assert.throws(() => {}, 'not a regexp'), /^Error: unexpected error value "not a regexp"$/);
+    assert.throws(() => assert.throws(() => {}, 'not a regexp'), /^Error: unexpected error, expected RegExp but got "not a regexp"$/);
+  });
+
+  test('throws early if fn is not a function with message', () => {
+    assert.throws(() => assert.throws('not a function', /boom/, 'msg'), /^Error: unexpected fn, expected Function but got "not a function"$/);
+  });
+
+  test('throws early if error is not a RegExp with message', () => {
+    assert.throws(() => assert.throws(() => {}, 'not a regexp', 'msg'), /^Error: unexpected error, expected RegExp but got "not a regexp"$/);
+  });
+
+  test('throws if message is not a string', () => {
+    assert.throws(() => assert.throws(() => { throw new Error('boom'); }, /boom/, 42), /^Error: unexpected message, expected string but got "42"$/);
+  });
+
+  test('throws on extra arguments', () => {
+    assert.throws(() => assert.throws(() => {}, /boom/, 'msg', 'extra'), /^Error: unexpected extra arguments$/);
   });
 });
 
 suite('assert.rejects', () => {
   test('exercises the public assert.rejects export', async () => {
     await assert.rejects(async () => { throw new Error('boom'); }, /boom/);
     await assert.rejects(async () => { throw new Error('boom'); }, /^Error: boom$/);
+    await assert.rejects(async () => { throw new Error('boom'); }, /boom/, 'with message');
+  });
+
+  test('throws with too few arguments', async () => {
+    await assert.rejects(() => assert.rejects(), /^Error: expected fn and error arguments, but got too few arguments$/);
+    await assert.rejects(() => assert.rejects(() => {}), /^Error: expected fn and error arguments, but got too few arguments$/);
   });
 
   test('throws early if fn is not a function', async () => {
-    await assert.rejects(() => assert.rejects('not a function', /boom/), /^Error: unexpected fn value "not a function"$/);
+    await assert.rejects(() => assert.rejects('not a function', /boom/), /^Error: unexpected fn, expected Function but got "not a function"$/);
   });
 
   test('throws early if error is not a RegExp', async () => {
-    await assert.rejects(() => assert.rejects(() => {}, 'not a regexp'), /^Error: unexpected error value "not a regexp"$/);
+    await assert.rejects(() => assert.rejects(() => {}, 'not a regexp'), /^Error: unexpected error, expected RegExp but got "not a regexp"$/);
+  });
+
+  test('throws early if fn is not a function with message', async () => {
+    await assert.rejects(() => assert.rejects('not a function', /boom/, 'msg'), /^Error: unexpected fn, expected Function but got "not a function"$/);
+  });
+
+  test('throws early if error is not a RegExp with message', async () => {
+    await assert.rejects(() => assert.rejects(() => {}, 'not a regexp', 'msg'), /^Error: unexpected error, expected RegExp but got "not a regexp"$/);
+  });
+
+  test('throws if message is not a string', async () => {
+    await assert.rejects(() => assert.rejects(async () => { throw new Error('boom'); }, /boom/, 42), /^Error: unexpected message, expected string but got "42"$/);
+  });
+
+  test('throws on extra arguments', async () => {
+    await assert.rejects(() => assert.rejects(async () => {}, /boom/, 'msg', 'extra'), /^Error: unexpected extra arguments$/);
   });
 });

types/x-test.d.ts

@@ -1,4 +1,12 @@
-export function assert(value: unknown, message?: string): asserts value;
+/**
+ * Simple assertion which throws exception when value is not truthy.
+ * @example
+ *   assert('foo' === 'bar', 'foo does not equal bar');
+ * @param {unknown} value - The condition to assert (truthy/falsy)
+ * @param {string} [message] - The assertion message
+ * @returns {asserts value} Throws if condition is falsy or arguments are invalid.
+ */
+export function assert(value: unknown, message?: string, ...args: any[]): asserts value;
 export namespace assert {
     /**
      * Strict deep-equality assertion. Supports primitives, plain objects, and
@@ -10,9 +18,9 @@ export namespace assert {
      * @param {unknown} actual - The actual value
      * @param {T} expected - The expected value
      * @param {string} [message] - The assertion message
-     * @returns {asserts actual is T} Throws if values are not deeply equal.
+     * @returns {asserts actual is T} Throws if values are not deeply equal or arguments are invalid.
      */
-    function deepEqual<T>(actual: unknown, expected: T, message?: string): asserts actual is T;
+    function deepEqual<T>(actual: unknown, expected: T, message?: string, ...args: any[]): asserts actual is T;
     /**
      * Asserts that a function throws, testing the thrown value against a RegExp via `String(thrown)`.
      * @example
@@ -21,9 +29,9 @@ export namespace assert {
      * @param {() => void} fn - The function expected to throw
      * @param {RegExp} error - Tested against `String(thrown)`
      * @param {string} [message] - The assertion message
-     * @returns {void}
+     * @returns {void} Throws if the function does not throw, the thrown value does not match, or arguments are invalid.
      */
-    function throws(fn: () => void, error: RegExp, message?: string): void;
+    function throws(fn: () => void, error: RegExp, message?: string, ...args: any[]): void;
     /**
      * Asserts that an async function rejects, testing the rejection against a RegExp via `String(thrown)`.
      * @example
@@ -32,9 +40,9 @@ export namespace assert {
      * @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>}
+     * @returns {Promise<void>} Rejects if the function does not reject, the rejection value does not match, or arguments are invalid.
      */
-    function rejects(fn: () => Promise<unknown>, error: RegExp, message?: string): Promise<void>;
+    function rejects(fn: () => Promise<unknown>, error: RegExp, message?: string, ...args: any[]): Promise<void>;
 }
 export function load(href: string): void;
 export function suite(text: string, callback: () => void): void;

x-test-frame.js

@@ -114,7 +114,7 @@ export class XTestFrame {
    * @param {any} context
    * @param {any} caller
    * @param {any} value
-   * @param {any} message
+   * @param {any} [message]
    */
   static assert(context, caller, value, message) {
     if (context && !context.state.bailed) {
@@ -134,12 +134,6 @@ export class XTestFrame {
    * @param {any} [message]
    */
   static throws(context, caller, fn, error, message) {
-    if (!(fn instanceof Function)) {
-      throw new Error(`unexpected fn value "${fn}"`);
-    }
-    if (!(error instanceof RegExp)) {
-      throw new Error(`unexpected error value "${error}"`);
-    }
     let threw = false;
     let thrownValue;
     try {
@@ -163,12 +157,6 @@ export class XTestFrame {
    * @param {any} [message]
    */
   static async rejects(context, caller, fn, error, message) {
-    if (!(fn instanceof Function)) {
-      throw new Error(`unexpected fn value "${fn}"`);
-    }
-    if (!(error instanceof RegExp)) {
-      throw new Error(`unexpected error value "${error}"`);
-    }
     let rejected = false;
     let rejectionValue;
     try {

x-test.js

@@ -8,9 +8,25 @@ import { XTestFrame } from './x-test-frame.js';
  *   assert('foo' === 'bar', 'foo does not equal bar');
  * @param {unknown} value - The condition to assert (truthy/falsy)
  * @param {string} [message] - The assertion message
- * @returns {asserts value} Throws if condition is falsy.
+ * @returns {asserts value} Throws if condition is falsy or arguments are invalid.
  */
-export const assert = (value, message) => XTestFrame.assert(suiteContext, assert, value, message);
+export function assert(value, message) {
+  switch (arguments.length) {
+    case 0:
+      throw new Error('expected value to assert, but got none');
+    case 1:
+      XTestFrame.assert(suiteContext, assert, value);
+      break;
+    case 2:
+      if (typeof message !== 'string') {
+        throw new Error(`unexpected message, expected string but got "${message}"`);
+      }
+      XTestFrame.assert(suiteContext, assert, value, message);
+      break;
+    default:
+      throw new Error('unexpected extra arguments');
+  }
+}
 
 /**
  * Strict deep-equality assertion. Supports primitives, plain objects, and
@@ -22,9 +38,26 @@ export const assert = (value, message) => XTestFrame.assert(suiteContext, assert
  * @param {unknown} actual - The actual value
  * @param {T} expected - The expected value
  * @param {string} [message] - The assertion message
- * @returns {asserts actual is T} Throws if values are not deeply equal.
+ * @returns {asserts actual is T} Throws if values are not deeply equal or arguments are invalid.
  */
-assert.deepEqual = (actual, expected, message) => XTestFrame.deepEqual(suiteContext, assert.deepEqual, actual, expected, message);
+assert.deepEqual = function deepEqual(actual, expected, message) {
+  switch (arguments.length) {
+    case 0:
+    case 1:
+      throw new Error('expected actual and expected values, but got too few arguments');
+    case 2:
+      XTestFrame.deepEqual(suiteContext, assert.deepEqual, actual, expected);
+      break;
+    case 3:
+      if (typeof message !== 'string') {
+        throw new Error(`unexpected message, expected string but got "${message}"`);
+      }
+      XTestFrame.deepEqual(suiteContext, assert.deepEqual, actual, expected, message);
+      break;
+    default:
+      throw new Error('unexpected extra arguments');
+  }
+};
 
 /**
  * Asserts that a function throws, testing the thrown value against a RegExp via `String(thrown)`.
@@ -34,9 +67,38 @@ assert.deepEqual = (actual, expected, message) => XTestFrame.deepEqual(suiteCont
  * @param {() => void} fn - The function expected to throw
  * @param {RegExp} error - Tested against `String(thrown)`
  * @param {string} [message] - The assertion message
- * @returns {void}
+ * @returns {void} Throws if the function does not throw, the thrown value does not match, or arguments are invalid.
  */
-assert.throws = (fn, error, message) => XTestFrame.throws(suiteContext, assert.throws, fn, error, message);
+assert.throws = function throws(fn, error, message) {
+  switch (arguments.length) {
+    case 0:
+    case 1:
+      throw new Error('expected fn and error arguments, but got too few arguments');
+    case 2:
+      if (!(fn instanceof Function)) {
+        throw new Error(`unexpected fn, expected Function but got "${fn}"`);
+      }
+      if (!(error instanceof RegExp)) {
+        throw new Error(`unexpected error, expected RegExp but got "${error}"`);
+      }
+      XTestFrame.throws(suiteContext, assert.throws, fn, error);
+      break;
+    case 3:
+      if (!(fn instanceof Function)) {
+        throw new Error(`unexpected fn, expected Function but got "${fn}"`);
+      }
+      if (!(error instanceof RegExp)) {
+        throw new Error(`unexpected error, expected RegExp but got "${error}"`);
+      }
+      if (typeof message !== 'string') {
+        throw new Error(`unexpected message, expected string but got "${message}"`);
+      }
+      XTestFrame.throws(suiteContext, assert.throws, fn, error, message);
+      break;
+    default:
+      throw new Error('unexpected extra arguments');
+  }
+};
 
 /**
  * Asserts that an async function rejects, testing the rejection against a RegExp via `String(thrown)`.
@@ -46,9 +108,36 @@ assert.throws = (fn, error, message) => XTestFrame.throws(suiteContext, assert.t
  * @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>}
+ * @returns {Promise<void>} Rejects if the function does not reject, the rejection value does not match, or arguments are invalid.
  */
-assert.rejects = (fn, error, message) => XTestFrame.rejects(suiteContext, assert.rejects, fn, error, message);
+assert.rejects = function rejects(fn, error, message) {
+  switch (arguments.length) {
+    case 0:
+    case 1:
+      throw new Error('expected fn and error arguments, but got too few arguments');
+    case 2:
+      if (!(fn instanceof Function)) {
+        throw new Error(`unexpected fn, expected Function but got "${fn}"`);
+      }
+      if (!(error instanceof RegExp)) {
+        throw new Error(`unexpected error, expected RegExp but got "${error}"`);
+      }
+      return XTestFrame.rejects(suiteContext, assert.rejects, fn, error);
+    case 3:
+      if (!(fn instanceof Function)) {
+        throw new Error(`unexpected fn, expected Function but got "${fn}"`);
+      }
+      if (!(error instanceof RegExp)) {
+        throw new Error(`unexpected error, expected RegExp but got "${error}"`);
+      }
+      if (typeof message !== 'string') {
+        throw new Error(`unexpected message, expected string but got "${message}"`);
+      }
+      return XTestFrame.rejects(suiteContext, assert.rejects, fn, error, message);
+    default:
+      throw new Error('unexpected extra arguments');
+  }
+};
 
 /**
  * Load a new frame.