permalink: 'testing/karma-esm.html' title: karma-esm section: guides tags:

- guides

Notice

We have stopped new development of this package.

We will continue to support security patches and bug fixes, but we recommend web test runner for testing web component projects.

karma-esm

Karma plugin for testing with real es modules without any bundling.

Out the box es modules don't work with karma because they import their dependencies at runtime from the browser. Karma doesn't allow requesting any files it doesn't know about upfront.

The karma-esm plugin fixes this and spins up es-dev-server behind the scenes. This lets you write tests using es modules, modern javascript syntax, and features, and have karma run them on all modern browsers and IE11.

es-dev-server takes care of loading the correct polyfills, and runs babel for older browsers if necessary. On browsers which don't support es modules, dynamic imports and/or import.meta.url, systemjs is used as a module polyfill.

See the es-dev-server docs for full details on how it works.

Usage

We recommend the testing-karma configuration for a good default karma setup which includes karma-esm and many other good defaults.

Manual setup

To manually set up this plugin, add it as a karma framework:

1. Install the plugin

npm i -D @open-wc/karma-esm

1. Add to your karma config

module.exports = {
  // define where your test files are, make sure to set type to module
  files: [
    { pattern: 'test/**/*.test.js', type: 'module' }
  ]

  plugins: [
    // load plugin
    require.resolve('@open-wc/karma-esm'),

    // fallback: resolve any karma- plugins
    'karma-*',
  ],

  frameworks: ['esm'],

  esm: {
    // if you are using 'bare module imports' you will need this option
    nodeResolve: true,
  },
}

Configuration

karma-esm can be configured with these options:

nodeResolve

Node resolve is necessary when you have 'bare imports' in your code and are not using import maps to resolve them.

It transforms: import foo from 'bar' to: import foo from './node_modules/bar/bar.js.

See the node-resolve documentation of es-dev-server for more information.

coverage

Due to a bug in karma, the test coverage reporter causes browser logs to appear twice which can be annoying

importMap

Allows controlling the behavior of ES imports according to the (in progress) spec. Since this feature is not enabled by default, is necessary to launch Chrome with --enable-experimental-web-platform-features flag.

In karma.config.js add:

customLaunchers: {
  ChromeHeadlessNoSandbox: {
    base: 'ChromeHeadless',
    flags: [
      '--no-sandbox', //default karma-esm configuration
      '--disable-setuid-sandbox', //default karma-esm configuration
      '--enable-experimental-web-platform-features' // necessary when using importMap option
    ],
  },
}

compatibility

The compatibility option makes your code compatible with older browsers. It loads polyfills and transforms modern syntax where needed.

See the compatibility documentation of es-dev-server for more information.

preserveSymlinks

The es-dev-server by default resolves the symlinks in the dependency directory. This can cause a problem when you're using npm link command or other tools which rely on them. This option will make es-dev-server preserve symlinks.

Karma preprocessors

Unfortunately, to make karma work with es modules regular karma preprocessors no longer work. You can, however, configure the es-dev-server to do code transformations if needed.

Custom babel plugins

You can configure karma-esm to pick up the babel configuration files in your project:

{
  esm: {
    babel: true
  },
}

Testing typescript

Because karma-esm doesn't do any bundling, it's easy to integrate it with typescript and doesn't require any extra tooling or plugins. Just run tsc on your code, and test the compiled output with karma-esm. You can run both tsc and karma in watch mode, changes will be picked up automatically.

Make sure to configure tsc to output real ES modules.

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

4.0.0 (2020-12-06)

BREAKING CHANGES

Updated to es-dev-server v2, which uses @rollup/plugin-node-resolve v11

3.0.9 (2020-10-11)

Note: Version bump only for package @open-wc/karma-esm

3.0.8 (2020-10-03)

Note: Version bump only for package @open-wc/karma-esm

3.0.7 (2020-10-01)

Note: Version bump only for package @open-wc/karma-esm

3.0.6 (2020-09-25)

Note: Version bump only for package @open-wc/karma-esm

3.0.5 (2020-08-27)

Note: Version bump only for package @open-wc/karma-esm

3.0.4 (2020-08-19)

Note: Version bump only for package @open-wc/karma-esm

3.0.3 (2020-08-10)

Note: Version bump only for package @open-wc/karma-esm

3.0.2 (2020-08-04)

Note: Version bump only for package @open-wc/karma-esm

3.0.1 (2020-07-29)

Note: Version bump only for package @open-wc/karma-esm

3.0.0 (2020-07-24)

Features

• testing-karma: use up to date coverage reporter (e853364), closes #1164

BREAKING CHANGES

• testing-karma: coverageIstanbulReporter object in karma config has been replaced with coverageReporter move from karma-coverage-istanbul-reporter to karma-coverage

See MIGRATION.md for more info.

2.16.18 (2020-07-24)

Note: Version bump only for package @open-wc/karma-esm

2.16.17 (2020-07-10)

Note: Version bump only for package @open-wc/karma-esm

2.16.16 (2020-06-25)

Note: Version bump only for package @open-wc/karma-esm

2.16.15 (2020-06-22)

Note: Version bump only for package @open-wc/karma-esm

2.16.14 (2020-06-11)

Note: Version bump only for package @open-wc/karma-esm

2.16.13 (2020-06-05)

Note: Version bump only for package @open-wc/karma-esm

2.16.12 (2020-05-29)

Note: Version bump only for package @open-wc/karma-esm

2.16.11 (2020-05-25)

Note: Version bump only for package @open-wc/karma-esm

2.16.10 (2020-05-24)

Note: Version bump only for package @open-wc/karma-esm

2.16.9 (2020-05-24)

Note: Version bump only for package @open-wc/karma-esm

2.16.8 (2020-05-22)

Note: Version bump only for package @open-wc/karma-esm

2.16.7 (2020-05-21)

Note: Version bump only for package @open-wc/karma-esm

2.16.6 (2020-05-17)

Note: Version bump only for package @open-wc/karma-esm

2.16.5 (2020-05-16)

Note: Version bump only for package @open-wc/karma-esm

2.16.4 (2020-05-16)

Note: Version bump only for package @open-wc/karma-esm

2.16.3 (2020-05-15)

Note: Version bump only for package @open-wc/karma-esm

2.16.2 (2020-05-15)

Note: Version bump only for package @open-wc/karma-esm

2.16.1 (2020-05-14)

Note: Version bump only for package @open-wc/karma-esm

2.16.0 (2020-05-14)

Features

• karma-esm: allow setting es-dev-server plugins (3ccc078)

2.15.0 (2020-05-14)

Features

• es-dev-server: add plugin system (2497345)

2.14.2 (2020-05-13)

Note: Version bump only for package @open-wc/karma-esm

2.14.1 (2020-05-05)

Note: Version bump only for package @open-wc/karma-esm

2.14.0 (2020-05-05)

Features

• es-dev-server: move to typescript (179b299)

2.13.28 (2020-04-26)

Bug Fixes

• karma-esm: fix polyfills-loader types (e301a94)
• testing-karma: missing dependency (2b37e90)

2.13.27 (2020-04-26)

Note: Version bump only for package @open-wc/karma-esm

2.13.26 (2020-04-21)

Note: Version bump only for package @open-wc/karma-esm

2.13.25 (2020-04-20)

Note: Version bump only for package @open-wc/karma-esm

2.13.23 (2020-04-12)

Note: Version bump only for package @open-wc/karma-esm

2.13.22 (2020-04-05)

Note: Version bump only for package @open-wc/karma-esm

2.13.21 (2020-03-26)

Note: Version bump only for package @open-wc/karma-esm

2.13.20 (2020-03-24)

Note: Version bump only for package @open-wc/karma-esm

2.13.19 (2020-03-19)

Note: Version bump only for package @open-wc/karma-esm

2.13.18 (2020-03-15)

Note: Version bump only for package @open-wc/karma-esm

2.13.17 (2020-03-15)

Note: Version bump only for package @open-wc/karma-esm

2.13.16 (2020-03-11)

Note: Version bump only for package @open-wc/karma-esm

2.13.15 (2020-03-10)

Note: Version bump only for package @open-wc/karma-esm

2.13.14 (2020-03-08)

Note: Version bump only for package @open-wc/karma-esm

2.13.13 (2020-03-06)

Note: Version bump only for package @open-wc/karma-esm

2.13.12 (2020-03-02)

Note: Version bump only for package @open-wc/karma-esm

2.13.11 (2020-02-29)

Note: Version bump only for package @open-wc/karma-esm

2.13.10 (2020-02-23)

Note: Version bump only for package @open-wc/karma-esm

2.13.9 (2020-02-10)

Note: Version bump only for package @open-wc/karma-esm

2.13.8 (2020-02-10)

Note: Version bump only for package @open-wc/karma-esm

2.13.7 (2020-02-09)

Note: Version bump only for package @open-wc/karma-esm

2.13.6 (2020-02-09)

Note: Version bump only for package @open-wc/karma-esm

2.13.5 (2020-02-06)

Note: Version bump only for package @open-wc/karma-esm

2.13.4 (2020-02-03)

Note: Version bump only for package @open-wc/karma-esm

2.13.3 (2020-02-03)

Note: Version bump only for package @open-wc/karma-esm

2.13.2 (2020-02-02)

Bug Fixes

• karma-esm: dont run coverage on debug, context and web_modules (4565222)

2.13.1 (2020-02-02)

Note: Version bump only for package @open-wc/karma-esm

2.13.0 (2020-01-31)

Bug Fixes

• skip brooken published versions (25d21de)

Features

• karma-esm: use new polyfills loader (ea69d3a)

2.12.8 (2020-01-27)

Note: Version bump only for package @open-wc/karma-esm

2.12.7 (2020-01-27)

Note: Version bump only for package @open-wc/karma-esm

2.12.6 (2020-01-13)

Note: Version bump only for package @open-wc/karma-esm

2.12.5 (2020-01-07)

Note: Version bump only for package @open-wc/karma-esm

2.12.4 (2020-01-06)

Note: Version bump only for package @open-wc/karma-esm

2.12.3 (2020-01-03)

Note: Version bump only for package @open-wc/karma-esm

2.12.2 (2019-12-30)

Note: Version bump only for package @open-wc/karma-esm

2.12.1 (2019-12-30)

Note: Version bump only for package @open-wc/karma-esm

2.12.0 (2019-12-30)

Bug Fixes

• karma-esm: handle configs without module scripts (860b552)

Features

• karma-esm: add dedupe option from es-dev-server (5a2f680)

2.11.14 (2019-12-20)

Bug Fixes

• karma-esm: modifies snapshot path to use pathResolver if configured (cdfbcfe)

2.11.13 (2019-12-18)

Note: Version bump only for package @open-wc/karma-esm

2.11.12 (2019-12-16)

Bug Fixes

• karma-esm: include user defined response transformers (c471ffc)

2.11.11 (2019-12-16)

Bug Fixes

• karma-esm: add close body tag when injecting code to import tests (5843b82)

2.11.10 (2019-12-15)

Bug Fixes

• karma-esm: Implement import map support (#1130) (dbe0975)

2.11.9 (2019-12-11)

Note: Version bump only for package @open-wc/karma-esm

2.11.8 (2019-12-09)

Note: Version bump only for package @open-wc/karma-esm

2.11.7 (2019-12-09)

Note: Version bump only for package @open-wc/karma-esm

2.11.6 (2019-12-08)

Note: Version bump only for package @open-wc/karma-esm

2.11.5 (2019-12-08)

Note: Version bump only for package @open-wc/karma-esm

2.11.4 (2019-12-05)

Note: Version bump only for package @open-wc/karma-esm

2.11.3 (2019-12-05)

Note: Version bump only for package @open-wc/karma-esm

2.11.2 (2019-12-02)

Note: Version bump only for package @open-wc/karma-esm

2.11.1 (2019-12-01)

Note: Version bump only for package @open-wc/karma-esm

2.11.0 (2019-11-30)

Features

• es-dev-server: add debug logging option (#1052) (879e997)

2.10.6 (2019-11-27)

Note: Version bump only for package @open-wc/karma-esm

2.10.5 (2019-11-24)

Note: Version bump only for package @open-wc/karma-esm

2.10.4 (2019-11-21)

Note: Version bump only for package @open-wc/karma-esm

2.10.3 (2019-11-20)

Note: Version bump only for package @open-wc/karma-esm

2.10.2 (2019-11-20)

Bug Fixes

• karma-esm: use hostname instead of listenaddress (7391682)

2.10.1 (2019-11-19)

Bug Fixes

• es-dev-server: resolve imports in inline modules (#997) (98322e4)

2.10.0 (2019-11-19)

Features

• update testing to use auto compatibility of es-dev-server (7d5ea56)

2.9.8 (2019-11-07)

Note: Version bump only for package @open-wc/karma-esm

2.9.7 (2019-11-06)

Note: Version bump only for package @open-wc/karma-esm

2.9.6 (2019-11-04)

Note: Version bump only for package @open-wc/karma-esm

2.9.5 (2019-11-03)

Bug Fixes

• align versions within the monorepo (fa2ad9f)

2.9.4 (2019-11-02)

Note: Version bump only for package @open-wc/karma-esm

2.9.3 (2019-11-02)

Note: Version bump only for package @open-wc/karma-esm

2.9.2 (2019-10-31)

Note: Version bump only for package @open-wc/karma-esm

2.9.1 (2019-10-30)

Note: Version bump only for package @open-wc/karma-esm

2.9.0 (2019-10-26)

Features

• karma-esm: fail test run when tests can't be loaded (#904) (221120e)

2.8.1 (2019-10-26)

Note: Version bump only for package @open-wc/karma-esm

2.8.0 (2019-10-26)

Features

• karma-esm: log 404 requests (f0e28a3)

2.7.5 (2019-10-25)

Note: Version bump only for package @open-wc/karma-esm

2.7.4 (2019-10-23)

Bug Fixes

• add package keywords (#859) (cd78405)

2.7.3 (2019-10-22)

Bug Fixes

• karma-esm: fix type in readme (9b8f01e)

2.7.2 (2019-10-13)

Note: Version bump only for package @open-wc/karma-esm

2.7.1 (2019-09-27)

Note: Version bump only for package @open-wc/karma-esm

2.7.0 (2019-09-27)

Features

• karma-esm: allow configuring preserveSymlinks (#798) (18d8db8)

2.6.1 (2019-09-27)

Note: Version bump only for package @open-wc/karma-esm

2.6.0 (2019-09-27)

Features

• building-utils: add option to polyfillsConfig to disable hashes in filenames (#808) (6763b83)

2.5.9 (2019-09-22)

Note: Version bump only for package @open-wc/karma-esm

2.5.8 (2019-09-11)

Note: Version bump only for package @open-wc/karma-esm

2.5.7 (2019-09-04)

Note: Version bump only for package @open-wc/karma-esm

2.5.6 (2019-08-29)

Note: Version bump only for package @open-wc/karma-esm

2.5.5 (2019-08-28)

Note: Version bump only for package @open-wc/karma-esm

2.5.4 (2019-08-27)

Note: Version bump only for package @open-wc/karma-esm

2.5.3 (2019-08-26)

Note: Version bump only for package @open-wc/karma-esm

2.5.2 (2019-08-26)

Note: Version bump only for package @open-wc/karma-esm

2.5.1 (2019-08-25)

Note: Version bump only for package @open-wc/karma-esm

2.5.0 (2019-08-25)

Features

• karma-esm: use file watcher for reloading karma (cf6346d)

2.4.3 (2019-08-22)

Note: Version bump only for package @open-wc/karma-esm

2.4.2 (2019-08-21)

Note: Version bump only for package @open-wc/karma-esm

2.4.1 (2019-08-20)

Note: Version bump only for package @open-wc/karma-esm

2.4.0 (2019-08-20)

Bug Fixes

• do not destructure exports to support es-module-lexer (3709413)

Features

• es-dev-server: faster node-resolve via use of es-module-lexer (9589e4e)

2.3.4 (2019-08-18)

Bug Fixes

• align sinon version (0d529bf)
• use chai instead of @bundled-es-modules/chai (f9d19bb)

2.3.3 (2019-08-17)

Bug Fixes

• karma-esm: log errors starting up es-dev-server (9aa3dfc)

2.3.2 (2019-08-14)

Note: Version bump only for package @open-wc/karma-esm

2.3.1 (2019-08-13)

Note: Version bump only for package @open-wc/karma-esm

2.3.0 (2019-08-13)

Features

• es-dev-server: improve node-resolve performance (#704) (3761a21)

2.2.13 (2019-08-12)

Note: Version bump only for package @open-wc/karma-esm

2.2.12 (2019-08-12)

Note: Version bump only for package @open-wc/karma-esm

2.2.11 (2019-08-07)

Note: Version bump only for package @open-wc/karma-esm

2.2.10 (2019-08-07)

Note: Version bump only for package @open-wc/karma-esm

2.2.9 (2019-08-05)

Note: Version bump only for package @open-wc/karma-esm

2.2.8 (2019-08-04)

Note: Version bump only for package @open-wc/karma-esm

2.2.7 (2019-08-04)

Note: Version bump only for package @open-wc/karma-esm

2.2.6 (2019-08-04)

Note: Version bump only for package @open-wc/karma-esm

2.2.5 (2019-08-04)

Note: Version bump only for package @open-wc/karma-esm

2.2.4 (2019-07-28)

Bug Fixes

• karma-esm: remove @types/deepmerge dependency (0150895)

2.2.3 (2019-07-26)

Note: Version bump only for package @open-wc/karma-esm

2.2.2 (2019-07-25)

Note: Version bump only for package @open-wc/karma-esm

2.2.1 (2019-07-24)

Note: Version bump only for package @open-wc/karma-esm

2.2.0 (2019-07-24)

Features

• es-dev-server: allow using the server as a library (89c3d4d)

2.1.2 (2019-07-24)

Note: Version bump only for package @open-wc/karma-esm

2.1.1 (2019-07-22)

Note: Version bump only for package @open-wc/karma-esm

2.1.0 (2019-07-22)

Features

• es-dev-server: handle inline modules (#596) (49e4013)

2.0.4 (2019-07-19)

Note: Version bump only for package @open-wc/karma-esm

2.0.3 (2019-07-17)

Note: Version bump only for package @open-wc/karma-esm

2.0.2 (2019-07-17)

Note: Version bump only for package @open-wc/karma-esm

2.0.1 (2019-07-17)

Note: Version bump only for package @open-wc/karma-esm

2.0.0 (2019-07-15)

Features

• karma-esm: support modules on all browsers (786cac0)

BREAKING CHANGES

• karma-esm: The plugin was rewritten completely, most config options changed. See the readme for an up to date overview of all options

1.1.5 (2019-07-13)

Note: Version bump only for package @open-wc/karma-esm

1.1.4 (2019-07-08)

Note: Version bump only for package @open-wc/karma-esm

1.1.3 (2019-07-08)

Note: Version bump only for package @open-wc/karma-esm

1.1.2 (2019-07-08)

Note: Version bump only for package @open-wc/karma-esm

1.1.1 (2019-07-02)

Note: Version bump only for package @open-wc/karma-esm

1.1.0 (2019-07-02)

Features

• add es dev server (2c6a0a8)

1.0.8 (2019-06-30)

Note: Version bump only for package @open-wc/karma-esm

1.0.7 (2019-06-23)

Note: Version bump only for package @open-wc/karma-esm

1.0.6 (2019-06-23)

Note: Version bump only for package @open-wc/karma-esm

1.0.5 (2019-06-18)

Note: Version bump only for package @open-wc/karma-esm

1.0.4 (2019-06-14)

Note: Version bump only for package @open-wc/karma-esm

1.0.3 (2019-05-25)

Bug Fixes

• karma-esm: correctly resolve symlinks (01445cf)

1.0.2 (2019-05-19)

Note: Version bump only for package @open-wc/karma-esm

1.0.1 (2019-05-06)

Note: Version bump only for package @open-wc/karma-esm

1.0.0 (2019-05-06)

Features

• testing-karma: use native es modules in modern browsers (187d155)

BREAKING CHANGES

• testing-karma: You need to specify type: 'module' for you files ```js // old karma.conf.js files: [ config.grep ? config.grep : 'test/*/.test.js', ]

// new karma.conf.js files: [ { pattern: config.grep ? config.grep : 'test/*/.test.js', type: 'module' }, ]