jasmine-browser-runner 2.3.0 → 2.4.0

package/MIT.LICENSE

@@ -1,4 +1,5 @@
-Copyright (c) 2019-2019 Pivotal Labs
+Copyright (c) 2019 Pivotal Labs
+Copyright (c) 2020-2024 The Jasmine developers
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/README.md

@@ -24,7 +24,9 @@ change the spec files, helpers, and source files that are loaded, specify the
 [Jasmine env's configuration](https://jasmine.github.io/api/edge/Configuration.html),
 and more.
 
-You can also use the `--config` option to specify a different file. This file can be a JSON file or a javascript file that exports a object that looks like the JSON above.
+You can also use the `--config` option to specify a different file. 
+This file can be a JSON file or a javascript file that exports a object that looks like the JSON above. 
+More information about the configuration can be found at the runner [documentation website](https://jasmine.github.io/api/browser-runner/edge/Configuration.html).
 
 To start the server so that you can run the specs interactively (particularly
 useful for debugging):
@@ -52,6 +54,63 @@ To use a browser other than Firefox, add a `browser` field to
 Its value can be `"firefox"`, `"headlessFirefox"`, `"safari"`, 
 `"MicrosoftEdge"`, `"chrome"`, or `"headlessChrome"`.
 
+## TLS support
+
+To serve tests over HTTPS instead of HTTP, supply a path to a TLS cert and key
+in PEM format in `jasmine-browser.json`:
+
+```javascript
+{
+  // ...
+  "tlsKey": "/path/to/tlsKey.pem",
+  "tlsCert": "/path/to/tlsCert.pem",
+  // ...
+}
+```
+
+These can also be specified on the command line with `--tlsKey` and `--tlsCert`.
+
+Note that if you are using a self-signed or otherwise invalid certificate, the
+browser will not allow the connection by default.  Additional browser configs
+or command line options may be necessary to use an invalid TLS certificate.
+
+## Hostname support
+
+To serve tests on a specific interface or IP, you can specify a hostname in
+`jasmine-browser.json`:
+
+```javascript
+{
+  // ...
+  "hostname": "mymachine.mynetwork",
+  // ...
+}
+```
+
+This can also be specified on the command line with `--hostname`.
+
+There are a few important caveats when doing this:
+
+1. This name must either be an IP or a name that can really be resolved on your
+   system. Otherwise, you will get `ENOTFOUND` errors.
+2. This name must correspond to an IP assigned to one of the network interfaces
+   on your system. Otherwise, you will get `EADDRNOTAVAIL` errors.
+3. If this name matches the [HSTS preload list](https://hstspreload.org/),
+   browsers will force the connection to HTTPS.  If you are not using TLS, you
+   will get an error that says `The browser tried to speak HTTPS to an HTTP
+   server.  Misconfiguration is likely.`  You may be surprised by the names on
+   that preload list, which include such favorite local network hostnames as:
+    - dev
+    - foo
+    - app
+    - nexus
+    - windows
+    - office
+    - dad
+  You can see a full list in [Chromium source](https://raw.githubusercontent.com/chromium/chromium/main/net/http/transport_security_state_static.json)
+  or query your hostname at the [HSTS preload site](https://hstspreload.org/).
+
+
 ## ES module support
 
 If a source, spec, or helper file's name ends in `.mjs`, it will be loaded as
@@ -93,7 +152,7 @@ whether you use the Asset Pipeline or Webpacker.
 
 ### Webpacker
 
-1. Run `yarn add --dev jasmine-browser-runner`.
+1. Run `yarn add --dev jasmine-browser-runner jasmine-core`.
 2. Run `npx jasmine-browser-runner init`.
 3. Edit `spec/support/jasmine-browser.json` as follows:
 ```
@@ -224,38 +283,11 @@ exception of the `url` will be used as `capabilties` sent to the grid hub url.
 if no value is specified for the `url` then a default of
 `http://localhost:4445/wd/hub` is used. 
 
-## Saucelabs support (legacy)
-> NOTE: the below configuration format only supports using Saucelabs in the US. if connecting from the EU, please use the above specifying a `url` value specific to your region (e.g. `https://ondemand.eu-central-1.saucelabs.com:443/wd/hub`) to avoid a connection error of `WebDriverError: This user is unauthorized to the region. Please try another region, or contact customer support.`
-
-> WARNING: the below configuration format may be removed in favour of using the above in the future so it is advised that you migrate to the above
-
-jasmine-browser-runner can run your Jasmine specs on [Saucelabs](https://saucelabs.com/).
-To use Saucelabs, set `browser.name`, `browser.useSauce`, and `browser.sauce`
-in your config file as follows:
-
-```json
-{
-  // ...
-  "browser": {
-    "name": "safari",
-    "useSauce": true,
-    "sauce": {
-      "browserVersion": "13",
-      "os": "OS X 10.15",
-      "tags": ["your tag", "your other tag"],
-      "tunnelIdentifier": "tunnel ID",
-      "username": "your Saucelabs username",
-      "accessKey": "your Saucelabs access key"
-    }
-  }
-}
-```
-
-All properties of `browser.sauce` are optional except for `username` and 
-`accessKey`. It's best to omit `browser.sauce.os` unless you need to run on a 
-specific operating system. Setting `browser.sauce.tunnelIdentifier` is strongly
-recommended unless you're sure that your account will never have more than one
-active tunnel.
+It's common for remote grids to support only a limited set of ports. Check your
+remote grid's documentation to make sure that the port you're using is 
+supported. When using a remote grid, `jasmine-browser-runner` will run on port 
+5555 unless you use the `--port` command line option or specify a port in the
+second parameter to`startServer`.
 
 ## Want more control?
 
@@ -277,9 +309,9 @@ Firefox, and Microsoft Edge) as well as Node.
 | Environment       | Supported versions     |
 |-------------------|------------------------|
 | Node              | 18, 20                 |
-| Safari            | 15-16                  |
+| Safari            | 15-17                  |
 | Chrome            | Evergreen              |
-| Firefox           | Evergreen, 102         |
+| Firefox           | Evergreen, 102, 115    |
 | Edge              | Evergreen              |
 
 For evergreen browsers, each version of jasmine-browser-runner is tested against
@@ -290,3 +322,6 @@ they aren't actively supported.
 
 To find out what environments work with a particular Jasmine release, see the [release notes](https://github.com/jasmine/jasmine/tree/main/release_notes).
 
+Copyright (c) 2019 Pivotal Labs<br>
+Copyright (c) 2020-2024 The Jasmine developers<br>
+This software is licensed under the MIT License.

package/bin/jasmine-browser-runner

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
- const path = require('path'),
-  jasmineCore = require('../lib/jasmineCore'),
-  Command = require('../lib/command'),
-  jasmineBrowser = require('../index.js');
+const path = require('path');
+const jasmineCore = require('../lib/jasmineCore');
+const Command = require('../lib/command');
+const jasmineBrowser = require('../index.js');
 const UsageError = require('../lib/usage_error');
 
- const command = new Command({
+const command = new Command({
   baseDir: path.resolve(),
   jasmineCore,
   jasmineBrowser,

package/index.js

@@ -1,8 +1,8 @@
-const ConsoleReporter = require('./lib/console_reporter'),
-  webdriverModule = require('./lib/webdriver'),
-  Server = require('./lib/server'),
-  Runner = require('./lib/runner'),
-  ModuleLoader = require('./lib/moduleLoader');
+const ConsoleReporter = require('./lib/console_reporter');
+const webdriverModule = require('./lib/webdriver');
+const Server = require('./lib/server');
+const Runner = require('./lib/runner');
+const ModuleLoader = require('./lib/moduleLoader');
 
 async function createReporters(options, deps) {
   const result = [];
@@ -84,16 +84,10 @@ module.exports = {
     const useRemote = options.browser && options.browser.useRemoteSeleniumGrid;
     let portRequest;
 
-    if (useSauce || useRemote) {
-      if (options.port) {
-        throw new Error(
-          "Can't specify a port when browser.useSauce or browser.useRemoteSeleniumGrid is true"
-        );
-      }
-
-      portRequest = 5555;
-    } else if (options.port) {
+    if (options.port) {
       portRequest = options.port;
+    } else if (useSauce || useRemote) {
+      portRequest = 5555;
     } else {
       portRequest = 0;
     }
@@ -104,7 +98,7 @@ module.exports = {
       const webdriver = buildWebdriver(options.browser);
 
       try {
-        const host = `http://localhost:${server.port()}`;
+        const host = `${server.scheme()}://${server.hostname()}:${server.port()}`;
         const runner = new RunnerClass({ webdriver, reporters, host });
 
         console.log('Running tests in the browser...');

package/lib/command.js

@@ -11,6 +11,17 @@ const UsageError = require('./usage_error');
 const commonOptions = [
   { name: 'config', type: 'string', description: 'path to the config file' },
   { name: 'port', type: 'number', description: 'port to run the server on' },
+  {
+    name: 'tlsCert',
+    type: 'string',
+    description: 'Path to TLS cert file for https',
+  },
+  {
+    name: 'tlsKey',
+    type: 'string',
+    description: 'Path to TLS key file for https',
+  },
+  { name: 'hostname', type: 'string', description: 'hostname to listen on' },
 ];
 
 const subCommands = [
@@ -80,6 +91,11 @@ const subCommands = [
         type: 'string',
         description: 'which local browser to launch',
       },
+      {
+        name: 'hideDisabled',
+        type: 'bool',
+        description: 'hide disabled tests',
+      },
     ]),
   },
 ];

package/lib/console_reporter.js

@@ -171,20 +171,20 @@ function ConsoleReporter() {
   this.specDone = function(result) {
     specCount++;
 
-    if (result.status == 'pending') {
+    if (result.status === 'pending') {
       pendingSpecs.push(result);
       executableSpecCount++;
       print(colored('yellow', '*'));
       return;
     }
 
-    if (result.status == 'passed') {
+    if (result.status === 'passed') {
       executableSpecCount++;
       print(colored('green', '.'));
       return;
     }
 
-    if (result.status == 'failed') {
+    if (result.status === 'failed') {
       failureCount++;
       failedSpecs.push(result);
       executableSpecCount++;
@@ -210,7 +210,7 @@ function ConsoleReporter() {
   }
 
   function plural(str, count) {
-    return count == 1 ? str : str + 's';
+    return count === 1 ? str : str + 's';
   }
 
   function repeat(thing, times) {

package/lib/runner.js

@@ -76,6 +76,7 @@ function urlParams(runOptions) {
         random: runOptions.random,
         seed: runOptions.seed,
         spec: runOptions.filter,
+        hideDisabled: runOptions.hideDisabled,
       })
     )
   );
@@ -100,9 +101,34 @@ class Runner {
 
   async run(runOptions) {
     runOptions = runOptions || {};
-    await this._options.webdriver.get(
-      this._options.host + urlParams(runOptions)
-    );
+
+    try {
+      await this._options.webdriver.get(
+        this._options.host + urlParams(runOptions)
+      );
+    } catch (error) {
+      // Looking for Chrome's "WebDriverError: ... net::ERR_SSL_PROTOCOL_ERROR"
+      // or Firefox's "WebDriverError: ... about:neterror?e=nssFailure2"
+      if (error.name === 'WebDriverError') {
+        if (
+          error.message.includes('ERR_SSL_PROTOCOL_ERROR') ||
+          error.message.includes('about:neterror?e=nssFailure2')
+        ) {
+          // Show a friendlier error.
+          throw new Error(
+            'The browser tried to speak HTTPS to an HTTP server. This ' +
+              "probably means that the configured hostname is on the browser's " +
+              'HSTS preload list. Try a different hostname or configure a TLS ' +
+              'certificate. See ' +
+              '<https://github.com/jasmine/jasmine-browser-runner?tab=readme-ov-file#hostname-support> ' +
+              'for more information.'
+          );
+        }
+      }
+
+      // Rethrow the original error.
+      throw error;
+    }
 
     return await runTillEnd(this._options.webdriver, this._options.reporters);
   }

package/lib/server.js

@@ -1,8 +1,10 @@
-const defaultExpress = require('express'),
-  glob = require('glob'),
-  ejs = require('ejs'),
-  path = require('path'),
-  fs = require('fs');
+const defaultExpress = require('express');
+const ejs = require('ejs');
+const fs = require('fs');
+const glob = require('glob');
+const http = require('http');
+const https = require('https');
+const path = require('path');
 
 /**
  * @class Server
@@ -57,11 +59,12 @@ class Server {
   }
 
   getUrls(baseDir, globs, urlRoot) {
-    return findFiles(path.join(this.projectBaseDir, baseDir), globs || []).map(
-      function(p) {
-        return isUrl(p) ? p : unWindows(path.join(urlRoot, p));
-      }
-    );
+    return findFiles(
+      path.resolve(this.projectBaseDir, baseDir),
+      globs || []
+    ).map(function(p) {
+      return isUrl(p) ? p : unWindows(path.join(urlRoot, p));
+    });
   }
 
   getSupportFiles() {
@@ -148,11 +151,15 @@ class Server {
     );
     app.use(
       '/__spec__',
-      this.express.static(path.join(this.projectBaseDir, this.options.specDir))
+      this.express.static(
+        path.resolve(this.projectBaseDir, this.options.specDir)
+      )
     );
     app.use(
       '/__src__',
-      this.express.static(path.join(this.projectBaseDir, this.options.srcDir))
+      this.express.static(
+        path.resolve(this.projectBaseDir, this.options.srcDir)
+      )
     );
 
     if (this.options.middleware) {
@@ -165,7 +172,10 @@ class Server {
 
     if (this.options.importMap) {
       const dir = this.options.importMap.moduleRootDir
-        ? path.join(this.projectBaseDir, this.options.importMap.moduleRootDir)
+        ? path.resolve(
+            this.projectBaseDir,
+            this.options.importMap.moduleRootDir
+          )
         : this.projectBaseDir;
       app.use('/__moduleRoot__', this.express.static(dir));
     }
@@ -210,12 +220,30 @@ class Server {
     });
 
     const port = findPort(serverOptions.port, this.options.port);
+    const tlsCert = serverOptions.tlsCert || this.options.tlsCert;
+    const tlsKey = serverOptions.tlsKey || this.options.tlsKey;
+    const hostname = serverOptions.hostname || this.options.hostname;
+
+    // NOTE: Before hostname support, jasmine-browser-runner would listen on
+    // all IPs (no hostname) and point browsers to "localhost".  We preserve
+    // backward compatibility here by using different defaults for these two
+    // things.
+    const listenOptions = {
+      port,
+      host: hostname || '',
+    };
+    this._httpHostname = hostname || 'localhost';
+
     return new Promise(resolve => {
-      this._httpServer = app.listen(port, () => {
+      const callback = () => {
         const runningPort = this._httpServer.address().port;
-        console.log(
-          `Jasmine server is running here: http://localhost:${runningPort}`
-        );
+        const url =
+          this._httpServerScheme +
+          '://' +
+          this._httpHostname +
+          ':' +
+          runningPort;
+        console.log(`Jasmine server is running here: ${url}`);
         console.log(
           `Jasmine tests are here:         ${path.resolve(
             self.options.specDir
@@ -225,7 +253,23 @@ class Server {
           `Source files are here:          ${path.resolve(self.options.srcDir)}`
         );
         resolve();
-      });
+      };
+
+      if (tlsKey && tlsCert) {
+        const httpsOptions = {
+          key: fs.readFileSync(tlsKey),
+          cert: fs.readFileSync(tlsCert),
+        };
+        this._httpServer = https
+          .createServer(httpsOptions, app)
+          .listen(listenOptions, callback);
+        this._httpServerScheme = 'https';
+      } else {
+        this._httpServer = http
+          .createServer(app)
+          .listen(listenOptions, callback);
+        this._httpServerScheme = 'http';
+      }
     });
   }
 
@@ -257,6 +301,28 @@ class Server {
 
     return this._httpServer.address().port;
   }
+
+  /**
+   * Gets the URL scheme that the server is listening on. The server must be
+   * started before this method is called.
+   * @function
+   * @name Server#scheme
+   * @return {string} The URL scheme ('http' or 'https')
+   */
+  scheme() {
+    return this._httpServerScheme;
+  }
+
+  /**
+   * Gets the hostname that the server is listening on. The server must be
+   * started before this method is called.
+   * @function
+   * @name Server#hostname
+   * @return {string} The hostname (localhost if not specified)
+   */
+  hostname() {
+    return this._httpHostname;
+  }
 }
 
 function findPort(serverPort, optionsPort) {

package/lib/types.js

@@ -39,6 +39,26 @@
  * @name ServerCtorOptions#port
  * @type number | undefined
  */
+/**
+ * The path to a TLS key. Activates HTTPS mode. If specified, tlsCert must also
+ * be specified.
+ * @name ServerCtorOptions#tlsKey
+ * @type string
+ */
+/**
+ * The path to a TLS cert. Activates HTTPS mode. If specified, tlsKey must also
+ * be specified.
+ * @name ServerCtorOptions#tlsCert
+ * @type string
+ */
+/**
+ * The hostname to use.  This influences both the URL given to browsers and the
+ * addresses on which the socket listens.  If blank, for backward
+ * compatibility, the browsers will be pointed to localhost, but the listening
+ * socket will listen on all IPs.
+ * @name ServerCtorOptions#hostname
+ * @type string
+ */
 /**
  * The root directory of the project.
  * @name ServerCtorOptions#projectBaseDir
@@ -271,6 +291,26 @@
  * @name ServerStartOptions#port
  * @type number | undefined
  */
+/**
+ * The path to a TLS key. Activates HTTPS mode. If specified, tlsCert must also
+ * be specified.
+ * @name ServerStartOptions#tlsKey
+ * @type string
+ */
+/**
+ * The path to a TLS cert. Activates HTTPS mode. If specified, tlsKey must also
+ * be specified.
+ * @name ServerStartOptions#tlsCert
+ * @type string
+ */
+/**
+ * The hostname to use.  This influences both the URL given to browsers and the
+ * addresses on which the socket listens.  If blank, for backward
+ * compatibility, the browsers will be pointed to localhost, but the listening
+ * socket will listen on all IPs.
+ * @name ServerStartOptions#hostname
+ * @type string
+ */
 
 /**
  * Describes an import map.

package/lib/webdriver.js

@@ -60,6 +60,12 @@ function buildWebdriver(browserInfo, webdriverBuilder) {
     }
   } else if (useSauce) {
     // handle legacy `sauce` object
+    console.warn(
+      'Deprecation warning: Direct support for Saucelabs is deprecated and ' +
+        'will be removed in a future release. Please use Saucelabs via the ' +
+        'remote Selenium grid feature. See the jasmine-browser-runner README ' +
+        'for details.'
+    );
     const sauce = browserInfo.sauce;
     if (sauce) {
       url = `http://${sauce.username}:${sauce.accessKey}@ondemand.saucelabs.com/wd/hub`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jasmine-browser-runner",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Serve and run your Jasmine specs in a browser",
   "bin": "bin/jasmine-browser-runner",
   "exports": "./index.js",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "ejs-lint": "^2.0.0",
-    "eslint": "^8.38.0",
+    "eslint": "^8.50.0",
     "eslint-plugin-jasmine": "^4.1.3",
     "jasmine": "^5.0.0",
     "jasmine-core": "^5.0.0",
@@ -72,7 +72,7 @@
       "expectAsync": "readonly"
     },
     "parserOptions": {
-      "ecmaVersion": 11
+      "ecmaVersion": 2022
     },
     "plugins": [
       "jasmine"
@@ -102,6 +102,7 @@
           "functions": "never"
         }
       ],
+      "eqeqeq": "error",
       "func-call-spacing": [
         "error",
         "never"