Implement a matcher API for "loosely" asserting on deep properties

We have come across this discussion a few times, but for many people deep.equal is too-strict of an assertion. For example:

• #97 discusses Sinon matchers, and having something similar.
• #324 went a bit further, including showing how Jasmine handles this with jasmine.any.
• This may help with issues like #193
• This would help to solve issues like #643 (and perhaps tangentially, #426)
• Personally I’ve run into small problems with this stuff before, with things like asserting arguments with chai-spies

The proposal is thus:

Using deep.equal or similar complex assertions, we are able to make much looser assertions about specific parts of the assertion, using an assertion sentinel in place of a value:

expect(o).to.deep.equal({
  foo: 'bar',
  baz: chai.match.a('function').with.length(2),
});

expect(someSpy).to.be.calledWith('foo', chai.match.a('string').that.matches(/bar/));

[keithamus]

We’ve not added it yet. It’s on my agenda after better error messaging though. Can’t promise timelines but it will be coming!

[jpbochi]

I ended up implementing @vaskevich approach as a plugin. It even replaces this potentially confusing text about stubs being called. Here it is:

chai.use((_chai, utils) => {
  chai.Assertion.addMethod('matchEql', function fn(expectedMatch) {
    const subject = utils.flag(this, 'object');
    const stub = sinon.stub();
    stub(subject);
    try {
      sinon.assert.calledWithMatch(stub, expectedMatch);
    } catch (error) {
      error.name = 'MatchAssertionError';
      error.message = error.message.replace(
        /^expected stub to be called with match/,
        `expected ${utils.objDisplay(subject)} to match`
      );
      throw error;
    }
  });
});