jasmine-browser-runner 2.0.0 → 2.1.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/types.js

@@ -143,6 +143,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 +160,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 +212,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.1.0",
   "description": "Serve and run your Jasmine specs in a browser",
   "bin": "bin/jasmine-browser-runner",
   "exports": "./index.js",