Validate all top-level interfaces.

theengineear · theengineear · commit c06d0f0fd55b · 2026-05-03T21:18:23.000-07:00
This is a developer-experience thing. It’s nice when tools fail early,
fast, and clearly. It’s some verbosity in the library, but it’s all very
simple code.
diff --git a/test/index.js b/test/index.js
@@ -6,5 +6,8 @@ load('./test-root.html');
 load('./test-tap.html');
 load('./test-common.html');
 load('./test-assert.html');
+load('./test-load.html');
+load('./test-suite.html');
+load('./test-test.html');
 load('./test-boot.html');
 load('./test-scratch.html');
diff --git a/test/test-frame.js b/test/test-frame.js
@@ -362,19 +362,7 @@ suite('suite', () => {
     assert(context.publish.calls[1][1].error.message === 'test failure');
   });
 
-  test('throws if callback is not a function', () => {
-    const { context } = getContext();
-    const callback = null;
-    const expected = 'Unexpected callback value "null".';
-    let actual;
-    try {
-      XTestFrame.suite(context, 'description', callback);
-    } catch (error) {
-      actual = error.message;
-    }
-    assert(context.publish.calls.length === 0);
-    assert(actual === expected, actual);
-  });
+
 });
 
 suite('test', () => {
@@ -403,7 +391,7 @@ suite('test', () => {
     test('this will break', 'this is expected to fail');
   } catch (error) {
     message = error.message;
-    passed = error.message === 'Unexpected callback value "this is expected to fail".';
+    passed = error.message === 'unexpected fn, expected Function but got "this is expected to fail"';
   }
   test('throws if "test" is not given a function as a callback', () => {
     assert(passed, message);
diff --git a/test/test-load.html b/test/test-load.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="content-security-policy" content="default-src 'self';">
+  </head>
+  <body>
+    <h3>test-load</h3>
+    <script type="module" src="test-load.js"></script>
+  </body>
+</html>
diff --git a/test/test-load.js b/test/test-load.js
@@ -0,0 +1,15 @@
+import { test, suite, assert, load } from '../x-test.js';
+
+suite('load', () => {
+  test('throws with no arguments', () => {
+    assert.throws(() => load(), /^Error: expected href argument, but got none$/);
+  });
+
+  test('throws if href is not a string', () => {
+    assert.throws(() => load(42), /^Error: unexpected href, expected string but got "42"$/);
+  });
+
+  test('throws on extra arguments', () => {
+    assert.throws(() => load('./foo.html', 'extra'), /^Error: unexpected extra arguments$/);
+  });
+});
diff --git a/test/test-suite.html b/test/test-suite.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="content-security-policy" content="default-src 'self';">
+  </head>
+  <body>
+    <h3>test-suite</h3>
+    <script type="module" src="test-suite.js"></script>
+  </body>
+</html>
diff --git a/test/test-suite.js b/test/test-suite.js
@@ -0,0 +1,31 @@
+import { test, suite, assert } from '../x-test.js';
+
+for (const [label, fn] of [
+  ['suite', suite],
+  ['suite.skip', suite.skip],
+  ['suite.only', suite.only],
+  ['suite.todo', suite.todo],
+]) {
+  suite(label, () => {
+    test('accepts valid arguments', () => {
+      fn('valid suite', () => {});
+    });
+
+    test('throws with too few arguments', () => {
+      assert.throws(() => fn(), /^Error: expected name and fn arguments, but got too few arguments$/);
+      assert.throws(() => fn('name'), /^Error: expected name and fn arguments, but got too few arguments$/);
+    });
+
+    test('throws if name is not a string', () => {
+      assert.throws(() => fn(42, () => {}), /^Error: unexpected name, expected string but got "42"$/);
+    });
+
+    test('throws if fn is not a Function', () => {
+      assert.throws(() => fn('name', 'not-a-function'), /^Error: unexpected fn, expected Function but got "not-a-function"$/);
+    });
+
+    test('throws on extra arguments', () => {
+      assert.throws(() => fn('name', () => {}, 'extra'), /^Error: unexpected extra arguments$/);
+    });
+  });
+}
diff --git a/test/test-test.html b/test/test-test.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="content-security-policy" content="default-src 'self';">
+  </head>
+  <body>
+    <h3>test-test</h3>
+    <script type="module" src="test-test.js"></script>
+  </body>
+</html>
diff --git a/test/test-test.js b/test/test-test.js
@@ -0,0 +1,47 @@
+import { test, suite, assert } from '../x-test.js';
+
+for (const [label, fn] of [
+  ['test', test],
+  ['test.skip', test.skip],
+  ['test.only', test.only],
+  ['test.todo', test.todo],
+]) {
+  suite(label, () => {
+    test('accepts valid arguments', () => {
+      fn('valid test', () => {});
+    });
+
+    test('accepts valid arguments with timeout', () => {
+      fn('valid test with timeout', () => {}, 1000);
+    });
+
+    test('throws with too few arguments', () => {
+      assert.throws(() => fn(), /^Error: expected name and fn arguments, but got too few arguments$/);
+      assert.throws(() => fn('name'), /^Error: expected name and fn arguments, but got too few arguments$/);
+    });
+
+    test('throws if name is not a string', () => {
+      assert.throws(() => fn(42, () => {}), /^Error: unexpected name, expected string but got "42"$/);
+    });
+
+    test('throws if fn is not a Function', () => {
+      assert.throws(() => fn('name', 'not-a-function'), /^Error: unexpected fn, expected Function but got "not-a-function"$/);
+    });
+
+    test('throws if name is not a string with timeout', () => {
+      assert.throws(() => fn(42, () => {}, 1000), /^Error: unexpected name, expected string but got "42"$/);
+    });
+
+    test('throws if fn is not a Function with timeout', () => {
+      assert.throws(() => fn('name', 'not-a-function', 1000), /^Error: unexpected fn, expected Function but got "not-a-function"$/);
+    });
+
+    test('throws if timeout is not a number', () => {
+      assert.throws(() => fn('name', () => {}, 'not-a-number'), /^Error: unexpected timeout, expected number but got "not-a-number"$/);
+    });
+
+    test('throws on extra arguments', () => {
+      assert.throws(() => fn('name', () => {}, 1000, 'extra'), /^Error: unexpected extra arguments$/);
+    });
+  });
+}
diff --git a/types/x-test.d.ts b/types/x-test.d.ts
@@ -44,55 +44,75 @@ export namespace assert {
      */
     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;
+/**
+ * Load a new frame.
+ * @example
+ *   load('./test-sibling.html');
+ * @param {string} href - The URL/path to the test file to run
+ * @returns {void}
+ */
+export function load(href: string, ...args: any[]): void;
+/**
+ * Register a grouping of tests. Alternatively, mark with flags (.skip, .only, .todo).
+ * @param {string} name - The description of the test group
+ * @param {() => void} fn - The callback function containing nested tests
+ * @returns {void}
+ */
+export function suite(name: string, fn: () => void, ...args: any[]): void;
 export namespace suite {
     /**
      * Register a test group that will be skipped during execution.
-     * @param {string} text - The description of the test group
-     * @param {() => void} callback - The callback function containing nested tests
+     * @param {string} name - The description of the test group
+     * @param {() => void} fn - The callback function containing nested tests
      * @returns {void}
      */
-    function skip(text: string, callback: () => void): void;
+    function skip(name: string, fn: () => void, ...args: any[]): void;
     /**
      * Register a test group that will run exclusively (skips other non-only tests).
-     * @param {string} text - The description of the test group
-     * @param {() => void} callback - The callback function containing nested tests
+     * @param {string} name - The description of the test group
+     * @param {() => void} fn - The callback function containing nested tests
      * @returns {void}
      */
-    function only(text: string, callback: () => void): void;
+    function only(name: string, fn: () => void, ...args: any[]): void;
     /**
      * Register a placeholder test group for future implementation.
-     * @param {string} text - The description of the test group
-     * @param {() => void} callback - The callback function containing nested tests
+     * @param {string} name - The description of the test group
+     * @param {() => void} fn - The callback function containing nested tests
      * @returns {void}
      */
-    function todo(text: string, callback: () => void): void;
+    function todo(name: string, fn: () => void, ...args: any[]): void;
 }
-export function test(text: string, callback: () => void | Promise<void>, interval?: number): void;
+/**
+ * Register an individual test case. Alternatively, mark with flags (.skip, .only, .todo).
+ * @param {string} name - The description of the test case
+ * @param {() => void | Promise<void>} fn - The test callback function
+ * @param {number} [timeout] - Optional timeout in milliseconds
+ * @returns {void}
+ */
+export function test(name: string, fn: () => void | Promise<void>, timeout?: number, ...args: any[]): void;
 export namespace test {
     /**
      * Register a test case that will be skipped during execution.
-     * @param {string} text - The description of the test case
-     * @param {() => void | Promise<void>} callback - The test callback function
-     * @param {number} [interval] - Optional timeout in milliseconds
+     * @param {string} name - The description of the test case
+     * @param {() => void | Promise<void>} fn - The test callback function
+     * @param {number} [timeout] - Optional timeout in milliseconds
      * @returns {void}
      */
-    function skip(text: string, callback: () => void | Promise<void>, interval?: number): void;
+    function skip(name: string, fn: () => void | Promise<void>, timeout?: number, ...args: any[]): void;
     /**
      * Register a test case that will run exclusively (skips other non-only tests).
-     * @param {string} text - The description of the test case
-     * @param {() => void | Promise<void>} callback - The test callback function
-     * @param {number} [interval] - Optional timeout in milliseconds
+     * @param {string} name - The description of the test case
+     * @param {() => void | Promise<void>} fn - The test callback function
+     * @param {number} [timeout] - Optional timeout in milliseconds
      * @returns {void}
      */
-    function only(text: string, callback: () => void | Promise<void>, interval?: number): void;
+    function only(name: string, fn: () => void | Promise<void>, timeout?: number, ...args: any[]): void;
     /**
      * Register a placeholder test case for future implementation.
-     * @param {string} text - The description of the test case
-     * @param {() => void | Promise<void>} callback - The test callback function
-     * @param {number} [interval] - Optional timeout in milliseconds
+     * @param {string} name - The description of the test case
+     * @param {() => void | Promise<void>} fn - The test callback function
+     * @param {number} [timeout] - Optional timeout in milliseconds
      * @returns {void}
      */
-    function todo(text: string, callback: () => void | Promise<void>, interval?: number): void;
+    function todo(name: string, fn: () => void | Promise<void>, timeout?: number, ...args: any[]): void;
 }
diff --git a/x-test-frame.js b/x-test-frame.js
@@ -266,9 +266,6 @@ export class XTestFrame {
    */
   static #suiteInner(context, text, callback, directive, only) {
     if (context && !context.state.bailed && !context.state.ready) {
-      if (!(callback instanceof Function)) {
-        throw new Error(`Unexpected callback value "${callback}".`);
-      }
       const suiteId = context.uuid();
       const parents = [...context.state.parents];
       directive = directive ?? null;
@@ -328,15 +325,12 @@ export class XTestFrame {
    * @param {any} context
    * @param {any} text
    * @param {any} callback
-   * @param {any} interval
-   * @param {any} directive
-   * @param {any} only
+   * @param {any} [interval]
+   * @param {any} [directive]
+   * @param {any} [only]
    */
   static #testInner(context, text, callback, interval, directive, only) {
     if (context && !context.state.bailed && !context.state.ready) {
-      if (!(callback instanceof Function)) {
-        throw new Error(`Unexpected callback value "${callback}".`);
-      }
       const testId = context.uuid();
       const parents = [...context.state.parents];
       interval = interval ?? null;
@@ -354,7 +348,7 @@ export class XTestFrame {
    * @param {any} context
    * @param {any} text
    * @param {any} callback
-   * @param {any} interval
+   * @param {any} [interval]
    */
   static test(context, text, callback, interval) {
     XTestFrame.#testInner(context, text, callback, interval, null, null);
@@ -364,7 +358,7 @@ export class XTestFrame {
    * @param {any} context
    * @param {any} text
    * @param {any} callback
-   * @param {any} interval
+   * @param {any} [interval]
    */
   static testSkip(context, text, callback, interval) {
     XTestFrame.#testInner(context, text, callback, interval, 'SKIP', null);
@@ -374,7 +368,7 @@ export class XTestFrame {
    * @param {any} context
    * @param {any} text
    * @param {any} callback
-   * @param {any} interval
+   * @param {any} [interval]
    */
   static testOnly(context, text, callback, interval) {
     XTestFrame.#testInner(context, text, callback, interval, null, true);
@@ -384,7 +378,7 @@ export class XTestFrame {
    * @param {any} context
    * @param {any} text
    * @param {any} callback
-   * @param {any} interval
+   * @param {any} [interval]
    */
   static testTodo(context, text, callback, interval) {
     XTestFrame.#testInner(context, text, callback, interval, 'TODO', null);
diff --git a/x-test.js b/x-test.js
