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

[keithamus]

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

• inclusion/containment semantics #97 discusses Sinon matchers, and having something similar.
• Deep expect anonymous function #324 went a bit further, including showing how Jasmine handles this with jasmine.any.
• This may help with issues like Chain .property() assertions on objects #193
• This would help to solve issues like Assertion Request: deepMatch() #643 (and perhaps tangentially, Have "match" perform matching of array elements #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/));

[meeber]

I like the idea behind this. Where do you envision this falling on the roadmap?

The only thing I'm not crazy about is the term "match", simply because of its existing association with regular expressions.

I haven't yet put any thought into the feasibility of this or anything resembling this, but just pie-in-the-skying, it'd be pretty neat if the syntax resembled whatever interface the developer was using:

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

o.should.deep.equal({
  foo: 'bar',
  baz: should.be.a('function').with.length(2),
});

[keithamus]

I'm doing some work on deep-eql - extending it to take an optional comparator function, which will go a lot of the way to providing this kind of functionality.

[Turbo87]

As mentioned in #709 I'd like to have some sort of high-level assertion that enables me to deep equal two JSON objects while using something like closeTo() for comparing numbers. I'm not quite sure if/how this new feature might help with that, but I'd be happy to discuss it... 😉

[keithamus]

As @Turbo87 mentioned in #709, deep equal could, for example, take a second arg of a comparitor

function compare(a, b) {
  if (typeof a === 'number' && typeof b === 'number') {
    // using the expect() semantics here might not be the best idea...
    expect(a).to.be.closeTo(b, 0.0001);
  } else {
    return this._super(a, b);
  }
}
expect(result).to.deep.equal(expected, compare);

Which fits the work we're doing in deep-eql to power this feature.