@jsenv/test 1.0.2 → 1.0.3

package/README.md

@@ -3,9 +3,9 @@
 Executing test files in web browsers and/or Node.js.  
 This tool enforce test files to be written as **standard** files, without any sort of complexity.
 
-# 1. Writing tests on web browsers 
+# 1. Writing tests on web browsers
 
-This section demonstrates how to write a test that will be executed in a web browser. 
+This section demonstrates how to write a test that will be executed in a web browser.
 
 The function that will be tested is inside "add.js" file:
 
@@ -39,7 +39,7 @@ project/
 
 ## 1.1 Writing the test file
 
-*src/add.test.html*
+_src/add.test.html_
 
 ```html
 <!DOCTYPE html>
@@ -66,7 +66,7 @@ project/
 
 ## 1.2 Executing the test file
 
-*scripts/dev.mjs*: will start a web server that is needed to executed "add.test.html" in a browser. 
+_scripts/dev.mjs_: will start a web server that is needed to executed "add.test.html" in a browser.
 
 ```js
 import { startDevServer } from "@jsenv/core"
@@ -77,7 +77,7 @@ await startDevServer({
 })
 ```
 
-*scripts/test.mjs*: will start a web browser and use it to execute all test files.
+_scripts/test.mjs_: will start a web browser and use it to execute all test files.
 
 ```js
 import { executeTestPlan, chromium } from "@jsenv/test"
@@ -87,7 +87,7 @@ await executeTestPlan({
   testPlan: {
     "./src/**/*.test.html": {
       chromium: {
-        runtime: chromium()
+        runtime: chromium(),
       },
     },
   },
@@ -118,25 +118,20 @@ node ./scripts/test.mjs
 ### 1.3 Executing on more browsers
 
 ```js
-import {
-  executeTestPlan,
-  chromium,
-  firefox,
-  webkit,
-} from "@jsenv/test"
+import { executeTestPlan, chromium, firefox, webkit } from "@jsenv/test"
 
 await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
   testPlan: {
     "./src/**/*.test.html": {
       chromium: {
-        runtime: chromium()
+        runtime: chromium(),
       },
       firefox: {
-        runtime: firefox()
+        runtime: firefox(),
       },
       webkit: {
-        runtime: webkit()
+        runtime: webkit(),
       },
     },
   },
@@ -148,9 +143,9 @@ await executeTestPlan({
 })
 ```
 
-## 2. Writing tests on Node.js
+# 2. Writing tests on Node.js
 
-This section demonstrates how to write a test that will be executed in Node.js. 
+This section demonstrates how to write a test that will be executed in Node.js.
 
 The function that will be tested is inside "add.js" file:
 
@@ -182,7 +177,7 @@ project/
 
 ## 2.1 Writing the test file
 
-*add.test.mjs*
+_add.test.mjs_
 
 ```js
 import { add } from "./add.js"
@@ -196,7 +191,7 @@ if (actual !== expected) {
 
 ## 2.2 Executing the test file
 
-*scripts/test.mjs*
+_scripts/test.mjs_
 
 ```js
 import { executeTestPlan, nodeWorkerThread } from "@jsenv/test"
@@ -206,7 +201,7 @@ await executeTestPlan({
   testPlan: {
     "./tests/**/*.test.mjs": {
       node: {
-        runtime: nodeWorkerThread()
+        runtime: nodeWorkerThread(),
       },
     },
   },
@@ -225,7 +220,7 @@ Command to execute tests:
 node ./scripts/test.mjs
 ```
 
-## 3. Assertion library
+# 3. Assertion library
 
 To have a basic example, the part of the code comparing `actual` and `expected` was done without an assertion library.  
 In pratice a test would likely use one. The diff below shows how the assertion can be written using [@jsenv/assert](../assert). Note that any other assertion library would work.
@@ -242,47 +237,102 @@ const expected = 3
 + assert({ actual, expected })
 ```
 
-## 4. API
-
-## 4.1 executeTestPlan
+# 4. API
 
 ```js
-import { executeTestPlan } from "@jsenv/test"
+import {
+  executeTestPlan,
+  chromium,
+  firefox,
+  webkit,
+  nodeWorkerThread,
+  nodeChildProcess,
+} from "@jsenv/test"
 
 const report = await executeTestPlan({
-  keepRunning: false, // true would keep process alive and all browsers opened even when tests are done 
-  coverageEnabled: false, // collect code coverage while executing tests
+  rootDirectoryUrl: new URL("../", import.meta.url),
+  testPlan: {
+    "./src/**/*.test.html": {
+      chromium: {
+        runtime: chromium(),
+      },
+      firefox: {
+        runtime: firefox(),
+      },
+      webkit: {
+        runtime: webkit(),
+      },
+    },
+    "./src/**/*.test.mjs": {
+      node_worker: {
+        runtime: nodeWorkerThread(),
+      },
+      node_process: {
+        runtime: nodeChildProcess({
+          commandLineOptions: ["--no-warnings"],
+          env: { TEST: "1" },
+          importMap: {
+            imports: { foo: "./foo_mock.js" },
+          },
+        }),
+      },
+    },
+  },
+  webServer: {
+    origin: "http://localhost:3456",
+    rootDirectoryUrl: new URL("../src/", import.meta.url),
+    moduleUrl: new URL("./dev.mjs", import.meta.url),
+  },
+  keepRunning: true,
+  logShortForCompletedExecutions: true,
+  logMergeForCompletedExecutions: true,
+  coverageEnabled: true,
+  coverageConfig: {
+    "./src/**/*.js": true,
+    "./src/**/*.test.mjs": false,
+  },
 })
 report // contains many information about test executions
 ```
 
+| Parameter                      | Description                                                                                           |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| rootDirectoryUrl               | Url used to resolve relative urls in other parameters (like testPlan)                                 |
+| testPlan                       | Object listing the files to execute and configuring where they will be executed                       |
+| keepRunning                    | Boolean that can be used to keep browser/node process alive after all executions are done             |
+| logShortForCompletedExecutions | Boolean, when enabled completed execution logs will be shorter                                        |
+| logMergeForCompletedExecutions | Boolean, when enabled, as long as executions are completed, logs are overridden to shorten the output |
+| coverageEnabled                | Boolean controlling if code coverage will be collected while executing test files                     |
+| coverageConfig                 | Object describing the files that should be covered                                                    |
+| coverageReportHtml             | Boolean controlling if a code coverage report will be written as HTML files                           |
+| coverageReportHtmlDirectoryUrl | String or url where html files composing the code coverage report will be written                     |
+
+# 4.1 webServer
+
+| Parameter                  | Description                                                                                                       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| webServer.origin           | Url listened by the web server                                                                                    |
+| webServer.rootDirectoryUrl | Url leading to the root directory for the web server                                                              |
+| webServer.moduleUrl        | `executeTestPlan` does a dynamic import on `webServer.moduleUrl` if there is nothing listening `webServer.origin` |
+
 ## 4.2 chromium/firefox/webkit
 
-Params can be used to configure how the browser runtime is started
+chromium, firefox and webkit runtimes can be configured, they use the parameters listed in the table below:
 
-```js
-chromium({
-  headful: true // browser UI would be displayed while running tests
-})
-```
+| Parameter               | Description                                                                                                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| headful                 | browser UI would be displayed while running tests                                                                 |
+| playwrightLaunchOptions | Will be forwarded to playwright launch, see https://playwright.dev/docs/api/class-browsertype#browser-type-launch |
 
 ## 4.3 nodeWorkerThread/nodeChildProcess
 
-Params can be used to configure how node child process or node worker thread is started.
-Both runtime share the same arguments.
+nodeWorkerThread and nodeChildProcess can be configured, they use the parameters listed in the table below:
 
-```js
-import {
-  nodeWorkerThread,
-  nodeChildProcess
-} from "@jsenv/test"
-
-nodeWorkerThread({
-  commandLineOptions: [], // see https://nodejs.org/api/cli.html#options
-  env: null // will be written on process.env, see https://nodejs.org/api/child_process.html#child_processexeccommand-options-callback
-  importMap: null, // can be used to override import resolution (redirect to other files during test)
-})
-```
+| Parameter          | Description                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| commandLineOptions | Command line options for node, see https://nodejs.org/api/cli.html#options                                              |
+| env                | Becomes `process.env`, see "env" in https://nodejs.org/api/child_process.html#child_processexeccommand-options-callback |
+| importMap          | Can be used to override import resolution (redirect to other files during test)                                         |
 
 ## 4.4 Allocated time
 
@@ -291,10 +341,7 @@ If this duration is exceeded the browser tab (or node process/worker thread) is
 This duration can be configured as shown below:
 
 ```js
-import {
-  executeTestPlan,
-  nodeWorkerThread
-} from "@jsenv/test"
+import { executeTestPlan, nodeWorkerThread } from "@jsenv/test"
 
 await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
@@ -302,7 +349,7 @@ await executeTestPlan({
     "./tests/**/*.test.mjs": {
       node: {
         runtime: nodeWorkerThread(),
-        allocatedMs: 60_000
+        allocatedMs: 60_000,
       },
     },
   },
@@ -310,5 +357,3 @@ await executeTestPlan({
 ```
 
 ☝️ Code above changes the default allocated time to 60s.
-
-

package/dist/jsenv_test.js

@@ -3244,7 +3244,7 @@ const createExecutionLog = ({
   startMs,
   endMs
 }, {
-  completedExecutionLogAbbreviation,
+  logShortForCompletedExecutions,
   counters,
   logRuntime,
   logEachDuration,
@@ -3267,7 +3267,7 @@ const createExecutionLog = ({
     memoryHeap
   });
   let log;
-  if (completedExecutionLogAbbreviation && status === "completed") {
+  if (logShortForCompletedExecutions && status === "completed") {
     log = `${description}${summary}`;
   } else {
     const {
@@ -3300,7 +3300,7 @@ const createExecutionLog = ({
     wordWrap: false
   });
   if (endMs) {
-    if (completedExecutionLogAbbreviation) {
+    if (logShortForCompletedExecutions) {
       return `${log}\n`;
     }
     if (executionIndex === counters.total - 1) {
@@ -3608,8 +3608,8 @@ const executeSteps = async (executionSteps, {
   logTimeUsage,
   logMemoryHeapUsage,
   logFileRelativeUrl,
-  completedExecutionLogMerging,
-  completedExecutionLogAbbreviation,
+  logMergeForCompletedExecutions,
+  logShortForCompletedExecutions,
   rootDirectoryUrl,
   webServer,
   keepRunning,
@@ -3697,9 +3697,9 @@ const executeSteps = async (executionSteps, {
       coverageMethodForNodeJs,
       stopAfterAllSignal
     };
-    if (completedExecutionLogMerging && !process.stdout.isTTY) {
-      completedExecutionLogMerging = false;
-      logger.debug(`Force completedExecutionLogMerging to false because process.stdout.isTTY is false`);
+    if (logMergeForCompletedExecutions && !process.stdout.isTTY) {
+      logMergeForCompletedExecutions = false;
+      logger.debug(`Force logMergeForCompletedExecutions to false because process.stdout.isTTY is false`);
     }
     const debugLogsEnabled = logger.levels.debug;
     const executionLogsEnabled = logger.levels.info;
@@ -3834,7 +3834,7 @@ const executeSteps = async (executionSteps, {
         }
         if (executionLogsEnabled) {
           const log = createExecutionLog(afterExecutionInfo, {
-            completedExecutionLogAbbreviation,
+            logShortForCompletedExecutions,
             counters,
             logRuntime,
             logEachDuration,
@@ -3850,7 +3850,7 @@ const executeSteps = async (executionSteps, {
           executionLog.write(log);
           rawOutput += stripAnsi(log);
           const canOverwriteLog = canOverwriteLogGetter({
-            completedExecutionLogMerging,
+            logMergeForCompletedExecutions,
             executionResult
           });
           if (canOverwriteLog) {
@@ -3906,10 +3906,10 @@ const executeSteps = async (executionSteps, {
   }
 };
 const canOverwriteLogGetter = ({
-  completedExecutionLogMerging,
+  logMergeForCompletedExecutions,
   executionResult
 }) => {
-  if (!completedExecutionLogMerging) {
+  if (!logMergeForCompletedExecutions) {
     return false;
   }
   if (executionResult.status === "aborted") {
@@ -3974,8 +3974,8 @@ const executeInParallel = async ({
  * @param {string|url} testPlanParameters.rootDirectoryUrl Directory containing test files;
  * @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 {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
+ * @param {boolean} [testPlanParameters.logShortForCompletedExecutions=false] Abbreviate completed execution information to shorten terminal output
+ * @param {boolean} [testPlanParameters.logMergeForCompletedExecutions=false] Merge completed execution logs to shorten terminal output
  * @param {number} [testPlanParameters.maxExecutionsInParallel=1] Maximum amount of execution in parallel
  * @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
@@ -3996,8 +3996,8 @@ const executeTestPlan = async ({
   logTimeUsage = false,
   logMemoryHeapUsage = false,
   logFileRelativeUrl = ".jsenv/test_plan_debug.txt",
-  completedExecutionLogAbbreviation = false,
-  completedExecutionLogMerging = false,
+  logShortForCompletedExecutions = false,
+  logMergeForCompletedExecutions = true,
   rootDirectoryUrl,
   webServer,
   testPlan,
@@ -4196,8 +4196,8 @@ const executeTestPlan = async ({
     logTimeUsage,
     logMemoryHeapUsage,
     logFileRelativeUrl,
-    completedExecutionLogMerging,
-    completedExecutionLogAbbreviation,
+    logShortForCompletedExecutions,
+    logMergeForCompletedExecutions,
     rootDirectoryUrl,
     webServer,
     maxExecutionsInParallel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/test",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/execution/execute_steps.js

@@ -25,8 +25,8 @@ export const executeSteps = async (
     logTimeUsage,
     logMemoryHeapUsage,
     logFileRelativeUrl,
-    completedExecutionLogMerging,
-    completedExecutionLogAbbreviation,
+    logMergeForCompletedExecutions,
+    logShortForCompletedExecutions,
     rootDirectoryUrl,
     webServer,
 
@@ -124,10 +124,10 @@ export const executeSteps = async (
       stopAfterAllSignal,
     }
 
-    if (completedExecutionLogMerging && !process.stdout.isTTY) {
-      completedExecutionLogMerging = false
+    if (logMergeForCompletedExecutions && !process.stdout.isTTY) {
+      logMergeForCompletedExecutions = false
       logger.debug(
-        `Force completedExecutionLogMerging to false because process.stdout.isTTY is false`,
+        `Force logMergeForCompletedExecutions to false because process.stdout.isTTY is false`,
       )
     }
     const debugLogsEnabled = logger.levels.debug
@@ -273,7 +273,7 @@ export const executeSteps = async (
         }
         if (executionLogsEnabled) {
           const log = createExecutionLog(afterExecutionInfo, {
-            completedExecutionLogAbbreviation,
+            logShortForCompletedExecutions,
             counters,
             logRuntime,
             logEachDuration,
@@ -292,7 +292,7 @@ export const executeSteps = async (
           rawOutput += stripAnsi(log)
 
           const canOverwriteLog = canOverwriteLogGetter({
-            completedExecutionLogMerging,
+            logMergeForCompletedExecutions,
             executionResult,
           })
           if (canOverwriteLog) {
@@ -352,10 +352,10 @@ export const executeSteps = async (
 }
 
 const canOverwriteLogGetter = ({
-  completedExecutionLogMerging,
+  logMergeForCompletedExecutions,
   executionResult,
 }) => {
-  if (!completedExecutionLogMerging) {
+  if (!logMergeForCompletedExecutions) {
     return false
   }
   if (executionResult.status === "aborted") {

package/src/execution/execute_test_plan.js

@@ -21,8 +21,8 @@ import { executeSteps } from "./execute_steps.js"
  * @param {string|url} testPlanParameters.rootDirectoryUrl Directory containing test files;
  * @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 {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
+ * @param {boolean} [testPlanParameters.logShortForCompletedExecutions=false] Abbreviate completed execution information to shorten terminal output
+ * @param {boolean} [testPlanParameters.logMergeForCompletedExecutions=false] Merge completed execution logs to shorten terminal output
  * @param {number} [testPlanParameters.maxExecutionsInParallel=1] Maximum amount of execution in parallel
  * @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
@@ -43,8 +43,8 @@ export const executeTestPlan = async ({
   logTimeUsage = false,
   logMemoryHeapUsage = false,
   logFileRelativeUrl = ".jsenv/test_plan_debug.txt",
-  completedExecutionLogAbbreviation = false,
-  completedExecutionLogMerging = false,
+  logShortForCompletedExecutions = false,
+  logMergeForCompletedExecutions = true,
 
   rootDirectoryUrl,
   webServer,
@@ -293,8 +293,8 @@ export const executeTestPlan = async ({
     logTimeUsage,
     logMemoryHeapUsage,
     logFileRelativeUrl,
-    completedExecutionLogMerging,
-    completedExecutionLogAbbreviation,
+    logShortForCompletedExecutions,
+    logMergeForCompletedExecutions,
     rootDirectoryUrl,
     webServer,
 

package/src/execution/logs_file_execution.js

@@ -21,7 +21,7 @@ export const createExecutionLog = (
     endMs,
   },
   {
-    completedExecutionLogAbbreviation,
+    logShortForCompletedExecutions,
     counters,
     logRuntime,
     logEachDuration,
@@ -43,7 +43,7 @@ export const createExecutionLog = (
     memoryHeap,
   })
   let log
-  if (completedExecutionLogAbbreviation && status === "completed") {
+  if (logShortForCompletedExecutions && status === "completed") {
     log = `${description}${summary}`
   } else {
     const { consoleCalls = [], errors = [] } = executionResult
@@ -75,7 +75,7 @@ export const createExecutionLog = (
     wordWrap: false,
   })
   if (endMs) {
-    if (completedExecutionLogAbbreviation) {
+    if (logShortForCompletedExecutions) {
       return `${log}\n`
     }
     if (executionIndex === counters.total - 1) {