velocious 1.0.643 → 1.0.644

package/src/testing/velocious-attempt-executor.js

@@ -0,0 +1,431 @@
+// @ts-check
+
+import { TestDatabaseAccessRevokedError } from "../environment-handlers/base.js"
+import { clearDeliveries } from "../mailer.js"
+import restArgsError from "../utils/rest-args-error.js"
+import { testConfig } from "./test.js"
+
+/**
+ * Marks one whole-lifecycle timeout while its underlying promise keeps running.
+ * @typedef {Error & {velociousTestTimeout?: true}} TestTimeoutError
+ */
+
+/**
+ * Runs one promise with a lifecycle timeout.
+ * @param {Promise<ReturnType<typeof JSON.parse>> | ReturnType<typeof JSON.parse>} promise - Promise or value.
+ * @param {number} timeoutMs - Timeout in milliseconds.
+ * @param {string} testDescription - Test description.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Lifecycle result.
+ */
+function runWithTimeout(promise, timeoutMs, testDescription) {
+  const timeoutSeconds = (timeoutMs / 1000).toFixed(3).replace(/\.?0+$/, "")
+  /** @type {TestTimeoutError} */
+  const timeoutError = new Error(`Timed out after ${timeoutSeconds}s: ${testDescription}`)
+  timeoutError.velociousTestTimeout = true
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(timeoutError), timeoutMs)
+
+    Promise.resolve(promise).then((result) => {
+      clearTimeout(timeout)
+      resolve(result)
+    }).catch((error) => {
+      clearTimeout(timeout)
+      reject(error)
+    })
+  })
+}
+
+/**
+ * Waits for detached lifecycle cleanup up to the timeout grace period.
+ * @param {Promise<ReturnType<typeof JSON.parse>>} lifecycle - Detached lifecycle promise.
+ * @param {number} graceMs - Maximum wait.
+ * @returns {Promise<{settled: false} | {settled: true, status: "fulfilled"} | {settled: true, status: "rejected", reason: ReturnType<typeof JSON.parse>}>} - Settlement outcome.
+ */
+function awaitSettledOrGrace(lifecycle, graceMs) {
+  return new Promise((resolve) => {
+    let settled = false
+    const graceTimer = setTimeout(() => {
+      if (settled) return
+
+      settled = true
+      resolve({settled: false})
+    }, graceMs)
+
+    Promise.resolve(lifecycle).then(
+      () => {
+        if (settled) return
+
+        settled = true
+        clearTimeout(graceTimer)
+        resolve({settled: true, status: "fulfilled"})
+      },
+      (reason) => {
+        if (settled) return
+
+        settled = true
+        clearTimeout(graceTimer)
+        resolve({settled: true, status: "rejected", reason})
+      }
+    )
+  })
+}
+
+/**
+ * Checks whether a late lifecycle stopped only because its attempt access was revoked.
+ * @param {ReturnType<typeof JSON.parse>} error - Lifecycle rejection.
+ * @returns {boolean} - Whether every contained error is expected revocation.
+ */
+function isTestDatabaseAccessRevocation(error) {
+  if (error instanceof TestDatabaseAccessRevokedError) return true
+  if (error instanceof AggregateError) {
+    return error.errors.length > 0 && error.errors.every((nestedError) => isTestDatabaseAccessRevocation(nestedError))
+  }
+
+  return false
+}
+
+export default class VelociousAttemptExecutor {
+  /**
+   * Creates an executor for framework-owned attempt lifecycle work.
+   * @param {object} args - Constructor arguments.
+   * @param {import("./test-runner.js").default} args.testRunner - Owning Velocious runner.
+   */
+  constructor({testRunner, ...restArgs}) {
+    restArgsError(restArgs)
+    this.testRunner = testRunner
+  }
+
+  /**
+   * Executes exactly one complete Velocious-owned test attempt.
+   * @param {object} args - Attempt arguments.
+   * @param {import("./test-runner.js").AfterBeforeEachCallbackObjectType[]} args.afterEaches - Cleanup hooks.
+   * @param {number} args.attemptNumber - One-based attempt number.
+   * @param {import("./test-runner.js").AfterBeforeEachCallbackObjectType[]} args.beforeEaches - Setup hooks.
+   * @param {string[]} args.descriptions - Parent descriptions.
+   * @param {import("./velocious-test-arguments.js").TestArgs} args.testArgs - Stable test arguments.
+   * @param {import("./velocious-test-arguments.js").TestData} args.testData - Test registration.
+   * @param {string} args.testDescription - Test description.
+   * @param {number} [args.timeoutMs] - Whole-lifecycle timeout.
+   * @returns {Promise<{abortRemainingTests: boolean, consoleOutput: string, error: ReturnType<typeof JSON.parse>, failed: boolean}>} - Attempt outcome.
+   */
+  async execute({afterEaches, attemptNumber, beforeEaches, descriptions, testArgs, testData, testDescription, timeoutMs, ...restArgs}) {
+    restArgsError(restArgs)
+    const testRunner = this.testRunner
+    /** @type {ReturnType<typeof JSON.parse>} */
+    let caughtError
+    let failed = false
+    /** @type {Promise<ReturnType<typeof JSON.parse>> | undefined} */
+    let testLifecycle
+    /** @type {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} */
+    let testSharedConnectionRegistrations = []
+    let testSharedConnectionsActive = false
+    /** @type {import("./test-runner.js").SharedTransactionBrokerRegistration | undefined} */
+    let sharedTransactionBrokerRegistration
+    /** @type {import("./test-runner.js").SharedTransactionBrokerRegistration | undefined} */
+    let sharedTransactionBrokerPreparation
+    /** @type {import("./test-runner.js").TransactionalTenantRegistration[]} */
+    const transactionalTenantRegistrations = []
+    /** @type {import("./test-runner.js").BrowserDummyConnectionRegistration[]} */
+    const browserDummyConnectionRegistrations = []
+    const testDatabaseAccessScope = {revoked: false}
+    /** @type {Set<Error>} */
+    const recordedTimeoutCleanupErrors = new Set()
+    let abortRemainingTests = false
+    let attemptTimedOut = false
+    /** @type {string} */
+    let consoleOutput
+    testArgs.registerTransactionalTenant = async (args) => {
+      await testRunner.registerTransactionalTenant(args, transactionalTenantRegistrations)
+    }
+    const stopConsoleCapture = testRunner.startConsoleCapture({
+      passthrough: testConfig.consoleOutput === "live"
+    })
+    const profiler = testRunner._profiler
+    const profileAttempt = profiler?.startAttempt({
+      descriptions,
+      attemptNumber,
+      testData,
+      testDescription
+    })
+
+    try {
+      const runLifecycleCallback = async () => await testRunner.runWithDummyIfNeeded(testArgs, async () => {
+        const useTransaction = testArgs.databaseCleaning?.transaction === true
+        const shouldTruncate = testArgs.databaseCleaning?.truncate ?? !useTransaction
+        const useSharedTestConnections = useTransaction || testArgs.type == "request"
+        const useTestConnections = useSharedTestConnections || shouldTruncate
+        const runTestAttempt = async () => {
+          if (useSharedTestConnections) {
+            testSharedConnectionRegistrations = testRunner.activateTestSharedConnections()
+            testSharedConnectionsActive = true
+          }
+          /** @type {ReturnType<typeof JSON.parse>[]} */
+          const lifecycleErrors = []
+          let runCleanupHooks = false
+
+          try {
+            if (useSharedTestConnections) {
+              sharedTransactionBrokerPreparation = await testRunner.prepareSharedTransactionBroker()
+            }
+            runCleanupHooks = true
+
+            clearDeliveries()
+            await this.runBeforeEaches({beforeEaches, testArgs, testData})
+
+            if (useSharedTestConnections) {
+              const activeConnections = testRunner.sharedTransactionConnections({transactionsOnly: true})
+              if (sharedTransactionBrokerPreparation && !testRunner.sharedTransactionBrokerMatchesConnections(sharedTransactionBrokerPreparation, activeConnections)) {
+                testRunner.clearTestSharedConnections(testSharedConnectionRegistrations)
+                testSharedConnectionRegistrations = []
+                testSharedConnectionsActive = false
+              }
+
+              sharedTransactionBrokerRegistration = await testRunner.startSharedTransactionBroker(sharedTransactionBrokerPreparation, activeConnections)
+              sharedTransactionBrokerPreparation = undefined
+              if (sharedTransactionBrokerRegistration && !testSharedConnectionsActive) {
+                testSharedConnectionRegistrations = testRunner.activateTestSharedConnections()
+                testSharedConnectionsActive = true
+              }
+            }
+
+            testRunner._lastTestContext = {
+              fullDescription: testRunner.buildFullDescription(descriptions, testDescription),
+              filePath: testData.filePath ?? "<unknown>",
+              line: testData.line ?? 0
+            }
+            await testRunner.runProfileSpan({phase: "test body", filePath: testData.ownerFilePath ?? testData.filePath}, async () => {
+              await testData.function(testArgs)
+            })
+          } catch (error) {
+            lifecycleErrors.push(error)
+          }
+
+          if (runCleanupHooks) {
+            try {
+              await testRunner.getConfiguration().awaitPendingBroadcasts()
+            } catch (error) {
+              lifecycleErrors.push(error)
+            }
+
+            try {
+              if (testSharedConnectionsActive) {
+                testRunner.clearTestSharedConnections(testSharedConnectionRegistrations)
+                testSharedConnectionRegistrations = []
+                testSharedConnectionsActive = false
+              }
+            } catch (error) {
+              lifecycleErrors.push(error)
+            }
+
+            try {
+              await testRunner.stopSharedTransactionBroker(sharedTransactionBrokerRegistration || sharedTransactionBrokerPreparation)
+              sharedTransactionBrokerRegistration = undefined
+              sharedTransactionBrokerPreparation = undefined
+            } catch (error) {
+              lifecycleErrors.push(error)
+            }
+
+            try {
+              await this.runAfterEaches({afterEaches, testArgs, testData})
+            } catch (error) {
+              lifecycleErrors.push(error)
+            }
+
+            try {
+              await testRunner.cleanupTransactionalTenants(transactionalTenantRegistrations)
+            } catch (error) {
+              lifecycleErrors.push(error)
+            }
+          }
+
+          if (testSharedConnectionsActive) {
+            try {
+              testRunner.clearTestSharedConnections(testSharedConnectionRegistrations)
+            } catch (error) {
+              lifecycleErrors.push(error)
+            }
+            testSharedConnectionsActive = false
+          }
+
+          if (lifecycleErrors.length == 1) throw lifecycleErrors[0]
+          if (lifecycleErrors.length > 1) {
+            throw new AggregateError(lifecycleErrors, "Test lifecycle and cleanup failed", {cause: lifecycleErrors[0]})
+          }
+        }
+
+        if (useTestConnections) {
+          await testRunner.getConfiguration().ensureConnections({name: `Test: ${testDescription}`}, runTestAttempt)
+        } else {
+          await runTestAttempt()
+        }
+      }, browserDummyConnectionRegistrations)
+      const lifecycleCallback = async () => await testRunner.getConfiguration().runWithTestDatabaseAccessScope(testDatabaseAccessScope, runLifecycleCallback)
+      testLifecycle = profileAttempt && profiler
+        ? profiler.runAttempt(profileAttempt, lifecycleCallback)
+        : lifecycleCallback()
+
+      if (timeoutMs !== undefined) {
+        await runWithTimeout(testLifecycle, timeoutMs, testDescription)
+      } else {
+        await testLifecycle
+      }
+    } catch (error) {
+      failed = true
+      caughtError = error
+      const timedOut = Boolean(/** @type {TestTimeoutError} */ (error)?.velociousTestTimeout)
+      attemptTimedOut = timedOut
+
+      if (timedOut && testLifecycle) {
+        const emergencyCleanupErrors = []
+
+        if (profileAttempt && profiler) profiler.finishAttempt(profileAttempt, "timed-out")
+        const lifecycleOutcome = await awaitSettledOrGrace(testLifecycle, timeoutMs ?? 60000)
+
+        if (lifecycleOutcome.settled && lifecycleOutcome.status === "rejected") {
+          emergencyCleanupErrors.push(lifecycleOutcome.reason)
+        }
+
+        if (!lifecycleOutcome.settled) {
+          testDatabaseAccessScope.revoked = true
+          void testLifecycle.catch((cleanupError) => {
+            if (isTestDatabaseAccessRevocation(cleanupError)) return
+            testRunner.recordTimeoutCleanupFailure(cleanupError, "test lifecycle", recordedTimeoutCleanupErrors)
+          })
+          const quarantine = testRunner.quarantineBrowserDummyConnections(browserDummyConnectionRegistrations)
+          const quarantineOutcome = await awaitSettledOrGrace(quarantine, timeoutMs ?? 60000)
+          const usesBrowserTransactions = testArgs.databaseCleaning?.transaction === true
+          const usesBrowserTruncation = testArgs.databaseCleaning?.truncate ?? !usesBrowserTransactions
+
+          abortRemainingTests = testRunner.isBrowserTestMode()
+            && testRunner.hasTag(testArgs, "dummy")
+            && (usesBrowserTransactions || usesBrowserTruncation)
+
+          if (quarantineOutcome.settled && quarantineOutcome.status === "rejected") {
+            emergencyCleanupErrors.push(quarantineOutcome.reason)
+          } else if (!quarantineOutcome.settled) {
+            void quarantine.catch((cleanupError) => {
+              testRunner.recordTimeoutCleanupFailure(cleanupError, "browser dummy connection quarantine", recordedTimeoutCleanupErrors)
+            })
+          }
+        }
+
+        try {
+          if (testSharedConnectionsActive) {
+            testRunner.clearTestSharedConnections(testSharedConnectionRegistrations)
+            testSharedConnectionRegistrations = []
+            testSharedConnectionsActive = false
+          }
+        } catch (cleanupError) {
+          emergencyCleanupErrors.push(cleanupError)
+        }
+
+        const brokerCleanup = testRunner.stopSharedTransactionBroker(sharedTransactionBrokerRegistration || sharedTransactionBrokerPreparation)
+        const brokerCleanupOutcome = await awaitSettledOrGrace(brokerCleanup, timeoutMs ?? 60000)
+
+        if (brokerCleanupOutcome.settled && brokerCleanupOutcome.status === "rejected") {
+          emergencyCleanupErrors.push(brokerCleanupOutcome.reason)
+        } else if (!brokerCleanupOutcome.settled) {
+          void brokerCleanup.catch((cleanupError) => {
+            testRunner.recordTimeoutCleanupFailure(cleanupError, "shared transaction broker", recordedTimeoutCleanupErrors)
+          })
+        }
+        sharedTransactionBrokerRegistration = undefined
+        sharedTransactionBrokerPreparation = undefined
+        const emergencyCleanup = testRunner.cleanupTransactionalTenants(transactionalTenantRegistrations, {discard: true})
+        const emergencyCleanupOutcome = await awaitSettledOrGrace(emergencyCleanup, timeoutMs ?? 60000)
+
+        if (emergencyCleanupOutcome.settled && emergencyCleanupOutcome.status === "rejected") {
+          emergencyCleanupErrors.push(emergencyCleanupOutcome.reason)
+        } else if (!emergencyCleanupOutcome.settled) {
+          void emergencyCleanup.catch((cleanupError) => {
+            testRunner.recordTimeoutCleanupFailure(cleanupError, "transactional tenant", recordedTimeoutCleanupErrors)
+          })
+        }
+
+        if (emergencyCleanupErrors.length > 0) {
+          caughtError = new AggregateError(
+            [caughtError, ...emergencyCleanupErrors],
+            "Test timeout and emergency cleanup failed",
+            {cause: caughtError}
+          )
+        }
+      }
+
+      if (browserDummyConnectionRegistrations.some((registration) => registration.quarantined)) {
+        testDatabaseAccessScope.revoked = true
+        abortRemainingTests = true
+      }
+    } finally {
+      testDatabaseAccessScope.revoked = true
+      consoleOutput = stopConsoleCapture()
+
+      if (profileAttempt && profiler) {
+        profiler.finishAttempt(profileAttempt, failed
+          ? (attemptTimedOut ? "timed-out" : "failed")
+          : "passed")
+      }
+    }
+
+    return {
+      abortRemainingTests,
+      consoleOutput,
+      error: caughtError,
+      failed
+    }
+  }
+
+  /**
+   * Runs before-each hooks in inherited declaration order.
+   * @param {object} args - Hook arguments.
+   * @param {import("./test-runner.js").AfterBeforeEachCallbackObjectType[]} args.beforeEaches - Setup hooks.
+   * @param {import("./velocious-test-arguments.js").TestArgs} args.testArgs - Stable test arguments.
+   * @param {import("./velocious-test-arguments.js").TestData} args.testData - Test registration.
+   * @returns {Promise<void>} - Resolves after all setup hooks complete.
+   */
+  async runBeforeEaches({beforeEaches, testArgs, testData}) {
+    for (const hook of beforeEaches) {
+      await this.testRunner.runProfileSpan({
+        phase: "beforeEach",
+        declarationIndex: hook.declarationIndex,
+        declarationScopeId: hook.declarationScopeId,
+        filePath: hook.ownerFilePath
+      }, async () => {
+        await hook.callback({configuration: this.testRunner.getConfiguration(), testArgs, testData})
+      })
+    }
+  }
+
+  /**
+   * Runs every after-each hook while preserving all failures.
+   * @param {object} args - Hook arguments.
+   * @param {import("./test-runner.js").AfterBeforeEachCallbackObjectType[]} args.afterEaches - Cleanup hooks.
+   * @param {import("./velocious-test-arguments.js").TestArgs} args.testArgs - Stable test arguments.
+   * @param {import("./velocious-test-arguments.js").TestData} args.testData - Test registration.
+   * @returns {Promise<void>} - Resolves after every cleanup hook settles.
+   */
+  async runAfterEaches({afterEaches, testArgs, testData}) {
+    /** @type {ReturnType<typeof JSON.parse>[]} */
+    const errors = []
+
+    for (const hook of afterEaches) {
+      try {
+        await this.testRunner.runProfileSpan({
+          phase: "afterEach",
+          declarationIndex: hook.declarationIndex,
+          declarationScopeId: hook.declarationScopeId,
+          filePath: hook.ownerFilePath
+        }, async () => {
+          await hook.callback({configuration: this.testRunner.getConfiguration(), testArgs, testData})
+        })
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+
+    if (errors.length == 1) throw errors[0]
+    if (errors.length > 1) {
+      throw new AggregateError(errors, "Multiple afterEach hooks failed", {cause: errors[0]})
+    }
+  }
+}

package/src/testing/velocious-runner-reporter.js

@@ -0,0 +1,166 @@
+// @ts-check
+
+import { addTrackedStackToError } from "../utils/with-tracked-stack.js"
+import BacktraceCleaner from "../utils/backtrace-cleaner-node.js"
+import picocolors from "picocolors"
+import restArgsError from "../utils/rest-args-error.js"
+import { testEvents } from "./test.js"
+
+export default class VelociousRunnerReporter {
+  /**
+   * Creates the legacy event and result projection adapter.
+   * @param {object} args - Constructor arguments.
+   * @param {import("./test-runner.js").default} args.testRunner - Owning Velocious runner.
+   */
+  constructor({testRunner, ...restArgs}) {
+    restArgsError(restArgs)
+    this.testRunner = testRunner
+  }
+
+  /**
+   * Projects one completed attempt into legacy events and final result accounting.
+   * Retry eligibility is decided by the caller before this method runs.
+   * @param {object} args - Completed attempt and retry metadata.
+   * @param {import("./test-runner.js").AttemptConsoleOutput[]} args.attemptConsoleOutputs - Captured output across attempts.
+   * @param {number} args.attemptNumber - Current one-based attempt.
+   * @param {string[]} args.descriptions - Parent description stack.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Raw thrown or rejected value.
+   * @param {boolean} args.failed - Whether the attempt failed, independently of error truthiness.
+   * @param {string} args.leftPadding - Console indentation.
+   * @param {number} args.retriesUsed - Retry count consumed after this attempt.
+   * @param {number} args.retryCount - Configured retry limit.
+   * @param {import("./velocious-test-arguments.js").TestArgs} args.testArgs - Stable test arguments.
+   * @param {import("./velocious-test-arguments.js").TestData} args.testData - Test registration.
+   * @param {string} args.testDescription - Test description.
+   * @param {boolean} args.willRetry - Whether the legacy loop will run another attempt.
+   * @returns {Promise<void>} - Resolves after all legacy listeners complete.
+   */
+  async reportAttempt({attemptConsoleOutputs, attemptNumber, descriptions, error, failed, leftPadding, retriesUsed, retryCount, testArgs, testData, testDescription, willRetry, ...restArgs}) {
+    restArgsError(restArgs)
+    const testRunner = this.testRunner
+
+    if (!failed) testRunner._successfulTests++
+
+    if (failed) {
+      await this.emitEvent("testAttemptFailed", {
+        configuration: testRunner.getConfiguration(),
+        descriptions,
+        error,
+        attemptNumber,
+        nextAttempt: willRetry ? attemptNumber + 1 : undefined,
+        retriesUsed,
+        retryCount,
+        testArgs,
+        testData,
+        testDescription,
+        testRunner,
+        willRetry
+      })
+    }
+
+    if (willRetry) {
+      console.warn(picocolors.red(`${leftPadding}  Retrying (${retriesUsed}/${retryCount}) after error: ${error instanceof Error ? error.message : String(error)}`))
+      await this.emitEvent("testRetrying", {
+        configuration: testRunner.getConfiguration(),
+        descriptions,
+        error,
+        nextAttempt: attemptNumber + 1,
+        retriesUsed,
+        retryCount,
+        testArgs,
+        testData,
+        testDescription,
+        testRunner
+      })
+    }
+
+    if (attemptNumber > 1) {
+      await this.emitEvent("testRetried", {
+        configuration: testRunner.getConfiguration(),
+        descriptions,
+        error,
+        attemptNumber,
+        retriesUsed,
+        retryCount,
+        testArgs,
+        testData,
+        testDescription,
+        testRunner
+      })
+    }
+
+    if (failed && !willRetry) {
+      await this.reportFailedTest({attemptConsoleOutputs, descriptions, error, leftPadding, testArgs, testData, testDescription})
+    }
+  }
+
+  /**
+   * Records and emits one final failed test result.
+   * @param {object} args - Final failure metadata.
+   * @param {import("./test-runner.js").AttemptConsoleOutput[]} args.attemptConsoleOutputs - Captured output across attempts.
+   * @param {string[]} args.descriptions - Parent description stack.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Raw final failure.
+   * @param {string} args.leftPadding - Console indentation.
+   * @param {import("./velocious-test-arguments.js").TestArgs} args.testArgs - Stable test arguments.
+   * @param {import("./velocious-test-arguments.js").TestData} args.testData - Test registration.
+   * @param {string} args.testDescription - Test description.
+   * @returns {Promise<void>} - Resolves after the final-failure listener completes.
+   */
+  async reportFailedTest({attemptConsoleOutputs, descriptions, error, leftPadding, testArgs, testData, testDescription}) {
+    const testRunner = this.testRunner
+    const consoleOutput = testRunner.buildConsoleOutput(attemptConsoleOutputs)
+
+    if (error instanceof Error) {
+      console.error(picocolors.red(`${leftPadding}  Test failed: ${error.message}`))
+      addTrackedStackToError(error)
+
+      const backtraceCleaner = new BacktraceCleaner(error)
+      const cleanedStack = backtraceCleaner.getCleanedStack()
+      const stackLines = cleanedStack?.split("\n")
+
+      if (stackLines) {
+        for (const stackLine of stackLines) {
+          console.error(picocolors.red(`${leftPadding}  ${stackLine}`))
+        }
+      }
+    } else {
+      console.error(picocolors.red(`${leftPadding}  Test failed with a ${typeof error}: ${String(error)}`))
+    }
+
+    testRunner.printFailedConsoleOutput({consoleOutput, leftPadding})
+    testRunner._failedTests++
+    testRunner._failedTestDetails.push({
+      fullDescription: testRunner.buildFullDescription(descriptions, testDescription),
+      filePath: testData.filePath,
+      line: testData.line,
+      error,
+      consoleOutput: consoleOutput || undefined
+    })
+
+    await this.emitEvent("testFailed", {
+      configuration: testRunner.getConfiguration(),
+      descriptions,
+      error,
+      testArgs,
+      testData,
+      testDescription,
+      testRunner
+    })
+
+    testRunner.printRerunCommand({descriptions, testDescription, testData, leftPadding})
+  }
+
+  /**
+   * Emits one legacy event and awaits listeners in registration order.
+   * @param {string} eventName - Event name.
+   * @param {object} payload - Event payload.
+   * @returns {Promise<void>} - Resolves when all listeners complete.
+   */
+  async emitEvent(eventName, payload) {
+    const listeners = testEvents.listeners(eventName)
+
+    for (const listener of listeners) {
+      await listener(payload)
+    }
+  }
+}

package/src/testing/velocious-suite-hook-executor.js

@@ -0,0 +1,71 @@
+// @ts-check
+
+import restArgsError from "../utils/rest-args-error.js"
+
+export default class VelociousSuiteHookExecutor {
+  /**
+   * Creates an executor for Velocious suite hooks.
+   * @param {object} args - Constructor arguments.
+   * @param {import("./test-runner.js").default} args.testRunner - Owning Velocious runner.
+   */
+  constructor({testRunner, ...restArgs}) {
+    restArgsError(restArgs)
+    this.testRunner = testRunner
+  }
+
+  /**
+   * Runs suite setup hooks in declaration order.
+   * @param {object} args - Hook execution arguments.
+   * @param {import("./test-runner.js").BeforeAfterAllCallbackObjectType[]} args.hooks - Profiled setup hooks.
+   * @returns {Promise<void>} - Resolves after every setup hook completes.
+   */
+  async runBeforeAlls({hooks, ...restArgs}) {
+    restArgsError(restArgs)
+
+    for (const hook of hooks) {
+      await this.runHook(hook, "beforeAll")
+    }
+  }
+
+  /**
+   * Runs every suite teardown hook in reverse declaration order.
+   * @param {object} args - Hook execution arguments.
+   * @param {import("./test-runner.js").BeforeAfterAllCallbackObjectType[]} args.hooks - Profiled teardown hooks.
+   * @returns {Promise<void>} - Resolves after every teardown hook settles.
+   */
+  async runAfterAlls({hooks, ...restArgs}) {
+    restArgsError(restArgs)
+    /** @type {ReturnType<typeof JSON.parse>[]} */
+    const errors = []
+
+    for (const hook of [...hooks].reverse()) {
+      try {
+        await this.runHook(hook, "afterAll")
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+
+    if (errors.length == 1) throw errors[0]
+    if (errors.length > 1) {
+      throw new AggregateError(errors, "Multiple afterAll hooks failed", {cause: errors[0]})
+    }
+  }
+
+  /**
+   * Runs one suite hook with its Velocious profiler attribution.
+   * @param {import("./test-runner.js").BeforeAfterAllCallbackObjectType} hook - Hook registration.
+   * @param {"beforeAll" | "afterAll"} phase - Profiler phase.
+   * @returns {Promise<void>} - Resolves when the hook completes.
+   */
+  async runHook(hook, phase) {
+    await this.testRunner.runProfileSpan({
+      phase,
+      declarationIndex: hook.declarationIndex,
+      declarationScopeId: hook.declarationScopeId,
+      filePath: hook.ownerFilePath
+    }, async () => {
+      await hook.callback({configuration: this.testRunner.getConfiguration()})
+    })
+  }
+}