@jsenv/test 3.7.35 → 3.7.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/test",
-  "version": "3.7.35",
+  "version": "3.7.37",
   "type": "module",
   "repository": {
     "type": "git",
@@ -13,6 +13,7 @@
   },
   "exports": {
     ".": {
+      "browser": "./src/main_browser.js",
       "import": {
         "dev:jsenv": "./src/main.js",
         "default": "./dist/jsenv_test.js"

package/src/execution/execute_test_plan.js

@@ -32,7 +32,9 @@ import { existsSync } from "node:fs";
 import { takeCoverage } from "node:v8";
 import stripAnsi from "strip-ansi";
 import { generateCoverage } from "../coverage/generate_coverage.js";
+import { createExecutionTimings } from "./execution_timings.js";
 import { githubAnnotationFromError } from "./github_annotation_from_error.js";
+import { readJsenvDirectives } from "./jsenv_directives.js";
 import { createIsInsideFragment } from "./is_inside_fragment.js";
 import { renderOutroContent, reporterList } from "./reporters/reporter_list.js";
 import { run } from "./run.js";
@@ -45,6 +47,7 @@ import { assertAndNormalizeWebServer } from "./web_server_param.js";
  * @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
@@ -103,6 +106,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,
 };
 
 export const executeTestPlan = async ({
@@ -118,6 +127,9 @@ export 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,
@@ -291,6 +303,7 @@ export const executeTestPlan = async ({
   const afterEachInOrderCallbackSet = new Set();
   const afterAllCallbackSet = new Set();
   let finalizeCoverage;
+  let timingsMemory;
 
   try {
     let logger;
@@ -418,6 +431,51 @@ export 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
       {
@@ -688,6 +746,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) {
@@ -709,7 +770,7 @@ To fix this warning:
             runtime,
             runtimeParams,
             allocatedMs = defaultMsAllocatedPerExecution,
-            uses,
+            locks,
           } = stepConfig;
           const params = {
             measureMemoryUsage: true,
@@ -717,7 +778,7 @@ To fix this warning:
             collectPerformance: false,
             collectConsole: true,
             allocatedMs,
-            uses,
+            locks,
             runtime,
             runtimeParams: {
               rootDirectoryUrl,
@@ -763,6 +824,8 @@ To fix this warning:
             params,
             skipped: false,
             skipReason: "",
+            // set when the file calls requestAllocatedMs
+            allocatedMsRequested: undefined,
 
             // will be set by run()
             status: "planified",
@@ -775,9 +838,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;
@@ -947,9 +1023,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],
@@ -963,14 +1063,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,
@@ -980,11 +1083,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) {
@@ -1015,6 +1121,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) {
@@ -1042,18 +1154,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();
@@ -1137,6 +1260,10 @@ To fix this warning:
     }
     timings.teardownEnd = takeTiming();
 
+    if (timingsMemory) {
+      timingsMemory.write();
+    }
+
     if (finalizeCoverage) {
       await finalizeCoverage();
     }

package/src/execution/execution_timings.js

@@ -0,0 +1,125 @@
+/*
+ * 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.
+ */
+
+import { writeFileSync } from "@jsenv/filesystem";
+import { readFileSync } from "node:fs";
+
+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;
+
+export 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;
+};

package/src/execution/jsenv_directives.js

@@ -0,0 +1,172 @@
+/*
+ * 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.
+ */
+
+import { createDetailedMessage } from "@jsenv/humanize";
+import { closeSync, openSync, readFileSync, readSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+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;
+
+export 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 };
+};

package/src/execution/run.js

@@ -19,6 +19,7 @@ export const run = async ({
   signal = new AbortController().signal,
   logger,
   allocatedMs,
+  onAllocatedMsRequested = () => {},
   keepRunning = false,
   mirrorConsole = false,
   collectConsole = false,
@@ -69,6 +70,22 @@ export 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) {
@@ -121,6 +138,7 @@ export const run = async ({
                 signal: runOperation.signal,
                 logger,
                 ...runtimeParams,
+                onAllocatedMsRequested: handleAllocatedMsRequest,
                 collectConsole,
                 measureMemoryUsage,
                 onMeasureMemoryAvailable,

package/src/main.js

@@ -8,6 +8,8 @@ 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";
+// called from within a test file
+export { requestAllocatedMs } from "./runtime_node/request_allocated_ms.js";
 // coverage
 export { reportCoverageAsHtml } from "./coverage/report_coverage_as_html.js";
 export { reportCoverageAsJson } from "./coverage/report_coverage_as_json.js";

package/src/main_browser.js

@@ -0,0 +1,4 @@
+// what a test file executed in a browser can import from "@jsenv/test";
+// everything else in this package is node code driving those executions
+
+export { requestAllocatedMs } from "./runtime_browsers/client/request_allocated_ms.js";

package/src/runtime_browsers/client/request_allocated_ms.js

@@ -0,0 +1,17 @@
+/*
+ * Browser side of requestAllocatedMs: reaches the process running the test plan
+ * through a function playwright exposed on the page before navigating to it
+ * (see using_playwright.js).
+ */
+
+export const requestAllocatedMs = (ms) => {
+  if (typeof ms !== "number") {
+    throw new TypeError(`requestAllocatedMs expects a number, got ${ms}`);
+  }
+  const requestAllocatedMsBinding = window.__jsenv_request_allocated_ms__;
+  if (!requestAllocatedMsBinding) {
+    // page opened on its own (dev server, browser tab): there is no allocated time
+    return;
+  }
+  requestAllocatedMsBinding(ms);
+};