jasmine-browser-runner 2.0.0-beta.0 → 2.0.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
@@ -68,7 +55,11 @@ Its value can be `"firefox"`, `"headlessFirefox"`, `"safari"`,
 ## ES module support
 
 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.
+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.
+`"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
@@ -78,6 +69,23 @@ running `npx jasmine-browser-runner init --esm`.
 If you have specs or helper files that use top-level await, set the
 `enableTopLevelAwait` config property is set to `true`.
 
+[Import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)
+are also supported:
+
+```javascript
+{
+   // ...
+   "importMap": {
+     "moduleRootDir": "node_modules", 
+     "imports": {
+       "some-lib":"some-lib/dist/index.mjs",
+       "some-lib/": "some-lib/dist/",
+       "some-cdn-lib": "https://example.com/some-cdn-lib"
+      }
+   }
+}
+```
+
 ## Use with Rails
 
 You can use jasmine-browser-runner to test your Rails application's JavaScript,
@@ -204,7 +212,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/bin/jasmine-browser-runner

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
-var path = require('path'),
+ const path = require('path'),
   jasmineCore = require('../lib/jasmineCore'),
   Command = require('../lib/command'),
   jasmineBrowser = require('../index.js');
 const UsageError = require('../lib/usage_error');
 
-var command = new Command({
+ const command = new Command({
   baseDir: path.resolve(),
   jasmineCore,
   jasmineBrowser,

package/lib/command.js

@@ -250,7 +250,7 @@ function wrapDescription(indentLevel, prefixWidth, maxWidth, text) {
     return text;
   }
 
-  var chunks = [];
+  const chunks = [];
   while (text.length > columnWidth) {
     const wrapChar = text.lastIndexOf(' ', columnWidth);
     chunks.push(text.substring(0, wrapChar));

package/lib/config.js

@@ -50,6 +50,10 @@ function validateConfig(config) {
       throw new Error(`Configuration's ${k} property is not an array`);
     }
   }
+
+  if (config.importMap) {
+    validateImportMap(config.importMap);
+  }
 }
 
 function defaultConfig() {
@@ -67,6 +71,83 @@ function defaultEsmConfig() {
   );
 }
 
+function validateImportMap(importMap) {
+  // basic validation, but not the entire spec.
+  // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
+
+  if (typeof importMap !== 'object') {
+    throw new Error("Configuration's importMap property is not an object");
+  }
+
+  if (!importMap.imports && !importMap.scopes) {
+    throw new Error("Configuration's importMap contains no imports or scopes");
+  }
+
+  if (importMap.imports) {
+    validateImports('importMap.imports', importMap.imports);
+  }
+
+  if (importMap.scopes) {
+    for (const [kScope, vScope] of Object.entries(importMap.scopes)) {
+      if (kScope === '') {
+        throw new Error(
+          "Configuration's importMap.scopes cannot contain empty keys"
+        );
+      }
+      if (typeof vScope !== 'object') {
+        throw new Error(
+          "Configuration's importMap.scopes property is not an object"
+        );
+      }
+      validateImports('importMap.scopes', vScope);
+    }
+  }
+
+  const moduleRootDir = importMap.moduleRootDir;
+
+  if (moduleRootDir === '') {
+    throw new Error(
+      'Configuration.importMap.moduleRootDir cannot be an empty string'
+    );
+  } else if (moduleRootDir && moduleRootDir.startsWith('../')) {
+    throw new Error(
+      'Configuration.importMap.moduleRootDir cannot start with ../'
+    );
+  }
+}
+
+// Both importMap.imports and importMap.scopes[k].value should be an object with
+// module specifiers, hence this helper function for DRY.
+// @param context `importMap.imports` | `importMap.scopes`
+// @param module specifier map of string -> string
+function validateImports(context, imports) {
+  if (typeof imports !== 'object') {
+    throw new Error(`Configuration's ${context} property is not an object`);
+  }
+
+  if (Object.keys(imports).length === 0) {
+    throw new Error(`Configuration's ${context} map cannot be empty`);
+  }
+
+  for (const [kImport, vImport] of Object.entries(imports)) {
+    if (kImport === '') {
+      throw new Error(
+        `Configuration's ${context} map cannot contain empty string keys`
+      );
+    }
+
+    if (vImport === '') {
+      throw new Error(
+        `Configuration's ${context} map cannot contain empty string values`
+      );
+    }
+
+    if (typeof vImport !== 'string') {
+      throw new Error(`Configuration's ${context} map value is not a string`);
+    }
+  }
+}
+
 module.exports = {
   loadConfig,
   validateConfig,

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() {
@@ -40,7 +47,7 @@ class Server {
   }
 
   allCss() {
-    var urls = this.getUrls(
+    const urls = this.getUrls(
       this.options.srcDir,
       this.options.cssFiles,
       '/__src__'
@@ -71,20 +78,20 @@ class Server {
   }
 
   userJs() {
-    var srcUrls = this.getUrls(
+    const srcUrls = this.getUrls(
       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);
     });
-    var helperUrls = this.getUrls(
+    const helperUrls = this.getUrls(
       this.options.specDir,
       this.options.helpers,
       '/__spec__'
     );
-    var specUrls = this.getUrls(
+    const specUrls = this.getUrls(
       this.options.specDir,
       this.options.specFiles,
       '/__spec__'
@@ -92,6 +99,33 @@ class Server {
     return [].concat(srcUrls, helperUrls, specUrls);
   }
 
+  // Bound property for ejs template, used to inject a `<script
+  // type="importmap">` tag. This changes specifier target values for any
+  // relative module paths according to `this.options.importMap.moduleRootDir`.
+  // @returns ImportMap | undefined
+  importMap() {
+    const { importMap } = this.options;
+    if (!importMap) {
+      return undefined;
+    }
+
+    const resultMap = {};
+
+    if (importMap.imports) {
+      resultMap.imports = reifyRawSpecifierMap(importMap.imports);
+    }
+
+    if (importMap.scopes) {
+      resultMap.scopes = {};
+
+      for (const [scope, map] of Object.entries(importMap.scopes)) {
+        resultMap.scopes[scope] = reifyRawSpecifierMap(map);
+      }
+    }
+
+    return resultMap;
+  }
+
   /**
    * Starts the server.
    * @param {ServerStartOptions} options
@@ -99,7 +133,7 @@ class Server {
    */
   start(serverOptions) {
     serverOptions = serverOptions || {};
-    var app = express();
+    const app = express();
 
     app.use('/__jasmine__', express.static(this.jasmineCore.files.path));
     app.use('/__boot__', express.static(this.jasmineCore.files.bootDir));
@@ -114,14 +148,21 @@ class Server {
       express.static(path.join(this.projectBaseDir, this.options.srcDir))
     );
 
-    var indexTemplate = ejs.compile(
+    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));
+    }
+
+    const indexTemplate = ejs.compile(
       fs.readFileSync(path.resolve(__dirname, '../run.html.ejs')).toString()
     );
-    var configTemplate = ejs.compile(
+    const configTemplate = ejs.compile(
       fs.readFileSync(path.resolve(__dirname, '../config.js.ejs')).toString()
     );
 
-    var self = this;
+    const self = this;
     app.get('/', function(req, res) {
       try {
         res.send(
@@ -129,6 +170,8 @@ class Server {
             cssFiles: self.allCss(),
             jasmineJsFiles: self.jasmineJs(),
             userJsFiles: self.userJs(),
+            esmFilenameExtension: self.options.esmFilenameExtension,
+            importMap: self.importMap(),
             enableTopLevelAwait: self.options.enableTopLevelAwait || false,
           })
         );
@@ -151,7 +194,7 @@ class Server {
       }
     });
 
-    var port = findPort(serverOptions.port, this.options.port);
+    const port = findPort(serverOptions.port, this.options.port);
     return new Promise(resolve => {
       this._httpServer = app.listen(port, () => {
         const runningPort = this._httpServer.address().port;
@@ -258,4 +301,22 @@ function unWindows(filePath) {
   return filePath.replace(/\\/g, '/');
 }
 
+// Processes the incoming `rawSpecifierMap`, converting targets to use actual
+// 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) {
+  const concreteMap = {};
+
+  for (const [key, value] of Object.entries(rawSpecifierMap)) {
+    if (value.match(/^https?:\/\//)) {
+      concreteMap[key] = value; // pass through unchanged
+    } else {
+      concreteMap[key] = './' + unWindows(path.join('__moduleRoot__', value));
+    }
+  }
+
+  return concreteMap;
+}
+
 module.exports = Server;

package/lib/support/batchReporter.js

@@ -1,9 +1,9 @@
 /* eslint-env browser, jasmine */
 function BatchReporter() {
-  var events = [];
+  let events = [];
 
   this.getBatch = function() {
-    var result = events;
+    const result = events;
     events = [];
     return result;
   };

package/lib/support/loaders.js

@@ -1,14 +1,14 @@
 /* eslint-env browser, jasmine */
 
 window._jasmine_loadEsModule = function(src) {
-  var script = document.createElement('script');
+  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) {
-    var msg =
+    const msg =
       'An error occurred while loading ' +
       src +
       '. Check the browser console for details.';
@@ -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
@@ -111,6 +117,14 @@
  * @type boolean | undefined
  * @default true
  */
+/**
+ * Import maps entry to generate the `<script type="importmap">` section in the
+ * `<head>`, to enable ES Module testing in the browser.
+ *
+ * @name Configuration#importMap
+ * @type ImportMap | undefined
+ * @default undefined
+ */
 /**
  * Whether to enable support for top-level await. This option is off by default
  * because it comes with a performance penalty.
@@ -197,3 +211,37 @@
  * @name ServerStartOptions#port
  * @type number | undefined
  */
+
+/**
+ * Describes an import map.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap}
+ * @see {@link https://github.com/WICG/import-maps}
+ * @interface ImportMap
+ */
+/**
+ * A single, unscoped module specifier map.
+ * @name ImportMap#imports
+ * @type {Object.<string, string>}
+ */
+/**
+ * Map of one or more scoped module specifier maps.
+ * @name ImportMap#scopes
+ * @type {Object.<string, Object.<string, string>>}
+ */
+/**
+ * Optional directory that specifies the root for relative paths in import map
+ * (if required).
+ *
+ * For example, if you only use import paths that resolve to absolute targets,
+ * e.g.  'my-pkg': 'https://mycdn.url/my-pkg', then you do not need this dir
+ * option. But if you need to reference a folder, e.g. `node_modules`, then this
+ * is required.
+ *
+ * moduleRootDir is evaluated relative to the project base directory, which is
+ * typically the current working directory from which jasmine-browser-runner is
+ * run.
+ *
+ * @name ImportMap#moduleRootDir
+ * @type string
+ * @example 'node_modules'
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jasmine-browser-runner",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.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"
@@ -115,7 +115,8 @@
         "always"
       ],
       "space-before-blocks": "error",
-      "no-console": "off"
+      "no-console": "off",
+      "no-var": "error"
     },
     "overrides": [
       {

package/run.html.ejs

@@ -8,6 +8,11 @@
   <% cssFiles.forEach(function(cssFile) { %>
     <link rel="stylesheet" href="<%= cssFile %>" type="text/css" media="screen"/>
   <% }) %>
+  <% if (importMap) { %>
+    <script type="importmap">
+    <%- JSON.stringify(importMap, null, 2) %>
+    </script>
+  <% } %>
 </head>
 <body>
   <% jasmineJsFiles.forEach(function(jsFile) { %>
@@ -19,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>