testem 3.20.0 → 3.20.1

package/README.md

@@ -1,53 +1,50 @@
 Got Scripts? Test’em!
 =================
 
-[![Build Status](https://github.com/testem/testem/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/testem/testem/actions/workflows/ci.yml?query=branch%3Amaster) [![npm version](https://badge.fury.io/js/testem.svg)](http://badge.fury.io/js/testem)
+[![Build Status](https://github.com/testem/testem/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/testem/testem/actions/workflows/ci.yml?query=branch%3Amaster) [![npm version](https://badge.fury.io/js/testem.svg)](https://badge.fury.io/js/testem)
 
-Testem is a **JavaScript test runner** that runs your tests in **real desktop browsers**—Chrome, Firefox, Safari, Edge, and others you launch—so your specs execute in the same browser engines and DOM your users get, not a pretend environment. It also runs tests in **[Node](http://nodejs.org/)**, [PhantomJS](http://phantomjs.org/), or any launcher you configure. It is **framework-agnostic** and aimed at **any kind of tests** you want to run: unit, integration, end-to-end style suites, or custom setups—you pick the style; Testem wires it to the browser or process.
+Testem is a **JavaScript test runner** that runs your tests in **real desktop browsers**—Chrome, Firefox, Safari, Edge, and others you launch—so your specs execute in the same browser engines and DOM your users get, not a pretend environment. It also runs tests in **[Node](https://nodejs.org/)**, **Chrome** (including **headless** runs via `browser_args`, e.g. `--headless`), or any launcher you configure. It is **framework-agnostic** and aimed at **any kind of tests** you want to run: unit, integration, end-to-end style suites, or custom setups—you pick the style; Testem wires it to the browser or process.
 
-Unit testing in Javascript can be tedious and painful, but Testem makes it so easy that you will actually *want* to write tests.
+Unit testing in JavaScript can be tedious and painful, but Testem makes it so easy that you will actually *want* to write tests.
 
 Features
 --------
 
 * Test-framework agnostic — designed for **any kind of tests** that fit your project (unit, integration, custom runners, etc.), not a single prescribed style. Support for
-    - [Jasmine](http://jasmine.github.io/)
-    - [QUnit](http://qunitjs.com/)
-    - [Mocha](http://mochajs.org/)
+    - [Jasmine](https://jasmine.github.io/)
+    - [QUnit](https://qunitjs.com/)
+    - [Mocha](https://mochajs.org/)
     - Others, through custom test framework adapters.
-* Run tests in **all** major **real** browsers (your tests load and run in the actual browser) as well as [Node](http://nodejs.org) and [PhantomJS](http://phantomjs.org/)
+* Run tests in **all** major **real** browsers (your tests load and run in the actual browser) as well as [Node](https://nodejs.org) and **Chrome** (use `browser_args` with `--headless` for headless runs—see `docs/browser_args.md`)
 * Two distinct use-cases:
     - Test-Driven-Development(TDD) — designed to streamline the TDD workflow
-    - Continuous Integration(CI) — designed to work well with popular CI servers like Jenkins or Teamcity
+    - Continuous Integration(CI) — designed to work well with **GitHub Actions** and other CI systems, including Jenkins and TeamCity
 * Cross-platform support
-    - OS X
+    - macOS
     - Windows
     - Linux
 * Preprocessor support
-    - CoffeeScript
+    - Babel
+    - TypeScript
     - Browserify
-    - JSHint/JSLint
+    - ESLint/JSHint/JSLint
+    - CoffeeScript
     - everything else
 
-**Internet Explorer** and **PhantomJS** are still supported as launchers, but we document them as **deprecated** targets: keeping them viable through transpilation and polyfills is likely to get more difficult over time, so prefer evergreen browsers or Node for new projects. See the [configuration reference](docs/config_file.md) for how we categorize browsers.
-
-Screencasts
------------
-
-* Watch this **[introductory screencast (11:39)](http://www.youtube.com/watch?v=-1mjv4yk5JM)** to see it in action! This one demonstrates the TDD workflow.
-* [Launchers (12:10)](http://www.youtube.com/watch?v=Up0lVjWk9Rk) — more detail about launchers: how to specify what to auto-launch and how to configure one yourself to run tests in **Node**.
-* [Continuous Integration (CI) Mode (4:24)](http://www.youtube.com/watch?v=Js16Cj80HKY) — details about how CI mode works.
-* [Making JavaScript Testing Fun With Testem (22:53)](http://net.tutsplus.com/tutorials/javascript-ajax/make-javascript-testing-fun-with-testem/) — a thorough screencast by NetTuts+'s Jeffery Way covering the basics, Jasmine, Mocha/Chai, CoffeeScript and more!
-
 Installation
 ------------
-You need [Node](http://nodejs.org/) version 0.10+ or iojs installed on your system. Node is extremely easy to install and has a small footprint, and is really awesome otherwise too, so [just do it](http://nodejs.org/).
+Testem needs a supported **[Node.js](https://nodejs.org/)** runtime. The required range is defined in [`package.json`](package.json) under `engines` (currently **^20.19.0**, **^22.12.0**, or **>=24.0.0**).
+
+**Recommended:** install Testem **both** as a **dev dependency** (so your project pins a version) **and** **globally** (so the `testem` command is always available on your `PATH`):
 
-Once you have Node installed:
+```bash
+npm install testem --save-dev
+npm install testem -g
+```
 
-    npm install testem -g
+When you run the global `testem` inside a project directory that has a local `testem` install, the CLI **automatically re-runs the local copy** so the version stays in sync with `package.json`. Set **`TESTEM_USE_GLOBAL=1`** if you ever need to force the global binary only.
 
-This will install the `testem` executable globally on your system.
+This README uses the `testem` command in examples; add it to npm scripts or invoke it as `testem` from a shell after the installs above.
 
 Usage
 -----
@@ -146,6 +143,8 @@ To use Testem for continuous integration
 
     testem ci
 
+**GitHub Actions** is a common way to run Testem in CI: add a workflow job that runs `testem ci` (often with the **Headless Chrome** or **Chromium** launcher). This project’s own workflow is in [`.github/workflows/ci.yml`](https://github.com/testem/testem/blob/master/.github/workflows/ci.yml).
+
 In CI mode, Testem runs your tests on all the browsers that are available on the system one after another.
 
 You can run multiple browsers in parallel in CI mode by specifying the `--parallel` (or `-P`) option to be the number of concurrent running browsers.
@@ -166,11 +165,12 @@ Will print them out. The output might look like
     Safari
     Safari Technology Preview
     Opera
-    PhantomJS
 
-When you run `testem ci` to run tests, it outputs the results in the [TAP](http://testanything.org/) format by default, which looks like
+Your machine may list other launchers too. For **headless** runs, prefer **Chrome** with `browser_args` (for example `--headless`) rather than the deprecated PhantomJS launcher—see `docs/browser_args.md`.
+
+When you run `testem ci` to run tests, it outputs the results in the [TAP](https://testanything.org/) format by default, which looks like
 
-    ok 1 Chrome 16.0 - hello should say hello.
+    ok 1 Chrome 130.0 - hello should say hello.
 
     1..1
     # tests 1
@@ -178,9 +178,9 @@ When you run `testem ci` to run tests, it outputs the results in the [TAP](http:
 
     # ok
 
-TAP is a human-readable and language-agnostic test result format. TAP plugins exist for popular CI servers
+TAP is a human-readable and language-agnostic test result format. On **GitHub Actions**, a typical pattern is a step that runs `testem ci` and relies on the exit code to fail the job (see [`.github/workflows/ci.yml`](https://github.com/testem/testem/blob/master/.github/workflows/ci.yml) in this repository). For **Jenkins** and **TeamCity**, use TAP plugins:
 
-* [Jenkins TAP plugin](https://wiki.jenkins-ci.org/display/JENKINS/TAP+Plugin) - I've added [detailed instructions](https://github.com/testem/testem/blob/master/docs/use_with_jenkins.md) for setup with Jenkins.
+* [Jenkins TAP plugin](https://plugins.jenkins.io/tap/) - I've added [detailed instructions](https://github.com/testem/testem/blob/master/docs/use_with_jenkins.md) for setup with Jenkins.
 * [TeamCity TAP plugin](https://github.com/pavelsher/teamcity-tap-parser)
 
 ## TAP Options
@@ -225,13 +225,14 @@ Testem has other test reporters besides TAP: `dot`, `xunit` and `teamcity`. You
 
 You can also [add your own reporter](docs/custom_reporter.md).
 
-### Example xunit reporter output
+<details>
+<summary>Example <code>xunit</code> reporter output</summary>
 
 Note that the real output is not pretty printed.
 ```xml
-<testsuite name="Testem Tests" tests="4" failures="1" timestamp="Wed Apr 01 2015 11:56:20 GMT+0100 (GMT Daylight Time)" time="9">
-  <testcase classname="PhantomJS 1.9" name="myFunc returns true when input is valid" time="0"/>
-  <testcase classname="PhantomJS 1.9" name="myFunc returns false when user tickles it" time="0"/>
+<testsuite name="Testem Tests" tests="4" failures="1" timestamp="2026-04-25T10:00:00.000Z" time="9">
+  <testcase classname="Firefox 128" name="myFunc returns true when input is valid" time="0"/>
+  <testcase classname="Firefox 128" name="myFunc returns false when user tickles it" time="0"/>
   <testcase classname="Chrome" name="myFunc returns true when input is valid" time="0"/>
   <testcase classname="Chrome" name="myFunc returns false when user tickles it" time="0">
     <failure name="myFunc returns false when user tickles it" message="function is not ticklish">
@@ -243,17 +244,24 @@ Note that the real output is not pretty printed.
 </testsuite>
 ```
 
-### Example teamcity reporter output
+</details>
+
+<details>
+<summary>Example <code>teamcity</code> reporter output</summary>
 
-    ##teamcity[testStarted name='PhantomJS 1.9 - hello should say hello']
-    ##teamcity[testFinished name='PhantomJS 1.9 - hello should say hello']
-    ##teamcity[testStarted name='PhantomJS 1.9 - hello should say hello to person']
-    ##teamcity[testFinished name='PhantomJS 1.9 - hello should say hello to person']
-    ##teamcity[testStarted name='PhantomJS 1.9 - goodbye should say goodbye']
-    ##teamcity[testFailed name='PhantomJS 1.9 - goodbye should say goodbye' message='expected |'hello world|' to equal |'goodbye world|'' details='AssertionError: expected |'hello world|' to equal |'goodbye world|'|n    at http://localhost:7357/testem/chai.js:873|n    at assertEqual (http://localhost:7357/testem/chai.js:1386)|n    at http://localhost:7357/testem/chai.js:3627|n    at http://localhost:7357/hello_spec.js:14|n    at callFn (http://localhost:7357/testem/mocha.js:4338)|n    at http://localhost:7357/testem/mocha.js:4331|n    at http://localhost:7357/testem/mocha.js:4728|n    at http://localhost:7357/testem/mocha.js:4819|n    at next (http://localhost:7357/testem/mocha.js:4653)|n    at http://localhost:7357/testem/mocha.js:4663|n    at next (http://localhost:7357/testem/mocha.js:4601)|n    at http://localhost:7357/testem/mocha.js:4630|n    at timeslice (http://localhost:7357/testem/mocha.js:5761)']
-    ##teamcity[testFinished name='PhantomJS 1.9 - goodbye should say goodbye']
+```text
+##teamcity[testStarted name='Firefox 128 - hello should say hello']
+##teamcity[testFinished name='Firefox 128 - hello should say hello']
+##teamcity[testStarted name='Firefox 128 - hello should say hello to person']
+##teamcity[testFinished name='Firefox 128 - hello should say hello to person']
+##teamcity[testStarted name='Firefox 128 - goodbye should say goodbye']
+##teamcity[testFailed name='Firefox 128 - goodbye should say goodbye' message='expected |'hello world|' to equal |'goodbye world|'' details='AssertionError: expected |'hello world|' to equal |'goodbye world|'|n    at http://localhost:7357/testem/chai.js:873|n    at assertEqual (http://localhost:7357/testem/chai.js:1386)|n    at http://localhost:7357/testem/chai.js:3627|n    at http://localhost:7357/hello_spec.js:14|n    at callFn (http://localhost:7357/testem/mocha.js:4338)|n    at http://localhost:7357/testem/mocha.js:4331|n    at http://localhost:7357/testem/mocha.js:4728|n    at http://localhost:7357/testem/mocha.js:4819|n    at next (http://localhost:7357/testem/mocha.js:4653)|n    at http://localhost:7357/testem/mocha.js:4663|n    at next (http://localhost:7357/testem/mocha.js:4601)|n    at http://localhost:7357/testem/mocha.js:4630|n    at timeslice (http://localhost:7357/testem/mocha.js:5761)']
+##teamcity[testFinished name='Firefox 128 - goodbye should say goodbye']
 
-    ##teamcity[testSuiteFinished name='mocha.suite' duration='11091']
+##teamcity[testSuiteFinished name='mocha.suite' duration='11091']
+```
+
+</details>
 
 ### Command line options
 
@@ -264,9 +272,9 @@ To see all command line options for CI
 Configuration File
 ------------------
 
-For the simplest JavaScript projects, the TDD workflow described above will work fine. There are times when you want
-to structure your source files into separate directories, or want to have finer control over what files to include.
-This calls for the `testem.json` configuration file (you can also alternatively use the YAML format with a `testem.yml` file). It looks like
+For the simplest JavaScript projects, the TDD workflow described above will work fine. There are times when you want to structure your source files into separate directories, or want to have finer control over what files to include.
+
+This calls for the `testem.json` configuration file (you can also alternatively use the YAML format with a `testem.yml` file or return json from a javascript file `testem.js`). It looks like
 
 ```json
 {
@@ -334,10 +342,10 @@ Or if you are using require.js or another loader, just make sure you load `/test
 
 ### Dynamic Substitution
 
-To enable dynamic substitutions within the Javascript files in your custom test page, you must
+To enable dynamic substitutions within the JavaScript files in your custom test page, you must
 
 1. name your test page using `.mustache` as the extension
-2. use `{{#serve_files}}` to loop over the set of Javascript files to be served, and then reference its `src` property to access their path (or `{{#css_files}}` for stylesheets)
+2. use `{{#serve_files}}` to loop over the set of JavaScript files to be served, and then reference its `src` property to access their path (or `{{#css_files}}` for stylesheets)
 
 Example:
 
@@ -391,14 +399,14 @@ You can add your own custom paths to browser binaries by including `browser_path
 
 ```javascript
 "browser_paths": {
-  "Chromium": "./node_modules/puppeteer/.local-chromium/mac-549031/chrome-mac/Chromium.app/Contents/MacOS/Chromium"
+  "Chromium": "./path/to/chromium"
 }
 "browser_exes": {
   "Chromium": "chrome-custom-binary"
 }
 ```
 
-Adding a browser_path for a browser will override all default places for testem to look for the browser. So if the browser doesn't exist at the path you provided, you will get failures.
+Set `Chromium` to a real browser binary path, for example the Chromium or Chrome under your Puppeteer install (the exact `path/to/chromium` depends on your platform and Puppeteer version). Adding a browser_path for a browser will override all default places for testem to look for the browser. So if the browser doesn't exist at the path you provided, you will get failures.
 
 Customizing Browser Arguments
 -----------------------------
@@ -435,7 +443,7 @@ When you run `testem`, it will auto-launch the mocha process based on the specif
 Processes with TAP Output
 -------------------------
 
-If your process outputs test results in [TAP](http://en.wikipedia.org/wiki/Test_Anything_Protocol) format, you can tell that to testem via the `protocol` property. For example
+If your process outputs test results in [TAP](https://en.wikipedia.org/wiki/Test_Anything_Protocol) format, you can tell that to testem via the `protocol` property. For example
 
 ```javascript
 "launchers": {
@@ -448,61 +456,38 @@ If your process outputs test results in [TAP](http://en.wikipedia.org/wiki/Test_
 
 When this is done, Testem will read in the process's stdout and parse it as TAP, and then display the test results in Testem's normal format. It will also hide the process's stdout output from the console log panel, although it will still display the stderr.
 
-PhantomJS
----------
+Headless Chrome
+---------------
 
-PhantomJS is a Webkit-based headless browser. It's fast and it's awesome! Testem will pick it up if you have [PhantomJS](http://www.phantomjs.org/) installed in your system and the `phantomjs` executable is in your path. Run
+Testem ships a **Headless Chrome** launcher that runs [Google Chrome](https://www.google.com/chrome/) (or Chromium where that is the detected binary) with **`--headless`**, **`--disable-gpu`**, and other defaults suitable for CI and unattended runs. You need Chrome installed; run
 
     testem launchers
 
-And verify that it's in the list.
-
-If you want to debug tests in PhantomJS, include the `phantomjs_debug_port` option in your testem configuration, referencing an available port number.  Once testem has started PhantomJS, navigate (with a traditional browser) to http://localhost:<port> and attach to one of PhantomJS's browser tabs (probably the second one in the list).  `debugger` statements will now break in the debugging console.
-
-If you want to use any of the [PhantomJS command line options](http://phantomjs.org/api/command-line.html), include the `phantomjs_args` option in your testem configuration. For example:
-
-```javascript
-"phantomjs_args": [
-  "--ignore-ssl-errors=true"
-]
-```
-
-You can also customize the phantomjs launcher file by specifying the `phantomjs_launch_script` option.
-In this launcher you can change options like the `viewPortSize`. See `assets/phantom.js` for the default launcher.
-
-Preprocessors (CoffeeScript, LESS, Sass, Browserify, etc)
----------------------------------------------------------
-
-If you need to run a preprocessor (or indeed any shell command before the start of the tests) use the `before_tests` option, such as
-
-    "before_tests": "coffee -c *.coffee"
+and confirm **Headless Chrome** appears.
 
-And Testem will run it before each test run. Point **`src_files`** at the sources you want
-watched (see **File watching** under Development Mode above).
+Select it like any other launcher, for example:
 
-```javascript
-"src_files": [
-  "*.coffee"
-]
+```json
+{
+  "launch_in_ci": ["Headless Chrome"]
+}
 ```
 
-Since you want to be serving the `.js` files that are generated and not the `.coffee` files, you want to specify the `serve_files` option to tell it that
+To add or override flags, use **`browser_args`** (see [`docs/browser_args.md`](docs/browser_args.md)). Testem merges these with the built-in headless arguments—for example a fixed remote-debugging port for attaching DevTools:
 
-```javascript
-"serve_files": [
-  "*.js"
-]
+```json
+{
+  "browser_args": {
+    "Headless Chrome": ["--remote-debugging-port=9222"]
+  }
+}
 ```
 
-Testem will throw up a big ol' error dialog if the preprocessor command exits with an error code, so code checkers like jshint can be used here as well.
+**Remote debugging:** By default the headless launcher passes **`--remote-debugging-port=0`**, so Chrome chooses a random port—set a **fixed** port in `browser_args` (as in the example above) so you can connect reliably. With Testem running, open a regular Chrome window to **`chrome://inspect`**, use **Configure…** under “Discover network targets” to add **`localhost:9222`** (or whatever port you set), find your test page under **Remote Target**, and click **inspect**. You can also open **`http://localhost:9222`** and follow the links to a target page. **`debugger`** statements and breakpoints work in the DevTools **Sources** panel.
 
-If you need to run a command after your tests have completed (such as removing compiled `.js` files), use the `after_tests` option.
+**Headless Chrome Beta** is available when the Chrome Beta channel is installed. For legacy **PhantomJS**-specific options (`phantomjs_args`, `phantomjs_debug_port`, etc.), see [`docs/config_file.md`](docs/config_file.md).
 
-```javascript
-"after_tests": "rm *.js"
-```
-
-If you would prefer simply to clean up when Testem exits, you can use the `on_exit` option.
+**Internet Explorer** and the legacy **PhantomJS** launcher are still available, but we document them as **deprecated** targets: keeping them viable through transpilation and polyfills is likely to get more difficult over time, so prefer evergreen browsers, **Chrome** with `--headless` for headless automation, or Node for new projects. See the [configuration reference](docs/config_file.md) for how we categorize browsers.
 
 Running browser code after tests complete
 -------------
@@ -540,7 +525,7 @@ Sometimes you may want to re-map a URL to a different directory on the file syst
     + public
       + tests.html
 
-Let's say you want to serve `tests.html` at the top level url `/tests.html`, all the Javascripts under `/js` and all the css under `/css`. You can use the "routes" option to do that
+Let's say you want to serve `tests.html` at the top level url `/tests.html`, all the JavaScript files under `/js` and all the css under `/css`. You can use the "routes" option to do that
 
 ```javascript
 "routes": {
@@ -566,7 +551,7 @@ And then make sure you include the adapter code in your test suite and you are r
 Native notifications
 --------------------------------
 
-If you'd prefer not to be looking at the terminal while developing, you can enable native notifications (e.g. notification center, growl) using the `-g` option.
+If you'd prefer not to be looking at the terminal while developing, you can enable native notifications (e.g. Notification Center on macOS) using the `-g` option.
 
 API Proxy
 --------------------------------
@@ -591,77 +576,110 @@ Simply add a `proxies` section to the `testem.json` configuration file.
 ```
 
 This functionality is implemented as a *transparent proxy*, hence a request to
-`http://localhost:7357/api/posts.json` will be proxied to `http://localhost:4200/api/posts.json` without removing the `/api` prefix. Setting the `secure` option to `false` as in the above `/xmlapi` configuration block will ignore TLS certificate validation and allow tests to successfully reach that URL even if testem was launched over HTTP. Other available options can be found here: https://github.com/nodejitsu/node-http-proxy#options
+`http://localhost:7357/api/posts.json` will be proxied to `http://localhost:4200/api/posts.json` without removing the `/api` prefix. Setting the `secure` option to `false` as in the above `/xmlapi` configuration block will ignore TLS certificate validation and allow tests to successfully reach that URL even if testem was launched over HTTP. Other available options can be found here: https://github.com/http-party/node-http-proxy#options
 
 To limit the functionality to only certain content types, use "onlyContentTypes".
 
+Preprocessors (Babel, TypeScript, LESS, Sass, Browserify, CoffeeScript, etc)
+---------------------------------------------------------
+
+If you need to run a preprocessor (or indeed any shell command before the start of the tests) use the `before_tests` option, such as
+
+    "before_tests": "coffee -c *.coffee"
+
+or, with Babel (see the [Babel example](https://github.com/testem/testem/tree/master/examples/babel)):
+
+    "before_tests": "babel src --out-dir ."
+
+or, with a `tsconfig.json` that emits JavaScript next to your project (see the [TypeScript example](https://github.com/testem/testem/tree/master/examples/typescript)):
+
+    "before_tests": "tsc"
+
+And Testem will run it before each test run. Point **`src_files`** at the sources you want
+watched (see **File watching** under Development Mode above).
+
+```javascript
+"src_files": [
+  "*.coffee"
+]
+```
+
+Since you want to be serving the `.js` files that are generated and not the `.coffee` files, you want to specify the `serve_files` option to tell it that
+
+```javascript
+"serve_files": [
+  "*.js"
+]
+```
+
+Testem will throw up a big ol' error dialog if the preprocessor command exits with an error code, so code checkers like JSHint or ESLint can be used here as well.
+
+If you need to run a command after your tests have completed (such as removing compiled `.js` files), use the `after_tests` option.
+
+```javascript
+"after_tests": "rm *.js"
+```
+
+If you would prefer simply to clean up when Testem exits, you can use the `on_exit` option.
+
 Example Projects
 ----------------
 
 I've created [examples](https://github.com/testem/testem/tree/master/examples/) for various setups
 
+* [Vite (middleware + plugin)](https://github.com/testem/testem/tree/master/examples/vite)
+* [Electron](https://github.com/testem/testem/tree/master/examples/electron)
+* [TypeScript Project](https://github.com/testem/testem/tree/master/examples/typescript)
+* [ESLint Example](https://github.com/testem/testem/tree/master/examples/eslint)
+* [Babel Project](https://github.com/testem/testem/tree/master/examples/babel)
 * [Simple QUnit project](https://github.com/testem/testem/tree/master/examples/qunit_simple)
 * [Simple Jasmine project](https://github.com/testem/testem/tree/master/examples/jasmine_simple)
 * [Jasmine 2](https://github.com/testem/testem/tree/master/examples/jasmine2)
 * [Custom Jasmine project](https://github.com/testem/testem/tree/master/examples/jasmine_custom)
-* [Custom Jasmine project using Require.js](https://github.com/testem/testem/tree/master/examples/jasmine_requirejs)
 * [Simple Mocha Project](https://github.com/testem/testem/tree/master/examples/mocha_simple)
 * [Mocha + Chai](https://github.com/testem/testem/tree/master/examples/mocha_chai_simple)
 * [Hybrid Project](https://github.com/testem/testem/tree/master/examples/hybrid_simple) - Mocha tests running in both the browser and Node.
-* [Coffeescript Project](https://github.com/testem/testem/tree/master/examples/coffeescript)
-* [Browserify Project](https://github.com/testem/testem/tree/master/examples/browserify)
-* [JSHint Example](https://github.com/testem/testem/tree/master/examples/jshint)
 * [Custom Test Framework](https://github.com/testem/testem/tree/master/examples/custom_adapter)
 * [Tape Example](https://github.com/testem/testem/tree/master/examples/tape_example)
-* [BrowserStack Integration](https://github.com/testem/testem/tree/master/examples/browserstack) **bleeding edge**
-* [SauceLabs Integration](https://github.com/testem/testem/tree/master/examples/saucelabs) **bleeding edge**
-* [Code Coverage with Istanbul](https://github.com/testem/testem/tree/master/examples/coverage_istanbul) **bleeding edge**
-
-Known Issues
-------------
+* [Browserify Project](https://github.com/testem/testem/tree/master/examples/browserify)
+* [JSHint Example](https://github.com/testem/testem/tree/master/examples/jshint)
+* [Coffeescript Project](https://github.com/testem/testem/tree/master/examples/coffeescript)
+* [Custom Jasmine project using Require.js](https://github.com/testem/testem/tree/master/examples/jasmine_requirejs)
+* [BrowserStack Integration](https://github.com/testem/testem/tree/master/examples/browserstack)
+* [SauceLabs Integration](https://github.com/testem/testem/tree/master/examples/saucelabs)
+* [Code Coverage with Istanbul](https://github.com/testem/testem/tree/master/examples/coverage_istanbul)
 
-1. On Windows, Mocha fails to run under Testem due to an [issue](https://github.com/joyent/node/issues/3871) in Node core. Until that gets resolved, I've made a [workaround](https://github.com/airportyh/mocha/tree/windowsfix) for Mocha. To install this fork of Mocha, do
+Historical Screencasts
+----------------------
 
-        npm install https://github.com/airportyh/mocha/tarball/windowsfix -g
+These YouTube screencasts are from around **2012** and may not match the current UI or features, but they still illustrate the core ideas:
 
-2. If you are using prototype.js version 1.6.3 or below, you will [encounter issues](https://github.com/testem/testem/issues/130).
+* **[Introductory screencast (11:39)](https://www.youtube.com/watch?v=-1mjv4yk5JM)** &mdash; TDD workflow
+* **[Launchers (12:10)](https://www.youtube.com/watch?v=Up0lVjWk9Rk)** &mdash; auto-launch and running tests in **Node**
+* **[CI mode (4:24)](https://www.youtube.com/watch?v=Js16Cj80HKY)** &mdash; continuous integration
 
 Contributing
 ------------
 
 If you want to [contribute to the project](https://github.com/testem/testem/blob/master/CONTRIBUTING.md), I am going to do my best to stay out of your way.
 
-Roadmap
--------
-
-1. [BrowserStack](http://www.browserstack.com/user/dashboard) integration - following [Bunyip](http://www.thecssninja.com/javascript/bunyip)'s example
-2. Figure out a happy path for testing on mobile browsers (maybe BrowserStack).
-
 Core Maintainer(s)
 ------------------
 
 * [Johannes Würbach](https://github.com/johanneswuerbach)
 
-Community
----------
-
-* **Mailing list**: <https://groups.google.com/forum/?fromgroups#!forum/testem-users>
-
 Credits
 -------
 
 Testem depends on the following great software
 
-* [Jasmine](http://jasmine.github.io/)
-* [QUnit](http://code.google.com/p/jqunit/)
-* [Mocha](http://mochajs.org/)
-* [Node](http://nodejs.org/)
-* [Socket.IO](http://socket.io/)
-* [PhantomJS](http://www.phantomjs.org/)
-* [Node-Tap](https://github.com/isaacs/node-tap)
-* [Node-Charm](https://github.com/substack/node-charm)
-* [Node Commander](http://tjholowaychuk.com/post/9103188408/commander-js-nodejs-command-line-interfaces-made-easy)
+* [Jasmine](https://jasmine.github.io/)
+* [QUnit](https://qunitjs.com/)
+* [Mocha](https://mochajs.org/)
+* [Node](https://nodejs.org/)
+* [Socket.IO](https://socket.io/)
+* [tap-parser](https://github.com/tapjs/tap-parser)
+* [Charm](https://github.com/aheckmann/charm)
+* [Commander.js](https://github.com/tj/commander.js)
 * [JS-Yaml](https://github.com/nodeca/js-yaml)
-* [Express](http://expressjs.com/)
-* [jQuery](http://jquery.com/)
-* [Backbone](http://backbonejs.org/)
+* [Express](https://expressjs.com/)

package/lib/api.js

@@ -10,7 +10,7 @@ const Server = require('./server');
 /*
   CLI-level options:
 
-  file:                 [String]  configuration file (testem.json, .testem.json, testem.yml, .testem.yml)
+  file:                 [String]  configuration file path (JSON, YAML, JS: testem.js / .cjs / .mjs and dotted variants)
   host:                 [String]  server host to use (localhost)
   port:                 [Number]  server port to use (7357)
   launch:               [Array]   list of launchers to use for current runs (defaults to current mode)

package/lib/cli-local-delegation.js

@@ -0,0 +1,93 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Walks upward from `startDir` looking for `node_modules/testem/testem.js`.
+ *
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+function findLocalTestemScript(startDir) {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+  while (true) {
+    const candidate = path.join(dir, 'node_modules', 'testem', 'testem.js');
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    if (dir === root) {
+      break;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * If a local install exists and is not the same file as the running CLI (e.g. global),
+ * returns the path to the local `testem.js`. Otherwise returns null.
+ *
+ * @param {string} currentFile - `__filename` of the running CLI
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string | null}
+ */
+function resolveLocalTestemCliOrNull(currentFile, cwd, env = process.env) {
+  if (env.TESTEM_USE_GLOBAL === '1') {
+    return null;
+  }
+  const local = findLocalTestemScript(cwd);
+  if (!local) {
+    return null;
+  }
+  let cur;
+  let loc;
+  try {
+    cur = fs.realpathSync(currentFile);
+    loc = fs.realpathSync(local);
+  } catch {
+    return null;
+  }
+  if (cur === loc) {
+    return null;
+  }
+  return local;
+}
+
+/**
+ * When the globally installed `testem` is run inside a project that has a local
+ * `testem` dependency, re-exec that local copy so CLI and project stay in sync.
+ *
+ * Exits the process when delegation runs; otherwise returns normally.
+ *
+ * @param {string} currentFile
+ * @param {string[]} argv
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} env
+ */
+function tryDelegateToLocalTestem(currentFile, argv, cwd, env) {
+  const local = resolveLocalTestemCliOrNull(currentFile, cwd, env);
+  if (!local) {
+    return;
+  }
+  const result = spawnSync(process.execPath, [local, ...argv.slice(2)], {
+    stdio: 'inherit',
+    env,
+    windowsHide: true,
+  });
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+  if (result.signal) {
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 0 : result.status);
+}
+
+module.exports = {
+  findLocalTestemScript,
+  resolveLocalTestemCliOrNull,
+  tryDelegateToLocalTestem,
+};

package/lib/config.js

@@ -14,6 +14,7 @@ const yaml = require('js-yaml');
 const log = require('./log');
 const path = require('path');
 const url = require('url');
+const { pathToFileURL } = url;
 const querystring = require('querystring');
 const { filter, reduce } = require('./utils/promises');
 
@@ -76,6 +77,8 @@ class Config {
         'testem.yml',
         'testem.js',
         '.testem.js',
+        'testem.mjs',
+        '.testem.mjs',
         'testem.cjs',
         '.testem.cjs',
       ];
@@ -144,7 +147,7 @@ class Config {
       if (callback) {
         callback.call(this);
       }
-    } else if (configFile.match(/\.c?js$/)) {
+    } else if (configFile.match(/\.(c?js|mjs)$/)) {
       this.readJS(configFile, callback);
     } else if (configFile.match(/\.json$/)) {
       this.readJSON(configFile, callback);
@@ -158,21 +161,59 @@ class Config {
     }
   }
 
+  unwrapJsExport(exported) {
+    if (
+      exported &&
+      typeof exported === 'object' &&
+      exported.__esModule === true &&
+      Object.prototype.hasOwnProperty.call(exported, 'default')
+    ) {
+      return exported.default;
+    }
+    return exported;
+  }
+
+  loadJsExportedConfig(absPath) {
+    const ext = path.extname(absPath);
+    if (ext === '.cjs') {
+      return Promise.resolve(this.unwrapJsExport(require(absPath)));
+    }
+    if (ext === '.mjs') {
+      return import(pathToFileURL(absPath).href).then((mod) =>
+        mod.default !== undefined ? mod.default : mod,
+      );
+    }
+    try {
+      return Promise.resolve(this.unwrapJsExport(require(absPath)));
+    } catch (e) {
+      if (e.code === 'ERR_REQUIRE_ESM') {
+        return import(pathToFileURL(absPath).href).then((mod) =>
+          mod.default !== undefined ? mod.default : mod,
+        );
+      }
+      throw e;
+    }
+  }
+
   readJS(configFile, callback) {
-    let exportedConfig = require(this.resolveConfigPath(configFile));
-    if (typeof exportedConfig === 'function') {
-      Promise.resolve(exportedConfig()).then((obj) => {
-        this.fileOptions = obj;
+    const absPath = this.resolveConfigPath(configFile);
+    this.loadJsExportedConfig(absPath)
+      .then((exportedConfig) => {
+        if (typeof exportedConfig === 'function') {
+          return Promise.resolve(exportedConfig()).then((obj) => {
+            this.fileOptions = obj;
+          });
+        }
+        this.fileOptions = exportedConfig;
+      })
+      .catch((err) => {
+        log.error(err);
+      })
+      .then(() => {
         if (callback) {
           callback.call(this);
         }
       });
-    } else {
-      this.fileOptions = exportedConfig;
-      if (callback) {
-        callback.call(this);
-      }
-    }
   }
 
   readYAML(configFile, callback) {

package/lib/reporters/dev/runner_tabs.js

@@ -8,22 +8,21 @@ When the tab is not selected, it hides the associated log panel.
 
 */
 
-
 const SplitLogPanel = require('./split_log_panel');
 const View = require('./view');
 const Backbone = require('backbone');
 const pad = require('../../utils/strutils').pad;
 const Chars = require('../../utils/chars');
 const Screen = require('./screen');
-const notifier = require('node-notifier');
+const toastNotify = require('./toast_notify');
 const constants = require('./constants');
 const TabWidth = constants.TabWidth;
 const TabStartLine = constants.TabStartLine;
 const TabHeight = constants.TabHeight;
 const TabStartCol = constants.TabStartCol;
-const RunnerTab = exports.RunnerTab = View.extend({
+const RunnerTab = (exports.RunnerTab = View.extend({
   defaults: {
-    allPassed: true
+    allPassed: true,
   },
   col: TabStartCol,
   line: TabStartLine,
@@ -46,7 +45,7 @@ const RunnerTab = exports.RunnerTab = View.extend({
       runner: runner,
       appview: appview,
       visible: visible,
-      screen: this.get('screen')
+      screen: this.get('screen'),
     });
 
     this.spinnerIdx = 0;
@@ -56,7 +55,7 @@ const RunnerTab = exports.RunnerTab = View.extend({
     }
 
     this.observe(appview, {
-      'change:currentTab': handleCurrentTab
+      'change:currentTab': handleCurrentTab,
     });
     this.observe(runner, {
       'change:name'() {
@@ -77,7 +76,7 @@ const RunnerTab = exports.RunnerTab = View.extend({
       },
       'change:allPassed'(model, value) {
         self.set('allPassed', value);
-      }
+      },
     });
 
     if (results) {
@@ -91,19 +90,19 @@ const RunnerTab = exports.RunnerTab = View.extend({
             let total = results.get('total');
             let pending = results.get('pending');
 
-            let allPassed = (passed + pending) === total;
+            let allPassed = passed + pending === total;
             let hasTests = total > 0;
             let failCuzNoTests = !hasTests && config.get('fail_on_zero_tests');
-            let hasError = runner.get('messages').filter(function(m) {
-              return m.get('type') === 'error';
-            }).length > 0;
-            self.set('allPassed',
-              allPassed && !failCuzNoTests && !hasError);
+            let hasError =
+              runner.get('messages').filter(function (m) {
+                return m.get('type') === 'error';
+              }).length > 0;
+            self.set('allPassed', allPassed && !failCuzNoTests && !hasError);
           }
         },
         'change:all'() {
           self.renderResults();
-        }
+        },
       });
     }
 
@@ -123,7 +122,7 @@ const RunnerTab = exports.RunnerTab = View.extend({
           self.renderRunnerName();
           self.renderResults();
         });
-      }
+      },
     });
     this.render();
 
@@ -132,7 +131,10 @@ const RunnerTab = exports.RunnerTab = View.extend({
 
   updateSplitPanelVisibility() {
     let appview = this.get('appview');
-    this.splitPanel.set('visible', this.get('selected') && !appview.isPopupVisible());
+    this.splitPanel.set(
+      'visible',
+      this.get('selected') && !appview.isPopupVisible(),
+    );
   },
 
   color() {
@@ -147,7 +149,7 @@ const RunnerTab = exports.RunnerTab = View.extend({
       let passed = results.get('passed');
       pending = results.get('pending');
       let total = results.get('total');
-      equal = (passed + pending) === total;
+      equal = passed + pending === total;
       hasTests = total > 0;
     }
     let failCuzNoTests = !hasTests && config.get('fail_on_zero_tests');
@@ -199,8 +201,7 @@ const RunnerTab = exports.RunnerTab = View.extend({
     let runnerName = runner.get('name');
 
     // write line 1
-    screen
-      .foreground(this.color());
+    screen.foreground(this.color());
 
     if (this.get('selected')) {
       screen.display('bright');
@@ -233,11 +234,12 @@ const RunnerTab = exports.RunnerTab = View.extend({
       let passed = results.get('passed');
       let pending = results.get('pending');
       resultsDisplay = passed + '/' + total;
-      equal = (passed + pending) === total;
+      equal = passed + pending === total;
     }
 
     if (results && results.get('all')) {
-      resultsDisplay += ' ' + ((this.get('allPassed') && equal) ? Chars.success : Chars.fail);
+      resultsDisplay +=
+        ' ' + (this.get('allPassed') && equal ? Chars.success : Chars.fail);
     } else if (!results && runner.get('allPassed') !== undefined) {
       resultsDisplay = runner.get('allPassed') ? Chars.success : Chars.fail;
     } else {
@@ -250,8 +252,7 @@ const RunnerTab = exports.RunnerTab = View.extend({
     resultsDisplay = pad(resultsDisplay, width - 4, ' ', 2);
 
     // write line 1
-    screen
-      .foreground(this.color());
+    screen.foreground(this.color());
 
     if (this.get('selected')) {
       screen.display('bright');
@@ -267,12 +268,13 @@ const RunnerTab = exports.RunnerTab = View.extend({
     let runner = this.get('runner');
     let results = runner.get('results');
     let name = runner.get('name');
-    let resultsDisplay = results ?
-      (results.get('passed') + '/' + results.get('total')) : 'finished';
+    let resultsDisplay = results
+      ? results.get('passed') + '/' + results.get('total')
+      : 'finished';
 
-    notifier.notify({
-      title: 'Test\'em',
-      message: name + ' : ' + resultsDisplay
+    toastNotify.notify({
+      title: "Test'em",
+      message: name + ' : ' + resultsDisplay,
     });
   },
 
@@ -329,9 +331,11 @@ const RunnerTab = exports.RunnerTab = View.extend({
     let firstCol = index === 0;
     screen.position(col, line);
 
-    screen.write((firstCol ? Chars.horizontal : Chars.topLeft) +
-      new Array(width - 1).join(Chars.horizontal) +
-        Chars.topRight);
+    screen.write(
+      (firstCol ? Chars.horizontal : Chars.topLeft) +
+        new Array(width - 1).join(Chars.horizontal) +
+        Chars.topRight,
+    );
     for (let i = 1; i < height - 1; i++) {
       if (!firstCol) {
         screen.position(col, line + i);
@@ -341,8 +345,10 @@ const RunnerTab = exports.RunnerTab = View.extend({
       screen.write(Chars.vertical);
     }
 
-    let bottomLine = (firstCol ? ' ' : Chars.bottomRight) +
-      new Array(width - 1).join(' ') + Chars.bottomLeft;
+    let bottomLine =
+      (firstCol ? ' ' : Chars.bottomRight) +
+      new Array(width - 1).join(' ') +
+      Chars.bottomLeft;
     screen.position(col, line + height - 1);
     screen.write(bottomLine);
   },
@@ -351,8 +357,8 @@ const RunnerTab = exports.RunnerTab = View.extend({
     this.stopSpinner();
     this.splitPanel.destroy();
     View.prototype.destroy.call(this);
-  }
-});
+  },
+}));
 
 // View container for all the tabs. It'll handle clean up of removed tabs and draw
 // the edge for where there are no tabs.
@@ -366,12 +372,12 @@ exports.RunnerTabs = Backbone.Collection.extend({
       let currentTab = self.appview.get('currentTab');
       if (currentTab >= self.length) {
         currentTab--;
-        self.appview.set('currentTab', currentTab, {silent: true});
+        self.appview.set('currentTab', currentTab, { silent: true });
       }
       self.forEach((runner, idx) => {
         runner.set({
           index: idx,
-          selected: idx === currentTab
+          selected: idx === currentTab,
         });
       });
       self.eraseLast();
@@ -380,9 +386,12 @@ exports.RunnerTabs = Backbone.Collection.extend({
         self.blankOutBackground();
       }
     });
-    this.appview.on('change:isPopupVisible change:lines change:cols', function() {
-      self.reRenderAll();
-    });
+    this.appview.on(
+      'change:isPopupVisible change:lines change:cols',
+      function () {
+        self.reRenderAll();
+      },
+    );
   },
 
   reRenderAll() {
@@ -397,9 +406,7 @@ exports.RunnerTabs = Backbone.Collection.extend({
     let screen = this.screen;
     let cols = this.appview.get('cols');
     for (let i = 0; i < TabHeight; i++) {
-      screen
-        .position(0, TabStartLine + i)
-        .write(pad('', cols, ' ', 1));
+      screen.position(0, TabStartLine + i).write(pad('', cols, ' ', 1));
     }
   },
 
@@ -439,9 +446,7 @@ exports.RunnerTabs = Backbone.Collection.extend({
     let col = TabStartCol + index * width;
 
     for (let i = 0; i < height - 1; i++) {
-      screen
-        .position(col, line + i)
-        .write(new Array(width + 1).join(' '));
+      screen.position(col, line + i).write(new Array(width + 1).join(' '));
     }
 
     let bottomLine = new Array(width + 1).join(Chars.horizontal);
@@ -452,5 +457,5 @@ exports.RunnerTabs = Backbone.Collection.extend({
   isPopupVisible() {
     let appview = this.appview;
     return appview && appview.isPopupVisible();
-  }
+  },
 });

package/lib/reporters/dev/toast_notify.js

@@ -0,0 +1,5 @@
+const notifier = require('toasted-notifier');
+
+exports.notify = function notify(opts) {
+  return notifier.notify(opts);
+};

package/lib/server/index.js

@@ -399,6 +399,12 @@ class Server extends EventEmitter {
         this.emit('file-requested', filePath);
       });
     } else {
+      // `dotfiles: 'allow'` restores the Express 4 (send@0.19) behavior of
+      // serving paths that contain intermediate dot-prefixed segments — common
+      // in pnpm projects, whose entire dependency tree lives under
+      // `node_modules/.pnpm/...`. send@1.x defaults to `'ignore'` and 404s any
+      // such path.
+      var sendOptions = { dotfiles: 'allow' };
       fs.promises.stat(filePath)
         .then(stat => {
           this.emit('file-requested', filePath);
@@ -408,11 +414,11 @@ class Server extends EventEmitter {
               res.render(dirListingPage, { files: files });
             });
           }
-          res.sendFile(filePath);
+          res.sendFile(filePath, sendOptions);
         })
         .catch(() => {
           this.emit('file-requested', filePath);
-          res.sendFile(filePath);
+          res.sendFile(filePath, sendOptions);
         });
     }
   }

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "testem",
-  "description": "Test'em 'scripts! Javascript Unit testing made easy.",
+  "description": "Test'em 'scripts! JavaScript unit testing made easy.",
   "keywords": [
     "javascript",
     "testing",
     "unittest",
     "browser"
   ],
-  "version": "3.20.0",
+  "version": "3.20.1",
   "author": "Toby Ho <airportyh@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "git://github.com/testem/testem.git"
+    "url": "https://github.com/testem/testem.git"
   },
   "bugs": {
-    "url": "http://github.com/testem/testem/issues"
+    "url": "https://github.com/testem/testem/issues"
   },
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
@@ -37,7 +37,7 @@
     "minimatch": "^10.2.5",
     "mkdirp": "^3.0.1",
     "mustache": "^4.2.0",
-    "node-notifier": "^10.0.1",
+    "toasted-notifier": "^10.1.0",
     "printf": "^0.6.1",
     "proc-log": "^6.1.0",
     "rimraf": "^6.1.3",
@@ -56,7 +56,6 @@
     "views"
   ],
   "scripts": {
-    "install:all": "npm install && npm install phantomjs-prebuilt",
     "test": "mocha tests/*_tests.js tests/**/*_tests.js",
     "test:verbose": "TESTEM_VERBOSE=1 mocha tests/*_tests.js tests/**/*_tests.js",
     "cover": "cover run ./node_modules/.bin/_mocha tests/*_tests.js tests/**/*_tests.js; cover report html; open cover_html/index.html",
@@ -66,7 +65,6 @@
     "lint": "eslint ."
   },
   "devDependencies": {
-    "@cypress/request": "^3.0.10",
     "@eslint/eslintrc": "^3.3.5",
     "@eslint/js": "^10.0.1",
     "chai": "^6.2.2",

package/testem.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 
+const { tryDelegateToLocalTestem } = require('./lib/cli-local-delegation');
+if (require.main === module) {
+  tryDelegateToLocalTestem(__filename, process.argv, process.cwd(), process.env);
+}
+
 const { Command } = require('commander');
 const Config = require('./lib/config');
 const Api = require('./lib/api');
@@ -43,7 +48,7 @@ function parseArgs(argv, { exitOverride = false } = {}) {
     .usage('[options]')
     .option(
       '-f, --file [file]',
-      'config file - defaults to testem.json or testem.yml',
+      'config file path (JSON, YAML, or JS: testem.js / testem.cjs / testem.mjs); when omitted, picks the first match among defaults (see docs)',
     )
     .option('-p, --port [num]', 'server port - defaults to 7357', Number)
     .option('--host [hostname]', 'host name - defaults to localhost', String)