modestbench 0.3.2 → 0.5.0

package/src/adapters/mocha-adapter.ts

@@ -0,0 +1,284 @@
+/**
+ * ModestBench Mocha Adapter
+ *
+ * Captures test definitions from Mocha test files by replacing global
+ * `describe`, `it`, and hook functions before the test file loads.
+ *
+ * Mocha exposes these as globals, making interception straightforward - no ES
+ * module loader hooks required.
+ */
+
+import { pathToFileURL } from 'node:url';
+
+import type {
+  CapturedSuite,
+  CapturedTest,
+  CapturedTestFile,
+  SuiteHooks,
+  TestFrameworkAdapter,
+} from './types.js';
+
+/**
+ * Internal state for capturing test definitions
+ */
+interface CaptureState {
+  /** Stack of suite contexts for nested describes */
+  currentSuite: CapturedSuite | null;
+  /** Root-level suites */
+  rootSuites: CapturedSuite[];
+  /** Root-level tests (if any, though Mocha usually uses describe) */
+  rootTests: CapturedTest[];
+}
+
+/**
+ * Mocha-style describe function signature
+ */
+type DescribeFn = {
+  (name: string, fn: () => void): void;
+  only: (name: string, fn: () => void) => void;
+  skip: (name: string, fn: () => void) => void;
+};
+
+/**
+ * Mocha-style hook function signature
+ */
+type HookFn = (fn: () => Promise<void> | void) => void;
+
+/**
+ * Mocha-style it function signature
+ */
+type ItFn = {
+  (name: string, fn: () => Promise<void> | void): void;
+  only: (name: string, fn: () => Promise<void> | void) => void;
+  skip: (name: string, fn: () => Promise<void> | void) => void;
+};
+
+/**
+ * Mocha test framework adapter
+ *
+ * Captures tests by installing global mocks before importing the test file.
+ */
+export class MochaAdapter implements TestFrameworkAdapter {
+  readonly framework = 'mocha' as const;
+
+  /**
+   * Capture test definitions from a Mocha test file
+   *
+   * @param filePath - Absolute path to the test file
+   * @returns Captured test structure
+   */
+  async capture(filePath: string): Promise<CapturedTestFile> {
+    // Install our mock globals
+    const state = installMochaGlobals();
+
+    try {
+      // Import the test file - this triggers describe/it calls
+      // which populate our state
+      const fileUrl = pathToFileURL(filePath).href;
+
+      // Use a cache-busting query param to ensure fresh import
+      const bustCache = `?t=${Date.now()}`;
+      await import(fileUrl + bustCache);
+
+      // Return captured structure
+      return {
+        filePath,
+        framework: 'mocha',
+        rootSuites: state.rootSuites,
+        rootTests: state.rootTests,
+      };
+    } finally {
+      // Clean up globals
+      uninstallMochaGlobals();
+    }
+  }
+}
+
+/**
+ * Create empty hooks structure
+ */
+const createEmptyHooks = (): SuiteHooks => {
+  return {
+    after: [],
+    afterEach: [],
+    before: [],
+    beforeEach: [],
+  };
+};
+
+/**
+ * Create a new suite structure
+ */
+const createSuite = (name: string): CapturedSuite => {
+  return {
+    children: [],
+    hooks: createEmptyHooks(),
+    name,
+    tests: [],
+  };
+};
+
+/**
+ * Install Mocha global mocks and return the capture state
+ *
+ * This replaces globalThis.describe, globalThis.it, etc. with our capturing
+ * implementations.
+ */
+const installMochaGlobals = (): CaptureState => {
+  const state: CaptureState = {
+    currentSuite: null,
+    rootSuites: [],
+    rootTests: [],
+  };
+
+  // describe() - creates a suite
+  const describe: DescribeFn = (name: string, fn: () => void) => {
+    const suite = createSuite(name);
+    const parent = state.currentSuite;
+
+    if (parent) {
+      // Nested describe: inherit beforeEach/afterEach from parent
+      // and add to parent's children
+      parent.children.push(suite);
+    } else {
+      // Root-level describe
+      state.rootSuites.push(suite);
+    }
+
+    // Enter this suite context
+    state.currentSuite = suite;
+
+    // Execute the describe body to capture tests and nested describes
+    fn();
+
+    // Exit back to parent context
+    state.currentSuite = parent;
+  };
+
+  // describe.only() - marks suite as exclusive
+  describe.only = (name: string, fn: () => void) => {
+    // For benchmarking, we treat .only the same as regular
+    // (filtering happens at a higher level)
+    describe(name, fn);
+  };
+
+  // describe.skip() - marks suite as skipped
+  describe.skip = (_name: string, _fn: () => void) => {
+    // Skip entirely - don't even register
+  };
+
+  // it() - creates a test
+  const it: ItFn = (name: string, fn: () => Promise<void> | void) => {
+    const test: CapturedTest = { fn, name };
+
+    if (state.currentSuite) {
+      state.currentSuite.tests.push(test);
+    } else {
+      // Root-level test (unusual for Mocha but supported)
+      state.rootTests.push(test);
+    }
+  };
+
+  // it.only() - marks test as exclusive
+  it.only = (name: string, fn: () => Promise<void> | void) => {
+    const test: CapturedTest = { fn, name, only: true };
+
+    if (state.currentSuite) {
+      state.currentSuite.tests.push(test);
+    } else {
+      state.rootTests.push(test);
+    }
+  };
+
+  // it.skip() - marks test as skipped
+  it.skip = (name: string, fn: () => Promise<void> | void) => {
+    const test: CapturedTest = { fn, name, skip: true };
+
+    if (state.currentSuite) {
+      state.currentSuite.tests.push(test);
+    } else {
+      state.rootTests.push(test);
+    }
+  };
+
+  // before() - runs once before all tests in suite
+  const before: HookFn = (fn: () => Promise<void> | void) => {
+    if (state.currentSuite) {
+      (
+        state.currentSuite.hooks.before as Array<() => Promise<void> | void>
+      ).push(fn);
+    }
+    // Root-level before is ignored (no suite to attach to)
+  };
+
+  // after() - runs once after all tests in suite
+  const after: HookFn = (fn: () => Promise<void> | void) => {
+    if (state.currentSuite) {
+      (
+        state.currentSuite.hooks.after as Array<() => Promise<void> | void>
+      ).push(fn);
+    }
+  };
+
+  // beforeEach() - runs before each test
+  const beforeEach: HookFn = (fn: () => Promise<void> | void) => {
+    if (state.currentSuite) {
+      (
+        state.currentSuite.hooks.beforeEach as Array<() => Promise<void> | void>
+      ).push(fn);
+    }
+  };
+
+  // afterEach() - runs after each test
+  const afterEach: HookFn = (fn: () => Promise<void> | void) => {
+    if (state.currentSuite) {
+      (
+        state.currentSuite.hooks.afterEach as Array<() => Promise<void> | void>
+      ).push(fn);
+    }
+  };
+
+  // Install globals
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.describe = describe;
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.it = it;
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.before = before;
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.after = after;
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.beforeEach = beforeEach;
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.afterEach = afterEach;
+
+  // Mocha aliases
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.context = describe;
+  // @ts-expect-error - intentionally modifying globalThis
+  globalThis.specify = it;
+
+  return state;
+};
+
+/**
+ * Remove Mocha globals installed by installMochaGlobals
+ */
+const uninstallMochaGlobals = (): void => {
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.describe;
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.it;
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.before;
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.after;
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.beforeEach;
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.afterEach;
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.context;
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.specify;
+};

package/src/adapters/node-test-adapter.ts

@@ -0,0 +1,391 @@
+/**
+ * ModestBench Node.js Test Runner Adapter
+ *
+ * Captures test definitions from node:test files using ES module loader hooks.
+ *
+ * Unlike Mocha (which uses globals), node:test requires ES module import
+ * interception. We use Node.js module.register() API to install a custom loader
+ * that returns our capturing mock instead of the real node:test.
+ *
+ * Architecture:
+ *
+ * 1. Register a custom loader that intercepts node:test imports
+ * 2. Import the test file - this triggers test/describe calls
+ * 3. Retrieve captured state from global storage
+ * 4. Unregister the loader
+ */
+
+import { pathToFileURL } from 'node:url';
+
+import type {
+  CapturedSuite,
+  CapturedTest,
+  CapturedTestFile,
+  SuiteHooks,
+  TestFrameworkAdapter,
+} from './types.js';
+
+/**
+ * Global capture state key
+ */
+const CAPTURE_STATE_KEY = '__MODESTBENCH_NODE_TEST_CAPTURE__';
+
+/**
+ * Internal capture state structure
+ */
+interface CaptureState {
+  currentSuite: MutableCapturedSuite | null;
+  rootSuites: MutableCapturedSuite[];
+  rootTests: MutableCapturedTest[];
+}
+
+/**
+ * Mutable version of CapturedSuite for building state
+ */
+interface MutableCapturedSuite {
+  children: MutableCapturedSuite[];
+  hooks: MutableSuiteHooks;
+  name: string;
+  tests: MutableCapturedTest[];
+}
+
+/**
+ * Mutable version of CapturedTest
+ */
+interface MutableCapturedTest {
+  fn: () => Promise<void> | void;
+  name: string;
+  only?: boolean;
+  skip?: boolean;
+}
+
+/**
+ * Mutable version of SuiteHooks
+ */
+interface MutableSuiteHooks {
+  after: Array<() => Promise<void> | void>;
+  afterEach: Array<() => Promise<void> | void>;
+  before: Array<() => Promise<void> | void>;
+  beforeEach: Array<() => Promise<void> | void>;
+}
+
+/**
+ * Node.js test runner adapter
+ *
+ * Captures test definitions by installing mock implementations before importing
+ * the test file.
+ *
+ * IMPORTANT: For this to work with actual node:test imports, you must run
+ * Node.js with our loader: node --import modestbench/node-test your-test.js
+ *
+ * Without the loader, this adapter only works with test files that use
+ * globalThis.**MODESTBENCH_NODE_TEST_MOCK** directly (not useful for real test
+ * files).
+ */
+export class NodeTestAdapter implements TestFrameworkAdapter {
+  readonly framework = 'node-test' as const;
+
+  /**
+   * Capture test definitions from a node:test file
+   *
+   * @param filePath - Absolute path to the test file
+   * @returns Captured test structure
+   */
+  async capture(filePath: string): Promise<CapturedTestFile> {
+    // Initialize capture state
+    const state = initCaptureState();
+
+    // Install mocks
+    installNodeTestMocks(state);
+
+    try {
+      // Import the test file
+      // The loader hook will intercept 'node:test' and use our mocks
+      const fileUrl = pathToFileURL(filePath).href;
+      const bustCache = `?t=${Date.now()}`;
+      await import(fileUrl + bustCache);
+
+      // Return captured structure
+      return toCapturedTestFile(state, filePath);
+    } finally {
+      // Clean up
+      uninstallNodeTestMocks();
+      clearCaptureState();
+    }
+  }
+}
+
+/**
+ * Clear capture state from globalThis
+ */
+const clearCaptureState = (): void => {
+  // @ts-expect-error - intentionally using globalThis
+  delete globalThis[CAPTURE_STATE_KEY];
+};
+
+/**
+ * Create empty hooks structure
+ */
+const createEmptyHooks = (): MutableSuiteHooks => {
+  return {
+    after: [],
+    afterEach: [],
+    before: [],
+    beforeEach: [],
+  };
+};
+
+/**
+ * Create a new suite structure
+ */
+const createSuite = (name: string): MutableCapturedSuite => {
+  return {
+    children: [],
+    hooks: createEmptyHooks(),
+    name,
+    tests: [],
+  };
+};
+
+/**
+ * Initialize capture state on globalThis
+ */
+const initCaptureState = (): CaptureState => {
+  const state: CaptureState = {
+    currentSuite: null,
+    rootSuites: [],
+    rootTests: [],
+  };
+
+  // @ts-expect-error - intentionally using globalThis for cross-module state
+  globalThis[CAPTURE_STATE_KEY] = state;
+
+  return state;
+};
+
+/**
+ * Install node:test mocks on globalThis for module interception
+ *
+ * Since we can't truly intercept ES imports without a loader, we use a
+ * workaround: install mocks that test files can import via a special path.
+ *
+ * For true node:test interception, users must run with: node --import
+ * modestbench/register test-file.js
+ */
+const installNodeTestMocks = (state: CaptureState): void => {
+  // Create mock test function
+  const mockTest = Object.assign(
+    (
+      nameOrOptions: string | { name?: string; only?: boolean; skip?: boolean },
+      fnOrOptions?:
+        | (() => Promise<void> | void)
+        | { only?: boolean; skip?: boolean },
+      maybeFn?: () => Promise<void> | void,
+    ): Promise<void> => {
+      let name: string;
+      let fn: () => Promise<void> | void;
+      let skip = false;
+      let only = false;
+
+      // Parse arguments - node:test has flexible signatures
+      if (typeof nameOrOptions === 'string') {
+        name = nameOrOptions;
+        if (typeof fnOrOptions === 'function') {
+          fn = fnOrOptions;
+        } else if (fnOrOptions && typeof fnOrOptions === 'object') {
+          skip = fnOrOptions.skip ?? false;
+          only = fnOrOptions.only ?? false;
+          fn = maybeFn ?? (() => {});
+        } else {
+          fn = () => {};
+        }
+      } else {
+        name = nameOrOptions.name ?? 'unnamed test';
+        skip = nameOrOptions.skip ?? false;
+        only = nameOrOptions.only ?? false;
+        fn = (fnOrOptions as () => Promise<void> | void) ?? (() => {});
+      }
+
+      const test: MutableCapturedTest = { fn, name, only, skip };
+
+      if (state.currentSuite) {
+        state.currentSuite.tests.push(test);
+      } else {
+        state.rootTests.push(test);
+      }
+
+      return Promise.resolve();
+    },
+    {
+      only: function only(
+        name: string,
+        fn?: () => Promise<void> | void,
+      ): Promise<void> {
+        return mockTest(name, { only: true }, fn);
+      },
+      skip: function skip(
+        name: string,
+        fn?: () => Promise<void> | void,
+      ): Promise<void> {
+        return mockTest(name, { skip: true }, fn);
+      },
+      todo: function todo(
+        name: string,
+        fn?: () => Promise<void> | void,
+      ): Promise<void> {
+        return mockTest(name, { skip: true }, fn);
+      },
+    },
+  );
+
+  // Create mock describe function
+  const mockDescribe = Object.assign(
+    (
+      nameOrOptions: string | { name?: string; only?: boolean; skip?: boolean },
+      fnOrOptions?: (() => void) | { only?: boolean; skip?: boolean },
+      maybeFn?: () => void,
+    ): Promise<void> => {
+      let name: string;
+      let fn: (() => void) | undefined;
+
+      if (typeof nameOrOptions === 'string') {
+        name = nameOrOptions;
+        if (typeof fnOrOptions === 'function') {
+          fn = fnOrOptions;
+        } else {
+          fn = maybeFn;
+        }
+      } else {
+        name = nameOrOptions.name ?? 'unnamed suite';
+        fn = fnOrOptions as (() => void) | undefined;
+      }
+
+      const suite = createSuite(name);
+      const parent = state.currentSuite;
+
+      if (parent) {
+        parent.children.push(suite);
+      } else {
+        state.rootSuites.push(suite);
+      }
+
+      // Enter suite context
+      state.currentSuite = suite;
+
+      // Execute describe body
+      if (fn) {
+        fn();
+      }
+
+      // Exit back to parent
+      state.currentSuite = parent;
+
+      return Promise.resolve();
+    },
+    {
+      only: function only(name: string, fn?: () => void): Promise<void> {
+        return mockDescribe(name, fn);
+      },
+      skip: function skip(_name: string, _fn?: () => void): Promise<void> {
+        return Promise.resolve();
+      },
+      todo: function todo(_name: string, _fn?: () => void): Promise<void> {
+        return Promise.resolve();
+      },
+    },
+  );
+
+  // Hook functions
+  const mockBefore = (fn: () => Promise<void> | void): void => {
+    if (state.currentSuite) {
+      state.currentSuite.hooks.before.push(fn);
+    }
+  };
+
+  const mockAfter = (fn: () => Promise<void> | void): void => {
+    if (state.currentSuite) {
+      state.currentSuite.hooks.after.push(fn);
+    }
+  };
+
+  const mockBeforeEach = (fn: () => Promise<void> | void): void => {
+    if (state.currentSuite) {
+      state.currentSuite.hooks.beforeEach.push(fn);
+    }
+  };
+
+  const mockAfterEach = (fn: () => Promise<void> | void): void => {
+    if (state.currentSuite) {
+      state.currentSuite.hooks.afterEach.push(fn);
+    }
+  };
+
+  // Install on globalThis for the loader to access
+  // @ts-expect-error - intentionally using globalThis
+  globalThis.__MODESTBENCH_NODE_TEST_MOCK__ = {
+    after: mockAfter,
+    afterEach: mockAfterEach,
+    before: mockBefore,
+    beforeEach: mockBeforeEach,
+    default: mockTest,
+    describe: mockDescribe,
+    it: mockTest,
+    mock: {
+      fn: () => () => {},
+      getter: () => {},
+      method: () => {},
+      reset: () => {},
+      restoreAll: () => {},
+      setter: () => {},
+      timers: {
+        enable: () => {},
+        reset: () => {},
+        runAll: () => {},
+        tick: () => {},
+      },
+    },
+    suite: mockDescribe,
+    test: mockTest,
+  };
+};
+
+/**
+ * Convert mutable capture state to immutable CapturedTestFile
+ */
+const toCapturedTestFile = (
+  state: CaptureState,
+  filePath: string,
+): CapturedTestFile => {
+  return {
+    filePath,
+    framework: 'node-test',
+    rootSuites: state.rootSuites.map(toImmutableSuite),
+    rootTests: state.rootTests.map(toImmutableTest),
+  };
+};
+
+const toImmutableSuite = (suite: MutableCapturedSuite): CapturedSuite => {
+  return {
+    children: suite.children.map(toImmutableSuite),
+    hooks: suite.hooks as SuiteHooks,
+    name: suite.name,
+    tests: suite.tests.map(toImmutableTest),
+  };
+};
+
+const toImmutableTest = (test: MutableCapturedTest): CapturedTest => {
+  return {
+    fn: test.fn,
+    name: test.name,
+    only: test.only,
+    skip: test.skip,
+  };
+};
+
+/**
+ * Uninstall node:test mocks
+ */
+const uninstallNodeTestMocks = (): void => {
+  // @ts-expect-error - cleaning up globalThis
+  delete globalThis.__MODESTBENCH_NODE_TEST_MOCK__;
+};