chore(debugger): add JSDoc types to debugger tests (#6962)

Author: watson

benchmark/sirun/debugger/start-devtools-client.js

@@ -1,13 +1,17 @@
 'use strict'
 
+const assert = require('node:assert')
+
 const getConfig = require('../../../packages/dd-trace/src/config')
 const { start } = require('../../../packages/dd-trace/src/debugger')
 const { generateProbeConfig } = require('../../../packages/dd-trace/test/debugger/devtools_client/utils')
 
-const breakpoint = {
-  file: process.env.BREAKPOINT_FILE,
-  line: process.env.BREAKPOINT_LINE
-}
+const sourceFile = process.env.BREAKPOINT_FILE
+const line = Number(process.env.BREAKPOINT_LINE)
+assert(sourceFile, 'BREAKPOINT_FILE environment variable must be set')
+assert(!Number.isNaN(line), 'BREAKPOINT_LINE environment variable must be a number')
+
+const breakpoint = { sourceFile, line }
 const config = getConfig()
 const rc = {
   setProductHandler (product, cb) {

integration-tests/debugger/re-evaluation.spec.js

@@ -114,9 +114,10 @@ describe('Dynamic Instrumentation Probe Re-Evaluation', function () {
               DD_DYNAMIC_INSTRUMENTATION_UPLOAD_INTERVAL_SECONDS: '0',
               DD_TRACE_AGENT_PORT: agent.port,
               DD_TRACE_DEBUG: process.env.DD_TRACE_DEBUG, // inherit to make debugging the sandbox easier
-              DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS: 0.1
+              DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS: '0.1'
             }
           }).then(_proc => {
+            assert(_proc, 'proc must be spawned successfully')
             proc = _proc
             // Possible race condition, in case axios.get() is called in the test before it's created here. But we have
             // to start the test quickly in order to test the re-evaluation of the probe.

integration-tests/debugger/utils.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const assert = require('assert')
 const { basename, join } = require('path')
 const { readFileSync } = require('fs')
 const { randomUUID } = require('crypto')
@@ -12,27 +13,111 @@ const { generateProbeConfig } = require('../../packages/dd-trace/test/debugger/d
 const BREAKPOINT_TOKEN = '// BREAKPOINT'
 const pollInterval = 0.1
 
+/**
+ * @typedef {import('../../packages/dd-trace/test/debugger/devtools_client/utils').ProbeConfig} ProbeConfig
+ */
+
+/**
+ * @typedef {typeof import('../../packages/dd-trace/test/debugger/devtools_client/utils').generateProbeConfig}
+ *   GenerateProbeConfigFn
+ */
+
+/**
+ * @typedef {Object} BreakpointInfo
+ * @property {string} sourceFile
+ * @property {string} deployedFile
+ * @property {number} line
+ * @property {string} url
+ */
+
+/**
+ * A breakpoint with helpers bound for convenient testing.
+ *
+ * @typedef {BreakpointInfo & {
+ *   rcConfig: object|null,
+ *   triggerBreakpoint: (url: string) => Promise<import('axios').AxiosResponse<unknown>>,
+ *   generateRemoteConfig: (overrides?: object) => object,
+ *   generateProbeConfig: GenerateProbeConfigFn
+ * }} EnrichedBreakpoint
+ */
+
+/**
+ * The live‑debugger integration test harness returned by {@link setup}. Provides the spawned app process, fake agent,
+ * axios client, and helpers to generate remote config and trigger breakpoints.
+ *
+ * @typedef {Object} DebuggerTestEnvironment
+ * @property {BreakpointInfo} breakpoint - Primary breakpoint metadata.
+ * @property {EnrichedBreakpoint[]} breakpoints - All discovered breakpoints with helpers.
+ * @property {import('axios').AxiosInstance} axios - HTTP client bound to the test app. Throws if accessed before
+ *   `beforeEach` hook runs.
+ * @property {string} appFile - Absolute path to the test app entry file. Throws if accessed before `before` hook runs.
+ * @property {import('../helpers').FakeAgent} agent - Started fake agent instance. Throws if accessed before
+ *   `beforeEach` hook runs.
+ * @property {import('../helpers').SpawnedProcess} proc - Spawned app process. Throws if accessed before `beforeEach`
+ *   hook runs.
+ * @property {object|null} rcConfig - Default remote config for the primary breakpoint.
+ * @property {() => Promise<import('axios').AxiosResponse<unknown>>} triggerBreakpoint - Triggers the primary breakpoint
+ *   once installed.
+ * @property {(overrides?: object) => object} generateRemoteConfig - Generates RC for the primary breakpoint.
+ * @property {GenerateProbeConfigFn} generateProbeConfig - Generates probe config for the primary breakpoint.
+ */
+
 module.exports = {
   pollInterval,
   setup
 }
 
+/**
+ * Setup the integration test harness for live‑debugger scenarios.
+ *
+ * @param {object} [options] The options for the test environment.
+ * @param {object} [options.env] The environment variables to set in the test environment.
+ * @param {string} [options.testApp] The path to the test application file.
+ * @param {string} [options.testAppSource] The path to the test application source file.
+ * @param {string[]} [options.dependencies] The dependencies to install in the test environment.
+ * @param {boolean} [options.silent] Whether to silence the output of the test environment.
+ * @param {(data: Buffer) => void} [options.stdioHandler] The function to handle the standard output of the test
+ *   environment.
+ * @param {(data: Buffer) => void} [options.stderrHandler] The function to handle the standard error output of the test
+ *   environment.
+ * @returns {DebuggerTestEnvironment} Test harness with agent, app process, axios client and breakpoint helpers.
+ */
 function setup ({ env, testApp, testAppSource, dependencies, silent, stdioHandler, stderrHandler } = {}) {
-  let cwd
+  let cwd, axios, appFile, agent, proc
 
   const breakpoints = getBreakpointInfo({
     deployedFile: testApp,
     sourceFile: testAppSource,
     stackIndex: 1 // `1` to disregard the `setup` function
-  })
+  }).map((breakpoint) => /** @type {EnrichedBreakpoint} */ ({
+    rcConfig: null,
+    triggerBreakpoint: triggerBreakpoint.bind(null, breakpoint.url),
+    generateRemoteConfig: generateRemoteConfig.bind(null, breakpoint),
+    generateProbeConfig: generateProbeConfig.bind(null, breakpoint),
+    ...breakpoint
+  }))
 
+  /** @type {DebuggerTestEnvironment} */
   const t = {
     breakpoint: breakpoints[0],
     breakpoints,
 
-    axios: null,
-    appFile: null,
-    agent: null,
+    get axios () {
+      assert(axios, 'axios must be initialized in beforeEach hook')
+      return axios
+    },
+    get appFile () {
+      assert(appFile, 'appFile must be initialized in before hook')
+      return appFile
+    },
+    get agent () {
+      assert(agent, 'agent must be initialized in beforeEach hook')
+      return agent
+    },
+    get proc () {
+      assert(proc, 'proc must be initialized in beforeEach hook')
+      return proc
+    },
 
     // Default to the first breakpoint in the file (normally there's only one)
     rcConfig: null,
@@ -41,18 +126,13 @@ function setup ({ env, testApp, testAppSource, dependencies, silent, stdioHandle
     generateProbeConfig: generateProbeConfig.bind(null, breakpoints[0])
   }
 
-  // Allow specific access to each breakpoint
-  for (let i = 0; i < breakpoints.length; i++) {
-    t.breakpoints[i] = {
-      rcConfig: null,
-      triggerBreakpoint: triggerBreakpoint.bind(null, breakpoints[i].url),
-      generateRemoteConfig: generateRemoteConfig.bind(null, breakpoints[i]),
-      generateProbeConfig: generateProbeConfig.bind(null, breakpoints[i]),
-      ...breakpoints[i]
-    }
-  }
-
-  // Trigger the breakpoint once probe is successfully installed
+  /**
+   * Trigger the breakpoint once probe is successfully installed
+   *
+   * @param {string} url The URL of the HTTP route containing the breakpoint to trigger.
+   * @returns {Promise<import('axios').AxiosResponse<unknown>>} A promise that resolves with the response from the HTTP
+   *   request after the breakpoint is triggered.
+   */
   async function triggerBreakpoint (url) {
     let triggered = false
     return new Promise((resolve, reject) => {
@@ -67,6 +147,13 @@ function setup ({ env, testApp, testAppSource, dependencies, silent, stdioHandle
     })
   }
 
+  /**
+   * Generate a remote config for a breakpoint
+   *
+   * @param {BreakpointInfo} breakpoint - The breakpoint to generate a remote config for.
+   * @param {object} [overrides] - The overrides to apply to the remote config.
+   * @returns {object} - The remote config.
+   */
   function generateRemoteConfig (breakpoint, overrides = {}) {
     overrides.id = overrides.id || randomUUID()
     return {
@@ -81,7 +168,7 @@ function setup ({ env, testApp, testAppSource, dependencies, silent, stdioHandle
   before(function () {
     cwd = sandboxCwd()
     // The sandbox uses the `integration-tests` folder as its root
-    t.appFile = join(cwd, 'debugger', breakpoints[0].deployedFile)
+    appFile = join(cwd, 'debugger', breakpoints[0].deployedFile)
   })
 
   beforeEach(async function () {
@@ -90,8 +177,8 @@ function setup ({ env, testApp, testAppSource, dependencies, silent, stdioHandle
     // Allow specific access to each breakpoint
     t.breakpoints.forEach((breakpoint) => { breakpoint.rcConfig = generateRemoteConfig(breakpoint) })
 
-    t.agent = await new FakeAgent().start()
-    t.proc = await spawnProc(t.appFile, {
+    agent = await new FakeAgent().start()
+    proc = await spawnProc(/** @type {string} */ (t.appFile), {
       cwd,
       env: {
         DD_DYNAMIC_INSTRUMENTATION_ENABLED: 'true',
@@ -103,7 +190,7 @@ function setup ({ env, testApp, testAppSource, dependencies, silent, stdioHandle
       },
       silent: silent ?? false
     }, stdioHandler, stderrHandler)
-    t.axios = Axios.create({ baseURL: t.proc.url })
+    axios = Axios.create({ baseURL: t.proc.url })
   })
 
   afterEach(async function () {
@@ -114,10 +201,20 @@ function setup ({ env, testApp, testAppSource, dependencies, silent, stdioHandle
   return t
 }
 
+/**
+ * Get breakpoint information from a test file by scanning for BREAKPOINT_TOKEN markers.
+ *
+ * @param {Object} [options] - Options for finding breakpoints.
+ * @param {string} [options.deployedFile] - The deployed file path. If not provided, will be inferred from the stack
+ *   trace.
+ * @param {string} [options.sourceFile] - The source file path. Defaults to `deployedFile` if not provided.
+ * @param {number} [options.stackIndex=0] - The stack index to use when inferring the file from the stack trace.
+ * @returns {BreakpointInfo[]} An array of breakpoint information objects found in the file.
+ */
 function getBreakpointInfo ({ deployedFile, sourceFile = deployedFile, stackIndex = 0 } = {}) {
   if (!deployedFile) {
     // First, get the filename of file that called this function
-    const testFile = new Error().stack
+    const testFile = /** @type {string} */ (new Error().stack)
       .split('\n')[stackIndex + 2] // +2 to skip this function + the first line, which is the error message
       .split(' (')[1]
       .slice(0, -1)
@@ -127,6 +224,8 @@ function getBreakpointInfo ({ deployedFile, sourceFile = deployedFile, stackInde
     deployedFile = sourceFile = join('target-app', basename(testFile).replace('.spec', ''))
   }
 
+  assert(sourceFile, 'sourceFile must be provided or inferred from stack trace')
+
   // Finally, find the line number(s) of the breakpoint(s)
   const lines = readFileSync(join(__dirname, sourceFile), 'utf8').split('\n')
   const result = []

integration-tests/helpers/index.js

@@ -164,6 +164,10 @@ function assertTelemetryPoints (pid, msgs, expectedTelemetryPoints) {
   }
 }
 
+/**
+ * @typedef {childProcess.ChildProcess & { url: string }} SpawnedProcess
+ */
+
 /**
  * Spawns a Node.js script in a child process and returns a promise that resolves when the process is ready.
  *
@@ -173,14 +177,14 @@ function assertTelemetryPoints (pid, msgs, expectedTelemetryPoints) {
  *   standard output of the child process. If not provided, the output will be logged to the console.
  * @param {(data: Buffer) => void} [stderrHandler] - A function that's called with one data argument to handle the
  *   standard error of the child process. If not provided, the error will be logged to the console.
- * @returns {Promise<childProcess.ChildProcess & { url?: string }|void>} A promise that resolves when the process
- *   is either ready or terminated without an error. If the process is terminated without an error, the promise will
- *   resolve with `undefined`.The returned process will have a `url` property if the process didn't terminate.
+ * @returns {Promise<SpawnedProcess|void>} A promise that resolves when the process is either ready or terminated
+ *   without an error. If the process is terminated without an error, the promise will resolve with `undefined`. The
+ *   returned process will have a `url` property if the process didn't terminate.
  */
 function spawnProc (filename, options = {}, stdioHandler, stderrHandler) {
   const proc = fork(filename, { ...options, stdio: 'pipe' })
 
-  return /** @type {Promise<childProcess.ChildProcess & { url?: string }|void>} */ (new Promise((resolve, reject) => {
+  return /** @type {Promise<SpawnedProcess|void>} */ (new Promise((resolve, reject) => {
     proc
       .on('message', ({ port }) => {
         if (typeof port !== 'number' && typeof port !== 'string') {

packages/dd-trace/test/debugger/devtools_client/index.spec.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const assert = require('node:assert')
+
 const { expect } = require('chai')
 const { describe, it, beforeEach } = require('mocha')
 const sinon = require('sinon')
@@ -23,7 +25,24 @@ const event = {
 }
 
 describe('onPause', function () {
-  let session, send, onPaused, ackReceived, log
+  /**
+   * @typedef {{
+   *   on: sinon.SinonSpy & { args: Array<[string, Function]> },
+   *   post: sinon.SinonSpy,
+   *   emit: sinon.SinonSpy,
+   *   '@noCallThru'?: boolean
+   * }} MockSession
+   */
+  /** @type {MockSession} */
+  let session
+  /** @type {Function} */
+  let send
+  /** @type {Function} */
+  let onPaused
+  /** @type {sinon.SinonSpy} */
+  let ackReceived
+  /** @type {unknown} */
+  let log
 
   beforeEach(async function () {
     ackReceived = sinon.spy()
@@ -82,6 +101,7 @@ describe('onPause', function () {
     })
 
     const onPausedCall = session.on.args.find(([event]) => event === 'Debugger.paused')
+    assert(onPausedCall, 'onPaused call should be found')
     onPaused = onPausedCall[1]
   })
 

packages/dd-trace/test/debugger/devtools_client/log.spec.js

@@ -23,6 +23,7 @@ describe('worker thread logger', function () {
       { level: 'debug', args: ['test4'] }
     ]
 
+    // @ts-expect-error - MessagePort has 'on' method at runtime but @types/node doesn't include it
     logChannel.port2.on('message', (message) => {
       assert.deepStrictEqual(message, expected.shift())
       if (expected.length === 0) done()
@@ -42,6 +43,7 @@ describe('worker thread logger', function () {
       }
     })
 
+    // @ts-expect-error - MessagePort has 'on' method at runtime but @types/node doesn't include it
     logChannel.port2.on('message', () => {
       throw new Error('should not have logged')
     })
@@ -62,6 +64,7 @@ describe('worker thread logger', function () {
       }
     })
 
+    // @ts-expect-error - MessagePort has 'on' method at runtime but @types/node doesn't include it
     logChannel.port2.on('message', (message) => {
       assert.deepStrictEqual(message, { level: 'debug', args: ['logged'] })
       done()
@@ -93,6 +96,7 @@ function checkLogLevel (level, expectedLevels) {
 
     const expected = expectedLevels.map((level) => ({ level, args: ['logged'] }))
 
+    // @ts-expect-error - MessagePort has 'on' method at runtime but @types/node doesn't include it
     logChannel.port2.on('message', (message) => {
       assert.deepStrictEqual(message, expected.shift())
       if (expected.length === 0) done()

packages/dd-trace/test/debugger/devtools_client/send.spec.js

@@ -27,7 +27,14 @@ const dd = { dd: true }
 const snapshot = { snapshot: true }
 
 describe('input message http requests', function () {
-  let clock, send, request, jsonBuffer
+  /** @type {sinon.SinonFakeTimers} */
+  let clock
+  /** @type {Function} */
+  let send
+  /** @type {sinon.SinonSpy} */
+  let request
+  /** @type {import('../../../src/debugger/devtools_client/json-buffer')} */
+  let jsonBuffer
 
   beforeEach(function () {
     clock = sinon.useFakeTimers({
@@ -108,6 +115,10 @@ describe('input message http requests', function () {
   })
 })
 
+/**
+ * @param {object} [_message] - The message to get the payload for. Defaults to the {@link message} object.
+ * @returns {object} - The payload.
+ */
 function getPayload (_message = message) {
   return {
     ddsource,

packages/dd-trace/test/debugger/devtools_client/snapshot/stub-session.js

@@ -1,7 +1,8 @@
 'use strict'
 
 const inspector = require('../../../../src/debugger/devtools_client/inspector_promises_polyfill')
-const session = module.exports = new inspector.Session()
+const session = module.exports = /** @type {import('../../../../src/debugger/devtools_client/session').CDPSession} */
+  (new inspector.Session())
 session.connect()
 
 session['@noCallThru'] = true