@jsenv/test 1.0.0

package/src/execution/logs_file_execution.js

@@ -0,0 +1,427 @@
+import wrapAnsi from "wrap-ansi"
+import {
+  ANSI,
+  UNICODE,
+  msAsEllapsedTime,
+  msAsDuration,
+  byteAsMemoryUsage,
+} from "@jsenv/log"
+
+import { EXECUTION_COLORS } from "./execution_colors.js"
+
+export const createExecutionLog = (
+  {
+    executionIndex,
+    fileRelativeUrl,
+    runtimeName,
+    runtimeVersion,
+    executionParams,
+    executionResult,
+    startMs,
+    endMs,
+  },
+  {
+    completedExecutionLogAbbreviation,
+    counters,
+    logRuntime,
+    logEachDuration,
+    timeEllapsed,
+    memoryHeap,
+  },
+) => {
+  const { status } = executionResult
+  const descriptionFormatter = descriptionFormatters[status]
+  const description = descriptionFormatter({
+    index: executionIndex,
+    total: counters.total,
+    executionParams,
+  })
+  const summary = createIntermediateSummary({
+    executionIndex,
+    counters,
+    timeEllapsed,
+    memoryHeap,
+  })
+  let log
+  if (completedExecutionLogAbbreviation && status === "completed") {
+    log = `${description}${summary}`
+  } else {
+    const { consoleCalls = [], errors = [] } = executionResult
+    const consoleOutput = formatConsoleCalls(consoleCalls)
+    const errorsOutput = formatErrors(errors)
+    log = formatExecution({
+      label: `${description}${summary}`,
+      details: {
+        file: fileRelativeUrl,
+        ...(logRuntime ? { runtime: `${runtimeName}/${runtimeVersion}` } : {}),
+        ...(logEachDuration
+          ? {
+              duration:
+                status === "executing"
+                  ? msAsEllapsedTime(Date.now() - startMs)
+                  : msAsDuration(endMs - startMs),
+            }
+          : {}),
+      },
+      consoleOutput,
+      errorsOutput,
+    })
+  }
+
+  const { columns = 80 } = process.stdout
+  log = wrapAnsi(log, columns, {
+    trim: false,
+    hard: true,
+    wordWrap: false,
+  })
+  if (endMs) {
+    if (completedExecutionLogAbbreviation) {
+      return `${log}\n`
+    }
+    if (executionIndex === counters.total - 1) {
+      return `${log}\n`
+    }
+    return `${log}\n\n`
+  }
+  return log
+}
+
+const formatErrors = (errors) => {
+  if (errors.length === 0) {
+    return ""
+  }
+  const formatError = (error) => error.stack || error.message || error
+
+  if (errors.length === 1) {
+    return `${ANSI.color(`-------- error --------`, ANSI.RED)}
+${formatError(errors[0])}
+${ANSI.color(`-------------------------`, ANSI.RED)}`
+  }
+
+  let output = []
+  errors.forEach((error) => {
+    output.push(
+      prefixFirstAndIndentRemainingLines({
+        prefix: `${UNICODE.CIRCLE_CROSS} `,
+        indentation: "   ",
+        text: formatError(error),
+      }),
+    )
+  })
+  return `${ANSI.color(`-------- errors (${errors.length}) --------`, ANSI.RED)}
+${output.join(`\n`)}
+${ANSI.color(`-------------------------`, ANSI.RED)}`
+}
+
+export const createSummaryLog = (
+  summary,
+) => `-------------- summary -----------------
+${createAllExecutionsSummary(summary)}
+total duration: ${msAsDuration(summary.duration)}
+----------------------------------------`
+
+const createAllExecutionsSummary = ({ counters }) => {
+  if (counters.total === 0) {
+    return `no execution`
+  }
+  const executionLabel =
+    counters.total === 1 ? `1 execution` : `${counters.total} executions`
+  return `${executionLabel}: ${createStatusSummary({
+    counters,
+  })}`
+}
+
+const createIntermediateSummary = ({
+  executionIndex,
+  counters,
+  memoryHeap,
+  timeEllapsed,
+}) => {
+  const parts = []
+  if (executionIndex > 0 || counters.done > 0) {
+    parts.push(
+      createStatusSummary({
+        counters: {
+          ...counters,
+          total: executionIndex + 1,
+        },
+      }),
+    )
+  }
+  if (timeEllapsed) {
+    parts.push(`duration: ${msAsEllapsedTime(timeEllapsed)}`)
+  }
+  if (memoryHeap) {
+    parts.push(`memory heap: ${byteAsMemoryUsage(memoryHeap)}`)
+  }
+  if (parts.length === 0) {
+    return ""
+  }
+  return ` (${parts.join(` / `)})`
+}
+
+const createStatusSummary = ({ counters }) => {
+  if (counters.aborted === counters.total) {
+    return `all ${ANSI.color(`aborted`, EXECUTION_COLORS.aborted)}`
+  }
+  if (counters.timedout === counters.total) {
+    return `all ${ANSI.color(`timed out`, EXECUTION_COLORS.timedout)}`
+  }
+  if (counters.failed === counters.total) {
+    return `all ${ANSI.color(`failed`, EXECUTION_COLORS.failed)}`
+  }
+  if (counters.completed === counters.total) {
+    return `all ${ANSI.color(`completed`, EXECUTION_COLORS.completed)}`
+  }
+  if (counters.cancelled === counters.total) {
+    return `all ${ANSI.color(`cancelled`, EXECUTION_COLORS.cancelled)}`
+  }
+  return createMixedDetails({
+    counters,
+  })
+}
+
+const createMixedDetails = ({ counters }) => {
+  const parts = []
+  if (counters.timedout) {
+    parts.push(
+      `${counters.timedout} ${ANSI.color(
+        `timed out`,
+        EXECUTION_COLORS.timedout,
+      )}`,
+    )
+  }
+  if (counters.failed) {
+    parts.push(
+      `${counters.failed} ${ANSI.color(`failed`, EXECUTION_COLORS.failed)}`,
+    )
+  }
+  if (counters.completed) {
+    parts.push(
+      `${counters.completed} ${ANSI.color(
+        `completed`,
+        EXECUTION_COLORS.completed,
+      )}`,
+    )
+  }
+  if (counters.aborted) {
+    parts.push(
+      `${counters.aborted} ${ANSI.color(`aborted`, EXECUTION_COLORS.aborted)}`,
+    )
+  }
+  if (counters.cancelled) {
+    parts.push(
+      `${counters.cancelled} ${ANSI.color(
+        `cancelled`,
+        EXECUTION_COLORS.cancelled,
+      )}`,
+    )
+  }
+  return `${parts.join(", ")}`
+}
+
+const descriptionFormatters = {
+  executing: ({ index, total }) => {
+    return ANSI.color(
+      `executing ${padNumber(index, total)} of ${total}`,
+      EXECUTION_COLORS.executing,
+    )
+  },
+  aborted: ({ index, total }) => {
+    return ANSI.color(
+      `${UNICODE.FAILURE_RAW} execution ${padNumber(
+        index,
+        total,
+      )} of ${total} aborted`,
+      EXECUTION_COLORS.aborted,
+    )
+  },
+  timedout: ({ index, total, executionParams }) => {
+    return ANSI.color(
+      `${UNICODE.FAILURE_RAW} execution ${padNumber(
+        index,
+        total,
+      )} of ${total} timeout after ${executionParams.allocatedMs}ms`,
+      EXECUTION_COLORS.timedout,
+    )
+  },
+  failed: ({ index, total }) => {
+    return ANSI.color(
+      `${UNICODE.FAILURE_RAW} execution ${padNumber(
+        index,
+        total,
+      )} of ${total} failed`,
+      EXECUTION_COLORS.failed,
+    )
+  },
+  completed: ({ index, total }) => {
+    return ANSI.color(
+      `${UNICODE.OK_RAW} execution ${padNumber(
+        index,
+        total,
+      )} of ${total} completed`,
+      EXECUTION_COLORS.completed,
+    )
+  },
+  cancelled: ({ index, total }) => {
+    return ANSI.color(
+      `${UNICODE.FAILURE_RAW} execution ${padNumber(
+        index,
+        total,
+      )} of ${total} cancelled`,
+      EXECUTION_COLORS.cancelled,
+    )
+  },
+}
+
+const padNumber = (index, total) => {
+  const number = index + 1
+  const numberWidth = String(number).length
+  const totalWith = String(total).length
+  let missingWidth = totalWith - numberWidth
+  let padded = ""
+  while (missingWidth--) {
+    padded += "0"
+  }
+  padded += number
+  return padded
+}
+
+const formatConsoleCalls = (consoleCalls) => {
+  if (consoleCalls.length === 0) {
+    return ""
+  }
+  const repartition = {
+    debug: 0,
+    info: 0,
+    warning: 0,
+    error: 0,
+    log: 0,
+  }
+  consoleCalls.forEach((consoleCall) => {
+    repartition[consoleCall.type]++
+  })
+  const consoleOutput = formatConsoleOutput(consoleCalls)
+
+  return `${ANSI.color(
+    `-------- ${formatConsoleSummary(repartition)} --------`,
+    ANSI.GREY,
+  )}
+${consoleOutput}
+${ANSI.color(`-------------------------`, ANSI.GREY)}`
+}
+
+export const formatConsoleOutput = (consoleCalls) => {
+  // inside Node.js you can do process.stdout.write()
+  // and in that case the consoleCall is not suffixed with "\n"
+  // we want to keep these calls together in the output
+  const regroupedCalls = []
+  consoleCalls.forEach((consoleCall, index) => {
+    if (index === 0) {
+      regroupedCalls.push(consoleCall)
+      return
+    }
+    const previousCall = consoleCalls[index - 1]
+    if (previousCall.type !== consoleCall.type) {
+      regroupedCalls.push(consoleCall)
+      return
+    }
+    if (previousCall.text.endsWith("\n")) {
+      regroupedCalls.push(consoleCall)
+      return
+    }
+    if (previousCall.text.endsWith("\r")) {
+      regroupedCalls.push(consoleCall)
+      return
+    }
+    const previousRegroupedCallIndex = regroupedCalls.length - 1
+    const previousRegroupedCall = regroupedCalls[previousRegroupedCallIndex]
+    previousRegroupedCall.text = `${previousRegroupedCall.text}${consoleCall.text}`
+  })
+
+  let consoleOutput = ``
+  regroupedCalls.forEach((regroupedCall, index) => {
+    const text = regroupedCall.text
+    const textFormatted = prefixFirstAndIndentRemainingLines({
+      prefix: CONSOLE_ICONS[regroupedCall.type],
+      text,
+      trimLines: true,
+      trimLastLine: index === regroupedCalls.length - 1,
+    })
+    consoleOutput += textFormatted
+  })
+  return consoleOutput
+}
+
+const prefixFirstAndIndentRemainingLines = ({
+  prefix,
+  indentation = "  ",
+  text,
+  trimLines,
+  trimLastLine,
+}) => {
+  const lines = text.split(/\r?\n/)
+  const firstLine = lines.shift()
+  let result = `${prefix} ${firstLine}`
+  let i = 0
+  while (i < lines.length) {
+    const line = trimLines ? lines[i].trim() : lines[i]
+    i++
+    result += line.length
+      ? `\n${indentation}${line}`
+      : trimLastLine && i === lines.length
+      ? ""
+      : `\n`
+  }
+  return result
+}
+
+const CONSOLE_ICONS = {
+  debug: UNICODE.DEBUG,
+  info: UNICODE.INFO,
+  warning: UNICODE.WARNING,
+  error: UNICODE.FAILURE,
+  log: " ",
+}
+
+const formatConsoleSummary = (repartition) => {
+  const { debug, info, warning, error } = repartition
+  const parts = []
+  if (error) {
+    parts.push(`${CONSOLE_ICONS.error} ${error}`)
+  }
+  if (warning) {
+    parts.push(`${CONSOLE_ICONS.warning} ${warning}`)
+  }
+  if (info) {
+    parts.push(`${CONSOLE_ICONS.info} ${info}`)
+  }
+  if (debug) {
+    parts.push(`${CONSOLE_ICONS.debug} ${debug}`)
+  }
+  if (parts.length === 0) {
+    return `console`
+  }
+  return `console (${parts.join(" ")})`
+}
+
+const formatExecution = ({
+  label,
+  details = {},
+  consoleOutput,
+  errorsOutput,
+}) => {
+  let message = ``
+  message += label
+  Object.keys(details).forEach((key) => {
+    message += `
+${key}: ${details[key]}`
+  })
+  if (consoleOutput) {
+    message += `\n${consoleOutput}`
+  }
+  if (errorsOutput) {
+    message += `\n${errorsOutput}`
+  }
+  return message
+}

package/src/execution/logs_file_execution.test.mjs

@@ -0,0 +1,41 @@
+import { assert } from "@jsenv/assert"
+
+import { formatConsoleOutput } from "./logs_file_execution.js"
+
+{
+  const actual = formatConsoleOutput([
+    { type: "log", text: "a\n" },
+    { type: "log", text: "b\n" },
+  ])
+  const expected = `  a
+  b`
+  assert({ actual, expected })
+}
+
+{
+  const actual = formatConsoleOutput([
+    { type: "log", text: "a" },
+    { type: "log", text: "b" },
+  ])
+  const expected = `  ab`
+  assert({ actual, expected })
+}
+
+{
+  const actual = formatConsoleOutput([
+    {
+      type: "log",
+      text: `1
+2`,
+    },
+    {
+      type: "log",
+      text: `alpha
+beta`,
+    },
+  ])
+  const expected = `  1
+  2alpha
+  beta`
+  assert({ actual, expected })
+}

package/src/execution/run.js

@@ -0,0 +1,160 @@
+/*
+ * Export a function capable to run a file on a runtime.
+ *
+ * - Used internally by "executeTestPlan" part of the documented API
+ * - Used internally by "execute" an advanced API not documented
+ * - logs generated during file execution can be collected
+ * - logs generated during file execution can be mirrored (re-logged to the console)
+ * - File is given allocatedMs to complete
+ * - Errors are collected
+ * - File execution result is returned, it contains status/errors/namespace/consoleCalls
+ */
+
+import { createId } from "@paralleldrive/cuid2"
+import { Abort, raceCallbacks } from "@jsenv/abort"
+import { ensureParentDirectories } from "@jsenv/filesystem"
+
+export const run = async ({
+  signal = new AbortController().signal,
+  logger,
+  allocatedMs,
+  keepRunning = false,
+  mirrorConsole = false,
+  collectConsole = false,
+  coverageEnabled = false,
+  coverageTempDirectoryUrl,
+  collectPerformance = false,
+  runtime,
+  runtimeParams,
+}) => {
+  const result = {
+    status: "pending",
+    errors: [],
+    namespace: null,
+  }
+  const callbacks = []
+
+  const onConsoleRef = { current: () => {} }
+  const stopSignal = { notify: () => {} }
+  const runtimeLabel = `${runtime.name}/${runtime.version}`
+
+  const runOperation = Abort.startOperation()
+  runOperation.addAbortSignal(signal)
+  let timeoutAbortSource
+  if (
+    // ideally we would rather log than the timeout is ignored
+    // when keepRunning is true
+    !keepRunning &&
+    typeof allocatedMs === "number" &&
+    allocatedMs !== Infinity
+  ) {
+    timeoutAbortSource = runOperation.timeout(allocatedMs)
+  }
+  const consoleCalls = []
+  onConsoleRef.current = ({ type, text }) => {
+    if (mirrorConsole) {
+      if (type === "error") {
+        process.stderr.write(text)
+      } else {
+        process.stdout.write(text)
+      }
+    }
+    if (collectConsole) {
+      consoleCalls.push({ type, text })
+    }
+  }
+  if (collectConsole) {
+    result.consoleCalls = consoleCalls
+  }
+
+  // we do not keep coverage in memory, it can grow very big
+  // instead we store it on the filesystem
+  // and they can be read later at "coverageFileUrl"
+  let coverageFileUrl
+  if (coverageEnabled) {
+    coverageFileUrl = new URL(
+      `./${runtime.name}/${createId()}.json`,
+      coverageTempDirectoryUrl,
+    ).href
+    await ensureParentDirectories(coverageFileUrl)
+    if (coverageEnabled) {
+      result.coverageFileUrl = coverageFileUrl
+      // written within the child_process/worker_thread or during runtime.run()
+      // for browsers
+      // (because it takes time to serialize and transfer the coverage object)
+    }
+  }
+
+  const startMs = Date.now()
+  callbacks.push(() => {
+    result.duration = Date.now() - startMs
+  })
+
+  try {
+    logger.debug(`run() ${runtimeLabel}`)
+    runOperation.throwIfAborted()
+    const winnerPromise = new Promise((resolve) => {
+      raceCallbacks(
+        {
+          aborted: (cb) => {
+            runOperation.signal.addEventListener("abort", cb)
+            return () => {
+              runOperation.signal.removeEventListener("abort", cb)
+            }
+          },
+          runned: async (cb) => {
+            try {
+              const runResult = await runtime.run({
+                signal: runOperation.signal,
+                logger,
+                ...runtimeParams,
+                collectConsole,
+                collectPerformance,
+                coverageFileUrl,
+                keepRunning,
+                stopSignal,
+                onConsole: (log) => onConsoleRef.current(log),
+              })
+              cb(runResult)
+            } catch (e) {
+              cb({
+                status: "failed",
+                errors: [e],
+              })
+            }
+          },
+        },
+        resolve,
+      )
+    })
+    const winner = await winnerPromise
+    if (winner.name === "aborted") {
+      runOperation.throwIfAborted()
+    }
+    const { status, namespace, errors, performance } = winner.data
+    result.status = status
+    result.errors.push(...errors)
+    result.namespace = namespace
+    if (collectPerformance) {
+      result.performance = performance
+    }
+  } catch (e) {
+    if (Abort.isAbortError(e)) {
+      if (timeoutAbortSource && timeoutAbortSource.signal.aborted) {
+        result.status = "timedout"
+      } else {
+        result.status = "aborted"
+      }
+    } else {
+      result.status = "failed"
+      result.errors.push(e)
+    }
+  } finally {
+    await runOperation.end()
+  }
+
+  callbacks.forEach((callback) => {
+    callback()
+  })
+  return result
+}

package/src/execution/web_server_param.js

@@ -0,0 +1,73 @@
+import { assertAndNormalizeDirectoryUrl } from "@jsenv/filesystem"
+import { pingServer } from "@jsenv/core/src/helpers/ping_server.js"
+import { basicFetch } from "@jsenv/core/src/helpers/basic_fetch.js"
+
+export const assertAndNormalizeWebServer = async (webServer) => {
+  if (!webServer) {
+    throw new TypeError(
+      `webServer is required when running tests on browser(s)`,
+    )
+  }
+  const unexpectedParamNames = Object.keys(webServer).filter((key) => {
+    return !["origin", "moduleUrl", "rootDirectoryUrl"].includes(key)
+  })
+  if (unexpectedParamNames.length > 0) {
+    throw new TypeError(
+      `${unexpectedParamNames.join(",")}: there is no such param to webServer`,
+    )
+  }
+
+  let aServerIsListening = await pingServer(webServer.origin)
+  if (!aServerIsListening) {
+    if (!webServer.moduleUrl) {
+      throw new TypeError(
+        `webServer.moduleUrl is required as there is no server listening "${webServer.origin}"`,
+      )
+    }
+    try {
+      process.env.IMPORTED_BY_TEST_PLAN = "1"
+      await import(webServer.moduleUrl)
+      delete process.env.IMPORTED_BY_TEST_PLAN
+    } catch (e) {
+      if (e.code === "ERR_MODULE_NOT_FOUND") {
+        throw new Error(
+          `webServer.moduleUrl does not lead to a file at "${webServer.moduleUrl}"`,
+        )
+      }
+      throw e
+    }
+    aServerIsListening = await pingServer(webServer.origin)
+    if (!aServerIsListening) {
+      throw new Error(
+        `webServer.moduleUrl did not start a server listening at "${webServer.origin}", check file at "${webServer.moduleUrl}"`,
+      )
+    }
+  }
+  const { headers } = await basicFetch(webServer.origin, {
+    method: "GET",
+    rejectUnauthorized: false,
+    headers: {
+      "x-server-inspect": "1",
+    },
+  })
+  if (String(headers["server"]).includes("jsenv_dev_server")) {
+    webServer.isJsenvDevServer = true
+    const { json } = await basicFetch(`${webServer.origin}/__params__.json`, {
+      rejectUnauthorized: false,
+    })
+    if (webServer.rootDirectoryUrl === undefined) {
+      const jsenvDevServerParams = await json()
+      webServer.rootDirectoryUrl = jsenvDevServerParams.sourceDirectoryUrl
+    } else {
+      webServer.rootDirectoryUrl = assertAndNormalizeDirectoryUrl(
+        webServer.rootDirectoryUrl,
+        "webServer.rootDirectoryUrl",
+      )
+    }
+  } else {
+    webServer.rootDirectoryUrl = assertAndNormalizeDirectoryUrl(
+      webServer.rootDirectoryUrl,
+      "webServer.rootDirectoryUrl",
+    )
+  }
+}

package/src/main.js

@@ -0,0 +1,10 @@
+// test
+export { executeTestPlan } from "./execution/execute_test_plan.js"
+// runtimes (used to execute tests)
+export { chromium, chromiumIsolatedTab } from "./runtime_browsers/chromium.js"
+export { firefox, firefoxIsolatedTab } from "./runtime_browsers/firefox.js"
+export { webkit, webkitIsolatedTab } from "./runtime_browsers/webkit.js"
+export { nodeChildProcess } from "./runtime_node/node_child_process.js"
+export { nodeWorkerThread } from "./runtime_node/node_worker_thread.js"
+// advanced
+export { execute } from "./execution/execute.js"