velocious 1.0.591 → 1.0.593

package/scripts/browser-test-session.js

@@ -0,0 +1,489 @@
+// @ts-check
+
+import { spawn } from "node:child_process"
+import { execFile } from "node:child_process"
+import fs from "node:fs/promises"
+import { createRequire } from "node:module"
+import path from "node:path"
+import { promisify } from "node:util"
+import timeout from "awaitery/build/timeout.js"
+
+/**
+ * @typedef {object} BrowserTestChromeRuntime
+ * @property {string} browserPath - Chrome executable path.
+ * @property {string} browserVersion - Chrome version.
+ * @property {string} driverPath - ChromeDriver executable path.
+ * @property {string} driverVersion - ChromeDriver version.
+ */
+
+/**
+ * @typedef {object} BrowserTestSystemTest
+ * @property {() => Promise<void>} start - Starts SystemTest.
+ * @property {() => Promise<void>} stop - Stops SystemTest.
+ */
+
+/**
+ * @typedef {object} BrowserTestChromeDriverService
+ * @property {() => Promise<string>} start - Starts ChromeDriver and returns its URL.
+ * @property {() => Promise<void>} stop - Stops ChromeDriver and its process group.
+ * @property {() => Promise<string>} diagnostics - Reads retained ChromeDriver diagnostics.
+ */
+
+const require = createRequire(import.meta.url)
+const { binaryPaths } = require("selenium-webdriver/common/seleniumManager.js")
+const { CancellationError, waitForServer } = require("selenium-webdriver/http/util.js")
+const { findFreePort } = require("selenium-webdriver/net/portprober.js")
+const execFileAsync = promisify(execFile)
+const CHROMEDRIVER_START_TIMEOUT_MS = 30000
+const PROCESS_STOP_TIMEOUT_MS = 10000
+
+/** @returns {string} - Default runtime manifest path. */
+function defaultManifestPath() {
+  return path.join(process.cwd(), "tmp", "browser-test-chrome-runtime.json")
+}
+
+/** @returns {string} - Default diagnostic directory. */
+function defaultDiagnosticsDirectory() {
+  return path.join(process.cwd(), "tmp", "browser-test-chrome")
+}
+
+/**
+ * @param {string} executablePath - Executable path.
+ * @returns {Promise<string>} - Version command output.
+ */
+async function readExecutableVersion(executablePath) {
+  const { stdout, stderr } = await execFileAsync(executablePath, ["--version"])
+
+  return `${stdout}${stderr}`.trim()
+}
+
+/**
+ * @param {string} versionOutput - Version command output.
+ * @param {string} executableName - Executable description.
+ * @returns {string} - Parsed four-part version.
+ */
+function parseExecutableVersion(versionOutput, executableName) {
+  const match = versionOutput.match(/\b(\d+\.\d+\.\d+\.\d+)\b/)
+
+  if (!match) throw new Error(`Could not parse ${executableName} version from: ${versionOutput}`)
+
+  return match[1]
+}
+
+/**
+ * @param {string} executablePath - Executable path.
+ * @param {string} description - Executable description.
+ * @returns {Promise<void>} - Resolves when executable exists and is executable.
+ */
+async function assertExecutable(executablePath, description) {
+  if (!path.isAbsolute(executablePath)) {
+    throw new Error(`${description} path must be absolute: ${executablePath}`)
+  }
+
+  try {
+    await fs.access(executablePath, fs.constants.X_OK)
+  } catch (error) {
+    throw new Error(`${description} is not executable: ${executablePath}`, {cause: error})
+  }
+}
+
+/**
+ * Resolves, validates, and persists the exact Chrome/ChromeDriver pair.
+ * @param {object} [args] - Prewarm options.
+ * @param {() => {browserPath?: string, driverPath?: string}} [args.binaryPathsResolver] - Selenium path resolver.
+ * @param {string} [args.manifestPath] - Runtime manifest path.
+ * @param {(executablePath: string) => Promise<string>} [args.versionReader] - Executable version reader.
+ * @returns {Promise<BrowserTestChromeRuntime>} - Prewarmed runtime.
+ */
+export async function prewarmBrowserTestChromeRuntime({
+  binaryPathsResolver = () => binaryPaths([
+    "--browser",
+    "chrome",
+    "--language-binding",
+    "javascript",
+    "--output",
+    "json",
+    "--avoid-browser-download"
+  ]),
+  manifestPath = defaultManifestPath(),
+  versionReader = readExecutableVersion
+} = {}) {
+  const { browserPath, driverPath } = binaryPathsResolver()
+
+  if (!browserPath) throw new Error("Selenium Manager did not resolve a Chrome executable")
+  if (!driverPath) throw new Error("Selenium Manager did not resolve a ChromeDriver executable")
+
+  await assertExecutable(browserPath, "Chrome")
+  await assertExecutable(driverPath, "ChromeDriver")
+
+  let browserVersionOutput
+  let driverVersionOutput
+
+  try {
+    browserVersionOutput = await versionReader(browserPath)
+  } catch (error) {
+    throw new Error(`Chrome could not report its version at ${browserPath}`, {cause: error})
+  }
+
+  try {
+    driverVersionOutput = await versionReader(driverPath)
+  } catch (error) {
+    throw new Error(`ChromeDriver could not report its version at ${driverPath}`, {cause: error})
+  }
+
+  const browserVersion = parseExecutableVersion(browserVersionOutput, "Chrome")
+  const driverVersion = parseExecutableVersion(driverVersionOutput, "ChromeDriver")
+
+  if (browserVersion.split(".")[0] !== driverVersion.split(".")[0]) {
+    throw new Error(`Chrome ${browserVersion} is incompatible with ChromeDriver ${driverVersion}`)
+  }
+
+  const runtime = {browserPath, browserVersion, driverPath, driverVersion}
+
+  await fs.mkdir(path.dirname(manifestPath), {recursive: true})
+  await fs.writeFile(manifestPath, `${JSON.stringify(runtime, null, 2)}\n`, "utf8")
+
+  return runtime
+}
+
+/**
+ * Loads the exact runtime persisted by prewarming.
+ * @param {object} [args] - Load options.
+ * @param {string} [args.manifestPath] - Runtime manifest path.
+ * @returns {Promise<BrowserTestChromeRuntime>} - Persisted runtime.
+ */
+export async function loadBrowserTestChromeRuntime({manifestPath = defaultManifestPath()} = {}) {
+  const parsed = JSON.parse(await fs.readFile(manifestPath, "utf8"))
+  const browserPath = parsed?.browserPath
+  const browserVersion = parsed?.browserVersion
+  const driverPath = parsed?.driverPath
+  const driverVersion = parsed?.driverVersion
+
+  if (typeof browserPath !== "string" || typeof browserVersion !== "string" || typeof driverPath !== "string" || typeof driverVersion !== "string") {
+    throw new Error(`Invalid browser test Chrome runtime manifest: ${manifestPath}`)
+  }
+
+  await assertExecutable(browserPath, "Chrome")
+  await assertExecutable(driverPath, "ChromeDriver")
+
+  return {browserPath, browserVersion, driverPath, driverVersion}
+}
+
+/**
+ * Loads a prewarmed runtime, preparing it for direct local browser runs when absent.
+ * @returns {Promise<BrowserTestChromeRuntime>} - Browser runtime.
+ */
+export async function loadOrPrewarmBrowserTestChromeRuntime() {
+  try {
+    return await loadBrowserTestChromeRuntime()
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return await prewarmBrowserTestChromeRuntime()
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Formats a child process exit.
+ * @param {{code: number | null, error?: Error, signal: NodeJS.Signals | null}} result - Exit result.
+ * @returns {string} - Exit description.
+ */
+function formatProcessExit(result) {
+  if (result.error) return result.error.message
+  if (result.signal) return `signal ${result.signal}`
+
+  return `exit code ${String(result.code)}`
+}
+
+export class ManagedChromeDriverProcess {
+  /**
+   * @param {BrowserTestChromeRuntime} runtime - Chrome runtime.
+   * @param {string} [diagnosticsDirectory] - Diagnostic output directory.
+   */
+  constructor(runtime, diagnosticsDirectory = defaultDiagnosticsDirectory()) {
+    this.runtime = runtime
+    this.diagnosticsDirectory = diagnosticsDirectory
+    this.driverLogPath = path.join(diagnosticsDirectory, "chromedriver.log")
+    this.processOutputPath = path.join(diagnosticsDirectory, "chromedriver-process.log")
+    /** @type {import("node:child_process").ChildProcess | undefined} */
+    this.child = undefined
+    /** @type {Promise<{code: number | null, error?: Error, signal: NodeJS.Signals | null}> | undefined} */
+    this.exitResult = undefined
+    /** @type {import("node:fs/promises").FileHandle | undefined} */
+    this.outputFile = undefined
+  }
+
+  /** @returns {Promise<string>} - ChromeDriver service URL. */
+  async start() {
+    await fs.mkdir(this.diagnosticsDirectory, {recursive: true})
+    await fs.rm(this.driverLogPath, {force: true})
+    this.outputFile = await fs.open(this.processOutputPath, "w")
+
+    const port = await findFreePort("127.0.0.1")
+    const child = spawn(this.runtime.driverPath, [
+      `--port=${port}`,
+      "--verbose",
+      `--log-path=${this.driverLogPath}`,
+      "--enable-chrome-logs"
+    ], {
+      detached: process.platform !== "win32",
+      stdio: ["ignore", this.outputFile.fd, this.outputFile.fd]
+    })
+
+    this.child = child
+    this.exitResult = new Promise((resolve) => {
+      child.once("error", (error) => resolve({code: null, error, signal: null}))
+      child.once("exit", (code, signal) => resolve({code, signal}))
+    })
+
+    const serviceUrl = `http://127.0.0.1:${port}`
+    const earlyExit = this.exitResult.then((result) => {
+      throw new Error(`ChromeDriver terminated during startup with ${formatProcessExit(result)}`)
+    })
+    const exitCancellation = this.exitResult.then(() => undefined)
+
+    try {
+      await Promise.race([
+        waitForServer(serviceUrl, CHROMEDRIVER_START_TIMEOUT_MS, exitCancellation),
+        earlyExit
+      ])
+    } catch (error) {
+      if (error instanceof CancellationError) await earlyExit
+
+      throw error
+    }
+
+    return serviceUrl
+  }
+
+  /**
+   * @param {NodeJS.Signals} signal - Signal to deliver.
+   * @returns {void}
+   */
+  signalProcessGroup(signal) {
+    const child = this.child
+
+    if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return
+
+    try {
+      if (process.platform === "win32") {
+        child.kill(signal)
+      } else {
+        process.kill(-child.pid, signal)
+      }
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return
+
+      throw error
+    }
+  }
+
+  /** @returns {Promise<void>} - Stops ChromeDriver and Chrome descendants. */
+  async stop() {
+    let stopError
+
+    try {
+      if (this.exitResult && this.child?.exitCode === null && this.child.signalCode === null) {
+        this.signalProcessGroup("SIGTERM")
+
+        try {
+          await timeout({
+            timeout: PROCESS_STOP_TIMEOUT_MS,
+            errorMessage: "Timed out waiting for ChromeDriver process group to stop"
+          }, async () => await this.exitResult)
+        } catch (error) {
+          this.signalProcessGroup("SIGKILL")
+          await this.exitResult
+          stopError = error instanceof Error ? error : new Error(String(error))
+        }
+      }
+    } catch (error) {
+      stopError = error instanceof Error ? error : new Error(String(error))
+    }
+
+    try {
+      await this.outputFile?.close()
+    } catch (error) {
+      const outputCloseError = error instanceof Error ? error : new Error(String(error))
+      stopError = stopError
+        ? new AggregateError([stopError, outputCloseError], "ChromeDriver process and output cleanup failed")
+        : outputCloseError
+    }
+
+    this.outputFile = undefined
+
+    if (stopError) throw stopError
+  }
+
+  /** @returns {Promise<string>} - Retained ChromeDriver diagnostics. */
+  async diagnostics() {
+    const sections = []
+
+    for (const [label, filePath] of [
+      ["ChromeDriver log", this.driverLogPath],
+      ["ChromeDriver process output", this.processOutputPath]
+    ]) {
+      try {
+        const content = await fs.readFile(filePath, "utf8")
+        sections.push(`${label} (${filePath}):\n${content || "(empty)"}`)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        sections.push(`${label} (${filePath}) unavailable: ${message}`)
+      }
+    }
+
+    return sections.join("\n")
+  }
+}
+
+/**
+ * Captures Chrome and ChromeDriver processes for startup diagnostics.
+ * @param {string} phase - Snapshot phase.
+ * @returns {Promise<string>} - Process snapshot.
+ */
+async function browserProcessSnapshot(phase) {
+  if (process.platform === "win32") return `${phase}: browser process snapshots are unavailable on Windows`
+
+  try {
+    const { stdout } = await execFileAsync("ps", ["-eo", "pid,ppid,pgid,stat,etime,comm,args"])
+    const processLines = stdout
+      .split("\n")
+      .filter((line) => /\s(?:chrome|chromedriver|google-chrome)\s/.test(line))
+
+    return `${phase}:\n${processLines.length > 0 ? processLines.join("\n") : "(no Chrome/ChromeDriver processes)"}`
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return `${phase}: process snapshot failed: ${message}`
+  }
+}
+
+/**
+ * Owns ChromeDriver and SystemTest startup as one cleanup boundary.
+ */
+export class BrowserTestSession {
+  /**
+   * @param {object} args - Session options.
+   * @param {(runtime: BrowserTestChromeRuntime) => Promise<BrowserTestChromeDriverService>} [args.chromeDriverServiceFactory] - Driver service factory.
+   * @param {(phase: string) => Promise<string>} [args.processSnapshot] - Process snapshot callback.
+   * @param {BrowserTestChromeRuntime} args.runtime - Chrome runtime.
+   * @param {(args: {browserPath: string, remoteUrl: string}) => BrowserTestSystemTest} args.systemTestFactory - SystemTest factory.
+   */
+  constructor({
+    chromeDriverServiceFactory = async (runtime) => new ManagedChromeDriverProcess(runtime),
+    processSnapshot = browserProcessSnapshot,
+    runtime,
+    systemTestFactory
+  }) {
+    this.chromeDriverServiceFactory = chromeDriverServiceFactory
+    this.processSnapshot = processSnapshot
+    this.runtime = runtime
+    this.systemTestFactory = systemTestFactory
+    /** @type {BrowserTestChromeDriverService | undefined} */
+    this.chromeDriverService = undefined
+    /** @type {BrowserTestSystemTest | undefined} */
+    this.systemTest = undefined
+    this.remoteUrlWasPresent = false
+    /** @type {string | undefined} */
+    this.previousRemoteUrl = undefined
+    /** @type {string | undefined} */
+    this.remoteUrl = undefined
+    this.startupPhase = "creating ChromeDriver service"
+    this.stopped = false
+  }
+
+  /** @returns {Promise<BrowserTestSystemTest>} - Started SystemTest instance. */
+  async start() {
+    this.remoteUrlWasPresent = Object.hasOwn(process.env, "SELENIUM_REMOTE_URL")
+    this.previousRemoteUrl = process.env.SELENIUM_REMOTE_URL
+
+    try {
+      this.chromeDriverService = await this.chromeDriverServiceFactory(this.runtime)
+      this.startupPhase = "starting ChromeDriver service"
+      this.remoteUrl = await this.chromeDriverService.start()
+      process.env.SELENIUM_REMOTE_URL = this.remoteUrl
+      this.systemTest = this.systemTestFactory({browserPath: this.runtime.browserPath, remoteUrl: this.remoteUrl})
+      this.startupPhase = "creating Selenium WebDriver session"
+      await this.systemTest.start()
+
+      return this.systemTest
+    } catch (error) {
+      const startupError = error instanceof Error ? error : new Error(String(error))
+      const beforeCleanup = await this.processSnapshot("before cleanup")
+      const cleanupErrors = await this.stopResources({driverFirst: true})
+      const afterCleanup = await this.processSnapshot("after cleanup")
+      const driverDiagnostics = this.chromeDriverService
+        ? await this.chromeDriverService.diagnostics()
+        : "ChromeDriver service was not created"
+      const message = [
+        `Browser test startup failed while ${this.startupPhase}: ${startupError.message}`,
+        `Chrome: ${this.runtime.browserVersion} (${this.runtime.browserPath})`,
+        `ChromeDriver: ${this.runtime.driverVersion} (${this.runtime.driverPath})`,
+        `ChromeDriver service: ${this.remoteUrl ?? "not started"}`,
+        beforeCleanup,
+        afterCleanup,
+        driverDiagnostics
+      ].join("\n")
+      if (cleanupErrors.length > 0) {
+        throw new AggregateError([startupError, ...cleanupErrors], message, {cause: error})
+      }
+
+      throw new Error(message, {cause: error})
+    }
+  }
+
+  /**
+   * @param {object} args - Cleanup options.
+   * @param {boolean} args.driverFirst - Stop the driver before SystemTest during failed startup.
+   * @returns {Promise<Error[]>} - Cleanup errors.
+   */
+  async stopResources({driverFirst}) {
+    if (this.stopped) return []
+
+    this.stopped = true
+    const cleanupErrors = []
+    const stopDriver = async () => {
+      try {
+        await this.chromeDriverService?.stop()
+      } catch (error) {
+        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)))
+      }
+    }
+    const stopSystemTest = async () => {
+      try {
+        await this.systemTest?.stop()
+      } catch (error) {
+        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)))
+      }
+    }
+
+    if (driverFirst) {
+      await stopDriver()
+      await stopSystemTest()
+    } else {
+      await stopSystemTest()
+      await stopDriver()
+    }
+
+    if (this.remoteUrlWasPresent) {
+      process.env.SELENIUM_REMOTE_URL = this.previousRemoteUrl
+    } else {
+      delete process.env.SELENIUM_REMOTE_URL
+    }
+
+    return cleanupErrors
+  }
+}
+
+/**
+ * Stops SystemTest and the managed ChromeDriver for a browser test session.
+ * @param {BrowserTestSession} session - Browser test session.
+ * @returns {Promise<void>} - Resolves when all session resources have stopped.
+ */
+export async function stopBrowserTestSession(session) {
+  const cleanupErrors = await session.stopResources({driverFirst: false})
+
+  if (cleanupErrors.length === 1) throw cleanupErrors[0]
+  if (cleanupErrors.length > 1) throw new AggregateError(cleanupErrors, "Browser test session cleanup failed")
+}

package/scripts/prewarm-chromedriver.js

@@ -1,26 +1,7 @@
 #!/usr/bin/env node
 
-import fs from "node:fs"
-import { createRequire } from "node:module"
+import { prewarmBrowserTestChromeRuntime } from "./browser-test-session.js"
 
-const require = createRequire(import.meta.url)
-const { binaryPaths } = require("selenium-webdriver/common/seleniumManager.js")
-const { browserPath, driverPath } = binaryPaths([
-  "--browser",
-  "chrome",
-  "--language-binding",
-  "javascript",
-  "--output",
-  "json",
-  "--avoid-browser-download"
-])
+const runtime = await prewarmBrowserTestChromeRuntime()
 
-if (!browserPath || !fs.existsSync(browserPath)) {
-  throw new Error(`Selenium Manager did not find installed Chrome at ${browserPath || "<missing path>"}`)
-}
-
-if (!driverPath || !fs.existsSync(driverPath)) {
-  throw new Error(`Selenium Manager did not provision ChromeDriver at ${driverPath || "<missing path>"}`)
-}
-
-console.log(`Prewarmed ChromeDriver at ${driverPath} for Chrome at ${browserPath}`)
+console.log(`Prewarmed ChromeDriver ${runtime.driverVersion} at ${runtime.driverPath} for Chrome ${runtime.browserVersion} at ${runtime.browserPath}`)

package/scripts/test-browser.js

@@ -20,6 +20,11 @@ import {normalizeExamplePatterns, parseFilters} from "../src/testing/test-filter
 import fileExists from "../src/utils/file-exists.js"
 import dummyDirectory from "../spec/dummy/dummy-directory.js"
 import {withSourcePeerPackage} from "../src/environment-handlers/node/source-peer-package.js"
+import {
+  BrowserTestSession,
+  loadOrPrewarmBrowserTestChromeRuntime,
+  stopBrowserTestSession
+} from "./browser-test-session.js"
 
 const rootDir = process.cwd()
 const distDir = path.join(rootDir, "dist")
@@ -367,6 +372,8 @@ async function runBrowserTests() {
   process.env.VELOCIOUS_BROWSER_BACKEND_PORT = String(browserBackendPort)
   process.env.SYSTEM_TEST_HTTP_PORT = String(systemTestHttpPort)
 
+  const chromeRuntime = await loadOrPrewarmBrowserTestChromeRuntime()
+
   await buildBrowserTestApp()
 
   const {testFiles, lineFilters, includeTags, excludeTags, examplePatterns} = await resolveTests(processArgs)
@@ -381,21 +388,30 @@ async function runBrowserTests() {
     lineFilters,
     examplePatterns
   })
-  /** @type {SystemTest | undefined} */
-  let systemTest
+  /** @type {BrowserTestSession | undefined} */
+  let browserTestSession
   /** @type {Application | undefined} */
   let backendApplication
+  /** @type {Error | undefined} */
+  let runError
 
   try {
     const backendConfiguration = await loadBrowserBackendConfiguration()
     globalThis.__velocious_browser_test_backend_configuration = backendConfiguration
     backendApplication = await startBrowserBackendServer(backendConfiguration, browserBackendPort)
-    systemTest = SystemTest.current({
-      debug: process.env.SYSTEM_TEST_DEBUG === "true",
-      httpHost: systemTestHttpHost,
-      httpPort: systemTestHttpPort
+    browserTestSession = new BrowserTestSession({
+      runtime: chromeRuntime,
+      systemTestFactory: ({browserPath}) => SystemTest.current({
+        debug: process.env.SYSTEM_TEST_DEBUG === "true",
+        driver: {
+          type: "selenium",
+          options: {chromeBinaryPath: browserPath}
+        },
+        httpHost: systemTestHttpHost,
+        httpPort: systemTestHttpPort
+      })
     })
-    await systemTest.start()
+    await browserTestSession.start()
 
     await testRunner.prepare()
 
@@ -413,10 +429,7 @@ async function runBrowserTests() {
     if ((hasTagFilters || hasLineFilters || hasExampleFilters) && executedTests === 0) {
       console.error("\nNo tests matched the provided filters")
       process.exitCode = 1
-      return
-    }
-
-    if (testRunner.isFailed()) {
+    } else if (testRunner.isFailed()) {
       await testRunner.persistFailedTestConsoleOutputsToAssets()
       const failedTests = testRunner.getFailedTestDetails()
 
@@ -443,15 +456,34 @@ async function runBrowserTests() {
     } else {
       console.log(`\nTest run succeeded with ${testRunner.getSuccessfulTests()} successful tests`)
     }
-  } finally {
-    if (systemTest) {
-      await systemTest.stop()
+  } catch (error) {
+    runError = error instanceof Error ? error : new Error(String(error))
+  }
+
+  const cleanupErrors = []
+
+  if (browserTestSession) {
+    try {
+      await stopBrowserTestSession(browserTestSession)
+    } catch (error) {
+      cleanupErrors.push(error instanceof Error ? error : new Error(String(error)))
     }
+  }
 
-    if (backendApplication) {
+  if (backendApplication) {
+    try {
       await backendApplication.stop()
+    } catch (error) {
+      cleanupErrors.push(error instanceof Error ? error : new Error(String(error)))
     }
   }
+
+  if (runError && cleanupErrors.length > 0) {
+    throw new AggregateError([runError, ...cleanupErrors], "Browser tests and resource cleanup failed", {cause: runError})
+  }
+  if (runError) throw runError
+  if (cleanupErrors.length === 1) throw cleanupErrors[0]
+  if (cleanupErrors.length > 1) throw new AggregateError(cleanupErrors, "Browser test resource cleanup failed")
 }
 
 async function main() {

package/src/configuration-types.js

@@ -72,7 +72,7 @@
  * @property {() => ReturnType<typeof JSON.parse>} [getConnection] - Custom connection factory override.
  * @property {string} [host] - Database host.
  * @property {boolean} [migrations] - Whether migrations are enabled for this database.
- * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
+ * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so structure SQL loads and all-table cleanup can batch into one round-trip. Off by default; ordinary queries otherwise reject stacked statements.
  * @property {number} [maxRowsPerInsert] - Maximum rows per `INSERT ... VALUES (...), (...), ...` statement generated by `Record.insertMultiple`. Defaults to 500.
  * @property {number} [maxInsertSqlBytes] - Maximum serialized SQL size, in bytes, for a single `INSERT ... VALUES (...), (...), ...` statement. Defaults to 1 MiB (1048576).
  * @property {number} [maxInClauseValues] - Maximum values in a single `IN (...)` cohort used by preloads, association counts, and queryData aggregates. Defaults to 999.