@jsenv/core 31.2.0 → 32.0.0

package/src/test/execute_plan.js

@@ -5,14 +5,13 @@ import wrapAnsi from "wrap-ansi"
 import stripAnsi from "strip-ansi"
 
 import { urlToFileSystemPath } from "@jsenv/urls"
-import { createDetailedMessage, createLog, startSpinner } from "@jsenv/log"
+import { createLog, startSpinner } from "@jsenv/log"
 import { Abort, raceProcessTeardownEvents } from "@jsenv/abort"
 import { ensureEmptyDirectory, writeFileSync } from "@jsenv/filesystem"
 
 import { reportToCoverage } from "./coverage/report_to_coverage.js"
 import { run } from "@jsenv/core/src/execute/run.js"
 
-import { pingServer } from "../ping_server.js"
 import { ensureGlobalGc } from "./gc.js"
 import { generateExecutionSteps } from "./execution_steps.js"
 import { createExecutionLog, createSummaryLog } from "./logs_file_execution.js"
@@ -48,7 +47,7 @@ export const executePlan = async (
     coverageMethodForBrowsers,
     coverageMethodForNodeJs,
     coverageV8ConflictWarning,
-    coverageTempDirectoryRelativeUrl,
+    coverageTempDirectoryUrl,
 
     beforeExecutionCallback = () => {},
     afterExecutionCallback = () => {},
@@ -59,30 +58,6 @@ export const executePlan = async (
   const callbacks = []
   const stopAfterAllSignal = { notify: () => {} }
 
-  let someNeedsServer = false
-  let someNodeRuntime = false
-  const runtimes = {}
-  Object.keys(plan).forEach((filePattern) => {
-    const filePlan = plan[filePattern]
-    Object.keys(filePlan).forEach((executionName) => {
-      const executionConfig = filePlan[executionName]
-      const { runtime } = executionConfig
-      if (runtime) {
-        runtimes[runtime.name] = runtime.version
-        if (runtime.type === "browser") {
-          someNeedsServer = true
-        }
-        if (runtime.type === "node") {
-          someNodeRuntime = true
-        }
-      }
-    })
-  })
-  logger.debug(
-    createDetailedMessage(`Prepare executing plan`, {
-      runtimes: JSON.stringify(runtimes, null, "  "),
-    }),
-  )
   const multipleExecutionsOperation = Abort.startOperation()
   multipleExecutionsOperation.addAbortSignal(signal)
   if (handleSIGINT) {
@@ -104,32 +79,6 @@ export const executePlan = async (
   }
 
   try {
-    const coverageTempDirectoryUrl = new URL(
-      coverageTempDirectoryRelativeUrl,
-      rootDirectoryUrl,
-    ).href
-    if (
-      someNodeRuntime &&
-      coverageEnabled &&
-      coverageMethodForNodeJs === "NODE_V8_COVERAGE"
-    ) {
-      if (process.env.NODE_V8_COVERAGE) {
-        // when runned multiple times, we don't want to keep previous files in this directory
-        await ensureEmptyDirectory(process.env.NODE_V8_COVERAGE)
-      } else {
-        coverageMethodForNodeJs = "Profiler"
-        logger.warn(
-          createDetailedMessage(
-            `process.env.NODE_V8_COVERAGE is required to generate coverage for Node.js subprocesses`,
-            {
-              "suggestion": `set process.env.NODE_V8_COVERAGE`,
-              "suggestion 2": `use coverageMethodForNodeJs: "Profiler". But it means coverage for child_process and worker_thread cannot be collected`,
-            },
-          ),
-        )
-      }
-    }
-
     if (gcBetweenExecutions) {
       ensureGlobalGc()
     }
@@ -177,19 +126,6 @@ export const executePlan = async (
       coverageMethodForNodeJs,
       stopAfterAllSignal,
     }
-    if (someNeedsServer) {
-      if (!devServerOrigin) {
-        throw new TypeError(
-          `devServerOrigin is required when running tests on browser(s)`,
-        )
-      }
-      const devServerStarted = await pingServer(devServerOrigin)
-      if (!devServerStarted) {
-        throw new Error(
-          `dev server not started at ${devServerOrigin}. It is required to run tests`,
-        )
-      }
-    }
 
     logger.debug(`Generate executions`)
     const executionSteps = await getExecutionAsSteps({
@@ -292,7 +228,10 @@ export const executePlan = async (
           executionResult = await run({
             signal: multipleExecutionsOperation.signal,
             logger,
-            allocatedMs: executionParams.allocatedMs,
+            allocatedMs:
+              typeof executionParams.allocatedMs === "function"
+                ? executionParams.allocatedMs(beforeExecutionInfo)
+                : executionParams.allocatedMs,
             keepRunning,
             mirrorConsole: false, // file are executed in parallel, log would be a mess to read
             collectConsole: executionParams.collectConsole,

package/src/test/execute_test_plan.js

@@ -1,13 +1,20 @@
+import { existsSync } from "node:fs"
 import { URL_META } from "@jsenv/url-meta"
 import {
   urlToFileSystemPath,
-  resolveDirectoryUrl,
-  urlIsInsideOf,
   urlToRelativeUrl,
+  urlIsInsideOf,
 } from "@jsenv/urls"
-import { ensureEmptyDirectory, validateDirectoryUrl } from "@jsenv/filesystem"
+import {
+  ensureEmptyDirectory,
+  assertAndNormalizeDirectoryUrl,
+  assertAndNormalizeFileUrl,
+} from "@jsenv/filesystem"
 import { createLogger, createDetailedMessage } from "@jsenv/log"
 
+import { lookupPackageDirectory } from "../lookup_package_directory.js"
+import { pingServer } from "../ping_server.js"
+import { basicFetch } from "../basic_fetch.js"
 import { generateCoverageJsonFile } from "./coverage/coverage_reporter_json_file.js"
 import { generateCoverageHtmlDirectory } from "./coverage/coverage_reporter_html_directory.js"
 import { generateCoverageTextLog } from "./coverage/coverage_reporter_text_log.js"
@@ -16,8 +23,8 @@ import { executePlan } from "./execute_plan.js"
 /**
  * Execute a list of files and log how it goes.
  * @param {Object} testPlanParameters
- * @param {string|url} testPlanParameters.rootDirectoryUrl Root directory of the project
- * @param {string|url} [testPlanParameters.serverOrigin=undefined] Jsenv dev server origin; required when executing test on browsers
+ * @param {string|url} testPlanParameters.testDirectoryUrl Directory containing test files
+ * @param {string|url} [testPlanParameters.devServerOrigin=undefined] Jsenv dev server origin; required when executing test on browsers
  * @param {Object} testPlanParameters.testPlan Object associating patterns leading to files to runtimes where they should be executed
  * @param {boolean} [testPlanParameters.completedExecutionLogAbbreviation=false] Abbreviate completed execution information to shorten terminal output
  * @param {boolean} [testPlanParameters.completedExecutionLogMerging=false] Merge completed execution logs to shorten terminal output
@@ -43,7 +50,8 @@ export const executeTestPlan = async ({
   logFileRelativeUrl = ".jsenv/test_plan_debug.txt",
   completedExecutionLogAbbreviation = false,
   completedExecutionLogMerging = false,
-  rootDirectoryUrl,
+  testDirectoryUrl,
+  devServerModuleUrl,
   devServerOrigin,
 
   testPlan,
@@ -61,9 +69,7 @@ export const executeTestPlan = async ({
   gcBetweenExecutions = logMemoryHeapUsage,
 
   coverageEnabled = process.argv.includes("--coverage"),
-  coverageConfig = {
-    "./src/": true,
-  },
+  coverageConfig = { "./**/*": true },
   coverageIncludeMissing = true,
   coverageAndExecutionAllowed = false,
   coverageMethodForNodeJs = process.env.NODE_V8_COVERAGE
@@ -71,16 +77,23 @@ export const executeTestPlan = async ({
     : "Profiler",
   coverageMethodForBrowsers = "playwright_api", // "istanbul" also accepted
   coverageV8ConflictWarning = true,
-  coverageTempDirectoryRelativeUrl = "./.coverage/tmp/",
+  coverageTempDirectoryUrl,
+  coverageReportRootDirectoryUrl,
   // skip empty means empty files won't appear in the coverage reports (json and html)
   coverageReportSkipEmpty = false,
   // skip full means file with 100% coverage won't appear in coverage reports (json and html)
   coverageReportSkipFull = false,
   coverageReportTextLog = true,
-  coverageReportJsonFile = process.env.CI ? null : "./.coverage/coverage.json",
-  coverageReportHtmlDirectory = process.env.CI ? "./.coverage/" : null,
+  coverageReportJson = process.env.CI,
+  coverageReportJsonFileUrl,
+  coverageReportHtml = !process.env.CI,
+  coverageReportHtmlDirectoryUrl,
   ...rest
 }) => {
+  let someNeedsServer = false
+  let someNodeRuntime = false
+  let stopDevServerNeeded = false
+  const runtimes = {}
   // param validation
   {
     const unexpectedParamNames = Object.keys(rest)
@@ -89,16 +102,81 @@ export const executeTestPlan = async ({
         `${unexpectedParamNames.join(",")}: there is no such param`,
       )
     }
-    const rootDirectoryUrlValidation = validateDirectoryUrl(rootDirectoryUrl)
-    if (!rootDirectoryUrlValidation.valid) {
-      throw new TypeError(
-        `rootDirectoryUrl ${rootDirectoryUrlValidation.message}, got ${rootDirectoryUrl}`,
-      )
+    testDirectoryUrl = assertAndNormalizeDirectoryUrl(
+      testDirectoryUrl,
+      "testDirectoryUrl",
+    )
+    if (!existsSync(new URL(testDirectoryUrl))) {
+      throw new Error(`ENOENT on testDirectoryUrl at ${testDirectoryUrl}`)
     }
-    rootDirectoryUrl = rootDirectoryUrlValidation.value
     if (typeof testPlan !== "object") {
       throw new Error(`testPlan must be an object, got ${testPlan}`)
     }
+
+    Object.keys(testPlan).forEach((filePattern) => {
+      const filePlan = testPlan[filePattern]
+      if (!filePlan) return
+      Object.keys(filePlan).forEach((executionName) => {
+        const executionConfig = filePlan[executionName]
+        const { runtime } = executionConfig
+        if (runtime) {
+          runtimes[runtime.name] = runtime.version
+          if (runtime.type === "browser") {
+            someNeedsServer = true
+          }
+          if (runtime.type === "node") {
+            someNodeRuntime = true
+          }
+        }
+      })
+    })
+
+    if (someNeedsServer) {
+      if (!devServerOrigin) {
+        throw new TypeError(
+          `devServerOrigin is required when running tests on browser(s)`,
+        )
+      }
+      let devServerStarted = await pingServer(devServerOrigin)
+      if (!devServerStarted) {
+        if (!devServerModuleUrl) {
+          throw new TypeError(
+            `devServerModuleUrl is required when dev server is not started in order to run tests on browser(s)`,
+          )
+        }
+        try {
+          process.env.IMPORTED_BY_TEST_PLAN = "1"
+          await import(devServerModuleUrl)
+          delete process.env.IMPORTED_BY_TEST_PLAN
+        } catch (e) {
+          if (e.code === "MODULE_NOT_FOUND") {
+            throw new Error(
+              `Cannot find file responsible to start dev server at "${devServerModuleUrl}"`,
+            )
+          }
+          throw e
+        }
+        devServerStarted = await pingServer(devServerOrigin)
+        if (!devServerStarted) {
+          throw new Error(
+            `dev server not started after importing "${devServerModuleUrl}", ensure this module file is starting a server at "${devServerOrigin}"`,
+          )
+        }
+        stopDevServerNeeded = true
+      }
+      const { sourceDirectoryUrl } = await basicFetch(
+        `${devServerOrigin}/__server_params__.json`,
+      )
+      if (
+        testDirectoryUrl !== sourceDirectoryUrl &&
+        !urlIsInsideOf(testDirectoryUrl, sourceDirectoryUrl)
+      ) {
+        throw new Error(
+          `testDirectoryUrl must be inside sourceDirectoryUrl when running tests on browser(s)`,
+        )
+      }
+    }
+
     if (coverageEnabled) {
       if (typeof coverageConfig !== "object") {
         throw new TypeError(
@@ -135,16 +213,96 @@ export const executeTestPlan = async ({
           )
         }
       }
+      if (coverageReportRootDirectoryUrl === undefined) {
+        coverageReportRootDirectoryUrl =
+          lookupPackageDirectory(testDirectoryUrl)
+      } else {
+        coverageReportRootDirectoryUrl = assertAndNormalizeDirectoryUrl(
+          coverageReportRootDirectoryUrl,
+          "coverageReportRootDirectoryUrl",
+        )
+      }
+      if (coverageTempDirectoryUrl === undefined) {
+        coverageTempDirectoryUrl = new URL(
+          "./.coverage/tmp/",
+          coverageReportRootDirectoryUrl,
+        )
+      } else {
+        coverageTempDirectoryUrl = assertAndNormalizeDirectoryUrl(
+          coverageTempDirectoryUrl,
+          "coverageTempDirectoryUrl",
+        )
+      }
+      if (coverageReportJson) {
+        if (coverageReportJsonFileUrl === undefined) {
+          coverageReportJsonFileUrl = new URL(
+            "./.coverage/coverage.json",
+            coverageReportRootDirectoryUrl,
+          )
+        } else {
+          coverageReportJsonFileUrl = assertAndNormalizeFileUrl(
+            coverageReportJsonFileUrl,
+            "coverageReportJsonFileUrl",
+          )
+        }
+      }
+      if (coverageReportHtml) {
+        if (coverageReportHtmlDirectoryUrl === undefined) {
+          coverageReportHtmlDirectoryUrl = new URL(
+            "./.coverage/",
+            coverageReportRootDirectoryUrl,
+          )
+        } else {
+          coverageReportHtmlDirectoryUrl = assertAndNormalizeDirectoryUrl(
+            coverageReportHtmlDirectoryUrl,
+            "coverageReportHtmlDirectoryUrl",
+          )
+        }
+      }
     }
   }
 
   const logger = createLogger({ logLevel })
-  if (Object.keys(coverageConfig).length === 0) {
-    logger.warn(
-      `coverageConfig is an empty object. Nothing will be instrumented for coverage so your coverage will be empty`,
-    )
+  logger.debug(
+    createDetailedMessage(`Prepare executing plan`, {
+      runtimes: JSON.stringify(runtimes, null, "  "),
+    }),
+  )
+
+  // param normalization
+  {
+    if (coverageEnabled) {
+      if (Object.keys(coverageConfig).length === 0) {
+        logger.warn(
+          `coverageConfig is an empty object. Nothing will be instrumented for coverage so your coverage will be empty`,
+        )
+      }
+      if (
+        someNodeRuntime &&
+        coverageEnabled &&
+        coverageMethodForNodeJs === "NODE_V8_COVERAGE"
+      ) {
+        if (process.env.NODE_V8_COVERAGE) {
+          // when runned multiple times, we don't want to keep previous files in this directory
+          await ensureEmptyDirectory(process.env.NODE_V8_COVERAGE)
+        } else {
+          coverageMethodForNodeJs = "Profiler"
+          logger.warn(
+            createDetailedMessage(
+              `process.env.NODE_V8_COVERAGE is required to generate coverage for Node.js subprocesses`,
+              {
+                "suggestion": `set process.env.NODE_V8_COVERAGE`,
+                "suggestion 2": `use coverageMethodForNodeJs: "Profiler". But it means coverage for child_process and worker_thread cannot be collected`,
+              },
+            ),
+          )
+        }
+      }
+    }
   }
 
+  testPlan = { ...testPlan, "**/.jsenv/": null }
+
   const result = await executePlan(testPlan, {
     signal,
     handleSIGINT,
@@ -158,7 +316,7 @@ export const executeTestPlan = async ({
     logFileRelativeUrl,
     completedExecutionLogMerging,
     completedExecutionLogAbbreviation,
-    rootDirectoryUrl,
+    rootDirectoryUrl: testDirectoryUrl,
     devServerOrigin,
 
     maxExecutionsInParallel,
@@ -174,8 +332,17 @@ export const executeTestPlan = async ({
     coverageMethodForBrowsers,
     coverageMethodForNodeJs,
     coverageV8ConflictWarning,
-    coverageTempDirectoryRelativeUrl,
+    coverageTempDirectoryUrl,
   })
+  if (stopDevServerNeeded) {
+    // we are expecting ECONNRESET because server will be stopped by the request
+    basicFetch(`${devServerOrigin}/__stop__`).catch((e) => {
+      if (e.code === "ECONNRESET") {
+        return
+      }
+      throw e
+    })
+  }
   if (
     updateProcessExitCode &&
     result.planSummary.counters.total !== result.planSummary.counters.completed
@@ -189,42 +356,29 @@ export const executeTestPlan = async ({
     // keep this one first because it does ensureEmptyDirectory
     // and in case coverage json file gets written in the same directory
     // it must be done before
-    if (coverageEnabled && coverageReportHtmlDirectory) {
-      const coverageHtmlDirectoryUrl = resolveDirectoryUrl(
-        coverageReportHtmlDirectory,
-        rootDirectoryUrl,
-      )
-      if (!urlIsInsideOf(coverageHtmlDirectoryUrl, rootDirectoryUrl)) {
-        throw new Error(
-          `coverageReportHtmlDirectory must be inside rootDirectoryUrl`,
-        )
-      }
-      await ensureEmptyDirectory(coverageHtmlDirectoryUrl)
-      const htmlCoverageDirectoryIndexFileUrl = `${coverageHtmlDirectoryUrl}index.html`
+    if (coverageEnabled && coverageReportHtml) {
+      await ensureEmptyDirectory(coverageReportHtmlDirectoryUrl)
+      const htmlCoverageDirectoryIndexFileUrl = `${coverageReportHtmlDirectoryUrl}index.html`
       logger.info(
         `-> ${urlToFileSystemPath(htmlCoverageDirectoryIndexFileUrl)}`,
       )
       promises.push(
         generateCoverageHtmlDirectory(planCoverage, {
-          rootDirectoryUrl,
+          rootDirectoryUrl: coverageReportRootDirectoryUrl,
           coverageHtmlDirectoryRelativeUrl: urlToRelativeUrl(
-            coverageHtmlDirectoryUrl,
-            rootDirectoryUrl,
+            coverageReportHtmlDirectoryUrl,
+            coverageReportRootDirectoryUrl,
           ),
           coverageReportSkipEmpty,
           coverageReportSkipFull,
         }),
       )
     }
-    if (coverageEnabled && coverageReportJsonFile) {
-      const coverageJsonFileUrl = new URL(
-        coverageReportJsonFile,
-        rootDirectoryUrl,
-      ).href
+    if (coverageEnabled && coverageReportJson) {
       promises.push(
         generateCoverageJsonFile({
           coverage: result.planCoverage,
-          coverageJsonFileUrl,
+          coverageJsonFileUrl: coverageReportJsonFileUrl,
           logger,
         }),
       )

package/src/watch_source_files.js

@@ -0,0 +1,50 @@
+import { registerDirectoryLifecycle } from "@jsenv/filesystem"
+
+export const watchSourceFiles = (
+  sourceDirectoryUrl,
+  callback,
+  { sourceFileConfig = {}, keepProcessAlive, cooldownBetweenFileEvents },
+) => {
+  // Project should use a dedicated directory (usually "src/")
+  // passed to the dev server via "sourceDirectoryUrl" param
+  // In that case all files inside the source directory should be watched
+  // But some project might want to use their root directory as source directory
+  // In that case source directory might contain files matching "node_modules/*" or ".git/*"
+  // And jsenv should not consider these as source files and watch them (to not hurt performances)
+  const watchPatterns = {
+    "**/*": true, // by default watch everything inside the source directory
+    "**/.*": false, // file starting with a dot -> do not watch
+    "**/.*/": false, // directory starting with a dot -> do not watch
+    "**/node_modules/": false, // node_modules directory -> do not watch
+    ...sourceFileConfig,
+  }
+  const stopWatchingSourceFiles = registerDirectoryLifecycle(
+    sourceDirectoryUrl,
+    {
+      watchPatterns,
+      cooldownBetweenFileEvents,
+      keepProcessAlive,
+      recursive: true,
+      added: ({ relativeUrl }) => {
+        callback({
+          url: new URL(relativeUrl, sourceDirectoryUrl).href,
+          event: "added",
+        })
+      },
+      updated: ({ relativeUrl }) => {
+        callback({
+          url: new URL(relativeUrl, sourceDirectoryUrl).href,
+          event: "modified",
+        })
+      },
+      removed: ({ relativeUrl }) => {
+        callback({
+          url: new URL(relativeUrl, sourceDirectoryUrl).href,
+          event: "removed",
+        })
+      },
+    },
+  )
+  stopWatchingSourceFiles.watchPatterns = watchPatterns
+  return stopWatchingSourceFiles
+}