mutation-testing-elements

What is mutation-testing-elements?

The mutation-testing-elements package is a web component library that provides a user interface for visualizing mutation testing results. Mutation testing is a method of software testing where certain statements in the source code are changed (mutated) to check if the test cases can detect the errors. This package helps in rendering these results in a human-readable format, making it easier to analyze the effectiveness of the test cases.

What are mutation-testing-elements's main functionalities?

Rendering Mutation Testing Report

This feature allows you to embed a mutation testing report in a web page. By providing the path to a JSON report generated by a mutation testing tool, the component will render an interactive report that can be explored by users to understand the mutation testing results.

<mutation-test-report-app src='path/to/mutation-report.json'></mutation-test-report-app>

Customizable Themes

The package supports different themes for the report viewer. By setting the 'theme' attribute, users can switch between different visual styles, such as a dark theme, to better suit their preferences or the design of their application.

<mutation-test-report-app theme='dark'></mutation-test-report-app>

Other packages similar to mutation-testing-elements

stryker

Stryker is a mutation testing framework for JavaScript and TypeScript. It provides the core functionality to perform mutation testing, generating reports that can be visualized using mutation-testing-elements. While Stryker focuses on the testing and report generation, mutation-testing-elements is specifically for rendering those reports in a user-friendly way.

README

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.4.0 (2024-11-22)

Bug Fixes

• deps: update dependency typescript-eslint to v8.11.0 (#3474) (c165771)
• deps: update dependency typescript-eslint to v8.12.2 (#3495) (31aa74e)
• deps: update dependency typescript-eslint to v8.13.0 (#3504) (622b685)
• deps: update dependency typescript-eslint to v8.14.0 (#3515) (c50c570)
• deps: update dependency typescript-eslint to v8.15.0 (#3523) (3702250)
• deps: update dependency typescript-eslint to v8.5.0 (#3413) (9ed659f)
• deps: update dependency typescript-eslint to v8.6.0 (#3429) (652d250)
• deps: update dependency typescript-eslint to v8.7.0 (#3438) (1b69574)
• deps: update dependency typescript-eslint to v8.8.0 (#3446) (effb179)
• deps: update dependency typescript-eslint to v8.8.1 (e4cbc5c)
• elements: consider statusReason for drawer detail (#3508) (3ce9a0e), closes #3481

Features

• elements: add file picker (#3404) (8310717)
• elements: animate dot/triangle opening/closing (#3507) (69127f9)
• elements: listen to prefers-color-scheme event to switch theme (#3518) (3c79cd1)
• elements: make mutant dots styling more clear (#3475) (10638f4)
• file-picker: add fuzzy search to file picker (#3517) (577c6c1)