@jsenv/test 3.7.37 → 3.7.39

package/dist/jsenv_test.js

@@ -5708,11 +5708,11 @@ 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.
+ * What it is for: with a fixed number of parallel slots, an execution still
+ * running when everything after it is done decides alone when the run ends.
+ * Started last it keeps one slot busy while every other one is idle. Knowing
+ * the durations of the previous run is what allows to recognize that execution
+ * and start it ahead of its turn (see "parallel.maxAhead").
  *
  * Only the start order is affected: executions keep the index they got from the
  * filesystem, so they are still reported in that order.
@@ -5735,33 +5735,36 @@ const createExecutionTimings = ({ fileUrl }) => {
       }
       return previousEntry.allocatedMsRequested;
     },
-    sortByLongestFirst: (executionArray) => {
+    // how long each execution is expected to take on this run
+    estimateDurations: (executionArray) => {
       const durationMsMap = new Map();
       const durationMsArray = [];
       for (const execution of executionArray) {
+        if (execution.skipped) {
+          // a skipped execution costs nothing; it must not weigh on what is
+          // expected from the others
+          durationMsMap.set(execution, 0);
+          continue;
+        }
         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
+      // being new is not a reason to be considered short
       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;
-      });
+        durationMsArray.length === 0
+          ? 0
+          : durationMsArray[Math.floor(durationMsArray.length / 2)];
+      for (const execution of executionArray) {
+        if (!durationMsMap.has(execution)) {
+          durationMsMap.set(execution, medianDurationMs);
+        }
+      }
+      return durationMsMap;
     },
     record: (execution) => {
       const { status, timings } = execution.result;
@@ -7848,7 +7851,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 {Object|false} [testPlanParameters.executionTimings=false] Remembers how long executions took; on the next run "parallel.maxAhead" uses it to start the longest ones ahead of their turn
  * @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
@@ -7910,6 +7913,9 @@ const parallelDefault = {
   // percentage resolved against parallel.max; an execution is heavy when it is
   // allocated more time than the others (see defaultMsAllocatedPerExecution)
   maxHeavy: "75%",
+  // how many slots may be given to an execution started ahead of its turn;
+  // 0 keeps the order given by the filesystem (see "executionTimings")
+  maxAhead: 0,
 };
 const executionTimingsDefault = {
   fileUrl: undefined,
@@ -8246,6 +8252,20 @@ const executeTestPlan = async ({
             `parallel.maxHeavy must be a number or a percentage, got ${maxHeavy}`,
           );
         }
+
+        const maxAhead = parallel.maxAhead;
+        if (typeof maxAhead === "string") {
+          const maxAheadAsRatio = assertPercentageAndConvertToRatio(maxAhead);
+          parallel.maxAhead = Math.round(maxAheadAsRatio * parallel.max);
+        } else if (typeof maxAhead === "number") {
+          if (maxAhead < 0) {
+            parallel.maxAhead = 0;
+          }
+        } else {
+          throw new TypeError(
+            `parallel.maxAhead must be a number or a percentage, got ${maxAhead}`,
+          );
+        }
       }
       // executionTimings
       {
@@ -8825,7 +8845,7 @@ To fix this warning:
       const callWhenPreviousExecutionAreDone = createCallOrderer();
 
       // 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
+      // worth not having too many of at once
       const heavyExecutionSet = new Set();
       for (const execution of executionPlanifiedArray) {
         if (execution.skipped) {
@@ -8844,13 +8864,91 @@ To fix this warning:
           }
         }
       }
-      const executionStartOrderArray = timingsMemory
-        ? timingsMemory.sortByLongestFirst(executionPlanifiedArray)
-        : executionPlanifiedArray;
-
-      const executionRemainingSet = new Set(executionStartOrderArray);
+      const executionRemainingSet = new Set(executionPlanifiedArray);
       const executionExecutingSet = new Set();
+      // the executions currently running ahead of their turn
+      const executionAheadSet = new Set();
       const lockedResourceSet = new Set();
+      const findResourceLockedByAnother = (execution) => {
+        if (!execution.params.locks) {
+          return null;
+        }
+        return (
+          execution.params.locks.find((resourceToLock) =>
+            lockedResourceSet.has(resourceToLock),
+          ) || null
+        );
+      };
+      const durationMsMap =
+        timingsMemory && parallel.maxAhead > 0
+          ? timingsMemory.estimateDurations(executionPlanifiedArray)
+          : null;
+      /*
+       * Executions start in the order the filesystem gives them, which is also
+       * the order they are reported in: the run then progresses where it is
+       * read. One departure from that order pays for itself: an execution still
+       * running once everything after it is done decides alone when the run
+       * ends, so the time it spends waiting for its turn is time the whole run
+       * waits at the end. "parallel.maxAhead" says how many slots can be spent
+       * on such an execution; the other slots keep the natural order, because
+       * starting the heaviest executions of the plan all at once makes them
+       * fight for cpu and memory, which pauses everything (see maxCpu/maxMemory).
+       */
+      const pickExecutionToStartAhead = (executionPickedSet) => {
+        if (!durationMsMap) {
+          // nothing remembers which execution is the long one
+          return null;
+        }
+        if (
+          executionAheadSet.size + executionPickedSet.size >=
+          parallel.maxAhead
+        ) {
+          return null;
+        }
+        const executionRemainingArray = [...executionRemainingSet];
+        // what a remaining execution costs on average; the last one to start is
+        // always the one still running at the end, so without this reference the
+        // slot would go to whichever execution happens to be last rather than to
+        // a long one
+        let msRemainingTotal = 0;
+        let executionRemainingCount = 0;
+        for (const execution of executionRemainingArray) {
+          const durationMs = durationMsMap.get(execution);
+          if (durationMs > 0) {
+            msRemainingTotal += durationMs;
+            executionRemainingCount++;
+          }
+        }
+        if (executionRemainingCount === 0) {
+          return null;
+        }
+        const msAverage = msRemainingTotal / executionRemainingCount;
+        let executionAhead = null;
+        let executionAheadMs = 0;
+        // the executions are visited backwards so that, for each one, the time
+        // still to be spent after it is already known
+        let msAfter = 0;
+        let index = executionRemainingArray.length;
+        while (index--) {
+          const execution = executionRemainingArray[index];
+          const durationMs = durationMsMap.get(execution);
+          if (
+            // the ones about to start anyway have nothing to gain
+            index >= parallel.max &&
+            durationMs > msAverage &&
+            durationMs > executionAheadMs &&
+            // it would still be running when everything after it is done
+            durationMs > msAfter / parallel.max &&
+            !executionPickedSet.has(execution) &&
+            !findResourceLockedByAnother(execution)
+          ) {
+            executionAhead = execution;
+            executionAheadMs = durationMs;
+          }
+          msAfter += durationMs;
+        }
+        return executionAhead;
+      };
       const start = async (execution) => {
         execution.fileExecutionCount = Object.keys(
           testPlanResult.results[execution.fileRelativeUrl],
@@ -8901,6 +8999,7 @@ To fix this warning:
         }
         mutateCountersAfterExecutionEnds(counters, execution);
         executionExecutingSet.delete(execution);
+        executionAheadSet.delete(execution);
         for (const afterEachCallback of afterEachCallbackSet) {
           afterEachCallback(execution, testPlanResult, testPlanHelpers);
         }
@@ -8928,8 +9027,21 @@ To fix this warning:
             heavyExecutingCount++;
           }
         }
+        // the executions allowed to run ahead of their turn are considered
+        // first: the slot they take is the whole point
+        const executionPickedSet = new Set();
+        while (true) {
+          const executionAhead = pickExecutionToStartAhead(executionPickedSet);
+          if (!executionAhead) {
+            break;
+          }
+          executionPickedSet.add(executionAhead);
+        }
         const promises = [];
-        for (const executionCandidate of executionRemainingSet) {
+        for (const executionCandidate of new Set([
+          ...executionPickedSet,
+          ...executionRemainingSet,
+        ])) {
           if (executionExecutingSet.size >= parallel.max) {
             break;
           }
@@ -8962,22 +9074,21 @@ To fix this warning:
                 continue;
               }
             }
-            if (executionCandidate.params.locks) {
-              const resourceLockedByAnother =
-                executionCandidate.params.locks.find((resourceToLock) =>
-                  lockedResourceSet.has(resourceToLock),
-                );
-              if (resourceLockedByAnother) {
-                logger.debug(
-                  `"${resourceLockedByAnother}" is locked, ${executionCandidate.name} will wait until it is released by a previous execution`,
-                );
-                continue;
-              }
+            const resourceLockedByAnother =
+              findResourceLockedByAnother(executionCandidate);
+            if (resourceLockedByAnother) {
+              logger.debug(
+                `"${resourceLockedByAnother}" is locked, ${executionCandidate.name} will wait until it is released by a previous execution`,
+              );
+              continue;
             }
           }
           if (heavyExecutionSet.has(executionCandidate)) {
             heavyExecutingCount++;
           }
+          if (executionPickedSet.has(executionCandidate)) {
+            executionAheadSet.add(executionCandidate);
+          }
           const promise = (async () => {
             await start(executionCandidate);
             await startAsMuchAsPossible();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/test",
-  "version": "3.7.37",
+  "version": "3.7.39",
   "type": "module",
   "repository": {
     "type": "git",
@@ -31,9 +31,9 @@
   },
   "dependencies": {
     "@c88/v8-coverage": "0.1.1",
-    "@jsenv/ast": "6.9.3",
-    "@jsenv/plugin-supervisor": "1.8.14",
-    "@jsenv/sourcemap": "1.4.2",
+    "@jsenv/ast": "6.10.0",
+    "@jsenv/plugin-supervisor": "1.8.16",
+    "@jsenv/sourcemap": "1.4.3",
     "he": "1.2.0",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-instrument": "6.0.3",

package/src/execution/execute_test_plan.js

@@ -47,7 +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 {Object|false} [testPlanParameters.executionTimings=false] Remembers how long executions took; on the next run "parallel.maxAhead" uses it to start the longest ones ahead of their turn
  * @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
@@ -109,6 +109,9 @@ const parallelDefault = {
   // percentage resolved against parallel.max; an execution is heavy when it is
   // allocated more time than the others (see defaultMsAllocatedPerExecution)
   maxHeavy: "75%",
+  // how many slots may be given to an execution started ahead of its turn;
+  // 0 keeps the order given by the filesystem (see "executionTimings")
+  maxAhead: 0,
 };
 const executionTimingsDefault = {
   fileUrl: undefined,
@@ -445,6 +448,20 @@ export const executeTestPlan = async ({
             `parallel.maxHeavy must be a number or a percentage, got ${maxHeavy}`,
           );
         }
+
+        const maxAhead = parallel.maxAhead;
+        if (typeof maxAhead === "string") {
+          const maxAheadAsRatio = assertPercentageAndConvertToRatio(maxAhead);
+          parallel.maxAhead = Math.round(maxAheadAsRatio * parallel.max);
+        } else if (typeof maxAhead === "number") {
+          if (maxAhead < 0) {
+            parallel.maxAhead = 0;
+          }
+        } else {
+          throw new TypeError(
+            `parallel.maxAhead must be a number or a percentage, got ${maxAhead}`,
+          );
+        }
       }
       // executionTimings
       {
@@ -1024,7 +1041,7 @@ To fix this warning:
       const callWhenPreviousExecutionAreDone = createCallOrderer();
 
       // 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
+      // worth not having too many of at once
       const heavyExecutionSet = new Set();
       for (const execution of executionPlanifiedArray) {
         if (execution.skipped) {
@@ -1043,13 +1060,91 @@ To fix this warning:
           }
         }
       }
-      const executionStartOrderArray = timingsMemory
-        ? timingsMemory.sortByLongestFirst(executionPlanifiedArray)
-        : executionPlanifiedArray;
-
-      const executionRemainingSet = new Set(executionStartOrderArray);
+      const executionRemainingSet = new Set(executionPlanifiedArray);
       const executionExecutingSet = new Set();
+      // the executions currently running ahead of their turn
+      const executionAheadSet = new Set();
       const lockedResourceSet = new Set();
+      const findResourceLockedByAnother = (execution) => {
+        if (!execution.params.locks) {
+          return null;
+        }
+        return (
+          execution.params.locks.find((resourceToLock) =>
+            lockedResourceSet.has(resourceToLock),
+          ) || null
+        );
+      };
+      const durationMsMap =
+        timingsMemory && parallel.maxAhead > 0
+          ? timingsMemory.estimateDurations(executionPlanifiedArray)
+          : null;
+      /*
+       * Executions start in the order the filesystem gives them, which is also
+       * the order they are reported in: the run then progresses where it is
+       * read. One departure from that order pays for itself: an execution still
+       * running once everything after it is done decides alone when the run
+       * ends, so the time it spends waiting for its turn is time the whole run
+       * waits at the end. "parallel.maxAhead" says how many slots can be spent
+       * on such an execution; the other slots keep the natural order, because
+       * starting the heaviest executions of the plan all at once makes them
+       * fight for cpu and memory, which pauses everything (see maxCpu/maxMemory).
+       */
+      const pickExecutionToStartAhead = (executionPickedSet) => {
+        if (!durationMsMap) {
+          // nothing remembers which execution is the long one
+          return null;
+        }
+        if (
+          executionAheadSet.size + executionPickedSet.size >=
+          parallel.maxAhead
+        ) {
+          return null;
+        }
+        const executionRemainingArray = [...executionRemainingSet];
+        // what a remaining execution costs on average; the last one to start is
+        // always the one still running at the end, so without this reference the
+        // slot would go to whichever execution happens to be last rather than to
+        // a long one
+        let msRemainingTotal = 0;
+        let executionRemainingCount = 0;
+        for (const execution of executionRemainingArray) {
+          const durationMs = durationMsMap.get(execution);
+          if (durationMs > 0) {
+            msRemainingTotal += durationMs;
+            executionRemainingCount++;
+          }
+        }
+        if (executionRemainingCount === 0) {
+          return null;
+        }
+        const msAverage = msRemainingTotal / executionRemainingCount;
+        let executionAhead = null;
+        let executionAheadMs = 0;
+        // the executions are visited backwards so that, for each one, the time
+        // still to be spent after it is already known
+        let msAfter = 0;
+        let index = executionRemainingArray.length;
+        while (index--) {
+          const execution = executionRemainingArray[index];
+          const durationMs = durationMsMap.get(execution);
+          if (
+            // the ones about to start anyway have nothing to gain
+            index >= parallel.max &&
+            durationMs > msAverage &&
+            durationMs > executionAheadMs &&
+            // it would still be running when everything after it is done
+            durationMs > msAfter / parallel.max &&
+            !executionPickedSet.has(execution) &&
+            !findResourceLockedByAnother(execution)
+          ) {
+            executionAhead = execution;
+            executionAheadMs = durationMs;
+          }
+          msAfter += durationMs;
+        }
+        return executionAhead;
+      };
       const start = async (execution) => {
         execution.fileExecutionCount = Object.keys(
           testPlanResult.results[execution.fileRelativeUrl],
@@ -1100,6 +1195,7 @@ To fix this warning:
         }
         mutateCountersAfterExecutionEnds(counters, execution);
         executionExecutingSet.delete(execution);
+        executionAheadSet.delete(execution);
         for (const afterEachCallback of afterEachCallbackSet) {
           afterEachCallback(execution, testPlanResult, testPlanHelpers);
         }
@@ -1127,8 +1223,21 @@ To fix this warning:
             heavyExecutingCount++;
           }
         }
+        // the executions allowed to run ahead of their turn are considered
+        // first: the slot they take is the whole point
+        const executionPickedSet = new Set();
+        while (true) {
+          const executionAhead = pickExecutionToStartAhead(executionPickedSet);
+          if (!executionAhead) {
+            break;
+          }
+          executionPickedSet.add(executionAhead);
+        }
         const promises = [];
-        for (const executionCandidate of executionRemainingSet) {
+        for (const executionCandidate of new Set([
+          ...executionPickedSet,
+          ...executionRemainingSet,
+        ])) {
           if (executionExecutingSet.size >= parallel.max) {
             break;
           }
@@ -1161,22 +1270,21 @@ To fix this warning:
                 continue;
               }
             }
-            if (executionCandidate.params.locks) {
-              const resourceLockedByAnother =
-                executionCandidate.params.locks.find((resourceToLock) =>
-                  lockedResourceSet.has(resourceToLock),
-                );
-              if (resourceLockedByAnother) {
-                logger.debug(
-                  `"${resourceLockedByAnother}" is locked, ${executionCandidate.name} will wait until it is released by a previous execution`,
-                );
-                continue;
-              }
+            const resourceLockedByAnother =
+              findResourceLockedByAnother(executionCandidate);
+            if (resourceLockedByAnother) {
+              logger.debug(
+                `"${resourceLockedByAnother}" is locked, ${executionCandidate.name} will wait until it is released by a previous execution`,
+              );
+              continue;
             }
           }
           if (heavyExecutionSet.has(executionCandidate)) {
             heavyExecutingCount++;
           }
+          if (executionPickedSet.has(executionCandidate)) {
+            executionAheadSet.add(executionCandidate);
+          }
           const promise = (async () => {
             await start(executionCandidate);
             await startAsMuchAsPossible();

package/src/execution/execution_timings.js

@@ -2,11 +2,11 @@
  * 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.
+ * What it is for: with a fixed number of parallel slots, an execution still
+ * running when everything after it is done decides alone when the run ends.
+ * Started last it keeps one slot busy while every other one is idle. Knowing
+ * the durations of the previous run is what allows to recognize that execution
+ * and start it ahead of its turn (see "parallel.maxAhead").
  *
  * Only the start order is affected: executions keep the index they got from the
  * filesystem, so they are still reported in that order.
@@ -31,33 +31,36 @@ export const createExecutionTimings = ({ fileUrl }) => {
       }
       return previousEntry.allocatedMsRequested;
     },
-    sortByLongestFirst: (executionArray) => {
+    // how long each execution is expected to take on this run
+    estimateDurations: (executionArray) => {
       const durationMsMap = new Map();
       const durationMsArray = [];
       for (const execution of executionArray) {
+        if (execution.skipped) {
+          // a skipped execution costs nothing; it must not weigh on what is
+          // expected from the others
+          durationMsMap.set(execution, 0);
+          continue;
+        }
         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
+      // being new is not a reason to be considered short
       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;
-      });
+        durationMsArray.length === 0
+          ? 0
+          : durationMsArray[Math.floor(durationMsArray.length / 2)];
+      for (const execution of executionArray) {
+        if (!durationMsMap.has(execution)) {
+          durationMsMap.set(execution, medianDurationMs);
+        }
+      }
+      return durationMsMap;
     },
     record: (execution) => {
       const { status, timings } = execution.result;