@jsenv/test 3.7.35 → 3.7.37

package/dist/jsenv_test.js

@@ -1,6 +1,6 @@
 import { createSupportsColor, isUnicodeSupported, stripAnsi, eastAsianWidth, clearTerminal, eraseLines } from "./jsenv_test_node_modules.js";
 import { URL_META, createException } from "./exception.js";
-import { readdir, chmod, stat, lstat, chmodSync, statSync, lstatSync, promises, readFile as readFile$1, readdirSync, openSync, closeSync, unlinkSync, rmdirSync, mkdirSync, readFileSync, writeFileSync as writeFileSync$1, unlink, rmdir, existsSync, realpathSync } from "node:fs";
+import { readdir, chmod, stat, lstat, chmodSync, statSync, lstatSync, promises, readFile as readFile$1, readdirSync, openSync, closeSync, unlinkSync, rmdirSync, mkdirSync, readFileSync, writeFileSync as writeFileSync$1, unlink, rmdir, existsSync, realpathSync, readSync } from "node:fs";
 import { takeCoverage } from "node:v8";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
@@ -15,7 +15,7 @@ import { availableParallelism, cpus, totalmem, release, freemem } from "node:os"
 import { SOURCEMAP, generateSourcemapDataUrl } from "@jsenv/sourcemap";
 import { injectSupervisorIntoHTML, supervisorFileUrl } from "@jsenv/plugin-supervisor";
 import { pidtree } from "pidtree";
-import { Worker } from "node:worker_threads";
+import { Worker, parentPort } from "node:worker_threads";
 import he from "he";
 import "node:tty";
 
@@ -5704,6 +5704,130 @@ const getCoverageFromTestPlanResults = async (
 
 const isV8Coverage = (coverage) => Boolean(coverage.result);
 
+/*
+ * Remembers, from one run to the next, how long each execution took and how much
+ * time it asked for (see requestAllocatedMs).
+ *
+ * What it is for: with a fixed number of parallel slots, the moment a long
+ * execution starts decides when the whole run ends. Started last it keeps one
+ * slot busy while every other one is idle; started first it runs while the short
+ * ones fill the slots around it. Knowing the durations of the previous run is
+ * what allows to start the long ones first.
+ *
+ * Only the start order is affected: executions keep the index they got from the
+ * filesystem, so they are still reported in that order.
+ */
+
+
+const MS_IN_A_DAY = 24 * 60 * 60 * 1000;
+// an execution not seen for that long is likely a file that no longer exists
+const ENTRY_MAX_AGE_MS = 30 * MS_IN_A_DAY;
+
+const createExecutionTimings = ({ fileUrl }) => {
+  const previousEntryMap = readEntries(fileUrl);
+  const entryMap = new Map();
+
+  return {
+    getAllocatedMsRequested: (executionName) => {
+      const previousEntry = previousEntryMap.get(executionName);
+      if (!previousEntry) {
+        return undefined;
+      }
+      return previousEntry.allocatedMsRequested;
+    },
+    sortByLongestFirst: (executionArray) => {
+      const durationMsMap = new Map();
+      const durationMsArray = [];
+      for (const execution of executionArray) {
+        const previousEntry = previousEntryMap.get(execution.name);
+        if (previousEntry) {
+          durationMsMap.set(execution, previousEntry.durationMs);
+          durationMsArray.push(previousEntry.durationMs);
+        }
+      }
+      if (durationMsArray.length === 0) {
+        return executionArray;
+      }
+      // an execution never seen before is assumed to last as long as the median:
+      // being new is not a reason to be pushed at the end of the run
+      durationMsArray.sort((a, b) => a - b);
+      const medianDurationMs =
+        durationMsArray[Math.floor(durationMsArray.length / 2)];
+      // sort is stable: executions with the same estimation stay in the order
+      // they were found on the filesystem
+      return [...executionArray].sort((leftExecution, rightExecution) => {
+        const leftDurationMs =
+          durationMsMap.get(leftExecution) ?? medianDurationMs;
+        const rightDurationMs =
+          durationMsMap.get(rightExecution) ?? medianDurationMs;
+        return rightDurationMs - leftDurationMs;
+      });
+    },
+    record: (execution) => {
+      const { status, timings } = execution.result;
+      if (
+        status !== "completed" &&
+        status !== "failed" &&
+        status !== "timedout"
+      ) {
+        // an execution that was skipped, aborted or cancelled says nothing
+        // about how long the file needs
+        return;
+      }
+      const entry = {
+        durationMs: timings.end,
+        updatedAt: Date.now(),
+      };
+      if (execution.allocatedMsRequested !== undefined) {
+        entry.allocatedMsRequested = execution.allocatedMsRequested;
+      }
+      entryMap.set(execution.name, entry);
+    },
+    write: () => {
+      const nowMs = Date.now();
+      const executions = {};
+      // executions not part of this run keep what was known about them
+      for (const [executionName, entry] of previousEntryMap) {
+        if (nowMs - entry.updatedAt < ENTRY_MAX_AGE_MS) {
+          executions[executionName] = entry;
+        }
+      }
+      for (const [executionName, entry] of entryMap) {
+        executions[executionName] = entry;
+      }
+      writeFileSync(fileUrl, JSON.stringify({ executions }, null, "  "));
+    },
+  };
+};
+
+const readEntries = (fileUrl) => {
+  const entryMap = new Map();
+  let fileContent;
+  try {
+    fileContent = readFileSync(new URL(fileUrl), "utf8");
+  } catch {
+    // no memory of a previous run: every execution is an unknown
+    return entryMap;
+  }
+  let executions;
+  try {
+    ({ executions } = JSON.parse(fileContent));
+  } catch {
+    // file was truncated by a run killed while writing it
+    return entryMap;
+  }
+  if (!executions) {
+    return entryMap;
+  }
+  for (const executionName of Object.keys(executions)) {
+    const entry = executions[executionName];
+    if (typeof entry.durationMs === "number") {
+      entryMap.set(executionName, entry);
+    }
+  }
+  return entryMap;
+};
+
 const githubAnnotationFromError = (
   error,
   { rootDirectoryUrl, execution },
@@ -5835,6 +5959,176 @@ const replaceUrls$1 = (source, replace) => {
   });
 };
 
+/*
+ * Reads what a test file declares about its own execution, from the directive
+ * prologue — the string literals a module may open with, as in "use strict" or
+ * "use client":
+ *
+ *   "jsenv:allocate 90s";
+ *   "jsenv:lock service-worker";
+ *
+ * They are read without running the file, which is what allows a lock to be
+ * honored: an execution must not have started before we know what it takes.
+ * Being grammar rather than convention, a directive cannot be built at runtime
+ * and cannot move: it is the first statement or it is nothing.
+ *
+ * A "jsenv:" directive that cannot be read throws. Everything ignores an
+ * unknown directive silently, so a typo would silently give the file back the
+ * default budget; the only way it stays useful is to be loud.
+ */
+
+
+const DIRECTIVE_PREFIX = "jsenv:";
+const DIRECTIVE_NAMES = `"jsenv:allocate <duration>", "jsenv:lock <resource>"`;
+const DURATION_REGEX = /^(\d+)(ms|s|m)$/;
+const MS_PER_UNIT = { ms: 1, s: 1_000, m: 60_000 };
+// a directive prologue sits at the top of the file; comments can precede it but
+// rarely for more than a few lines, and the whole file is read when they do
+const HEAD_BYTE_COUNT = 4096;
+
+const readJsenvDirectives = (fileUrl) => {
+  const head = readHead(fileUrl);
+  let scanResult = scanDirectivePrologue(head.text);
+  if (head.partial && !scanResult.complete) {
+    scanResult = scanDirectivePrologue(readFileSync(new URL(fileUrl), "utf8"));
+  }
+
+  let allocatedMs;
+  const lockArray = [];
+  for (const directiveText of scanResult.directiveTextArray) {
+    if (!directiveText.startsWith(DIRECTIVE_PREFIX)) {
+      continue;
+    }
+    const body = directiveText.slice(DIRECTIVE_PREFIX.length);
+    const spaceIndex = body.indexOf(" ");
+    const name = spaceIndex === -1 ? body : body.slice(0, spaceIndex);
+    const argument = spaceIndex === -1 ? "" : body.slice(spaceIndex + 1).trim();
+    const fail = (reason, details = {}) => {
+      throw new Error(
+        createDetailedMessage(reason, {
+          directive: `"${directiveText}"`,
+          file: fileURLToPath(fileUrl),
+          ...details,
+        }),
+      );
+    };
+
+    if (name === "allocate") {
+      const match = DURATION_REGEX.exec(argument);
+      if (!match) {
+        fail(`"jsenv:allocate" expects a duration, got "${argument}"`, {
+          ["durations accepted"]: `"500ms", "90s", "2m"`,
+        });
+      }
+      allocatedMs = Number(match[1]) * MS_PER_UNIT[match[2]];
+      continue;
+    }
+    if (name === "lock") {
+      if (argument === "") {
+        fail(`"jsenv:lock" expects the name of a resource`);
+      }
+      lockArray.push(argument);
+      continue;
+    }
+    fail(`unknown jsenv directive "${name}"`, {
+      ["directives available"]: DIRECTIVE_NAMES,
+    });
+  }
+  return { allocatedMs, lockArray };
+};
+
+const readHead = (fileUrl) => {
+  const fileDescriptor = openSync(fileURLToPath(fileUrl), "r");
+  try {
+    const buffer = Buffer.allocUnsafe(HEAD_BYTE_COUNT);
+    const byteCount = readSync(fileDescriptor, buffer, 0, HEAD_BYTE_COUNT, 0);
+    return {
+      text: buffer.toString("utf8", 0, byteCount),
+      partial: byteCount === HEAD_BYTE_COUNT,
+    };
+  } finally {
+    closeSync(fileDescriptor);
+  }
+};
+
+/*
+ * Collects the string literals opening the module, stopping at the first token
+ * that is neither a comment nor one of them. "complete" tells whether that
+ * token was reached: when it was not, the source given was cut short and the
+ * caller must read further before trusting the result.
+ */
+const scanDirectivePrologue = (source) => {
+  const directiveTextArray = [];
+  const length = source.length;
+  let index = 0;
+  if (source.startsWith("#!")) {
+    const lineEndIndex = source.indexOf("\n");
+    if (lineEndIndex === -1) {
+      return { directiveTextArray, complete: false };
+    }
+    index = lineEndIndex + 1;
+  }
+  while (index < length) {
+    const char = source[index];
+    if (
+      char === " " ||
+      char === "\t" ||
+      char === "\n" ||
+      char === "\r" ||
+      char === ";"
+    ) {
+      index++;
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "/") {
+      const lineEndIndex = source.indexOf("\n", index);
+      if (lineEndIndex === -1) {
+        return { directiveTextArray, complete: false };
+      }
+      index = lineEndIndex + 1;
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "*") {
+      const commentEndIndex = source.indexOf("*/", index + 2);
+      if (commentEndIndex === -1) {
+        return { directiveTextArray, complete: false };
+      }
+      index = commentEndIndex + 2;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      const quote = char;
+      let stringIndex = index + 1;
+      let text = "";
+      while (stringIndex < length) {
+        const stringChar = source[stringIndex];
+        if (stringChar === "\\") {
+          text += source[stringIndex + 1];
+          stringIndex += 2;
+          continue;
+        }
+        if (stringChar === quote) {
+          break;
+        }
+        if (stringChar === "\n") {
+          // an unterminated string is not a directive, and not our problem
+          return { directiveTextArray, complete: true };
+        }
+        text += stringChar;
+        stringIndex++;
+      }
+      if (stringIndex >= length) {
+        return { directiveTextArray, complete: false };
+      }
+      directiveTextArray.push(text);
+      index = stringIndex + 1;
+      continue;
+    }
+    return { directiveTextArray, complete: true };
+  }
+  return { directiveTextArray, complete: false };
+};
+
 const createIsInsideFragment = (fragment, total) => {
   let [dividend, divisor] = fragment.split("/");
   dividend = parseInt(dividend);
@@ -6980,6 +7274,7 @@ const run = async ({
   signal = new AbortController().signal,
   logger,
   allocatedMs,
+  onAllocatedMsRequested = () => {},
   keepRunning = false,
   mirrorConsole = false,
   collectConsole = false,
@@ -7030,6 +7325,22 @@ const run = async ({
   if (allocatedMs) {
     timeoutAbortSource = runOperation.timeout(allocatedMs);
   }
+  // the file being executed can ask for more time, see requestAllocatedMs
+  const handleAllocatedMsRequest = (ms) => {
+    onAllocatedMsRequested(ms);
+    if (!timeoutAbortSource) {
+      // nothing to extend: execution has no time limit
+      return;
+    }
+    if (ms <= allocatedMs) {
+      return;
+    }
+    allocatedMs = ms;
+    // the request arrives once execution has started, what is left of the
+    // requested duration is what the file can still use
+    timeoutAbortSource.remove();
+    timeoutAbortSource = runOperation.timeout(ms - takeTiming());
+  };
   const consoleCalls = [];
   onConsoleRef.current = ({ type, text }) => {
     if (mirrorConsole) {
@@ -7082,6 +7393,7 @@ const run = async ({
                 signal: runOperation.signal,
                 logger,
                 ...runtimeParams,
+                onAllocatedMsRequested: handleAllocatedMsRequest,
                 collectConsole,
                 measureMemoryUsage,
                 onMeasureMemoryAvailable,
@@ -7536,6 +7848,7 @@ const ensureWebServerIsStarted = async (
  * @param {Object} [testPlanParameters.webServer] Web server info; required when executing test on browsers
  * @param {Object} testPlanParameters.testPlan Object associating files with runtimes where they will be executed
  * @param {Object|false} [testPlanParameters.parallel] Maximum amount of execution running at the same time
+ * @param {Object|false} [testPlanParameters.executionTimings=false] Remembers how long executions took to start the longest ones first on the next run
  * @param {number} [testPlanParameters.defaultMsAllocatedPerExecution=30000] Milliseconds after which execution is aborted and considered as failed by timeout
  * @param {boolean} [testPlanParameters.failFast=false] Fails immediatly when a test execution fails
  * @param {Object|false} [testPlanParameters.coverage=false] Controls if coverage is collected during files executions
@@ -7594,6 +7907,12 @@ const parallelDefault = {
   max: "80%", // percentage resolved against the available cpus
   maxCpu: "80%",
   maxMemory: "50%",
+  // percentage resolved against parallel.max; an execution is heavy when it is
+  // allocated more time than the others (see defaultMsAllocatedPerExecution)
+  maxHeavy: "75%",
+};
+const executionTimingsDefault = {
+  fileUrl: undefined,
 };
 
 const executeTestPlan = async ({
@@ -7609,6 +7928,9 @@ const executeTestPlan = async ({
   handleSIGTERM = true,
   updateProcessExitCode = true,
   parallel = parallelDefault,
+  // opt-in: it makes the start order depend on a file written by a previous run,
+  // which a test plan snapshotting its own execution order cannot afford
+  executionTimings = false,
   // https://github.com/avajs/ava/blob/main/docs/recipes/splitting-tests-ci.md
   // https://playwright.dev/docs/test-sharding
   fragment,
@@ -7782,6 +8104,7 @@ const executeTestPlan = async ({
   const afterEachInOrderCallbackSet = new Set();
   const afterAllCallbackSet = new Set();
   let finalizeCoverage;
+  let timingsMemory;
 
   try {
     let logger;
@@ -7909,6 +8232,51 @@ const executeTestPlan = async ({
             `parallel.maxCpu must be a number or a percentage, got ${maxCpu}`,
           );
         }
+
+        const maxHeavy = parallel.maxHeavy;
+        if (typeof maxHeavy === "string") {
+          const maxHeavyAsRatio = assertPercentageAndConvertToRatio(maxHeavy);
+          parallel.maxHeavy = Math.round(maxHeavyAsRatio * parallel.max) || 1;
+        } else if (typeof maxHeavy === "number") {
+          if (maxHeavy < 1) {
+            parallel.maxHeavy = 1;
+          }
+        } else {
+          throw new TypeError(
+            `parallel.maxHeavy must be a number or a percentage, got ${maxHeavy}`,
+          );
+        }
+      }
+      // executionTimings
+      {
+        if (executionTimings === true) {
+          executionTimings = {};
+        }
+        if (executionTimings) {
+          if (typeof executionTimings !== "object") {
+            throw new TypeError(
+              `executionTimings must be an object, got ${executionTimings}`,
+            );
+          }
+          const unexpectedExecutionTimingsKeys = Object.keys(
+            executionTimings,
+          ).filter((key) => !Object.hasOwn(executionTimingsDefault, key));
+          if (unexpectedExecutionTimingsKeys.length > 0) {
+            throw new TypeError(
+              `${unexpectedExecutionTimingsKeys.join(",")}: no such key on executionTimings`,
+            );
+          }
+          executionTimings = {
+            ...executionTimingsDefault,
+            ...executionTimings,
+          };
+          timingsMemory = createExecutionTimings({
+            fileUrl:
+              executionTimings.fileUrl === undefined
+                ? new URL("./.jsenv/jsenv_tests_timings.json", rootDirectoryUrl)
+                : executionTimings.fileUrl,
+          });
+        }
       }
       // fragment/fragmentByRuntime
       {
@@ -8179,6 +8547,9 @@ To fix this warning:
           }
         }
         const filePlan = meta.testPlan;
+        const directives = readJsenvDirectives(
+          new URL(relativeUrl, rootDirectoryUrl),
+        );
         for (const groupName of Object.keys(filePlan)) {
           const stepConfig = filePlan[groupName];
           if (stepConfig === null || stepConfig === undefined) {
@@ -8200,7 +8571,7 @@ To fix this warning:
             runtime,
             runtimeParams,
             allocatedMs = defaultMsAllocatedPerExecution,
-            uses,
+            locks,
           } = stepConfig;
           const params = {
             measureMemoryUsage: true,
@@ -8208,7 +8579,7 @@ To fix this warning:
             collectPerformance: false,
             collectConsole: true,
             allocatedMs,
-            uses,
+            locks,
             runtime,
             runtimeParams: {
               rootDirectoryUrl,
@@ -8254,6 +8625,8 @@ To fix this warning:
             params,
             skipped: false,
             skipReason: "",
+            // set when the file calls requestAllocatedMs
+            allocatedMsRequested: undefined,
 
             // will be set by run()
             status: "planified",
@@ -8266,9 +8639,22 @@ To fix this warning:
                 ? defaultMsAllocatedPerExecution
                 : allocatedMsResult;
           }
-          if (typeof params.uses === "function") {
-            const usesResult = params.uses(execution);
-            params.uses = usesResult;
+          if (typeof params.locks === "function") {
+            const locksResult = params.locks(execution);
+            params.locks = locksResult;
+          }
+          // what the file declares about itself wins over the plan: it is
+          // closer to the reason
+          if (
+            directives.allocatedMs !== undefined &&
+            directives.allocatedMs > params.allocatedMs
+          ) {
+            params.allocatedMs = directives.allocatedMs;
+          }
+          if (directives.lockArray.length > 0) {
+            params.locks = params.locks
+              ? [...new Set([...params.locks, ...directives.lockArray])]
+              : directives.lockArray;
           }
 
           lastExecution = execution;
@@ -8438,9 +8824,33 @@ To fix this warning:
 
       const callWhenPreviousExecutionAreDone = createCallOrderer();
 
-      const executionRemainingSet = new Set(executionPlanifiedArray);
+      // an execution allowed more time than the others is a heavy one: it is
+      // both worth starting early and worth not having too many of at once
+      const heavyExecutionSet = new Set();
+      for (const execution of executionPlanifiedArray) {
+        if (execution.skipped) {
+          continue;
+        }
+        if (execution.params.allocatedMs > defaultMsAllocatedPerExecution) {
+          heavyExecutionSet.add(execution);
+          continue;
+        }
+        if (timingsMemory) {
+          const allocatedMsRequested = timingsMemory.getAllocatedMsRequested(
+            execution.name,
+          );
+          if (allocatedMsRequested > defaultMsAllocatedPerExecution) {
+            heavyExecutionSet.add(execution);
+          }
+        }
+      }
+      const executionStartOrderArray = timingsMemory
+        ? timingsMemory.sortByLongestFirst(executionPlanifiedArray)
+        : executionPlanifiedArray;
+
+      const executionRemainingSet = new Set(executionStartOrderArray);
       const executionExecutingSet = new Set();
-      const usedTagSet = new Set();
+      const lockedResourceSet = new Set();
       const start = async (execution) => {
         execution.fileExecutionCount = Object.keys(
           testPlanResult.results[execution.fileRelativeUrl],
@@ -8454,14 +8864,17 @@ To fix this warning:
           execution.result.status = "skipped";
           execution.result.value = execution.skipReason;
         } else {
-          if (execution.params.uses) {
-            for (const tagThatWillBeUsed of execution.params.uses) {
-              usedTagSet.add(tagThatWillBeUsed);
+          if (execution.params.locks) {
+            for (const resourceToLock of execution.params.locks) {
+              lockedResourceSet.add(resourceToLock);
             }
           }
           execution.status = "executing";
           const executionResult = await run({
             ...execution.params,
+            onAllocatedMsRequested: (ms) => {
+              execution.allocatedMsRequested = ms;
+            },
             signal: operation.signal,
             logger,
             keepRunning,
@@ -8471,11 +8884,14 @@ To fix this warning:
           });
           Object.assign(execution.result, executionResult);
           execution.status = "executed";
-          if (execution.params.uses) {
-            for (const tagNoLongerInUse of execution.params.uses) {
-              usedTagSet.delete(tagNoLongerInUse);
+          if (execution.params.locks) {
+            for (const resourceToRelease of execution.params.locks) {
+              lockedResourceSet.delete(resourceToRelease);
             }
           }
+          if (timingsMemory) {
+            timingsMemory.record(execution);
+          }
           if (execution.result.status !== "completed") {
             testPlanResult.failed = true;
             if (updateProcessExitCode) {
@@ -8506,6 +8922,12 @@ To fix this warning:
       };
       const startAsMuchAsPossible = async () => {
         operation.throwIfAborted();
+        let heavyExecutingCount = 0;
+        for (const executionExecuting of executionExecutingSet) {
+          if (heavyExecutionSet.has(executionExecuting)) {
+            heavyExecutingCount++;
+          }
+        }
         const promises = [];
         for (const executionCandidate of executionRemainingSet) {
           if (executionExecutingSet.size >= parallel.max) {
@@ -8533,18 +8955,29 @@ To fix this warning:
               promises.push(promise);
               break;
             }
-            if (executionCandidate.params.uses) {
-              const nonAvailableTag = executionCandidate.params.uses.find(
-                (tagToUse) => usedTagSet.has(tagToUse),
-              );
-              if (nonAvailableTag) {
+            if (heavyExecutionSet.has(executionCandidate)) {
+              if (heavyExecutingCount >= parallel.maxHeavy) {
+                // leave this slot to a lighter execution: filling every slot
+                // with the heavy ones makes them fight for cpu and memory
+                continue;
+              }
+            }
+            if (executionCandidate.params.locks) {
+              const resourceLockedByAnother =
+                executionCandidate.params.locks.find((resourceToLock) =>
+                  lockedResourceSet.has(resourceToLock),
+                );
+              if (resourceLockedByAnother) {
                 logger.debug(
-                  `"${nonAvailableTag}" is not available, ${executionCandidate.name} will wait until it is released by a previous execution`,
+                  `"${resourceLockedByAnother}" is locked, ${executionCandidate.name} will wait until it is released by a previous execution`,
                 );
                 continue;
               }
             }
           }
+          if (heavyExecutionSet.has(executionCandidate)) {
+            heavyExecutingCount++;
+          }
           const promise = (async () => {
             await start(executionCandidate);
             await startAsMuchAsPossible();
@@ -8627,6 +9060,10 @@ To fix this warning:
     }
     timings.teardownEnd = takeTiming();
 
+    if (timingsMemory) {
+      timingsMemory.write();
+    }
+
     if (finalizeCoverage) {
       await finalizeCoverage();
     }
@@ -8904,6 +9341,7 @@ const createRuntimeUsingPlaywright = ({
     onConsole,
     onRuntimeStarted,
     onRuntimeStopped,
+    onAllocatedMsRequested = () => {},
     teardownCallbackSet,
     isTestPlan,
 
@@ -9025,6 +9463,11 @@ ${webServer.rootDirectoryUrl}`);
     }
 
     const page = await browserContext.newPage();
+    // the only thing the page can tell node before it is done executing;
+    // see runtime_browsers/client/request_allocated_ms.js
+    await page.exposeFunction("__jsenv_request_allocated_ms__", (ms) => {
+      onAllocatedMsRequested(ms);
+    });
     if (!isBrowserDedicatedToExecution) {
       page.on("close", () => {
         onRuntimeStopped();
@@ -10046,6 +10489,7 @@ const nodeChildProcess = ({
       onConsole,
       onRuntimeStarted,
       onRuntimeStopped,
+      onAllocatedMsRequested = () => {},
 
       measureMemoryUsage,
       onMeasureMemoryAvailable,
@@ -10153,6 +10597,15 @@ const nodeChildProcess = ({
           onRuntimeStopped();
         }),
       );
+      cleanupCallbackSet.add(
+        onChildProcessMessage(
+          childProcess,
+          "allocated-ms-request",
+          ({ ms }) => {
+            onAllocatedMsRequested(ms);
+          },
+        ),
+      );
 
       const removeOutputListener = installChildProcessOutputListener(
         childProcess,
@@ -10534,6 +10987,7 @@ const nodeWorkerThread = ({
       onConsole,
       onRuntimeStarted,
       onRuntimeStopped,
+      onAllocatedMsRequested = () => {},
 
       measureMemoryUsage,
       onMeasureMemoryAvailable,
@@ -10620,6 +11074,15 @@ const nodeWorkerThread = ({
           onRuntimeStopped();
         }),
       );
+      cleanupCallbackSet.add(
+        onWorkerThreadMessage(
+          workerThread,
+          "allocated-ms-request",
+          ({ ms }) => {
+            onAllocatedMsRequested(ms);
+          },
+        ),
+      );
 
       const stop = memoize(async () => {
         // read all stdout before terminating
@@ -10871,6 +11334,42 @@ const onceWorkerThreadEvent = (worker, type, callback) => {
   };
 };
 
+/*
+ * Asks the test runner for more time from a test file, when the amount is
+ * computed rather than known in advance (it depends on the platform, on how
+ * many fixtures were found...). A fixed amount belongs in a directive instead,
+ * which the runner reads without executing the file:
+ *
+ *   "jsenv:allocate 90s";
+ *
+ * The request is sent to the process running the test plan, which restarts the
+ * timeout with the requested duration and remembers it: a file asking for more
+ * time than the others is also a file worth starting early when parallelizing.
+ *
+ * Node.js runtimes only; a browser has no channel to reach the test plan while
+ * the file is executing.
+ */
+
+
+const requestAllocatedMs = (ms) => {
+  if (typeof ms !== "number") {
+    throw new TypeError(`requestAllocatedMs expects a number, got ${ms}`);
+  }
+  const message = {
+    __jsenv__: "allocated-ms-request",
+    data: JSON.stringify({ ms }),
+  };
+  if (parentPort) {
+    parentPort.postMessage(message);
+    return;
+  }
+  if (process.send && process.connected) {
+    process.send(message);
+    return;
+  }
+  // file executed on its own (node ./file.test.mjs): there is no allocated time
+};
+
 const istanbulCoverageMapFromCoverage = (coverage) => {
   const { createCoverageMap } = importWithRequire("istanbul-lib-coverage");
 
@@ -11553,4 +12052,4 @@ const inlineRuntime = (fn) => {
   };
 };
 
-export { chromium, chromiumIsolatedTab, execute, executeTestPlan, firefox, firefoxIsolatedTab, inlineRuntime, nodeChildProcess, nodeWorkerThread, reportAsJson, reportAsJunitXml, reportCoverageAsHtml, reportCoverageAsJson, reportCoverageInConsole, reporterList, webkit, webkitIsolatedTab };
+export { chromium, chromiumIsolatedTab, execute, executeTestPlan, firefox, firefoxIsolatedTab, inlineRuntime, nodeChildProcess, nodeWorkerThread, reportAsJson, reportAsJunitXml, reportCoverageAsHtml, reportCoverageAsJson, reportCoverageInConsole, reporterList, requestAllocatedMs, webkit, webkitIsolatedTab };