@jsenv/test 1.0.1 → 1.0.3

package/README.md

@@ -3,19 +3,45 @@
 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. Example
+# 1. Writing tests on web browsers
 
-Let's see how to write tests for the following code 
+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:
 
 ```js
-// add.js
 export const add = (a, b) => a + b
 ```
 
-## 1.1 Testing on web browser
+The demonstration uses the following file structure:
+
+<pre>
+project/
+  src/
+    <strong>add.js</strong>
+    index.html
+  package.json
+</pre>
+
+At the end of the demo, the file structure will be like this:
+
+<pre>
+project/
+  scripts/
+    <strong>dev.mjs</strong>
+    <strong>test.mjs</strong>
+  src/
+    add.js
+    <strong>add.test.html</strong>
+    index.html
+  package.json
+</pre>
+
+## 1.1 Writing the test file
+
+_src/add.test.html_
 
 ```html
-<!-- add.test.html -->
 <!DOCTYPE html>
 <html>
   <head>
@@ -38,51 +64,75 @@ export const add = (a, b) => a + b
 </html>
 ```
 
-## 1.2 Testing on Node.js
+## 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.
 
 ```js
-// add.test.mjs
-import { add } from "./add.js"
+import { startDevServer } from "@jsenv/core"
 
-const actual = add(1, 2)
-const expected = 3
-if (actual !== expected) {
-  throw new Error(`add(1,2) should return 3, got ${actual}`)
-}
+await startDevServer({
+  sourceDirectoryUrl: new URL("../src/", import.meta.url),
+  port: 3456,
+})
 ```
 
-## 1.3 Assertion library
+_scripts/test.mjs_: will start a web browser and use it to execute all test files.
 
-To keep example very basic "assert" block do not use an assertion library.  
-In pratice test likely needs one. The diff below showns how the "assert" block can be written using [@jsenv/assert](../assert). Note that any other assertion library would work.
+```js
+import { executeTestPlan, chromium } from "@jsenv/test"
 
-```diff
-+ import { assert } from "@jsenv/assert"
-import { add } from "./add.js"
+await executeTestPlan({
+  rootDirectoryUrl: new URL("../", import.meta.url),
+  testPlan: {
+    "./src/**/*.test.html": {
+      chromium: {
+        runtime: chromium(),
+      },
+    },
+  },
+  webServer: {
+    origin: "http://localhost:3456",
+    rootDirectoryUrl: new URL("../src/", import.meta.url),
+    moduleUrl: new URL("./dev.mjs", import.meta.url),
+  },
+})
+```
 
-const actual = add(1, 2)
-const expected = 3
-- if (actual !== expected) {
--   throw new Error(`add(1,2) should return 3, got ${actual}`)
-- }
-+ assert({ actual, expected })
+Command to install dependencies:
+
+```console
+npm i --save-dev @jsenv/core
+npm i --save-dev @jsenv/test
+npm i --save-dev playwright
 ```
 
-# 2. JavaScript API
+☝️ Playwright is used by `@jsenv/test` to start a web browser, see [playwright website](https://github.com/microsoft/playwright)<sup>↗</sup>.
 
-## 2.1 Executing tests on browsers
+Command to execute tests:
+
+```console
+node ./scripts/test.mjs
+```
 
-Code below execute all files endings by `".test.html"` on chromium.  
-[playwright](https://github.com/microsoft/playwright)<sup>↗</sup> is used to start a headless chromium.
+### 1.3 Executing on more browsers
 
 ```js
-import { executeTestPlan, chromium } from "@jsenv/test"
+import { executeTestPlan, chromium, firefox, webkit } from "@jsenv/test"
 
 await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
   testPlan: {
-    "./**/*.test.html": {
-      chromium: { runtime: chromium() },
+    "./src/**/*.test.html": {
+      chromium: {
+        runtime: chromium(),
+      },
+      firefox: {
+        runtime: firefox(),
+      },
+      webkit: {
+        runtime: webkit(),
+      },
     },
   },
   webServer: {
@@ -93,89 +143,201 @@ await executeTestPlan({
 })
 ```
 
-When executing tests on browsers there is a few things to ensure:
+# 2. Writing tests on Node.js
 
-1. `"playwright"` must be in package.json dependencies (`npm i playwright --save-dev`)
+This section demonstrates how to write a test that will be executed in Node.js.
 
-2. `webServer` parameter must be used:
+The function that will be tested is inside "add.js" file:
 
-| Param                      | Description                                       | Example                                 |
-| -------------------------- | ------------------------------------------------- | --------------------------------------- |
-| webServer.origin           | url listened by a web server                      | `"http://localhost:3456"`               |
-| webServer.rootDirectoryUrl | url of directory served by the web server         | `new URL("../src/", import.meta.url)`   |
-| webServer.moduleUrl        | url of the file responsible to start a web server | `new URL("./dev.mjs", import.meta.url)` |
+```js
+export const add = (a, b) => a + b
+```
 
-Test files must be inside `webServer.rootDirectoryUrl`:
+The demonstration uses the following file structure:
 
 <pre>
 project/
   src/
-    bar.js
-    <strong>bar.test.html</strong>
-    foo.js
-    <strong>foo.test.html</strong>
-    index.html
+    <strong>add.js</strong>
+  package.json
 </pre>
 
-It's also possible to create a directory dedicated to tests
+At the end of the demo, the file structure will be like this:
 
 <pre>
 project/
+  scripts/
+    <strong>test.mjs</strong>
   src/
-    tests/
-       <strong>bar.test.html</strong>
-       <strong>foo.test.html</strong>
-    bar.js
-    foo.js
-    index.html
+    add.js
+  tests/
+    <strong>add.test.mjs</strong>
+  package.json
 </pre>
 
-This way the web server can serve test files alongside with source files.  
-It's best to configure `webServer` to lead to jsenv dev server but it does not have to; Any server serving files from a directory can be used.
+## 2.1 Writing the test file
 
-## 2.2 Executing on more browsers
+_add.test.mjs_
 
 ```js
-import { executeTestPlan, chromium, firefox, webkit } from "@jsenv/test"
+import { add } from "./add.js"
+
+const actual = add(1, 2)
+const expected = 3
+if (actual !== expected) {
+  throw new Error(`add(1,2) should return 3, got ${actual}`)
+}
+```
+
+## 2.2 Executing the test file
+
+_scripts/test.mjs_
+
+```js
+import { executeTestPlan, nodeWorkerThread } from "@jsenv/test"
 
 await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
   testPlan: {
-    "./src/**/*.test.html": {
-      chromium: { runtime: chromium() },
-      firefox: { runtime: firefox() },
-      webkit: { runtime: webkit() },
+    "./tests/**/*.test.mjs": {
+      node: {
+        runtime: nodeWorkerThread(),
+      },
     },
   },
-  webServer: {
-    origin: "http://localhost:3456",
-    rootDirectoryUrl: new URL("../src/", import.meta.url),
-    moduleUrl: new URL("./dev.mjs", import.meta.url),
-  },
 })
 ```
 
-## 2.3 Executing tests on Node.js
+Command to install dependencies:
 
-With Node.js there is no server involved so test files can be anywhere and only rootDirectoryUrl and testPlan parameters are **required**.
+```console
+npm i --save-dev @jsenv/test
+```
 
-```js
-import { executeTestPlan, nodeWorkerThread } from "@jsenv/test"
+Command to execute tests:
 
-await executeTestPlan({
+```console
+node ./scripts/test.mjs
+```
+
+# 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.
+
+```diff
++ import { assert } from "@jsenv/assert"
+import { add } from "./add.js"
+
+const actual = add(1, 2)
+const expected = 3
+- if (actual !== expected) {
+-   throw new Error(`add(1,2) should return 3, got ${actual}`)
+- }
++ assert({ actual, expected })
+```
+
+# 4. API
+
+```js
+import {
+  executeTestPlan,
+  chromium,
+  firefox,
+  webkit,
+  nodeWorkerThread,
+  nodeChildProcess,
+} from "@jsenv/test"
+
+const report = await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
   testPlan: {
-    "./tests/**/*.test.mjs": {
-      node: { runtime: nodeWorkerThread() },
+    "./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
 ```
 
-## 2.4 Allocated time
+| 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
+
+chromium, firefox and webkit runtimes can be configured, they use the parameters listed in the table below:
+
+| 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
+
+nodeWorkerThread and nodeChildProcess can be configured, they use the parameters listed in the table below:
+
+| 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
 
 Each file is given 30s to execute.
-If this duration is exceeded the browser tab (or node process/worker thread) is closed and executiong is considered as failed.
+If this duration is exceeded the browser tab (or node process/worker thread) is closed and execution is considered as failed.
 This duration can be configured as shown below:
 
 ```js
@@ -185,16 +347,13 @@ await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
   testPlan: {
     "./tests/**/*.test.mjs": {
-      node: { runtime: nodeWorkerThread(), allocatedMs: 60_000 },
+      node: {
+        runtime: nodeWorkerThread(),
+        allocatedMs: 60_000,
+      },
     },
   },
 })
 ```
 
 ☝️ Code above changes the default allocated time to 60s.
-
-# 3. Installation
-
-```console
-npm install --save-dev @jsenv/test
-```

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,
@@ -4505,7 +4505,7 @@ const createRuntimeUsingPlaywright = ({
           stopOnExit: true,
           playwrightLaunchOptions: {
             ...playwrightLaunchOptions,
-            headless: !headful
+            headless: headful === undefined ? !keepRunning : !headful
           }
         });
         if (browser._initializer.version) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/test",
-  "version": "1.0.1",
+  "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) {

package/src/runtime_browsers/using_playwright.js

@@ -83,7 +83,7 @@ export const createRuntimeUsingPlaywright = ({
           stopOnExit: true,
           playwrightLaunchOptions: {
             ...playwrightLaunchOptions,
-            headless: !headful,
+            headless: headful === undefined ? !keepRunning : !headful,
           },
         })
         if (browser._initializer.version) {