# chai-html

> HTML assertions for Chai.

Latest version **3.2.0** (published 2025-09-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install chai-html
pnpm add chai-html
yarn add chai-html
bun add chai-html
```

## Health

**Score 48/100 (D)** — status: stable.

Positive: has types package; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2025-09-19 |
| First published | 2015-11-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/chai-html) |
| Module format | ESM |
| Node | >= 18.0.0 |
| Dependencies | 2 |
| Unpacked size | 11.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Matt Hinchliffe |
| Maintainers | i-like-robots |
| Keywords | chai, html, test, assert, assertion |

## Links

- npm: https://www.npmjs.com/package/chai-html
- Repository: https://github.com/i-like-robots/chai-html
- Issues: https://github.com/i-like-robots/chai-html/issues
- npm.io page: https://npm.io/package/chai-html

## Dependencies (2)

- [parse5](https://npm.io/package/parse5.md) ^7.2.0
- [deep-diff](https://npm.io/package/deep-diff.md) ^1.0.2

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads
- [aws-elasticsearch-connector](https://npm.io/package/aws-elasticsearch-connector.md) — 37.4K weekly downloads

## Recent versions

- 3.2.0 (latest) — 2025-09-19
- 3.1.0 — 2025-02-12
- 3.0.0 — 2024-02-05
- 2.1.0 — 2022-06-12
- 2.0.1 — 2021-04-19
- 2.0.0 — 2021-04-19
- 1.3.0 — 2019-06-24
- 1.2.3 — 2019-04-27
- 1.2.2 — 2018-11-22
- 1.2.1 — 2018-07-03
- 1.2.0 — 2018-05-14
- 1.1.6 — 2018-05-14
- 1.1.5 — 2018-01-23
- 1.1.4 — 2017-04-26
- 1.1.3 — 2017-04-26
- … 11 more at https://npm.io/package/chai-html/versions

## README

# chai-html

[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/i-like-robots/chai-html/blob/main/LICENSE) ![build status](https://github.com/i-like-robots/chai-html/actions/workflows/test.yml/badge.svg?branch=main) [![npm version](https://img.shields.io/npm/v/chai-html.svg?style=flat)](https://www.npmjs.com/package/chai-html)

A focussed HTML assertions plugin for [Chai](http://chaijs.com/).

## Installation

This is a [Node.js] module available through the [npm] registry. Node.js 18 or higher is required.

```sh
$ npm install --save-dev chai-html
```

👋 _Please note_ this package is for Chai v5 or v6 and is [ESM](https://nodejs.org/api/esm.html) only. For Chai v4 and CommonJS support use [version 2][v2] of this package.

[Node.js]: https://nodejs.org/en/
[npm]: https://www.npmjs.com/
[v2]: https://github.com/i-like-robots/chai-html/tree/v2

## Usage

```js
import { use, expect } from 'chai'
import chaiHtml from 'chai-html'

// Register the plugin
use(chaiHtml)

// Write assertions!
expect('<div><img /></div>').html.to.equal('<div><img></div>')
expect('<h1>Hello World!</h1>').html.to.not.equal('<h1>Hallo Welt!</h1>')
```

HTML assertions will throw an error directing you to the change, so instead of squinting at a long HTML string you'll get something useful:

```js
expect('<img />').html.to.equal('<br />')
// throws: tag <img> was changed to tag <br>

expect('<img src="..." />').html.to.equal('<img src="..." alt="..." />')
// throws: attribute [alt="..."] has been added

expect('<p>Hello World!</p> Hej!').html.to.equal('<p>Hello World!</p>')
// throws: text " Hej!" has been removed
```

### .ignoringComments

Add the `ignoringComments` flag to the chain to ignore HTML comments.

```js
expect('<div><!--Comment--></div>').html.ignoringComments.to.equal('<div></div>')
```

## How does it work?

Underneath this plugin uses [parse5](https://github.com/inikulin/parse5) to parse the given HTML strings and normalize the generated trees before being compared. This means that although the two strings of markup may not be the same they should generate equivalent structures.

## Credits

This plugin is inspired by the similar [chai-xml](https://www.npmjs.com/package/chai-xml) plugin.

## License

This package is MIT licensed.

---
_Source: https://npm.io/package/chai-html · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
