jasmine-browser-runner 2.4.0 → 3.0.0-beta.1

package/README.md

@@ -1,6 +1,7 @@
 jasmine-browser-runner runs your Jasmine specs in a browser. It's suitable for
 interactive use with normal browsers as well as running specs in CI builds
-using either headless Chrome or Saucelabs.
+using either headless browsers or with a remote Selenuium grid provider
+such as Saucelabs.
 
 # Getting started
 
@@ -19,13 +20,21 @@ npx jasmine-browser-runner init
 If you intend to use ES modules, add `--esm` to the `jasmine-browser-runner init`
 command.
 
-Then, customize `spec/support/jasmine-browser.json` to suit your needs. You can
+Then, customize `spec/support/jasmine-browser.mjs` to suit your needs. You can
 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. 
+In addition to `spec/support/jasmine-browser.mjs`, jasmine-browser-runner also
+supports other config file paths:
+
+* `spec/support/jasmine-browser.js`
+* `spec/support/jasmine-browser.json` (generated by previous versions of the 
+  `init` subcommand)
+* Any other JavaScript or JSON file, if you use the `--config` option. This 
+  file can be a JSON file or a javascript file whose default export is a config
+  object.
+
 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
@@ -42,10 +51,10 @@ npx jasmine-browser-runner runSpecs
 ```
 
 To use a browser other than Firefox, add a `browser` field to 
-`jasmine-browser.json`:
+`jasmine-browser.mjs`:
 
 ```javascript
-{
+export default {
   // ...
   "browser": "chrome"
 }
@@ -57,10 +66,10 @@ Its value can be `"firefox"`, `"headlessFirefox"`, `"safari"`,
 ## 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`:
+in PEM format in `jasmine-browser.mjs`:
 
 ```javascript
-{
+export default {
   // ...
   "tlsKey": "/path/to/tlsKey.pem",
   "tlsCert": "/path/to/tlsCert.pem",
@@ -74,13 +83,27 @@ 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.
 
+## Controlling which network interfaces are listened to
+
+By default, jasmine-browser-runner listens to all available network interfaces.
+You might need that if you're using a remote grid such as Saucelabs. If you 
+don't need that, you can improve security by listening only to localhost. 
+
+```javascript
+export default {
+  // ...
+  "listenAddress": "localhost",
+  // ...
+}
+```
+
 ## Hostname support
 
-To serve tests on a specific interface or IP, you can specify a hostname in
-`jasmine-browser.json`:
+If you need to access your tests via a specific hostname, you can do that by
+setting the `hostname` configuration property:
 
 ```javascript
-{
+export default {
   // ...
   "hostname": "mymachine.mynetwork",
   // ...
@@ -89,6 +112,11 @@ To serve tests on a specific interface or IP, you can specify a hostname in
 
 This can also be specified on the command line with `--hostname`.
 
+Setting `hostname` but not `listenAddress` has the same effect as setting
+`listenAddress` to the same value as `hostname`. If you need to set a hostname
+but retain the default behavior of listening to all network interfaces, you can
+do that by setting `listenAddress` to `"*"`.
+
 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
@@ -132,7 +160,7 @@ If you have specs or helper files that use top-level await, set the
 are also supported:
 
 ```javascript
-{
+export default {
    // ...
    "importMap": {
      "moduleRootDir": "node_modules", 
@@ -154,9 +182,9 @@ whether you use the Asset Pipeline or Webpacker.
 
 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:
+3. Edit `spec/support/jasmine-browser.mjs` as follows:
 ```
-{
+export default {
   "srcDir": ".",
   "srcFiles": [],
   "specDir": "public/packs/js",
@@ -196,9 +224,9 @@ To run the specs:
    the Rails application.
 2. Run `yarn add --dev jasmine-browser-runner`.
 3. Run `npx jasmine-browser-runner init`.
-5. Edit `spec/support/jasmine-browser.json` as follows:
+5. Edit `spec/support/jasmine-browser.mjs` as follows:
 ```
-{
+export default {
   "srcDir": "public/assets",
   "srcFiles": [
     "application-*.js"
@@ -230,9 +258,9 @@ provider like [Saucelabs](https://saucelabs.com/),
 To use a remote grid hub, set the `browser` object
 in your config file as follows:
 
-```json
-// jasmine-browser.json
-{
+```javascript
+// jasmine-browser.mjs
+export default {
   // ...
   // BrowserStack
   "browser": {
@@ -254,9 +282,9 @@ in your config file as follows:
   }
 }
 ```
-```json
-// jasmine-browser.json
-{
+```javascript
+// jasmine-browser.mjs
+export default {
   // ...
   // Saucelabs
   "browser": {
@@ -292,13 +320,24 @@ second parameter to`startServer`.
 ## Want more control?
 
 ```javascript
-const path = require('path');
-const jasmineBrowser = require('jasmine-browser-runner');
+// ESM
+import path from 'path';
+import jasmineBrowser from 'jasmine-browser-runner';
+import config from './spec/support/jasmine-browser.mjs';
 
-const config = require(path.resolve('spec/support/jasmine-browser.json'));
 config.projectBaseDir = path.resolve('some/path');
-
 jasmineBrowser.startServer(config, { port: 4321 });
+
+
+// CommonJS
+const path = require('path');
+const jasmineBrowser = require('jasmine-browser-runner');
+
+import('./spec/support/jasmine-browser.mjs')
+  .then(function({default: config}) {
+    config.projectBaseDir = path.resolve('some/path');
+    jasmineBrowser.startServer(config, { port: 4321 });
+  });
 ```
 
 ## Supported environments
@@ -306,13 +345,13 @@ jasmineBrowser.startServer(config, { port: 4321 });
 jasmine-browser-runner tests itself across popular browsers (Safari, Chrome, 
 Firefox, and Microsoft Edge) as well as Node.
 
-| Environment       | Supported versions     |
-|-------------------|------------------------|
-| Node              | 18, 20                 |
-| Safari            | 15-17                  |
-| Chrome            | Evergreen              |
-| Firefox           | Evergreen, 102, 115    |
-| Edge              | Evergreen              |
+| Environment       | Supported versions       |
+|-------------------|--------------------------|
+| Node              | 18, 20, 22               |
+| Safari            | 15-17                    |
+| Chrome            | Evergreen                |
+| Firefox           | Evergreen, 102, 115, 128 |
+| Edge              | Evergreen                |
 
 For evergreen browsers, each version of jasmine-browser-runner is tested against
 the version of the browser that is available to us at the time of release. Other 

package/index.js

@@ -56,13 +56,12 @@ module.exports = {
   /**
    * Starts a {@link Server} that will serve the specs and supporting files via HTTP.
    * @param {ServerCtorOptions} options to use to construct the server
-   * @param {ServerStartOptions} serverOptions Options to use to start the server
    * @return {Promise<undefined>} A promise that is resolved when the server is
    * started.
    */
-  startServer: function(options, serverOptions) {
+  startServer: function(options) {
     const server = new Server(options);
-    return server.start(serverOptions || {});
+    return server.start();
   },
   /**
    * Runs the specs.
@@ -70,8 +69,18 @@ module.exports = {
    * @return {Promise<JasmineDoneInfo>} A promise that resolves to the {@link https://jasmine.github.io/api/edge/global.html#JasmineDoneInfo|overall result} when the suite has finished running.
    */
   runSpecs: async function(options, deps) {
-    options = options || {};
+    options = { ...options };
     deps = deps || {};
+    const useRemote = options.browser && options.browser.useRemoteSeleniumGrid;
+
+    if (!options.port) {
+      if (useRemote) {
+        options.port = 5555;
+      } else {
+        options.port = 0;
+      }
+    }
+
     const ServerClass = deps.Server || Server;
     const RunnerClass = deps.Runner || Runner;
     const buildWebdriver =
@@ -80,19 +89,11 @@ module.exports = {
     const server = new ServerClass(options);
 
     const reporters = await createReporters(options, deps);
-    const useSauce = options.browser && options.browser.useSauce;
-    const useRemote = options.browser && options.browser.useRemoteSeleniumGrid;
-    let portRequest;
-
-    if (options.port) {
-      portRequest = options.port;
-    } else if (useSauce || useRemote) {
-      portRequest = 5555;
-    } else {
-      portRequest = 0;
-    }
+    const useSauceCompletionReporting =
+      useRemote &&
+      options.browser.remoteSeleniumGrid?.url?.includes('saucelabs.com');
 
-    await server.start({ port: portRequest });
+    await server.start();
 
     try {
       const webdriver = buildWebdriver(options.browser);
@@ -122,7 +123,7 @@ module.exports = {
 
         return details;
       } finally {
-        if (useSauce) {
+        if (useSauceCompletionReporting) {
           await webdriver.executeScript(
             `sauce:job-result=${process.exitCode === 0}`
           );

package/lib/command.js

@@ -165,7 +165,7 @@ class Command {
   }
 
   init(options) {
-    const dest = 'spec/support/jasmine-browser.json';
+    const dest = 'spec/support/jasmine-browser.mjs';
 
     if (fs.existsSync(dest)) {
       this._logger.log(`${dest} already exists.`);

package/lib/config.js

@@ -20,10 +20,12 @@ async function loadConfig(baseDir, cliOptions) {
 
   const candidates = (specifiedConfigFile
     ? [specifiedConfigFile]
-    : ['spec/support/jasmine-browser.js', 'spec/support/jasmine-browser.json']
-  )
-    .filter(name => !!name)
-    .map(name => path.resolve(baseDir, name));
+    : [
+        'spec/support/jasmine-browser.mjs',
+        'spec/support/jasmine-browser.js',
+        'spec/support/jasmine-browser.json',
+      ]
+  ).map(name => path.resolve(baseDir, name));
 
   const fullPath = candidates.find(p => fs.existsSync(p));
 
@@ -57,18 +59,15 @@ function validateConfig(config) {
 }
 
 function defaultConfig() {
-  return fs.readFileSync(require.resolve('./examples/default_config.json'), {
+  return fs.readFileSync(require.resolve('./examples/default_config.mjs'), {
     encoding: 'utf8',
   });
 }
 
 function defaultEsmConfig() {
-  return fs.readFileSync(
-    require.resolve('./examples/default_esm_config.json'),
-    {
-      encoding: 'utf8',
-    }
-  );
+  return fs.readFileSync(require.resolve('./examples/default_esm_config.mjs'), {
+    encoding: 'utf8',
+  });
 }
 
 function validateImportMap(importMap) {

package/lib/examples/default_config.mjs

@@ -0,0 +1,30 @@
+export default {
+  srcDir: "src",
+  srcFiles: [
+    "**/*.js"
+  ],
+  specDir: "spec",
+  specFiles: [
+    "**/*[sS]pec.js"
+  ],
+  helpers: [
+    "helpers/**/*.js"
+  ],
+  env: {
+    stopSpecOnExpectationFailure: false,
+    stopOnSpecFailure: false,
+    random: true
+  },
+
+  // For security, listen only to localhost. You can also specify a different
+  // hostname or IP address, or remove the property or set it to "*" to listen
+  // to all network interfaces.
+  listenAddress: "localhost",
+
+  // The hostname that the browser will use to connect to the server.
+  hostname: "localhost",
+
+  browser: {
+    name: "firefox"
+  }
+};

package/lib/examples/default_esm_config.mjs

@@ -0,0 +1,34 @@
+export default {
+  srcDir: "src",
+  // srcFiles should usually be left empty when using ES modules, because you'll
+  // explicitly import sources from your specs.
+  srcFiles: [],
+  specDir: ".",
+  specFiles: [
+    "spec/**/*[sS]pec.?(m)js"
+  ],
+  helpers: [
+    "spec/helpers/**/*.?(m)js"
+  ],
+  esmFilenameExtension: ".mjs",
+  // Allows the use of top-level await in src/spec/helper files. This is off by
+  // default because it makes files load more slowly.
+  enableTopLevelAwait: false,
+  env: {
+    stopSpecOnExpectationFailure: false,
+    stopOnSpecFailure: false,
+    random: true
+  },
+
+  // For security, listen only to localhost. You can also specify a different
+  // hostname or IP address, or remove the property or set it to "*" to listen
+  // to all network interfaces.
+  listenAddress: "localhost",
+
+  // The hostname that the browser will use to connect to the server.
+  hostname: "localhost",
+
+  browser: {
+    name: "firefox"
+  }
+};

package/lib/server.js

@@ -15,8 +15,9 @@ class Server {
    * @constructor
    * @param {ServerCtorOptions} options
    */
-  constructor(options) {
+  constructor(options, deps) {
     this.options = { ...options };
+    this._deps = deps || { http, https };
     this.express = this.options.express || defaultExpress;
     this.useHtmlReporter =
       options.useHtmlReporter === undefined ? true : options.useHtmlReporter;
@@ -132,11 +133,9 @@ class Server {
 
   /**
    * Starts the server.
-   * @param {ServerStartOptions} options
    * @return {Promise<undefined>} A promise that resolves upon successful start.
    */
-  start(serverOptions) {
-    serverOptions = serverOptions || {};
+  start() {
     const app = this.express();
 
     app.use('/__jasmine__', this.express.static(this.jasmineCore.files.path));
@@ -219,18 +218,23 @@ 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;
+    const port = this.options.port === undefined ? 8888 : this.options.port;
+    const tlsCert = this.options.tlsCert;
+    const tlsKey = this.options.tlsKey;
+    const hostname = this.options.hostname;
+    let listenAddress;
+
+    if (!this.options.listenAddress) {
+      listenAddress = 'localhost';
+    } else if (this.options.listenAddress === '*') {
+      listenAddress = ''; // all interfaces
+    } else {
+      listenAddress = this.options.listenAddress;
+    }
 
-    // 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 || '',
+      host: listenAddress,
     };
     this._httpHostname = hostname || 'localhost';
 
@@ -260,12 +264,12 @@ class Server {
           key: fs.readFileSync(tlsKey),
           cert: fs.readFileSync(tlsCert),
         };
-        this._httpServer = https
+        this._httpServer = this._deps.https
           .createServer(httpsOptions, app)
           .listen(listenOptions, callback);
         this._httpServerScheme = 'https';
       } else {
-        this._httpServer = http
+        this._httpServer = this._deps.http
           .createServer(app)
           .listen(listenOptions, callback);
         this._httpServerScheme = 'http';
@@ -325,18 +329,6 @@ class Server {
   }
 }
 
-function findPort(serverPort, optionsPort) {
-  if (typeof serverPort !== 'undefined') {
-    return serverPort;
-  }
-
-  if (typeof optionsPort !== 'undefined') {
-    return optionsPort;
-  }
-
-  return 8888;
-}
-
 function isUrl(s) {
   return s.startsWith('http://') || s.startsWith('https://');
 }

package/lib/types.js

@@ -52,12 +52,19 @@
  * @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.
+ * The hostname or IP address of the network interface to listen on. For
+ * security, jasmine-browser-runner will listen to localhost unless if this
+ * property is not specified. Set to "*" to listen on all interfaces, which may
+ * be required by some remote Selenium grids.
+ * @name ServerCtorOptions#listenAddress
+ * @default "localhost"
+ * @type string | undefined
+ */
+/**
+ * The hostname to use in the URL given to browsers.
  * @name ServerCtorOptions#hostname
- * @type string
+ * @default "localhost"
+ * @type string | undefined
  */
 /**
  * The root directory of the project.
@@ -180,12 +187,6 @@
  * Describes a web browser.
  * @interface BrowserInfo
  */
-/**
- * Whether to run the specs on {@link https://saucelabs.com/|Saucelabs}.
- * Defaults to false.
- * @name BrowserInfo#useSauce
- * @type boolean | undefined
- */
 /**
  * Whether to run the specs on a remote Selenium grid.
  * Defaults to false.
@@ -198,63 +199,11 @@
  * @name BrowserInfo#name
  * @type string | undefined
  */
-/**
- * Configuration for running specs on {@link https://saucelabs.com/|Saucelabs}
- * @name BrowserInfo#sauce
- * @type SauceConfig | undefined
- */
 /**
  * Configuration for running specs on a remote Selenium grid
  * @name BrowserInfo#remoteSeleniumGrid
  * @type RemoteSeleniumGridConfig | undefined
  */
-
-/**
- * Configuration for running specs on {@link https://saucelabs.com/|Saucelabs}
- * @interface SauceConfig
- */
-/**
- * Saucelabs username
- * @name SauceConfig#username
- * @type string
- */
-/**
- * Saucelabs access key
- * @name SauceConfig#accessKey
- * @type string
- */
-/**
- * Browser version. Omit this to use the latest version of the specified browser.
- * @name SauceConfig#browserVersion
- * @type string
- */
-/**
- * Identifier of the Sauce Connect tunnel to use.
- * @name SauceConfig#tunnelIdentifier
- * @type string
- */
-/**
- * Operating system to run the browser on.
- *
- * _Note_: It's best to omit this property
- * unless you really need your specs to run on a specific OS. If you omit it,
- * Saucelabs will select a suitable OS. If you specify an unsupported combination
- * of os and browserVersion, Saucelabs will select a different browser version
- * that's available on the specified OS.
- * @name SauceConfig#os
- * @type string
- */
-/**
- * Build identifier to pass to Saucelabs
- * @name SauceConfig#build
- * @type string
- */
-/**
- * Tags to pass to Saucelabs
- * @name SauceConfig#tags
- * @type Array.<string>
- */
-
 /**
  * Configuration for running specs on a remote Selenium grid
  * Any additional properties, such as "sauce:options" or "bstack:options", will
@@ -281,37 +230,6 @@
  * @type string
  */
 
-/**
- * Options passed to {@link Server#start}
- * @interface
- * @name ServerStartOptions
- */
-/**
- * The port number to listen on.
- * @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.
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap}

package/lib/webdriver.js

@@ -3,7 +3,6 @@ function buildWebdriver(browserInfo, webdriverBuilder) {
     Capability = webdriver.Capability;
 
   webdriverBuilder = webdriverBuilder || new webdriver.Builder();
-  const useSauce = typeof browserInfo === 'object' && browserInfo.useSauce;
   const useRemote =
     typeof browserInfo === 'object' && browserInfo.useRemoteSeleniumGrid;
   let browserName;
@@ -16,7 +15,7 @@ function buildWebdriver(browserInfo, webdriverBuilder) {
 
   browserName = browserName || 'firefox';
 
-  if (!(useRemote || useSauce)) {
+  if (!useRemote) {
     if (browserName === 'headlessChrome') {
       const caps = webdriver.Capabilities.chrome();
       caps.set('goog:chromeOptions', {
@@ -58,29 +57,6 @@ function buildWebdriver(browserInfo, webdriverBuilder) {
       };
       delete capabilities.url;
     }
-  } 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`;
-      capabilities = {
-        [Capability.BROWSER_NAME]: browserName,
-        build: sauce.build,
-        tags: sauce.tags,
-      };
-
-      capabilities[Capability.PLATFORM_NAME] = sauce.os;
-      capabilities[Capability.BROWSER_VERSION] = sauce.browserVersion;
-      capabilities['sauce:options'] = {
-        'tunnel-identifier': sauce.tunnelIdentifier,
-      };
-    }
   }
 
   if (!capabilities) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jasmine-browser-runner",
-  "version": "2.4.0",
+  "version": "3.0.0-beta.1",
   "description": "Serve and run your Jasmine specs in a browser",
   "bin": "bin/jasmine-browser-runner",
   "exports": "./index.js",
@@ -13,8 +13,8 @@
     "run.html.ejs",
     "bin/*.js",
     "lib/**/*.js",
-    "lib/examples/default_config.json",
-    "lib/examples/default_esm_config.json"
+    "lib/examples/default_config.mjs",
+    "lib/examples/default_esm_config.mjs"
   ],
   "scripts": {
     "posttest": "eslint bin/* lib spec index.js --ignore-path=.styleIgnore && prettier --check --ignore-path=.styleIgnore \"lib/**/*.js\" \"spec/**/*.js\" index.js",
@@ -38,7 +38,7 @@
   "homepage": "https://github.com/jasmine/jasmine-browser-runner#readme",
   "dependencies": {
     "ejs": "^3.1.6",
-    "express": "^4.16.4",
+    "express": "^5.0.0",
     "glob": "^10.0.0",
     "selenium-webdriver": "^4.12.0"
   },
@@ -46,7 +46,6 @@
     "jasmine-core": "^5.0.0"
   },
   "devDependencies": {
-    "ejs-lint": "^2.0.0",
     "eslint": "^8.50.0",
     "eslint-plugin-jasmine": "^4.1.3",
     "jasmine": "^5.0.0",

package/lib/examples/default_config.json

@@ -1,21 +0,0 @@
-{
-  "srcDir": "src",
-  "srcFiles": [
-    "**/*.js"
-  ],
-  "specDir": "spec",
-  "specFiles": [
-    "**/*[sS]pec.js"
-  ],
-  "helpers": [
-    "helpers/**/*.js"
-  ],
-  "env": {
-    "stopSpecOnExpectationFailure": false,
-    "stopOnSpecFailure": false,
-    "random": true
-  },
-  "browser": {
-    "name": "firefox"
-  }
-}

package/lib/examples/default_esm_config.json

@@ -1,21 +0,0 @@
-{
-  "srcDir": "src",
-  "srcFiles": [],
-  "specDir": ".",
-  "specFiles": [
-    "spec/**/*[sS]pec.?(m)js"
-  ],
-  "helpers": [
-    "spec/helpers/**/*.?(m)js"
-  ],
-  "esmFilenameExtension": ".mjs",
-  "enableTopLevelAwait": false,
-  "env": {
-    "stopSpecOnExpectationFailure": false,
-    "stopOnSpecFailure": false,
-    "random": true
-  },
-  "browser": {
-    "name": "firefox"
-  }
-}