jasmine-browser-runner 2.0.0 → 2.2.0

package/README.md

@@ -163,7 +163,71 @@ To run the specs:
 2. Run `npx jasmine-browser-runner`.
 3. Visit <http://localhost:8888>.
 
-## Saucelabs support
+## Remote Grid support (Saucelabs, BrowserStack, etc.)
+
+jasmine-browser-runner can run your Jasmine specs on a remote grid
+provider like [Saucelabs](https://saucelabs.com/), 
+[BrowserStack](https://browserstack.com) or your own Selenium Grid.
+To use a remote grid hub, set the `browser` object
+in your config file as follows:
+
+```json
+// jasmine-browser.json
+{
+  // ...
+  // BrowserStack
+  "browser": {
+    "name": "safari",
+    "useRemoteSeleniumGrid": true,
+    "remoteSeleniumGrid": {
+      "url": "https://hub-cloud.browserstack.com/wd/hub",
+      "bstack:options": {
+        "browserVersion": "16",
+        "os": "OS X",
+        "osVersion": "Monterey",
+        "local": "true",
+        "localIdentifier": "tunnel ID",
+        "debug": "true",
+        "userName": "your BrowserStack username",
+        "accessKey": "your BrowserStack access key"
+      }
+    }
+  }
+}
+```
+```json
+// jasmine-browser.json
+{
+  // ...
+  // Saucelabs
+  "browser": {
+    "name": "safari",
+    "useRemoteSeleniumGrid": true,
+    "remoteSeleniumGrid": {
+      "url": "https://ondemand.saucelabs.com/wd/hub",
+      "platformName": "macOS 12",
+      "sauce:options": {
+        "tunnel-identifier": "tunnel ID",
+        "userName": "your Saucelabs username",
+        "accessKey": "your Saucelabs access key"
+      }
+    }
+  }
+}
+```
+
+When using a remote grid provider, all properties of the `browser` object are
+optional except for `name` which will be passed as the `browserName` capability,
+and `useRemoteSeleniumGrid` which must be set to a value of `true`. if a
+`remoteSeleniumGrid` object is included, any values it contains, with the
+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`

package/index.js

@@ -81,11 +81,14 @@ module.exports = {
 
     const reporters = await createReporters(options, deps);
     const useSauce = options.browser && options.browser.useSauce;
+    const useRemote = options.browser && options.browser.useRemoteSeleniumGrid;
     let portRequest;
 
-    if (useSauce) {
+    if (useSauce || useRemote) {
       if (options.port) {
-        throw new Error("Can't specify a port when browser.useSauce is true");
+        throw new Error(
+          "Can't specify a port when browser.useSauce or browser.useRemoteSeleniumGrid is true"
+        );
       }
 
       portRequest = 5555;

package/lib/server.js

@@ -1,4 +1,4 @@
-const express = require('express'),
+const defaultExpress = require('express'),
   glob = require('glob'),
   ejs = require('ejs'),
   path = require('path'),
@@ -15,6 +15,7 @@ class Server {
    */
   constructor(options) {
     this.options = { ...options };
+    this.express = this.options.express || defaultExpress;
     this.useHtmlReporter =
       options.useHtmlReporter === undefined ? true : options.useHtmlReporter;
     this.projectBaseDir = options.projectBaseDir || path.resolve();
@@ -133,26 +134,40 @@ class Server {
    */
   start(serverOptions) {
     serverOptions = serverOptions || {};
-    const app = express();
+    const app = this.express();
 
-    app.use('/__jasmine__', express.static(this.jasmineCore.files.path));
-    app.use('/__boot__', express.static(this.jasmineCore.files.bootDir));
-    app.use('/__images__', express.static(this.jasmineCore.files.imagesDir));
-    app.use('/__support__', express.static(path.join(__dirname, 'support')));
+    app.use('/__jasmine__', this.express.static(this.jasmineCore.files.path));
+    app.use('/__boot__', this.express.static(this.jasmineCore.files.bootDir));
+    app.use(
+      '/__images__',
+      this.express.static(this.jasmineCore.files.imagesDir)
+    );
+    app.use(
+      '/__support__',
+      this.express.static(path.join(__dirname, 'support'))
+    );
     app.use(
       '/__spec__',
-      express.static(path.join(this.projectBaseDir, this.options.specDir))
+      this.express.static(path.join(this.projectBaseDir, this.options.specDir))
     );
     app.use(
       '/__src__',
-      express.static(path.join(this.projectBaseDir, this.options.srcDir))
+      this.express.static(path.join(this.projectBaseDir, this.options.srcDir))
     );
 
+    if (this.options.middleware) {
+      for (const [path, middleware] of Object.entries(
+        this.options.middleware
+      )) {
+        app.use(path, middleware);
+      }
+    }
+
     if (this.options.importMap) {
       const dir = this.options.importMap.moduleRootDir
         ? path.join(this.projectBaseDir, this.options.importMap.moduleRootDir)
         : this.projectBaseDir;
-      app.use('/__moduleRoot__', express.static(dir));
+      app.use('/__moduleRoot__', this.express.static(dir));
     }
 
     const indexTemplate = ejs.compile(

package/lib/types.js

@@ -132,6 +132,29 @@
  * @type boolean | undefined
  * @default false
  */
+/**
+ * <p>An optional map from paths to Express application middleware to mount on
+ * those paths. This can be used to serve static files, proxy requests to
+ * another server, etc.
+ * <p>Note: Requests made by jasmine-browser-runner (e.g. /, /__jasmine__/*,
+ * /__spec__/*, etc) are considered private APIs for semver purposes. If you
+ * configure middleware that modifies these requests and responses, there is a
+ * possibility that future jasmine-browser-runner releases, including minor and
+ * patch releases, may be incompatible with that middleware.
+ * @example
+ * // jasmine-browser.js
+ * const express = require('express');
+ *
+ * module.exports = {
+ *   // ...
+ *   middleware: {
+ *     '/assets': express.static('./path/to/assets')
+ *   }
+ * }
+ * @name Configuration#middleware
+ * @type object | undefined
+ * @default undefined
+ */
 
 /**
  * Describes a web browser.
@@ -143,6 +166,12 @@
  * @name BrowserInfo#useSauce
  * @type boolean | undefined
  */
+/**
+ * Whether to run the specs on a remote Selenium grid.
+ * Defaults to false.
+ * @name BrowserInfo#useRemoteSeleniumGrid
+ * @type boolean | undefined
+ */
 /**
  * The browser name. Valid values include "firefox", "headlessFirefox",
  * "safari", "MicrosoftEdge", "chrome", and "headlessChrome".
@@ -154,6 +183,11 @@
  * @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}
@@ -201,6 +235,32 @@
  * @type Array.<string>
  */
 
+/**
+ * Configuration for running specs on a remote Selenium grid
+ * Any additional properties, such as "sauce:options" or "bstack:options", will
+ * be included in the capabilities object passed through to Selenium Webdriver.
+ * @interface RemoteSeleniumGridConfig
+ * @example
+ * {
+ *    "url": "https://hub-cloud.browserstack.com/wd/hub",
+ *    "bstack:options": {
+ *      "browserVersion": "16",
+ *      "os": "OS X",
+ *      "osVersion": "Monterey",
+ *      "local": "true",
+ *      "localIdentifier": "tunnel ID",
+ *      "debug": "true",
+ *      "userName": "your BrowserStack username",
+ *      "accessKey": "your BrowserStack access key"
+ *    }
+ *  }
+ */
+/**
+ * URL of the remote Selenium grid
+ * @name RemoteSeleniumGridConfig#url
+ * @type string
+ */
+
 /**
  * Options passed to {@link Server#start}
  * @interface

package/lib/webdriver.js

@@ -4,6 +4,8 @@ function buildWebdriver(browserInfo, webdriverBuilder) {
 
   webdriverBuilder = webdriverBuilder || new webdriver.Builder();
   const useSauce = typeof browserInfo === 'object' && browserInfo.useSauce;
+  const useRemote =
+    typeof browserInfo === 'object' && browserInfo.useRemoteSeleniumGrid;
   let browserName;
 
   if (typeof browserInfo === 'string') {
@@ -14,7 +16,7 @@ function buildWebdriver(browserInfo, webdriverBuilder) {
 
   browserName = browserName || 'firefox';
 
-  if (!useSauce) {
+  if (!(useRemote || useSauce)) {
     if (browserName === 'headlessChrome') {
       const caps = webdriver.Capabilities.chrome();
       caps.set('goog:chromeOptions', {
@@ -44,26 +46,46 @@ function buildWebdriver(browserInfo, webdriverBuilder) {
     }
   }
 
-  const sauce = browserInfo.sauce;
-  const capabilities = {
-    [Capability.BROWSER_NAME]: browserName,
-    build: sauce.build,
-    tags: sauce.tags,
-  };
+  let url;
+  let capabilities;
+  if (useRemote) {
+    const remote = browserInfo.remoteSeleniumGrid;
+    if (remote) {
+      url = remote.url;
+      capabilities = {
+        ...remote,
+        [Capability.BROWSER_NAME]: browserName,
+      };
+      delete capabilities.url;
+    }
+  } else if (useSauce) {
+    // handle legacy `sauce` object
+    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,
-  };
+      capabilities[Capability.PLATFORM_NAME] = sauce.os;
+      capabilities[Capability.BROWSER_VERSION] = sauce.browserVersion;
+      capabilities['sauce:options'] = {
+        'tunnel-identifier': sauce.tunnelIdentifier,
+      };
+    }
+  }
+
+  if (!capabilities) {
+    capabilities = {
+      [Capability.BROWSER_NAME]: browserName,
+    };
+  }
 
   return webdriverBuilder
     .withCapabilities(capabilities)
-    .usingServer(
-      browserInfo.useSauce
-        ? `http://${sauce.username}:${sauce.accessKey}@ondemand.saucelabs.com/wd/hub`
-        : 'http://@localhost:4445/wd/hub'
-    )
+    .usingServer(url || 'http://localhost:4445/wd/hub')
     .build();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jasmine-browser-runner",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Serve and run your Jasmine specs in a browser",
   "bin": "bin/jasmine-browser-runner",
   "exports": "./index.js",