jasmine-browser-runner 2.4.0 → 2.5.0

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

package/index.js

@@ -80,13 +80,17 @@ module.exports = {
     const server = new ServerClass(options);
 
     const reporters = await createReporters(options, deps);
-    const useSauce = options.browser && options.browser.useSauce;
+    const useLegacySauce = options.browser && options.browser.useSauce;
     const useRemote = options.browser && options.browser.useRemoteSeleniumGrid;
+    const useSauceCompletionReporting =
+      useLegacySauce ||
+      (useRemote &&
+        options.browser.remoteSeleniumGrid?.url?.includes('saucelabs.com'));
     let portRequest;
 
     if (options.port) {
       portRequest = options.port;
-    } else if (useSauce || useRemote) {
+    } else if (useLegacySauce || useRemote) {
       portRequest = 5555;
     } else {
       portRequest = 0;
@@ -122,7 +126,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;
@@ -223,14 +224,20 @@ class Server {
     const tlsCert = serverOptions.tlsCert || this.options.tlsCert;
     const tlsKey = serverOptions.tlsKey || this.options.tlsKey;
     const hostname = serverOptions.hostname || this.options.hostname;
+    // The last two fallbacks here are necessary for backwards compatibility.
+    let listenAddress =
+      serverOptions.listenAddress ||
+      this.options.listenAddress ||
+      hostname ||
+      '';
+
+    if (listenAddress === '*') {
+      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 +267,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';

package/lib/types.js

@@ -52,12 +52,23 @@
  * @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, this should be set to localhost or an equivalent unless you need
+ * the server to be accessible over other network interfaces. Set to "*" to
+ * listen on all interfaces, which may be required by some remote Selenium
+ * grids.
+ * @name ServerCtorOptions#listenAddress
+ * @default The value of {@link ServerCtorOptions#hostname} or {@link ServerStartOptions#hostname} if configured, otherwise "*"
+ * @type string | undefined
+ */
+/**
+ * The hostname to use in the URL given to browsers. For backward compatibility,
+ * setting this property without also setting {@link ServerCtorOptions#listenAddress}
+ * or {@link ServerStartOptions#listenAddress} has the same effect as setting
+ * the listen address to the hostname.
  * @name ServerCtorOptions#hostname
- * @type string
+ * @default "localhost"
+ * @type string | undefined
  */
 /**
  * The root directory of the project.
@@ -304,12 +315,12 @@
  * @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.
+ * @see ServerCtorOptions#hostname
  * @name ServerStartOptions#hostname
- * @type string
+ */
+/**
+ * @see ServerCtorOptions#listenAddress
+ * @name ServerStartOptions#listenAddress
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jasmine-browser-runner",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "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": "^4.19.2",
     "glob": "^10.0.0",
     "selenium-webdriver": "^4.12.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"
-  }
-}