@marko/jest

A preprocessor and preset to use Marko with Jest. Templates are automatically compiled for the correct environment based on your Jest config. Browser tests are compiled to the dom api, and server tests to the html streaming api.

Installation

npm install @marko/jest -D

or

yarn add @marko/jest -D

Examples

jest.config.js

module.exports = {
  preset: "@marko/jest/preset/browser",
};

The above is roughly equivalent to:

const { defaults } = require("jest-config");

module.exports = {
  // uses a webpack style resolver for older versions of Marko
  resolver: "...",
  // allows for stuff like file watching of `.marko` files
  moduleFileExtensions: defaults.moduleFileExtensions.concat("marko"),
  // preprocesses Marko files.
  transform: { "\\.marko$": "@marko/jest/transform/browser" },
  // transforms `.marko` files in node_modules as well
  transformIgnorePatterns: ["node_modules/.*(?<!\\.marko)$"
};

Customizing the preset

Jest presets are extensible by default, meaning you should be able to continue to use your existing config with the Marko preset. For example, if you want typescript support you could have a config like:

jest.config.js

module.exports = {
  preset: "@marko/jest/preset/browser",
  transform: {
    "\\.ts$": "ts-jest",
  },
};

You can also get access to the preset configuration manually by importing @marko/jest/preset/browser/jest-preset and use it like so:

const markoJest = require("@marko/jest/preset/browser/jest-preset");
module.exports = {
  resolver: markoJest.resolver,
  transform: markoJest.transform,
  testEnvironment: markoJest.testEnvironment,
  moduleFileExtensions: markoJest.moduleFileExtensions,
  transformIgnorePatterns: markoJest.transformIgnorePatterns,
};

Customizing the Marko compiler

You can override the default Marko compiler options by adding a Jest "globals" config with a marko property. An additional taglib property can be set which supports excludeDirs and excludePackages arrays which will prevent Marko from discovering taglibs in a directory or package respectively. You can also specify a register array on this object which will cause a taglib to be registered unconditionally for every template.

jest.config.js

module.exports = {
  preset: "@marko/jest/preset/browser",
  globals: {
    marko: {
      ignoreUnrecognizedTags: true,
      taglib: {
        register: ["@marko/compat-v4"],
        excludePackages: ["@scope/package-name"],
      },
    },
  },
};

Test both server & browser

For many Marko projects you may have a mix of server and browser components. You can test all of these with Jest by using the projects configuration like this project does! Simply make sure to use @marko/jest/preset/node and @marko/jest/preset/browser according to the test environment.

jest.config.js

module.exports = {
  projects: [
    {
      displayName: "browser",
      preset: "@marko/jest/preset/browser",
      testMatch: ["**/__tests__/**/*.browser.js"],
    },
    {
      displayName: "server",
      preset: "@marko/jest/preset/node",
      testMatch: ["**/__tests__/**/*.server.js"],
    },
  ],
};

In the above example config, any tests with *.browser.js will run in a JSDOM context with browser path resolution and Marko's DOM API, those with *.server.js will instead be run in a node context with the Marko HTML streaming API.

Using tags from npm

By default Jest will not transform any .marko files within your node_modules folder. Marko recommends publishing the original source Marko files when publishing to npm. To get around this you can use the transformIgnorePatterns option in Jest and whitelist .marko files.

The @marko/jest/preset/* helpers set the ignore pattern for you. If you are using the @marko/jest/transform/* directly then you will have to do this yourself, like so:

jest.config.js

module.exports = {
  ...,
  transformIgnorePatterns: ["node_modules/.*(?<!\\.marko)$"]
};

Including style files

Since jest is uses JSDOM, which has limited support for stylesheets, including styles in the page often does not add a ton of value. However in some cases it can be useful to include these styles, for example with visual-html or jsdom-screenshot.

This plugin will automatically include any Marko dependencies, including style files, if an appropriate jest transform is available. To have Marko include a style.css file you could add jest-transform-css to your jest.config.js.

Why override the resolver (enhanced-resolve-jest)?

The default jest resolver does actually work fine with Marko when running server side tests, however in the browser they rely on browser-resolve. The browser resolver then relies on a version of resolve which is over three years old and has had many fixes since. Newer versions of Marko have been updated to avoid these issues, but @marko/jest will override the resolver if a version of Marko older than 5.25.12 is used.

On top of the issues from using this outdated module, there are a number of limitations. Below i've outlined some issues and limitations you might come across because of this dependency used by jest, one of which completely stops Marko's browser modules from being resolved correctly, hence the recommendation here.

https://github.com/facebook/jest/issues/7840 https://github.com/facebook/jest/issues/5356 https://github.com/facebook/jest/issues/5356 https://github.com/facebook/jest/issues/4756 https://github.com/facebook/jest/issues/2702

Code of Conduct

This project adheres to the eBay Code of Conduct. By participating in this project you agree to abide by its terms.