jasmine-browser-runner 2.0.0-beta.1 → 2.1.0

package/README.md

@@ -1,6 +1,3 @@
-[![Build Status](https://circleci.com/gh/jasmine/jasmine-browser.svg?style=shield)](https://circleci.com/gh/jasmine/jasmine-browser)
-
-
 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.
@@ -9,44 +6,34 @@ using either headless Chrome or Saucelabs.
 
 ```bash
 npm install --save-dev jasmine-browser-runner jasmine-core
+npx jasmine-browser-runner init
 ```
 
 or
 
 ```bash
 yarn add -D jasmine-browser-runner jasmine-core
+npx jasmine-browser-runner init
 ```
 
-Add a `spec/support/jasmine-browser.json`. For example:
+If you intend to use ES modules, add `--esm` to the `jasmine-browser-runner init`
+command.
 
-```json
-{
-  "srcDir": "src",
-  "srcFiles": [
-    "**/*.?(m)js"
-  ],
-  "specDir": "spec",
-  "specFiles": [
-    "**/*[Ss]pec.?(m)js"
-  ],
-  "helpers": [
-    "helpers/asyncAwait.js"
-  ],
-  "env": {
-    "random": true
-  }
-}
-```
+Then, customize `spec/support/jasmine-browser.json` 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.
 
-Start the server:
+To start the server so that you can run the specs interactively (particularly
+useful for debugging):
 
 ```
 npx jasmine-browser-runner serve
 ```
 
-Run the tests in a browser (defaults to Firefox)
+To run the specs in a browser (defaults to Firefox):
 
 ```
 npx jasmine-browser-runner runSpecs
@@ -70,7 +57,9 @@ Its value can be `"firefox"`, `"headlessFirefox"`, `"safari"`,
 If a source, spec, or helper file's name ends in `.mjs`, it will be loaded as
 an ES module rather than a regular script. Note that ES modules can only be
 loaded from other ES modules. So if your source files are ES modules, your
-spec files need to be ES modules too.
+spec files need to be ES modules too. Want to use a different extension than
+`.esm`? Just set the `esmFilenameExtension` config property, e.g.
+`"esmFilenameExtension": ".js"`.
 
 To allow spec files to import source files via relative paths, set the `specDir`
 config field to something that's high enough up to include both spec and source
@@ -174,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`
@@ -223,7 +276,7 @@ Firefox, and Microsoft Edge) as well as Node.
 
 | Environment       | Supported versions     |
 |-------------------|------------------------|
-| Node              | 12.17+, 14, 16, 18, 20 |
+| Node              | 18, 20                 |
 | Safari            | 15-16                  |
 | Chrome            | Evergreen              |
 | Firefox           | Evergreen, 102         |

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/examples/default_esm_config.json

@@ -8,6 +8,8 @@
   "helpers": [
     "spec/helpers/**/*.?(m)js"
   ],
+  "esmFilenameExtension": ".mjs",
+  "enableTopLevelAwait": false,
   "env": {
     "stopSpecOnExpectationFailure": false,
     "stopOnSpecFailure": false,

package/lib/server.js

@@ -14,7 +14,7 @@ class Server {
    * @param {ServerCtorOptions} options
    */
   constructor(options) {
-    this.options = options;
+    this.options = { ...options };
     this.useHtmlReporter =
       options.useHtmlReporter === undefined ? true : options.useHtmlReporter;
     this.projectBaseDir = options.projectBaseDir || path.resolve();
@@ -29,6 +29,13 @@ class Server {
         return unWindows(path.join('/__jasmine__', fileName));
       })
       .concat(this.bootFiles());
+
+    if (!this.options.esmFilenameExtension) {
+      this.options.esmFilenameExtension = '.mjs';
+    } else if (this.options.esmFilenameExtension[0] !== '.') {
+      this.options.esmFilenameExtension =
+        '.' + this.options.esmFilenameExtension;
+    }
   }
 
   bootFiles() {
@@ -75,9 +82,9 @@ class Server {
       this.options.srcDir,
       this.options.srcFiles,
       '/__src__'
-    ).filter(function(url) {
+    ).filter(url => {
       // Exclude ES modules. These will be loaded by other ES modules.
-      return !url.endsWith('.mjs');
+      return !url.endsWith(this.options.esmFilenameExtension);
     });
     const helperUrls = this.getUrls(
       this.options.specDir,
@@ -163,6 +170,7 @@ class Server {
             cssFiles: self.allCss(),
             jasmineJsFiles: self.jasmineJs(),
             userJsFiles: self.userJs(),
+            esmFilenameExtension: self.options.esmFilenameExtension,
             importMap: self.importMap(),
             enableTopLevelAwait: self.options.enableTopLevelAwait || false,
           })

package/lib/support/loaders.js

@@ -19,7 +19,10 @@ window._jasmine_loadEsModule = function(src) {
   document.head.appendChild(script);
 };
 
-window._jasmine_loadWithTopLevelAwaitSupport = async function(scriptUrls) {
+window._jasmine_loadWithTopLevelAwaitSupport = async function(
+  scriptUrls,
+  esmFilenameExtension
+) {
   const scriptsLoaded = (async function() {
     // Load scripts sequentially to ensure that users can get a stable order
     // by disabling randomization or setting a seed. This can be considerably
@@ -28,7 +31,7 @@ window._jasmine_loadWithTopLevelAwaitSupport = async function(scriptUrls) {
     // describes will execute in a consistent order in the presence of top-level
     // await.
     for (const url of scriptUrls) {
-      const isEsm = url.endsWith('.mjs');
+      const isEsm = url.endsWith(esmFilenameExtension);
 
       if (isEsm) {
         try {

package/lib/types.js

@@ -70,6 +70,12 @@
  * @name ServerCtorOptions#srcFiles
  * @type string[] | undefined
  */
+/**
+ * The file extension used by ES modules
+ * @name ServerCtorOptions#esmFilenameExtension
+ * @type string | undefined
+ * @default ".mjs"
+ */
 
 /**
  * Specifies the properties of the configuration file, as well as
@@ -137,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".
@@ -148,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}
@@ -195,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-beta.1",
+  "version": "2.1.0",
   "description": "Serve and run your Jasmine specs in a browser",
   "bin": "bin/jasmine-browser-runner",
   "exports": "./index.js",
@@ -43,14 +43,14 @@
     "selenium-webdriver": "^4.8.2"
   },
   "peerDependencies": {
-    "jasmine-core": "^5.0.0-beta.0"
+    "jasmine-core": "^5.0.0"
   },
   "devDependencies": {
     "ejs-lint": "^2.0.0",
     "eslint": "^8.38.0",
     "eslint-plugin-jasmine": "^4.1.3",
-    "jasmine": "^5.0.0-beta.0",
-    "jasmine-core": "^5.0.0-beta.0",
+    "jasmine": "^5.0.0",
+    "jasmine-core": "^5.0.0",
     "prettier": "^1.17.1",
     "shelljs": "^0.8.3",
     "temp": "^0.9.4"

package/run.html.ejs

@@ -24,11 +24,11 @@
         <% userJsFiles.forEach(function(jsFile) { %>
           '<%= jsFile %>',
         <% }) %>
-      ]);
+      ], '<%=esmFilenameExtension%>');
     </script>
   <% } else { %>
     <% userJsFiles.forEach(function(jsFile) { %>
-      <% if (jsFile.endsWith('.mjs')) { %>
+      <% if (jsFile.endsWith(esmFilenameExtension)) { %>
         <script type="module">_jasmine_loadEsModule('<%= jsFile %>')</script>
       <% } else { %>
         <script src="<%= jsFile %>" type="text/javascript"></script>