chai-exclude

What is chai-exclude?

The chai-exclude npm package is a plugin for the Chai assertion library that allows you to exclude specific keys from objects when performing deep equality checks. This is particularly useful when you want to ignore certain properties that may vary or are not relevant to the test.

What are chai-exclude's main functionalities?

Exclude specific keys from deep equality checks

This feature allows you to exclude specific keys from deep equality checks. In the example, the key 'c' is excluded from the comparison, so the objects are considered equal even though their 'c' values differ.

const chai = require('chai');
const chaiExclude = require('chai-exclude');
chai.use(chaiExclude);
const expect = chai.expect;

const obj1 = { a: 1, b: 2, c: 3 };
const obj2 = { a: 1, b: 2, c: 4 };

expect(obj1).excluding('c').to.deep.equal(obj2);

Exclude multiple keys from deep equality checks

This feature allows you to exclude multiple keys from deep equality checks. In the example, the keys 'c' and 'd' are excluded from the comparison, so the objects are considered equal even though their 'c' and 'd' values differ.

const chai = require('chai');
const chaiExclude = require('chai-exclude');
chai.use(chaiExclude);
const expect = chai.expect;

const obj1 = { a: 1, b: 2, c: 3, d: 4 };
const obj2 = { a: 1, b: 2, c: 5, d: 6 };

expect(obj1).excluding(['c', 'd']).to.deep.equal(obj2);

Exclude nested keys from deep equality checks

This feature allows you to exclude nested keys from deep equality checks. In the example, the nested key 'b.y' is excluded from the comparison, so the objects are considered equal even though their 'b.y' values differ.

const chai = require('chai');
const chaiExclude = require('chai-exclude');
chai.use(chaiExclude);
const expect = chai.expect;

const obj1 = { a: 1, b: { x: 2, y: 3 } };
const obj2 = { a: 1, b: { x: 2, y: 4 } };

expect(obj1).excluding('b.y').to.deep.equal(obj2);

Other packages similar to chai-exclude

deep-equal

The deep-equal package provides deep equality comparison for Node.js and browsers. It does not offer the ability to exclude specific keys from the comparison, making chai-exclude more flexible for tests where certain properties should be ignored.

lodash.isequal

Lodash's isEqual function performs a deep comparison between two values to determine if they are equivalent. While powerful, it does not natively support excluding specific keys from the comparison, which is a feature provided by chai-exclude.

README

chai-exclude

Exclude keys to compare from a deep equal operation with chai expect or assert.

Why?

Sometimes you'll need to exclude object properties that generate unique values while doing an assertion. This plugin makes it easier to remove those properties from comparison.

Works with both objects and array of objects with or without circular references.

Installation

chai-exclude is an ESM package targeting Chai v5 and above.

npm install chai-exclude --save-dev

If you are using Chai v4, you can use the CommonJS version of the package.

npm install chai-exclude@2.1.1 --save-dev

Usage

import { use } from 'chai'
import chaiExclude from 'chai-exclude'

// If you are using TypeScript, the typings for chai-exclude are included in the package
use(chaiExclude)

Examples

All these examples are for JavaScript. If you are using TypeScript and assert, you'll need to deal with strict types. Take a look at the type definition.

a) excluding

1. Excluding a top level property from an object

// Object
assert.deepEqualExcluding({ a: 'a', b: 'b' }, { b: 'b' }, 'a')
assert.deepEqualExcluding({ a: 'a', b: 'b' }, { a: 'z', b: 'b' }, 'a')

expect({ a: 'a', b: 'b' }).excluding('a').to.deep.equal({ b: 'b' })
expect({ a: 'a', b: 'b' }).excluding('a').to.deep.equal({ a: 'z', b: 'b' })

// Array
assert.deepEqualExcluding([{ a: 'a', b: 'b' }], [{ b: 'b' }], 'a')
assert.deepEqualExcluding([{ a: 'a', b: 'b' }], [{ a: 'z', b: 'b' }], 'a')

expect([{ a: 'a', b: 'b' }]).excluding('a').to.deep.equal([{ b: 'b' }])
expect([{ a: 'a', b: 'b' }]).excluding('a').to.deep.equal([{ a: 'z', b: 'b' }])

1. Excluding multiple top level properties from an object

const obj = {
  a: 'a',
  b: 'b',
  c: {
    d: 'd',
    e: 'e'
  }
}

// Object
assert.deepEqualExcluding(obj, { b: 'b' }, ['a', 'c'])
assert.deepEqualExcluding(obj, { a: 'z', b: 'b' }, ['a', 'c'])

expect(obj).excluding(['a', 'c']).to.deep.equal({ b: 'b' })
expect(obj).excluding(['a', 'c']).to.deep.equal({ a: 'z', b: 'b' })

const array = [
  {
    a: 'a',
    b: 'b',
    c: {
      d: 'd',
      e: 'e'
    }
  }
]

// Array
assert.deepEqualExcluding(array, [{ b: 'b' }], ['a', 'c'])
assert.deepEqualExcluding(array, [{ a: 'z', b: 'b' }], ['a', 'c'])

expect(array).excluding(['a', 'c']).to.deep.equal([{ b: 'b' }])
expect(array).excluding(['a', 'c']).to.deep.equal([{ a: 'z', b: 'b' }])

b) excludingEvery

1. Excluding every property in a deeply nested object

const actualObj = {
  a: 'a',
  b: 'b',
  c: {
    a: 'a',
    b: {
      a: 'a',
      d: {
        a: 'a',
        b: 'b',
        d: null
      }
    }
  },
  d: ['a', 'c']
}

const actualArray = [actualObj]

const expectedObj = {
  a: 'z',     // a is excluded from comparison
  b: 'b',
  c: {
    b: {
      d: {
        b: 'b',
        d: null
      }
    }
  },
  d: ['a', 'c']
}

const expectedArray = [expectedObj]

// Object
assert.deepEqualExcludingEvery(actualObj, expectedObj, 'a')
expect(actualObj).excludingEvery('a').to.deep.equal(expectedObj)

// Array
assert.deepEqualExcludingEvery(actualArray, expectedArray, 'a')
expect(actualArray).excludingEvery('a').to.deep.equal(expectedArray)

1. Excluding multiple properties in a deeply nested object

const actualObj = {
  a: 'a',
  b: 'b',
  c: {
    a: 'a',
    b: {
      a: 'a',
      d: {
        a: 'a',
        b: 'b',
        d: null
      }
    }
  },
  d: ['a', 'c']
}

const actualArray = [actualObj]

const expectedObj = {
  b: 'b',
  c: {
    b: {
    }
  }
}

const expectedArray = [expectedObj]

// Object
assert.deepEqualExcludingEvery(actualObj, expectedObj, ['a', 'd'])
expect(actualObj).excludingEvery(['a', 'd']).to.deep.equal(expectedObj)

// Array
assert.deepEqualExcludingEvery(actualArray, expectedArray, ['a', 'd'])
expect(actualArray).excludingEvery(['a', 'd']).to.deep.equal(expectedArray)

Contributing

Contributions are welcome. If you have any questions create an issue here.

License

MIT