Mochaterial

Mochaterial is a browser-based reporter for mocha.js, a premier JavaScript testing framework. It's written as a native ES6 module, allowing you to execute your test packages installation free, and outside of a node.js environment. Using any vanilla web server, you can deliver test suites to your infrastructure, integration, and support teams with a rich, easy to consume interface.

Why Mochaterial?

There are plenty of great mocha reporters out there (mochawesome being our favorite), so why do we need another? The majority of the reporters available run through node.js, which is fine in many cases, but does include the following pain points:

You'll obviously need node.js, which makes sharing tests on most JavaScript Playgrounds an issue
If your package has browser dependencies, you'll now need to attach a headless browser
Delivering your tests as part of the product may be difficult, particularly if it's a client side library

Mochaterial allows you to quickly execute tests in any browser you choose, verify that your modules load properly, and ship your test packages with simplicity.

Demo

Mochaterial ships in three flavours: Default which uses Material Design's baseline theme, Coffee which incorporates Mocha API's theme, and a Dark variant is provided as well. Themes are very easy to customize as you'll see below, so you can create the look that fits with your product.

Setup

Mochaterial does not require any installation for basic use. Simply copy the required markup to an html document, include your tests, and publish to a web server of your choosing. This setup is very similar to the default html reporter which mocha.js provides. All of the required resources are available through the UNPKG cdn, so you can reference them from there (although you can certainly download them and serve locally if you prefer). Basic options are set via reporterOptions, and simple theme changes can be accomplished through inline styles. For more advanced customization, you can grab the repository from github.

Internals

Mochaterial utilizes the following packages for HTML rendering:

Material Web Components (https://material.io)
Highlight.js (https://highlightjs.org)
StackTrace.js (https://www.stacktracejs.com)
diff2html (https://diff2html.xyz)

Options

You can configure Mochaterial by providing the well-formed reporterOptions object in mocha.setup:

<script type="module">

  import { Mochaterial } from "./mochaterial.mjs";

  mocha.setup({
    ui: "bdd",
    reporter: Mochaterial,
    // Configure options here, default values shown for reference
    reporterOptions: { 
      title: "document.title",
      titlePath: "window.location",
      showHooksDefault: true,
      rootSuiteTitle: "Isolated Tests",
      indentSuites: "tablet-up",
      codeBackground: "surface",
      codeDefaultText: "on-surface",
      diffFormat: "side-by-side"
    }       
  });
      
</script>

title

The title of the page in the header bar. Defaults to the <title> element in the <head> section, or just "Mochaterial" if not found.

titlePath

The title's destination when clicked. Defaults to the current page location (reload) when not specified.

showHooksDefault

Displays passing hooks by default. This toggles the initial state of the switch within the navigation menu. Defaults to true.

rootSuiteTitle

Tests which appear outside of a suite are automatically assigned to the "root" suite, and this option sets that title. Defaults to "Isolated Tests".

indentSuites

Defines when to indent child suites. Valid values include "no-indent" which eliminates indentation, "indent" to always indent, or "tablet-up" to enable indentation on tablets or larger. Defaults to "tablet-up".

codeBackground

Styles from highlight.js provide a background for code blocks. This option controls whether to use it via "hljs" or the "surface" background from material components. Defaults to "surface".

codeDefaultText

Similarly, default text within a highlight.js block will get a default color. You can use it with "hljs" or the "on-surface" color from material components. Defaults to "on-surface".

diffFormat

Specify whether to display the assertion differences in "line-by-line" or "side-by-side" format. Defaults to "side-by-side".

Customization

Mochaterial makes use of and extends the theming engine provided by Material Web Components, so you can swap out colors and icons by overriding the :root css variables with inline styles. This allows you to quickly create a new look without having to crawl through a slew of css classes. If you prefer, you can also create your own theme by downloading the repository and generating a new theme through sass.

Directly in your html markup page:

<!-- Load the default stylesheet, or a theme to start from -->
<link rel="stylesheet" href="./mochaterial.css">
<style>
  /* Now override mdc-theme & mocha colors, and set Material Icons as desired */
  :root {
    --mdc-theme-primary: #5d3b1e;
    --mdc-theme-secondary: #e8c89e;
    --mdc-theme-surface: #8c6546;
    --mdc-theme-text-primary-on-background: #5d3b1e;
    --mdc-theme-text-hint-on-background: #8c6546;

    --mocha-passed: #76ff03;
    --mocha-failed: #ffa4a2;
    --mocha-fast: #76ff03;
    --mocha-slow: #ffa4a2;
    --mocha-replay: #e8c89e;

    --icon-blocked: "error";
    --icon-passed-count: "check_circle_outline";
    --icon-failed-count: "highlight_off";
    --icon-pending-count: "pause_circle_outline";
    --icon-blocked-count: "error_outline"; 
  } 
</style>

In a new Sass theme file, like mochaterial.coffee.scss:

// Set the Sass variables to override
$mdc-theme-primary: #5d3b1e;
$mdc-theme-secondary: #e8c89e;
$mdc-theme-surface: #8c6546;
$mdc-theme-on-surface: #FFFFFF;
$mdc-theme-text-primary-on-background: #5d3b1e;
$mdc-theme-text-hint-on-background: #8c6546;

$mocha-passed: #76ff03;
$mocha-failed: #ffa4a2;
// Note: fast, slow, replay are inherited so they can be dropped 

$icon-blocked: "error";
$icon-passed-count: "check_circle_outline";
$icon-failed-count: "highlight_off";
$icon-pending-count: "pause_circle_outline";
$icon-blocked-count: "error_outline"; 

// Now import the base scss
@import "mochaterial";

Build with "gulp styles", and in your html markup include the new theme:

<link rel="stylesheet" href="./mochaterial.coffee.css">

License

Mochaterial is MIT licensed.

Go Forth and Test!

We hope you find Mochaterial to be a useful tool in your JavaScript testing belt. If you need assistance getting your test suites off the ground, let us know, we can help with that!