Feature Request: .toMatchArray()

I was looking for a shortcut to check if an Array exactly matches the contents including order (but was not necessarily strictly equal). The matcher would have test cases like this:

describe('matchArray', () => {

  it('matches arrays', () => {
    expect(matchArray(['a', 'b'], ['a', 'b'])).toBeTruthy();
    expect(matchArray(['a', 'b', 'c'], ['a', 'b'])).toBeFalsy();
    expect(matchArray(['a', 'b'], ['a', 'b', 'c'])).toBeFalsy();
    expect(matchArray(['a', 'b'], ['b', 'a'])).toBeFalsy();
  });

  it('short-circuits via equality', () => {
    const a = [NaN]; // NaN === NaN returns false
    expect(matchArray(a, a)).toBeTruthy();
  });

  it('uses strict equality', () => {
    expect(matchArray(['1'], [1])).toBeFalsy();
    expect(matchArray([{}], [{}])).toBeFalsy();
    const a = {};
    expect(matchArray([a], [a])).toBeTruthy();
  });

});

I ended up writing this myself but would be happy to contribute it if you’ll accept it.

[overlookmotel]

.toIncludeAllMembers() does what you want, I think, except it accepts the same items in different order.

So maybe .toIncludeAllMembersInOrder() would be a good name for this?

expect( [1, 2, 3] ).toIncludeAllMembersInOrder( [1, 2, 3] ) // => pass
expect( [3, 2, 1] ).toIncludeAllMembersInOrder( [1, 2, 3] ) // => fail

That would throw an error like “Expected list to have all of the following members in order”, rather than your implementation which will throw “expect(received).toBeTruthy()”, which is less clear.

[kara-ryli]

I don’t have a way of telling, but I’d wager that when I opened this issue, toEqual didn’t behave the same way. Regardless, I think the example above is close enough for the use case I was looking for that it would make sense to add similar-yet-different matcher.