velocious 1.0.602 → 1.0.604

package/build/database/pool/base.js

@@ -3,6 +3,7 @@
 import Configuration from "../../configuration.js"
 import Logger from "../../logger.js"
 import baseMethodsForward from "./base-methods-forward.js"
+import sha256Hex from "../../utils/sha256-hex.js"
 
 /**
  * Opaque ownership handle for an in-process test shared connection registration.
@@ -44,7 +45,7 @@ import baseMethodsForward from "./base-methods-forward.js"
  * @property {Array<DatabasePoolPendingCheckoutDebugSnapshot>} [pendingCheckouts] - Waiting checkout snapshots.
  * @property {number} pendingCheckoutCount - Number of queued checkout requests.
  * @property {string} poolClass - Pool class name.
- * @property {{checkoutWaitCount: number, checkoutWaitMaxMs: number, checkoutWaitTotalMs: number, idleReapDisposalCount: number}} [telemetry] - Cumulative pool lifecycle telemetry.
+ * @property {{connectionCreationCount: number, connectionCreationFailureCount: number, connectionCreationMaxMs: number, connectionCreationTotalMs: number, checkoutTimeoutCount: number, checkoutWaitCount: number, checkoutWaitMaxMs: number, checkoutWaitTotalMs: number, idleReapCount: number, idleReapDisposalCount: number, idleReapFailureCount: number, idleReapMaxMs: number, idleReapTotalMs: number, peakLiveConnections: number}} [telemetry] - Cumulative pool lifecycle telemetry.
  */
 export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
 
@@ -337,15 +338,31 @@ class VelociousDatabasePoolBase {
   async spawnConnectionForConfiguration(databaseConfiguration) {
     const reuseKey = this.getConfigurationReuseKey(databaseConfiguration)
     const connection = await this.spawnConnectionWithConfiguration(databaseConfiguration)
+
+    this.stampConnectionForConfigurationReuseKey(connection, reuseKey)
+
+    return connection
+  }
+
+  /**
+   * Stamps a connected driver with its pool reuse identity and diagnostic-safe opaque identity.
+   * @param {import("../drivers/base.js").default} connection - Connected driver.
+   * @param {string} reuseKey - Exact physical configuration reuse key captured for this spawn.
+   * @returns {void}
+   */
+  stampConnectionForConfigurationReuseKey(connection, reuseKey) {
     const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
+    const databaseIdentityFingerprint = `sha256:${sha256Hex(`database-configuration-reuse:v1\0${reuseKey}`)}`
 
     connectionWithPoolKey[POOL_CONFIGURATION_KEY] = reuseKey
+    connection.setPoolDiagnosticIdentity({
+      databaseIdentifier: this.identifier,
+      databaseIdentityFingerprint
+    })
     connection.setSchemaCacheInvalidator(() => {
       this.clearSchemaCache()
       this.configuration.clearSchemaCachesForReuseKey(reuseKey)
     })
-
-    return connection
   }
 
   /**

package/build/environment-handlers/base.js

@@ -54,6 +54,22 @@ export default class VelociousEnvironmentHandlerBase {
    */
   runWithSharedTransactionCoordinatorOwner(_connection, _owner, callback) { return callback() }
 
+  /**
+   * Runs work with test-profile attribution. Runtimes without async-context
+   * storage execute the callback without installing ambient attribution.
+   * @template T
+   * @param {import("../testing/test-profiler.js").TestProfileAsyncContext | undefined} _context - Captured profile context, or an explicit absence of attribution.
+   * @param {() => T} callback - Profiled work.
+   * @returns {T} - Callback result.
+   */
+  runWithTestProfileContext(_context, callback) { return callback() }
+
+  /**
+   * Gets the current test-profile attribution context.
+   * @returns {import("../testing/test-profiler.js").TestProfileAsyncContext | undefined} - Active context.
+   */
+  getCurrentTestProfileContext() { return undefined }
+
   /**
    * Mutable ambient tenant used by runtimes without async-context storage.
    * @type {ReturnType<typeof JSON.parse> | undefined}

package/build/environment-handlers/node/cli/commands/test.js

@@ -2,12 +2,15 @@
 
 import BaseCommand from "../../../../cli/base-command.js"
 import fs from "fs/promises"
+import path from "node:path"
 import picocolors from "picocolors"
 import TestFilesFinder from "../../../../testing/test-files-finder.js"
+import TestProfiler from "../../../../testing/test-profiler.js"
+import { formatTestProfileSummary, writeTestProfileOutputs } from "../../../../testing/test-profile-output.js"
 import TestRunner from "../../../../testing/test-runner.js"
 import TestSuiteSplitter from "../../../../testing/test-suite-splitter.js"
-import {normalizeExamplePatterns, parseFilters} from "../../../../testing/test-filter-parser.js"
-import {prepareSourcePeerPackage} from "../../source-peer-package.js"
+import { normalizeExamplePatterns, parseFilters } from "../../../../testing/test-filter-parser.js"
+import { prepareSourcePeerPackage } from "../../source-peer-package.js"
 
 export default class VelociousCliCommandsTest extends BaseCommand {
   async execute() {
@@ -27,119 +30,252 @@ export default class VelociousCliCommandsTest extends BaseCommand {
       directories.push(`${this.directory()}/spec`)
     }
 
-    const {includeTags, excludeTags, examplePatterns, filteredProcessArgs, groups, groupNumber, timingManifestPath} = parseFilters(this.processArgs || [])
+    const {
+      includeTags,
+      excludeTags,
+      examplePatterns,
+      filteredProcessArgs,
+      groups,
+      groupNumber,
+      profile,
+      profileJsonPath,
+      timingManifestPath,
+      timingManifestOutputPath
+    } = parseFilters(this.processArgs || [])
+    const profileOptions = resolveTestProfileOptions({
+      cwd: process.cwd(),
+      profile,
+      profileJsonPath,
+      timingManifestPath,
+      timingManifestOutputPath
+    })
+    const selection = {
+      excludeTagCount: excludeTags.length,
+      hasExampleFilters: examplePatterns.length > 0,
+      includeTagCount: includeTags.length,
+      shard: groups !== undefined && groupNumber !== undefined ? {groups, groupNumber} : undefined
+    }
+    const profiler = profileOptions.profile
+      ? new TestProfiler({configuration: this.getConfiguration(), projectDirectory: directory, selection})
+      : undefined
     const testFilesFinder = new TestFilesFinder({directory, directories, processArgs: filteredProcessArgs})
-    let testFiles = await testFilesFinder.findTestFiles()
-
-    if (groups !== undefined || groupNumber !== undefined) {
-      if (groups === undefined || groupNumber === undefined) {
-        throw new Error("Both --groups and --group-number must be provided together")
-      }
-
-      const timingManifest = await loadTimingManifest(timingManifestPath)
-      const splitter = new TestSuiteSplitter({groups, groupNumber, testFiles, baseDirectory: directory, timingManifest})
-
-      testFiles = splitter.getGroupFiles()
-      console.log(picocolors.cyan(`Running group ${groupNumber} of ${groups} (${testFiles.length} files)`))
+    /** @type {TestRunner | undefined} */
+    let testRunner
+    let profileFinalized = false
+
+    /**
+     * Finalizes requested outputs once for every command outcome.
+     * @param {string} status - Run status.
+     * @returns {Promise<void>} - Resolves after requested outputs are written.
+     */
+    const finalizeProfile = async (status) => {
+      if (!profiler || profileFinalized) return
+
+      profileFinalized = true
+      const failed = testRunner?.getFailedTests() ?? 0
+      const passed = testRunner?.getSuccessfulTests() ?? 0
+      const profileDocument = profiler.finish({
+        counts: {
+          discovered: testRunner?.getTestsCount() ?? 0,
+          executed: testRunner?.getExecutedTestsCount() ?? 0,
+          failed,
+          passed
+        },
+        focused: Boolean(testRunner?.anyTestsFocussed),
+        status
+      })
+
+      await writeTestProfileOutputs({
+        profile: profileDocument,
+        profileJsonPath: profileOptions.profileJsonPath,
+        timingManifestOutputPath: profileOptions.timingManifestOutputPath
+      })
+      console.log(`\n${formatTestProfileSummary(profileDocument, profileOptions)}`)
     }
 
-    const testRunner = new TestRunner({
-      configuration: this.getConfiguration(),
-      excludeTags,
-      includeTags,
-      testFiles,
-      lineFilters: testFilesFinder.getLineFiltersByFile(),
-      examplePatterns: normalizeExamplePatterns(examplePatterns)
-    })
-    let signalHandled = false
+    try {
+      const discoverTestFiles = async () => {
+        let discoveredTestFiles = await testFilesFinder.findTestFiles()
 
-    const handleSignal = async (/** @type {string} */ signal) => {
-      if (signalHandled) return
-      signalHandled = true
-      console.error(`\nReceived ${signal}, running afterAll hooks before exit...`)
+        if (groups !== undefined || groupNumber !== undefined) {
+          if (groups === undefined || groupNumber === undefined) {
+            throw new Error("Both --groups and --group-number must be provided together")
+          }
 
-      try {
-        await testRunner.runAfterAllsForActiveScopes()
-      } catch (error) {
-        console.error("Failed while running afterAll hooks:", error)
-      } finally {
-        process.exit(130)
+          const timingManifest = await loadTimingManifest(profileOptions.timingManifestPath)
+          const splitter = new TestSuiteSplitter({
+            groups,
+            groupNumber,
+            testFiles: discoveredTestFiles,
+            baseDirectory: directory,
+            timingManifest
+          })
+
+          discoveredTestFiles = splitter.getGroupFiles()
+          console.log(picocolors.cyan(`Running group ${groupNumber} of ${groups} (${discoveredTestFiles.length} files)`))
+        }
+
+        return discoveredTestFiles
+      }
+      const testFiles = profiler
+        ? await profiler.measurePhase("discovery", discoverTestFiles)
+        : await discoverTestFiles()
+
+      profiler?.setSelection({fileCount: testFiles.length})
+      testRunner = new TestRunner({
+        configuration: this.getConfiguration(),
+        excludeTags,
+        includeTags,
+        testFiles,
+        lineFilters: testFilesFinder.getLineFiltersByFile(),
+        examplePatterns: normalizeExamplePatterns(examplePatterns),
+        profiler
+      })
+      const activeTestRunner = testRunner
+      let signalHandled = false
+
+      const handleSignal = async (/** @type {string} */ signal) => {
+        if (signalHandled) return
+        signalHandled = true
+        profiler?.interrupt()
+        console.error(`\nReceived ${signal}, running afterAll hooks before exit...`)
+
+        try {
+          await activeTestRunner.runAfterAllsForActiveScopes()
+        } catch (error) {
+          console.error("Failed while running afterAll hooks:", error)
+        } finally {
+          try {
+            await finalizeProfile("interrupted")
+          } catch (error) {
+            console.error("Failed while writing interrupted test profile:", error)
+          }
+          process.exit(130)
+        }
       }
-    }
 
-    process.once("SIGINT", () => { void handleSignal("SIGINT") })
-    process.once("SIGTERM", () => { void handleSignal("SIGTERM") })
+      process.once("SIGINT", () => { void handleSignal("SIGINT") })
+      process.once("SIGTERM", () => { void handleSignal("SIGTERM") })
 
-    await testRunner.prepare()
+      await testRunner.prepare()
 
-    if (testRunner.getTestsCount() === 0) {
-      throw new Error(`${testRunner.getTestsCount()} tests was found in ${testFiles.length} file(s)`)
-    }
-
-    await testRunner.run()
+      if (testRunner.getTestsCount() === 0) {
+        await finalizeProfile("no-tests")
+        throw new Error(`${testRunner.getTestsCount()} tests was found in ${testFiles.length} file(s)`)
+      }
 
-    const executedTests = testRunner.getExecutedTestsCount()
+      await testRunner.run()
 
-    const lineFilters = testRunner.getLineFilters()
-    const hasLineFilters = Object.keys(lineFilters).length > 0
-    const hasExampleFilters = examplePatterns.length > 0
-    const hasTagFilters = includeTags.length > 0 || excludeTags.length > 0
+      const executedTests = testRunner.getExecutedTestsCount()
+      const lineFilters = testRunner.getLineFilters()
+      const hasLineFilters = Object.keys(lineFilters).length > 0
+      const hasExampleFilters = examplePatterns.length > 0
+      const hasTagFilters = includeTags.length > 0 || excludeTags.length > 0
 
-    if ((hasTagFilters || hasLineFilters || hasExampleFilters) && executedTests === 0) {
-      console.error(picocolors.red("\nNo tests matched the provided filters"))
-      process.exit(1)
-    }
+      if ((hasTagFilters || hasLineFilters || hasExampleFilters) && executedTests === 0) {
+        console.error(picocolors.red("\nNo tests matched the provided filters"))
+        await finalizeProfile("no-tests")
+        process.exit(1)
+      }
 
-    // Report the slowest tests so suite hotspots are visible every run. Defaults to
-    // the top 10; tune with VELOCIOUS_SLOW_TEST_COUNT (0 disables). Skipped for
-    // single-test runs where it would just be noise.
-    const slowTestCount = resolveSlowTestCount(process.env.VELOCIOUS_SLOW_TEST_COUNT)
+      // Report the slowest tests so suite hotspots are visible every run. Defaults to
+      // the top 10; tune with VELOCIOUS_SLOW_TEST_COUNT (0 disables). Skipped for
+      // single-test runs where it would just be noise.
+      const slowTestCount = resolveSlowTestCount(process.env.VELOCIOUS_SLOW_TEST_COUNT)
 
-    if (slowTestCount > 0 && executedTests > 1) {
-      const slowestTests = testRunner.getSlowestTests(slowTestCount)
+      if (slowTestCount > 0 && executedTests > 1) {
+        const slowestTests = testRunner.getSlowestTests(slowTestCount)
 
-      if (slowestTests.length > 0) {
-        console.log(picocolors.cyan(`\nSlowest ${slowestTests.length} tests:`))
+        if (slowestTests.length > 0) {
+          console.log(picocolors.cyan(`\nSlowest ${slowestTests.length} tests:`))
 
-        for (const slowTest of slowestTests) {
-          const location = slowTest.filePath && slowTest.line ? ` (${slowTest.filePath}:${slowTest.line})` : ""
+          for (const slowTest of slowestTests) {
+            const location = slowTest.filePath && slowTest.line ? ` (${slowTest.filePath}:${slowTest.line})` : ""
 
-          console.log(picocolors.cyan(`  ${String(slowTest.durationMs).padStart(6)}ms  ${slowTest.fullDescription}${location}`))
+            console.log(picocolors.cyan(`  ${String(slowTest.durationMs).padStart(6)}ms  ${slowTest.fullDescription}${location}`))
+          }
         }
       }
-    }
 
-    if (testRunner.isFailed()) {
-      await testRunner.persistFailedTestConsoleOutputsToAssets()
-      const failedTests = testRunner.getFailedTestDetails()
+      if (testRunner.isFailed()) {
+        await testRunner.persistFailedTestConsoleOutputsToAssets()
+        const failedTests = testRunner.getFailedTestDetails()
 
-      if (failedTests.length > 0) {
-      console.error(picocolors.red("\nFailed tests:"))
+        if (failedTests.length > 0) {
+          console.error(picocolors.red("\nFailed tests:"))
 
-        for (const failed of failedTests) {
-          const location = failed.filePath && failed.line
-            ? ` (${failed.filePath}:${failed.line})`
-            : ""
-          console.error(picocolors.red(`- ${failed.fullDescription}${location}`))
+          for (const failed of failedTests) {
+            const location = failed.filePath && failed.line
+              ? ` (${failed.filePath}:${failed.line})`
+              : ""
+            console.error(picocolors.red(`- ${failed.fullDescription}${location}`))
 
-          if (failed.consoleLogPath) {
-            console.error(picocolors.red(`  Console log: ${failed.consoleLogPath}`))
+            if (failed.consoleLogPath) {
+              console.error(picocolors.red(`  Console log: ${failed.consoleLogPath}`))
+            }
           }
         }
+
+        console.error(picocolors.red(`\nTest run failed with ${testRunner.getFailedTests()} failed tests and ${testRunner.getSuccessfulTests()} successfull`))
+        await finalizeProfile("failed")
+        process.exit(1)
+      } else if (testRunner.areAnyTestsFocussed()) {
+        console.error(picocolors.red(`\nFocussed run with ${testRunner.getFailedTests()} failed tests and ${testRunner.getSuccessfulTests()} successfull`))
+        await finalizeProfile("focused")
+        process.exit(1)
+      } else {
+        console.log(picocolors.green(`\nTest run succeeded with ${testRunner.getSuccessfulTests()} successful tests`))
+        await finalizeProfile("passed")
+        process.exit(0)
+      }
+    } catch (error) {
+      try {
+        await finalizeProfile("error")
+      } catch (profileError) {
+        throw new AggregateError([error, profileError], "Test command and profile finalization both failed", {cause: profileError})
       }
 
-      console.error(picocolors.red(`\nTest run failed with ${testRunner.getFailedTests()} failed tests and ${testRunner.getSuccessfulTests()} successfull`))
-      process.exit(1)
-    } else if (testRunner.areAnyTestsFocussed()) {
-      console.error(picocolors.red(`\nFocussed run with ${testRunner.getFailedTests()} failed tests and ${testRunner.getSuccessfulTests()} successfull`))
-      process.exit(1)
-    } else {
-      console.log(picocolors.green(`\nTest run succeeded with ${testRunner.getSuccessfulTests()} successful tests`))
-      process.exit(0)
+      throw error
     }
   }
 }
 
+/**
+ * Resolves and validates profiling paths before test discovery starts.
+ * @param {object} args - Raw profiling options.
+ * @param {string} args.cwd - Command working directory.
+ * @param {boolean} args.profile - Whether console profiling was requested.
+ * @param {string} [args.profileJsonPath] - Rich profile output path.
+ * @param {string} [args.timingManifestPath] - Timing manifest input path.
+ * @param {string} [args.timingManifestOutputPath] - Timing manifest output path.
+ * @returns {{profile: boolean, profileJsonPath: string | undefined, timingManifestPath: string | undefined, timingManifestOutputPath: string | undefined}} - Resolved profiling options.
+ */
+export function resolveTestProfileOptions({cwd, profile, profileJsonPath, timingManifestPath, timingManifestOutputPath}) {
+  const resolvedProfileJsonPath = profileJsonPath ? path.resolve(cwd, profileJsonPath) : undefined
+  const resolvedTimingManifestPath = timingManifestPath ? path.resolve(cwd, timingManifestPath) : undefined
+  const resolvedTimingManifestOutputPath = timingManifestOutputPath
+    ? path.resolve(cwd, timingManifestOutputPath)
+    : undefined
+
+  if (resolvedProfileJsonPath && resolvedTimingManifestOutputPath && resolvedProfileJsonPath === resolvedTimingManifestOutputPath) {
+    throw new Error("Test profiling output paths must be different")
+  }
+
+  if (resolvedTimingManifestPath && (
+    resolvedProfileJsonPath === resolvedTimingManifestPath ||
+    resolvedTimingManifestOutputPath === resolvedTimingManifestPath
+  )) {
+    throw new Error("Test profiling outputs must not overwrite --timing-manifest input")
+  }
+
+  return {
+    profile: profile || Boolean(resolvedProfileJsonPath || resolvedTimingManifestOutputPath),
+    profileJsonPath: resolvedProfileJsonPath,
+    timingManifestPath: resolvedTimingManifestPath,
+    timingManifestOutputPath: resolvedTimingManifestOutputPath
+  }
+}
+
 /**
  * Loads an optional JSON timing manifest. Unreadable or malformed input intentionally falls back to heuristics.
  * @param {string | undefined} timingManifestPath - Timing manifest path.

package/build/environment-handlers/node.js

@@ -43,7 +43,7 @@ import { createSharedTransactionProxyDriver, sharedTransactionBrokerConfig } fro
 
 /**
  * Defines this typedef.
- * @typedef {{ability?: import("../authorization/ability.js").default, offsetMinutes: number, requestTiming?: import("../http-server/client/request-timing.js").default, tenant?: ReturnType<typeof JSON.parse>, timeZone?: string}} TimezoneStore */
+ * @typedef {{ability?: import("../authorization/ability.js").default, offsetMinutes: number, requestTiming?: import("../http-server/client/request-timing.js").default, tenant?: ReturnType<typeof JSON.parse>, testProfileContext?: import("../testing/test-profiler.js").TestProfileAsyncContext, timeZone?: string}} TimezoneStore */
 
 /**
  * Runs path within allowed prefixes.
@@ -147,6 +147,36 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return this._sharedTransactionCoordinatorAsyncLocalStorage.run(owners, callback)
   }
 
+  /**
+   * Runs work with async-safe test profile attribution.
+   * @template T
+   * @param {import("../testing/test-profiler.js").TestProfileAsyncContext | undefined} context - Captured profile context, or an explicit absence of attribution.
+   * @param {() => T} callback - Profiled work.
+   * @returns {T} - Callback result.
+   */
+  runWithTestProfileContext(context, callback) {
+    if (!this._timezoneAsyncLocalStorage) return callback()
+
+    const existingStore = this._timezoneAsyncLocalStorage.getStore()
+
+    return this._timezoneAsyncLocalStorage.run({
+      ability: existingStore?.ability,
+      offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
+      requestTiming: existingStore?.requestTiming,
+      tenant: existingStore?.tenant,
+      testProfileContext: context,
+      timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
+    }, callback)
+  }
+
+  /**
+   * Gets the current async-safe test profile attribution context.
+   * @returns {import("../testing/test-profiler.js").TestProfileAsyncContext | undefined} - Current context.
+   */
+  getCurrentTestProfileContext() {
+    return this._timezoneAsyncLocalStorage?.getStore()?.testProfileContext
+  }
+
   /**
    * Find commands result.
    * @type {import("./base.js").CommandFileObjectType[] | undefined} */
@@ -378,6 +408,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       offsetMinutes,
       requestTiming: existingStore?.requestTiming,
       tenant: existingStore?.tenant,
+      testProfileContext: existingStore?.testProfileContext,
       timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
     }, callback)
   }
@@ -400,6 +431,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
       requestTiming: existingStore?.requestTiming,
       tenant: existingStore?.tenant,
+      testProfileContext: existingStore?.testProfileContext,
       timeZone: validateTimeZone(timeZone, "timeZone")
     }, callback)
   }
@@ -424,6 +456,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         offsetMinutes,
         requestTiming: existingStore?.requestTiming,
         tenant: existingStore?.tenant,
+        testProfileContext: existingStore?.testProfileContext,
         timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
       })
     }
@@ -453,6 +486,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
         requestTiming: existingStore?.requestTiming,
         tenant: existingStore?.tenant,
+        testProfileContext: existingStore?.testProfileContext,
         timeZone: normalizedTimeZone
       })
     }
@@ -510,6 +544,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
       requestTiming: existingStore?.requestTiming,
       tenant: existingStore?.tenant,
+      testProfileContext: existingStore?.testProfileContext,
       timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
     }, callback)
   }
@@ -535,6 +570,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         offsetMinutes: this.getTimezoneOffsetMinutes(this.getConfiguration()),
         requestTiming: undefined,
         tenant: undefined,
+        testProfileContext: undefined,
         timeZone: this.getTimeZone(this.getConfiguration())
       })
     }
@@ -570,6 +606,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
       requestTiming,
       tenant: existingStore?.tenant,
+      testProfileContext: existingStore?.testProfileContext,
       timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
     }, callback)
   }
@@ -604,6 +641,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       offsetMinutes: existingStore?.offsetMinutes ?? this.getTimezoneOffsetMinutes(this.getConfiguration()),
       requestTiming: existingStore?.requestTiming,
       tenant,
+      testProfileContext: existingStore?.testProfileContext,
       timeZone: existingStore?.timeZone ?? this.getTimeZone(this.getConfiguration())
     }, callback)
   }
@@ -629,6 +667,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         offsetMinutes: this.getTimezoneOffsetMinutes(this.getConfiguration()),
         requestTiming: undefined,
         tenant,
+        testProfileContext: undefined,
         timeZone: this.getTimeZone(this.getConfiguration())
       })
     }

package/build/src/configuration.d.ts

@@ -1346,6 +1346,15 @@ export default class VelociousConfiguration {
      * @returns {Promise<ReturnType<typeof JSON.parse>>} - Callback result.
      */
     runWithRequestTiming(requestTiming: import("./http-server/client/request-timing.js").default | undefined, callback: () => Promise<ReturnType<typeof JSON.parse>>): Promise<ReturnType<typeof JSON.parse>>;
+    /**
+     * Profiles an application-defined test activity when an opt-in test profile
+     * context is active. The callback always runs, including outside profiling.
+     * @template T
+     * @param {string} name - Low-cardinality activity identifier.
+     * @param {() => (T | Promise<T>)} callback - Activity callback.
+     * @returns {Promise<T>} - Callback result.
+     */
+    profileTestActivity<T>(name: string, callback: () => (T | Promise<T>)): Promise<T>;
     /**
      * Runs run with timezone.
      * @param {string} timeZone - IANA timezone identifier.