Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/bem/html-differ

Сompares two HTML
https://github.com/bem/html-differ
Last synced: 6 days ago
JSON representation
Сompares two HTML
Host: GitHub
URL: https://github.com/bem/html-differ
Owner: bem
License: mit
Created: 2014-04-23T12:14:52.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2024-08-06T04:52:22.000Z (3 months ago)
Last Synced: 2024-10-16T02:04:53.124Z (26 days ago)
Language: JavaScript
Homepage: http://bem.info/tools/testing/html-differ/
Size: 256 KB
Stars: 212
Watchers: 14
Forks: 45
Open Issues: 28
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project

README

        # html-differ [![Build Status](https://travis-ci.org/bem/html-differ.svg)](https://travis-ci.org/bem/html-differ) [![Coverage Status](https://img.shields.io/coveralls/bem/html-differ.svg)](https://coveralls.io/r/bem/html-differ?branch=master) [![Dependency Status](https://david-dm.org/bem/html-differ.svg)](https://david-dm.org/bem/html-differ) [![devDependency Status](https://david-dm.org/bem/html-differ/dev-status.svg)](https://david-dm.org/bem/html-differ#info=devDependencies)

Compares two HTML.

- [The comparison algorithm](#the-comparison-algorithm)

- [Install](#install)

- [API](#api)

  - [HtmlDiffer](#htmldiffer)

    - [Options](#options)

      - [ignoreAttributes](#ignoreattributes-array)

      - [compareAttributesAsJSON](#compareattributesasjson-array)

      - [ignoreWhitespaces](#ignorewhitespaces-boolean)

      - [ignoreComments](#ignorecomments-boolean)

      - [ignoreEndTags](#ignoreendtags-boolean)

      - [ignoreDuplicateAttributes](#ignoreduplicateattributes-boolean)

    - [Presets](#presets)

      - [Usage](#usage)

    - [Methods](#methods)

      - [htmlDiffer.diffHtml](#htmldifferdiffhtml)

      - [htmlDiffer.isEqual](#htmldifferisequal)

  - [Logger](#logger)

    - [Methods](#methods-1)

      - [logger.getDiffText](#loggergetdifftext)

      - [logger.logDiffText](#loggerlogdifftext)

  - [Example](#example)

- [Usage as a program](#usage-as-a-program)

  - [Example](#example-1)

  - [Configuration file](#configuration-file)

- [Masks](#masks)

  - [Syntax](#syntax)

  - [Screening](#screening)

## The comparison algorithm

**html-differ** compares HTML using the following criteria:

* `` declarations are case-insensitive, so the following two code samples will be considered to be equivalent:

```html

```

```html

```

* Whitespaces (spaces, tabs, new lines etc.) inside start and end tags are ignored during the comparison.

For example, the following two code samples will be considered to be equivalent:

```html



```

```html



```

* Two respective lists of attributes are considered to be equivalent even if they are specified in different order.

For example, the following two code samples will be considered to be equivalent:

```html

Text

```

```html

Text

```

* Two respective attributes `class` are considered to be equivalent if they refer to the same groups of CSS styles.

For example, the following two code samples will be considered to be equivalent:

```html

Text

```

```html

Text

```

**CAUTION!**


**html-differ** does not check the validity of HTML, but compares them using the above shown criteria and specified options (see the list of possible [options](https://github.com/bem/html-differ/tree/master#options)).

## Install

```bash

$ npm install html-differ

```

## API

### HtmlDiffer

```js

var HtmlDiffer = require('html-differ').HtmlDiffer,

    htmlDiffer = new HtmlDiffer(options);

```

where `options` is an object.

#### Options

##### ignoreAttributes: [Array]

Sets what kind of respective attributes' content will be ignored during the comparison (default: `[]`).

**Example**: `['id', 'for']`


The following two code samples will be considered to be equivalent:

```html

Text

```

```html

Text

```

##### compareAttributesAsJSON: [Array]

Sets what kind of respective attributes' content will be compared as JSON objects, but not as strings (default: `[]`).


In cases when the value of the attribute is an invalid JSON or can not be wrapped into a function, it will be compared as `undefined`.

**Example**: `[{ name: 'data', isFunction: false }, { name: 'onclick', isFunction: true }]`


The following two code samples will be considered to be equivalent:

```html





```

```html





```

**REMARK!**


The first element of the array could be written in a short form as string:


`['data', { name: 'onclick', isFunction: true }]`.

##### ignoreWhitespaces: Boolean

Makes **html-differ** ignore whitespaces (spaces, tabs, new lines etc.) during the comparison (default: `true`).

**Example**: `true`


The following two code samples will be considered to be equivalent:

```html

Text TextText

```

```html

 

 Text   Text

                   

            

     Text

    

```

##### ignoreComments: Boolean

Makes **html-differ** ignore HTML comments during the comparison (default: `true`).

**REMARK!**


Does not ignore [conditional comments](http://en.wikipedia.org/wiki/Conditional_comment).

**Example**: `true`


The following two code samples will be considered to be equivalent:

```html

    

    

    

        

    

Text

```

```html

    

    

    

        

    

Text

```

##### ignoreEndTags: Boolean

Makes **html-differ** ignore end tags during the comparison (default: `false`).

**Example**: `true`


The following two code samples will be considered to be equivalent:

```html

Text

```

```html

Text

```

##### ignoreDuplicateAttributes: Boolean

Makes **html-differ** ignore tags' duplicate attributes during the comparison.


From the list of the same tag's attributes, the attribute which goes the first will be taken for comparison, others will be ignored (default: `false`).

**Example**: `true`


For example, the following two code samples will be considered to be equivalent:

```html

Text

```

```html

Text

```

#### Presets

* [bem](https://github.com/bem/html-differ/blob/master/presets/bem.json) - sets predefined options for [BEM](http://bem.info/).

##### Usage

Passing of a preset via the constructor:

```js

var HtmlDiffer = require('html-differ').HtmlDiffer,

    htmlDiffer = new HtmlDiffer('bem');

```

Redefinition of a preset via the constructor:

```js

var HtmlDiffer = require('html-differ').HtmlDiffer,

    htmlDiffer = new HtmlDiffer({ preset: 'bem', ignoreAttributes: [] });

```

#### Methods

##### htmlDiffer.diffHtml

**@param** *{String}* - the 1-st HTML code


**@param** *{String}* - the 2-nd HTML code


**@returns** *{Array of objects}* - [array with diffs](https://github.com/kpdecker/jsdiff#change-objects) between HTML

##### htmlDiffer.isEqual

**@param** *{String}* - the 1-st HTML code


**@param** *{String}* - the 2-nd HTML code


**@returns** *{Boolean}*

### Logger

```js

var logger = require('html-differ/lib/logger');

```

#### Methods

##### logger.getDiffText

**@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)


**@param** *{Object}* - options:


* **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`).

**@returns** *{String}*

##### logger.logDiffText

**@param** *{Array of objects}* - the result of the work of the method [htmlDiffer.diffHtml](https://github.com/bem/html-differ/tree/master#htmldifferdiffhtml)


**@param** *{Object}* - options:


* **charsAroundDiff: Number** - the number of characters around the diff result between two HTML (default: `40`).

**@returns** - pretty logging of diffs:



### Example

```js

var fs = require('fs'),

    HtmlDiffer = require('html-differ').HtmlDiffer,

    logger = require('html-differ/lib/logger');

var html1 = fs.readFileSync('1.html', 'utf-8'),

    html2 = fs.readFileSync('2.html', 'utf-8');

var options = {

        ignoreAttributes: [],

        compareAttributesAsJSON: [],

        ignoreWhitespaces: true,

        ignoreComments: true,

        ignoreEndTags: false,

        ignoreDuplicateAttributes: false

    };

var htmlDiffer = new HtmlDiffer(options);

var diff = htmlDiffer.diffHtml(html1, html2),

    isEqual = htmlDiffer.isEqual(html1, html2),

    res = logger.getDiffText(diff, { charsAroundDiff: 40 });

logger.logDiffText(diff, { charsAroundDiff: 40 });

```

## Usage as a program

```bash

$ html-differ --help

Compares two HTML

Usage:

  html-differ [OPTIONS] [ARGS]

Options:

  -h, --help : Help

  -v, --version : Shows the version number

  --config=CONFIG : Path to a configuration JSON file

  --bem : Uses predefined options for BEM (deprecated)

  -p PRESET, --preset=PRESET : Name of a preset

  --chars-around-diff=CHARSAROUNDDIFF : The number of characters around the diff (default: 40)

Arguments:

  PATH1 : Path to the 1-st HTML file (required)

  PATH2 : Path to the 2-nd HTML file (required)

```

### Example

```bash

$ html-differ path/to/html1 path/to/html2

$ html-differ --config=path/to/config --chars-around-diff=40 path/to/html1 path/to/html2

$ html-differ --preset=bem path/to/html1 path/to/html2

```

### Configuration file

Study the following file `config.json`:

```js

{

    "ignoreAttributes": [],

    "compareAttributesAsJSON": [],

    "ignoreWhitespaces": true,

    "ignoreComments": true,

    "ignoreEndTags": false,

    "ignoreDuplicateAttributes": false

}

```

## Masks

**html-differ** supports handling of _masks_ in HTML.

For example, the following two code samples will be considered to be equivalent:

```html



```

```html



```

### Syntax

_Masks_ in **html-differ** have the following syntax:

```js

{{RegExp}}

```

where:

* `{{` – opening identifier of the _mask_.

* `RegExp` – regular expression for matching with the corresponding value in another HTML. The syntax is similar to regular expressions in JavaScript written in a literal notation.

* `}}` – closing identifier of the _mask_.

### Screening

The rules of screening of symbols are similar to the rules which are used in regular expressions in JavaScript written in a literal notation.

For example, the following two code samples will be considered to be equivalent:

```html



```

```html



```

If you want to use `{{` or `}}` inside a mask, you should screen both curly braces, i.e. `\{\}` or `\}\}`.

For example, the following two code samples will be considered to be equivalent:

```html



```

```html



```