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

package/README.md

@@ -68,7 +68,9 @@ 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.
 
 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 +80,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,

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/server.js

@@ -40,7 +40,7 @@ class Server {
   }
 
   allCss() {
-    var urls = this.getUrls(
+    const urls = this.getUrls(
       this.options.srcDir,
       this.options.cssFiles,
       '/__src__'
@@ -71,7 +71,7 @@ class Server {
   }
 
   userJs() {
-    var srcUrls = this.getUrls(
+    const srcUrls = this.getUrls(
       this.options.srcDir,
       this.options.srcFiles,
       '/__src__'
@@ -79,12 +79,12 @@ class Server {
       // Exclude ES modules. These will be loaded by other ES modules.
       return !url.endsWith('.mjs');
     });
-    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 +92,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 +126,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 +141,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 +163,7 @@ class Server {
             cssFiles: self.allCss(),
             jasmineJsFiles: self.jasmineJs(),
             userJsFiles: self.userJs(),
+            importMap: self.importMap(),
             enableTopLevelAwait: self.options.enableTopLevelAwait || false,
           })
         );
@@ -151,7 +186,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 +293,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.';

package/lib/types.js

@@ -111,6 +111,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 +205,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-beta.1",
   "description": "Serve and run your Jasmine specs in a browser",
   "bin": "bin/jasmine-browser-runner",
   "exports": "./index.js",
@@ -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) { %>