jasmine-browser-runner 3.0.0-beta.2 → 3.0.0

package/MIT.LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2019 Pivotal Labs
-Copyright (c) 2020-2024 The Jasmine developers
+Copyright (c) 2020-2025 The Jasmine developers
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/README.md

@@ -56,7 +56,7 @@ To use a browser other than Firefox, add a `browser` field to
 ```javascript
 export default {
   // ...
-  "browser": "chrome"
+  browser: "chrome"
 }
 ```
 
@@ -71,8 +71,8 @@ in PEM format in `jasmine-browser.mjs`:
 ```javascript
 export default {
   // ...
-  "tlsKey": "/path/to/tlsKey.pem",
-  "tlsCert": "/path/to/tlsCert.pem",
+  tlsKey: "/path/to/tlsKey.pem",
+  tlsCert: "/path/to/tlsCert.pem",
   // ...
 }
 ```
@@ -85,38 +85,41 @@ 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. 
+**Note: This behavior differs between 2.x and 3.x. If you are using 2.x, please
+consult the README for the version you're using.**
+
+By default, jasmine-browser-runner listens to the network interface that
+corresponds to localhost. To listen on a different interface, set `listenAddress`
+to the corresponding hostname or IP address. To listen on all available network
+interfaces, set `listenAddress` to `"*"`. You might need to do that if you're
+using a remote grid such as Saucelabs.
 
 ```javascript
 export default {
   // ...
-  "listenAddress": "localhost",
+  listenAddress: "*",
   // ...
 }
 ```
 
 ## Hostname support
 
+**Note: This behavior differs between 2.x and 3.x. If you are using 2.x, please
+consult the README for the version you're using.**
+
 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",
+  hostname: "mymachine.mynetwork",
   // ...
 }
 ```
 
 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
@@ -145,7 +148,7 @@ 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. Want to use a different extension than
-`.esm`? Just set the `esmFilenameExtension` config property, e.g.
+`.mjs`? Just set the `esmFilenameExtension` config property, e.g.
 `"esmFilenameExtension": ".js"`.
 
 To allow spec files to import source files via relative paths, set the `specDir`
@@ -153,8 +156,11 @@ config field to something that's high enough up to include both spec and source
 files, and set `srcFiles` to `[]`. You can autogenerate such a configuration by
 running `npx jasmine-browser-runner init --esm`.
 
+If you want to load ES module source directly on load instead of loading it from
+the corresponding spec, set the `modulesWithSideEffectsInSrcFiles` config property to `true`.
+
 If you have specs or helper files that use top-level await, set the
-`enableTopLevelAwait` config property is set to `true`.
+`enableTopLevelAwait` config property to `true`.
 
 [Import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
 are also supported:
@@ -326,7 +332,7 @@ import jasmineBrowser from 'jasmine-browser-runner';
 import config from './spec/support/jasmine-browser.mjs';
 
 config.projectBaseDir = path.resolve('some/path');
-jasmineBrowser.startServer(config, { port: 4321 });
+jasmineBrowser.startServer(config);
 
 
 // CommonJS
@@ -336,7 +342,7 @@ 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 });
+    jasmineBrowser.startServer(config);
   });
 ```
 
@@ -348,7 +354,7 @@ Firefox, and Microsoft Edge) as well as Node.
 | Environment       | Supported versions         |
 |-------------------|----------------------------|
 | Node              | 18, 20, 22                 |
-| Safari            | 15*, 16, 17                |
+| Safari            | 15*, 16*, 17*              |
 | Chrome            | Evergreen                  |
 | Firefox           | Evergreen, 102*, 115*, 128 |
 | Edge              | Evergreen                  |
@@ -359,13 +365,13 @@ browsers, as well as older & newer versions of some supported browsers, are
 likely to work. However, jasmine-browser-runner isn't tested against them and 
 they aren't actively supported.
 
-\* Environments that are past end of life are supported on a best-effort
-basis. They may be dropped in a future minor release if continued support
-becomes impractical.
+\* Supported on a best-effort basis. Support for these versions may be dropped
+if it becomes impractical, and bugs affecting only these versions may not be
+treated as release blockers.
 
 
 To find out what environments work with a particular Jasmine release, see the [release notes](https://github.com/jasmine/jasmine/tree/main/release_notes).
 
 Copyright (c) 2019 Pivotal Labs<br>
-Copyright (c) 2020-2024 The Jasmine developers<br>
+Copyright (c) 2020-2025 The Jasmine developers<br>
 This software is licensed under the MIT License.

package/lib/examples/default_esm_config.mjs

@@ -11,6 +11,8 @@ export default {
     "spec/helpers/**/*.?(m)js"
   ],
   esmFilenameExtension: ".mjs",
+  // Set to true if you need to load module src files instead of loading via the spec files.
+  modulesWithSideEffectsInSrcFiles: false,
   // 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,

package/lib/runner.js

@@ -8,11 +8,6 @@ function getBatch(driver) {
       'if (results[i][1].passedExpectations) {\n' +
       'expectations = expectations.concat(results[i][1].passedExpectations);\n' +
       '}\n' +
-      'for (var j = 0; j < expectations.length; j++) {\n' +
-      'var expectation = expectations[j];\n' +
-      "try { JSON.stringify(expectation.expected); } catch (e) { expectation.expected = '<circular expected>'; }\n" +
-      "try { JSON.stringify(expectation.actual); } catch (e) { expectation.actual = '<circular actual>'; }\n" +
-      '}\n' +
       '}\n' +
       'return results;'
   );

package/lib/server.js

@@ -82,8 +82,11 @@ class Server {
       this.options.srcFiles,
       '/__src__'
     ).filter(url => {
-      // Exclude ES modules. These will be loaded by other ES modules.
-      return !url.endsWith(this.options.esmFilenameExtension);
+      // Exclude ES modules by default. These will be loaded by other ES modules.
+      return (
+        this.options.modulesWithSideEffectsInSrcFiles ||
+        !url.endsWith(this.options.esmFilenameExtension)
+      );
     });
     const helperUrls = this.getUrls(
       this.options.specDir,
@@ -111,14 +114,22 @@ class Server {
     const resultMap = {};
 
     if (importMap.imports) {
-      resultMap.imports = reifyRawSpecifierMap(importMap.imports);
+      resultMap.imports = reifyRawSpecifierMap(
+        importMap.imports,
+        this.options,
+        this.projectBaseDir
+      );
     }
 
     if (importMap.scopes) {
       resultMap.scopes = {};
 
       for (const [scope, map] of Object.entries(importMap.scopes)) {
-        resultMap.scopes[scope] = reifyRawSpecifierMap(map);
+        resultMap.scopes[scope] = reifyRawSpecifierMap(
+          map,
+          this.options,
+          this.projectBaseDir
+        );
       }
     }
 
@@ -191,6 +202,8 @@ class Server {
             esmFilenameExtension: self.options.esmFilenameExtension,
             importMap: self.importMap(),
             enableTopLevelAwait: self.options.enableTopLevelAwait || false,
+            modulesWithSideEffectsInSrcFiles:
+              self.options.modulesWithSideEffectsInSrcFiles || false,
           })
         );
       } catch (error) {
@@ -372,14 +385,32 @@ function unWindows(filePath) {
 // paths that the run.html.ejs file will contain.  The `rawSpecifierMap` is not
 // the entire importMap. It is a key/value map that may be the "imports" value
 // or an individual map inside of "scopes"[someScope].
-function reifyRawSpecifierMap(rawSpecifierMap) {
+function reifyRawSpecifierMap(rawSpecifierMap, options, projectBaseDir) {
   const concreteMap = {};
+  const absoluteModuleRootDir = options.importMap.moduleRootDir
+    ? path.resolve(projectBaseDir, options.importMap.moduleRootDir)
+    : projectBaseDir;
 
   for (const [key, value] of Object.entries(rawSpecifierMap)) {
     if (value.match(/^https?:\/\//)) {
       concreteMap[key] = value; // pass through unchanged
-    } else {
+      continue;
+    }
+
+    const absolutePath = path.join(absoluteModuleRootDir, value);
+    const endsWithSeparator = value.endsWith('/') || value.endsWith('\\');
+
+    const resolvedSrcDir = path.join(absoluteModuleRootDir, options.srcDir);
+    const relativeFromSrcDir = path.relative(resolvedSrcDir, absolutePath);
+
+    if (relativeFromSrcDir.startsWith('..')) {
       concreteMap[key] = './' + unWindows(path.join('__moduleRoot__', value));
+    } else {
+      // We are under srcDir: Reuse existing __src__ path
+      concreteMap[key] =
+        './' +
+        unWindows(path.join('__src__', relativeFromSrcDir)) +
+        (endsWithSeparator ? '/' : '');
     }
   }
 

package/lib/support/batchReporter.js

@@ -21,16 +21,31 @@ function BatchReporter() {
   };
 
   this.jasmineDone = function(info) {
+    deleteExpectedAndActual(info);
     events.push(['jasmineDone', info]);
   };
 
   this.suiteDone = function(info) {
+    deleteExpectedAndActual(info);
     events.push(['suiteDone', info]);
   };
 
   this.specDone = function(info) {
+    deleteExpectedAndActual(info);
     events.push(['specDone', info]);
   };
+
+  function deleteExpectedAndActual(info) {
+    for (const e of info.failedExpectations) {
+      // Delete expected and actual. Not all JS objects are serializable, we
+      // don't have a reliable way to determine what Selenium can and can't
+      // serialize, not everything that's serializable survives the process
+      // intact, and there are no known reporters that use the expected or
+      // actual properties of expectation results.
+      delete e.expected;
+      delete e.actual;
+    }
+  }
 }
 
 window.batchReporter = new BatchReporter();

package/lib/support/loaders.js

@@ -1,24 +1,5 @@
 /* eslint-env browser, jasmine */
 
-window._jasmine_loadEsModule = function(src) {
-  const script = document.createElement('script');
-  script.type = 'module';
-
-  // Safari reports syntax errors in ES modules as a script element error
-  // event rather than a global error event. Rethrow so that Jasmine can
-  // pick it up and fail the suite.
-  script.addEventListener('error', function(event) {
-    const msg =
-      'An error occurred while loading ' +
-      src +
-      '. Check the browser console for details.';
-    throw new Error(msg);
-  });
-
-  script.src = src;
-  document.head.appendChild(script);
-};
-
 window._jasmine_loadWithTopLevelAwaitSupport = async function(
   scriptUrls,
   esmFilenameExtension

package/lib/types.js

@@ -153,6 +153,16 @@
  * @type boolean | undefined
  * @default false
  */
+/**
+ * If set to true jasmine loads also ES Modules which are included in SrcFiles.
+ * This option is off by default because in most scenarios it is better to load the
+ * module under test from the test itself.
+ * But if the module has wanted side effects (like for example polyfills) you can
+ * interleave ES module and classic scripts in your SrcFiles.
+ * @name Configuration#modulesWithSideEffectsInSrcFiles
+ * @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

package/package.json

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

package/run.html.ejs

@@ -29,7 +29,9 @@
   <% } else { %>
     <% userJsFiles.forEach(function(jsFile) { %>
       <% if (jsFile.endsWith(esmFilenameExtension)) { %>
-        <script type="module">_jasmine_loadEsModule('<%= jsFile %>')</script>
+        <script src="<%= jsFile %>" type="module"></script>
+      <% } else if (modulesWithSideEffectsInSrcFiles) { %>
+        <script src="<%= jsFile %>" type="text/javascript" defer></script>
       <% } else { %>
         <script src="<%= jsFile %>" type="text/javascript"></script>
       <% } %>