@jsenv/test 1.0.1 → 1.0.2

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,80 @@ 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:
 
-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.
+```console
+node ./scripts/test.mjs
+```
+
+### 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,71 +148,55 @@ 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"
 
-await executeTestPlan({
-  rootDirectoryUrl: new URL("../", import.meta.url),
-  testPlan: {
-    "./src/**/*.test.html": {
-      chromium: { runtime: chromium() },
-      firefox: { runtime: firefox() },
-      webkit: { runtime: webkit() },
-    },
-  },
-  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}`)
+}
 ```
 
-## 2.3 Executing tests on Node.js
+## 2.2 Executing the test file
 
-With Node.js there is no server involved so test files can be anywhere and only rootDirectoryUrl and testPlan parameters are **required**.
+*scripts/test.mjs*
 
 ```js
 import { executeTestPlan, nodeWorkerThread } from "@jsenv/test"
@@ -166,26 +205,105 @@ await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
   testPlan: {
     "./tests/**/*.test.mjs": {
-      node: { runtime: nodeWorkerThread() },
+      node: {
+        runtime: nodeWorkerThread()
+      },
     },
   },
 })
 ```
 
-## 2.4 Allocated time
+Command to install dependencies:
+
+```console
+npm i --save-dev @jsenv/test
+```
+
+Command to execute tests:
+
+```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
+
+## 4.1 executeTestPlan
+
+```js
+import { executeTestPlan } 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
+})
+report // contains many information about test executions
+```
+
+## 4.2 chromium/firefox/webkit
+
+Params can be used to configure how the browser runtime is started
+
+```js
+chromium({
+  headful: true // browser UI would be displayed while running tests
+})
+```
+
+## 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.
+
+```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)
+})
+```
+
+## 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
-import { executeTestPlan, nodeWorkerThread } from "@jsenv/test"
+import {
+  executeTestPlan,
+  nodeWorkerThread
+} from "@jsenv/test"
 
 await executeTestPlan({
   rootDirectoryUrl: new URL("../", import.meta.url),
   testPlan: {
     "./tests/**/*.test.mjs": {
-      node: { runtime: nodeWorkerThread(), allocatedMs: 60_000 },
+      node: {
+        runtime: nodeWorkerThread(),
+        allocatedMs: 60_000
+      },
     },
   },
 })
@@ -193,8 +311,4 @@ await executeTestPlan({
 
 ☝️ Code above changes the default allocated time to 60s.
 
-# 3. Installation
 
-```console
-npm install --save-dev @jsenv/test
-```

package/dist/jsenv_test.js

@@ -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.2",
   "license": "MIT",
   "repository": {
     "type": "git",

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) {