jodyheavener / mjml-testing-library

💌 Simple MJML DOM testing utilities that encourage good testing practices.

MJML Testing Library

Simple MJML DOM testing utilities that encourage good testing practices.

---

Table of Contents

• Installation
• Examples
  • Basic Example
  • Using MJML configuration
  • Inspecting JSON structures
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
• LICENSE

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev mjml-testing-library

Or for installation via yarn:

yarn add --dev mjml-testing-library

This library has a peerDependencies listing for mjml.

You may also be interested in installing @testing-library/jest-dom so you can use the custom jest matchers.

Examples

Basic Example

At its basic level this library compiles MJML down to HTML and then configures it to work with DOM Testing Library.

// this import is something you'd normally configure
// Jest to import for you automatically
import '@testing-library/jest-dom';

import { render, screen } from 'mjml-testing-library';

const testMessage = 'Hello, World!';
const template = `
  <mjml>
    <mj-body>
      <mj-section>
        <mj-column>
          <mj-text color="blue" font-size="10px">
            ${testMessage}
          </mj-text>
        </mj-column>
      </mj-section>
    </mj-body>
  </mjml>
`;

test('displays the welcome text', () => {
  // Render the MJML and insert it into the global document
  render(template);

  // Check the rendered HTML to ensure our expected text is in place
  // .toBeInTheDocument() is an assertion that comes from jest-dom
  // otherwise you could use .toBeDefined()
  expect(screen.getByText(testMessage)).toBeInTheDocument();
});

Using MJML configuration

You can also supply an MJML configuration object to the render function. One example of this being useful is ensuring your MJML is valid:

import { render } from 'mjml-testing-library';

const template = `
  <mjml>
    <mj-section>
      <mj-body>
        <mj-text color="blue" font-size="10px">
          ${testMessage}
        </mj-text>
      </mj-body>
    </mj-section>
  </mjml>
`;

test('the template is valid', () => {
  expect(() => {
    // Render the MJML with MJML validation set to strict
    render(template, {
      mjmlOptions: { validationLevel: 'strict' },
    });
  })
    // This will fail because the provided template is invalid MJML
    .not.toThrow();
});

Inspecting JSON structures

This library also allows you to inspect the parsed MJML as JSON, which is useful if you'd rather assert on specific object values:

import { render } from 'mjml-testing-library';

const template = `
  <mjml>
    <mj-body>
      <mj-text color="blue">
        Hello, World!
      </mj-text>
      <mj-text color="red">
        Hello, World!
      </mj-text>
      <mj-text color="green">
        Hello, World!
      </mj-text>
    </mj-body>
  </mjml>
`;

test('correctly renders the children', () => {
  // Render the MJML and grab the JSON representation
  const { json } = render(template);

  const body = json.children[0];
  expect(body.tagName).toEqual('mj-body');
  expect(body.children).toHaveLength(3);
});

Issues

Looking to contribute? Look for the Good First Issue label.

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

See Bugs

💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

LICENSE

MIT