@marko/testing-library

Simple and complete Marko testing utilities that encourage good testing practices.

Table of Contents

• Read The Docs | Edit the docs
• The problem
• This solution
• Installation
• API
• Setup
• Guiding Principles
• Docs
• Code of Conduct

The problem

You want to write maintainable tests for your Marko components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your testbase to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.

This solution

The @marko/testing-library is a very lightweight solution for testing Marko components. It provides light utility functions on top of @testing-library/dom in a way that encourages better testing practices. Its primary guiding principle is:

The more your tests resemble the way your software is used, the more confidence they can give you.

Installation

npm install --save-dev @marko/testing-library

You may also be interested in installing jest-dom so you can use the custom jest matchers. Or if using another test runner like mocha you could check out chai-dom.

API

Marko testing library exposes all of the same utilities for querying the dom, firing events and testing asynchronous behavior as @testing-library/dom. This module only exposes two additional APIs to make testing against your components easier.

render(template, input?, { container }?)

This funcition renders your template asynchronously and provides you with query helpers that are scoped to output DOM.

import { render } from "@marko/testing-library";
import HelloTemplate from "./src/__test__/fixtures/hello-name.marko";

test("contains the text", async () => {
  const { getByText, rerender } = await render(
    HelloTemplate,
    { name: "World" }
  );

  // Will find the element within the rendered result from the template.
  expect(getByText("Hello World")).toBeInTheDocument();

  // You can also rerender the component if needed.
  await rerender({ name: "Marko" });

  expect(getByText("Hello Marko")).toBeInTheDocument();
});

The render result will also provide you with a container HTMLElement. This acts as an escape hatch and allows you to test your components going against the guiding principles. With the container you can grab any element using querySelector or other means that mean nothing to your users.

test("not a great test", async () => {
  const { container } = await render(
    HelloTemplate,
    { name: "World" }
  );

  expect(container.querySelector('div')).toBeInTheDocument();
});

The problem with the above test is that your user does not care about or see that there is a div element, the user only see's the text content of the div. Maybe it turns out that a div wasn't the best element and we should switch to an h1? Now your tests are broken, even though there is likely no perceptable change to the user.

cleanup()

With client side tests your components are rendered into a placeholder HTMLElement. To ensure that your components are properly removed, and destroyed, you can call cleanup at any time which will remove any attached components.

import { cleanup } from "@marko/testing-library";
// automatically unmount and cleanup DOM after the test is finished.
afterEach(cleanup);

To save some typing, you could also import a file with the above.

import "@marko/testing-library/cleanup-after-each";

If you are using Jest, you can simply include setupFilesAfterEnv: ["@marko/testing-library/cleanup-after-each"] to your Jest config to avoid doing this in each file.

Setup

Marko testing library is not dependent on any test runner, however it is dependent on the test environment. These utilities work for testing both server side, and client side Marko templates and provide a slightly different implementation for each. This is done using a browser shim, just like in Marko.

The browser shim is picked up by many tools, including all bundlers and some test runners.

Below is some example configurations to test both server and browser components with some popular test runners.

Jest

For Jest to understand Marko templates you must first install the @marko/jest preset. This allows your Marko templates to be imported into your tests.

In Jest there is a browser option which will tell Jest to resolve the browser shim version of all modules as mentioned above.

To test components rendered in the client side, be sure to enable both the browser option and the preset and you are good to go!

jest.config.js

module.exports = {
  preset: "@marko/jest",
  browser: true // Tells Jest to resolve browser shims.
};

For testing components rendered server side we can omit the browser option, however ideally you should also set the testEnvironment option to node which will disable loading JSDOM globally.

jest.config.js

module.exports = {
  preset: "@marko/jest",
  testEnvironment: "node", // Tells Jest not to load a global JSDOM for server side.
};

A Jest configuration can also have multiple projects which we can use to create a combined configuration for server side tests, and browser side tests, like so:

jest.config.js

module.exports = {
  projects: [
    {
      displayName: "server",
      testEnvironment: "node",
      preset: "@marko/jest",
      testRegex: "/__tests__/[^.]+\\.server\\.js$"
    },
    {
      displayName: "browser",
      preset: "@marko/jest",
      browser: true,
      testRegex: "/__tests__/[^.]+\\.browser\\.js$"
    }
  ]
};

Mocha

Mocha also works great for testing Marko components. Mocha, however, has no understanding of browser shims which means out of the box it can only work with server side Marko components.

To run server side Marko tests with mocha you can simply run the following command:

mocha -r marko/node-require

This enables the Marko require hook and allows you to require server side Marko templates directly in your tests.

For client side testing of your components with Mocha often you will use a bundler to build your tests (this will properly resolve the browser shims mentioned above) and then you can load these tests in some kind of browser context.

Guiding Principles

[The more your tests resemble the way your software is used, the more confidence they can give you.][https://testing-library.com/docs/guiding-principles]

We try to only expose methods and utilities that encourage you to write tests that closely resemble how your Marko components are used.

Utilities are included in this project based on the following guiding principles:

1. If it relates to rendering components, then it should deal with DOM nodes rather than component instances, and it should not encourage dealing with component instances.
2. It should be generally useful for testing the application components in the way the user would use it. We are making some trade-offs here because we're using a computer and often a simulated browser environment, but in general, utilities should encourage tests that use the components the way they're intended to be used.
3. Utility implementations and APIs should be simple and flexible.

At the end of the day, what we want is for this library to be pretty light-weight, simple, and understandable.

Docs

Read The Docs | Edit the docs

Code of Conduct

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