mutation-testing-elements

Mutation testing elements

A suite of elements designed to display a mutation testing report.

*Note: Please see https://stryker-mutator.io for an introduction to mutation testing.*

Features

The mutation test report supports the following features:

📊 Calculates and displays the mutation score and other metrics
📁 Group results into directories
👓 Show mutants directly in your source code
😎 Code highlighting with Prism
🧙‍ Filter mutants based on the outcome
🌑 Switch between light and dark theme
🔗 Deep linking using anchors (uses fragment, so path will not be contaminated)
💅 A beautifully crafted UI made with tailwind CSS
🎓 Adheres to custom element best practices

Install

Install with npm:

$ npm install mutation-testing-elements

Add to your page:

<script defer src="mutation-test-elements/dist/mutation-test-elements.js"></script>

Or you can use the unpkg as your CDN:

<script defer src="https://www.unpkg.com/mutation-testing-elements"></script>

Usage

Use the mutation-test-report-app element to load the mutation test report.

<mutation-test-report-app src="mutation-report.json" title-postfix="Mutation Test Report"></mutation-test-report-app>

This loads the report from the source (src) and displays it.

Alternatively, you can use property binding directly:

<mutation-test-report-app></mutation-test-report-app>
<script>
  document.getElementsByTagName('mutation-test-report-app').item(0).report = {
    /* ... */
  };
</script>

Add this snippet to change the background color of the whole page when the theme is changed from light to dark:

<script>
  const app = document.getElementsByTagName('mutation-test-report-app').item(0);
  function updateTheme() {
    document.body.style.backgroundColor = app.themeBackgroundColor;
  }
  app.addEventListener('theme-changed', updateTheme);
  updateTheme();
</script>

Feel free to use other ways to bind the report property. For example, you can use <mutation-test-report-app [report]="myReport"></mutation-test-report-app> to bind report to the myReport property in an Angular component.

Mutation testing report schema

The mutation testing report data is expected to be in the format of a the mutation-testing-report-schema. Please view that readme to understand the structure.

For some examples, please see the testResources.

API Reference

src [string]

Default: undefined

Specify a source to load the mutation testing report from. The source is expected to be in JSON format and adhere to the mutation-testing-report-schema.

report [object]

Default: undefined

Specify the mutation testing report directly by binding it to this property. It is expected to adhere to the mutation-testing-report-schema.

titlePostfix [string]

Default: undefined

Specify the postfix to append to the title of the current page. It us reflected as attribute: title-postfix.

theme ['light' | 'dark']

Default: user preference (OS setting)

Specify in which theme the report needs to be shown. Possibilities: 'light' or 'dark'.

themeBackgroundColor [string]

Read-only property with the hex code of the background-color from the current theme.

⚡ theme-changed [CustomEvent<{ theme: string, themeBackgroundColor: string }>]

Add an event listener that will raise an event when the theme is changed.

const app = document.querySelector('mutation-test-report-app');
app.addEventListener('theme-changed', (event) => {
  console.log('new theme is', event.detail.theme);
  console.log('backgroundColor hex is', event.detail.themeBackgroundColor);
  // You can also use `app.theme` or `app.themeBackgroundColor` here.
});

Browser compatibility

These elements are built with LitElement, which uses the Web Components set of standards. They are currently supported by all major browsers with the exception of Edge.

For compatibility with older browsers and Edge, load the Web Components polyfills: https://lit-element.polymer-project.org/guide/use#polyfills

Run tests

There are unit tests with Vitest (browser mode) and integration tests using playwright. You can run them with npx nx test or by running npx nx test:unit or npx nx test:integration respectively. There is also a launch configuration so you can debug from vscode.

The integration tests also do screenshot comparisons. Currently, they only run when you're running in a headless browser, because the screenshots differ ever so slightly with the snapshots. You can run npm run test:integration:headless to run locally with screenshot comparison. It will compare and show you a diff file if the diff is deemed to large. Screenshot tests can be updated for your environment with npm run test:integration:update.

Screenshot snapshots are OS dependent, because, again, the screenshots differ ever so slightly on linux vs windows. You can update the screenshot for both linux and windows by running the "Update screenshots" workflow on your branch (with github). Use with caution always double check the diff before updating!

Changelog

3.3.0 (2024-09-11)

Bug Fixes

• deps: update dependency typescript-eslint to v8.0.1 (bc40fc5)
• deps: update dependency typescript-eslint to v8.1.0 (#3363) (e9c2030)
• deps: update dependency typescript-eslint to v8.2.0 (#3378) (94e4352)
• deps: update dependency typescript-eslint to v8.3.0 (#3384) (45c20b5)
• deps: update dependency typescript-eslint to v8.4.0 (#3399) (936f7dc)
• elements: fix breadcrumb margin for active item (#3369) (35cc30f)
• elements: improve usage as a library (#3367) (a9d8ff8)

Features

• elements: close drawer when pressing Escape (#3371) (7accac1), closes #3370
• elements: export theme-changed event type (#3372) (b2d2817)