docs: clarify the difference between toIncludeAllMembers and toIncludeSameMembers

test/matchers/toIncludeSameMembers.test.js

@@ -15,6 +15,10 @@ describe('.toIncludeSameMembers', () => {
   test('passes when arrays match in a different order', () => {
     expect([1, 2, 3]).toIncludeSameMembers([3, 1, 2]);
     expect([{ foo: 'bar' }, { baz: 'qux' }]).toIncludeSameMembers([{ baz: 'qux' }, { foo: 'bar' }]);
+    expect([{ foo: 'bar' }, { baz: 'qux' }, { fred: 'thud' }]).not.toIncludeSameMembers([
+      { baz: 'qux' },
+      { foo: 'bar' },
+    ]);
   });
 
   test('fails when the arrays are not equal in length', () => {

types/index.d.ts

@@ -63,7 +63,7 @@ interface CustomMatchers<R> extends Record<string, any> {
   toBeBefore(date: Date): R;
 
   /**
-   * Use `.toIncludeAllMembers` when checking if an `Array` contains all of the same members of a given set.
+   * Use `.toIncludeAllMembers` when checking if an `Array` contains all of the members of a given set.
    * @param {Array.<*>} members
    */
   toIncludeAllMembers<E = unknown>(members: readonly E[]): R;
@@ -491,13 +491,13 @@ declare namespace jest {
     toBeBefore(date: Date): R;
 
     /**
-     * Use `.toIncludeAllMembers` when checking if an `Array` contains all of the same members of a given set.
+     * Use `.toIncludeAllMembers` when checking if an `Array` contains all of the members of a given set.
      * @param {Array.<*>} members
      */
     toIncludeAllMembers<E = unknown>(members: readonly E[]): R;
 
     /**
-     * Use `.toIncludeAllPartialMembers` when checking if an `Array` contains all of the same partial members of a given set.
+     * Use `.toIncludeAllPartialMembers` when checking if an `Array` contains all of the partial members of a given set.
      * @param {Array.<*>} members
      */
     toIncludeAllPartialMembers<E = unknown>(members: readonly E[]): R;

website/docs/matchers/Array.mdx

@@ -28,18 +28,19 @@ Use `.toBeArrayOfSize` when checking if a value is an `Array` of size x.
 
 ### .toIncludeAllMembers([members])
 
-Use `.toIncludeAllMembers` when checking if an `Array` contains all of the same members of a given set.
+Use `.toIncludeAllMembers` when checking if an `Array` contains all of the members of a given set.
 
 <TestFile name="toIncludeAllMembers">
   {`test('passes when given array values match the members of the set', () => {
   expect([1, 2, 3]).toIncludeAllMembers([2, 1, 3]);
   expect([1, 2, 2]).toIncludeAllMembers([2, 1]);
+  expect([1, 2, 2]).not.toIncludeAllMembers([3, 1]);
 });`}
 </TestFile>
 
 ### .toIncludeAllPartialMembers([members])
 
-Use `.toIncludeAllPartialMembers` when checking if an `Array` contains all of the same partial members of a given set.
+Use `.toIncludeAllPartialMembers` when checking if an `Array` contains all of the partial members of a given set, in any order.
 
 <TestFile name="toIncludeAllPartialMembers">
   {`test('passes when given array values match the partial members of the set', () => {
@@ -61,12 +62,13 @@ Use `.toIncludeAnyMembers` when checking if an `Array` contains any of the membe
 
 ### .toIncludeSameMembers([members])
 
-Use `.toIncludeSameMembers` when checking if two arrays contain equal values, in any order.
+Use `.toIncludeSameMembers` when checking if two arrays contain members in exact match, in any order.
 
 <TestFile name="toIncludeSameMembers">
   {`test('passes when arrays match in a different order', () => {
   expect([1, 2, 3]).toIncludeSameMembers([3, 1, 2]);
   expect([{ foo: 'bar' }, { baz: 'qux' }]).toIncludeSameMembers([{ baz: 'qux' }, { foo: 'bar' }]);
+  expect([1, 2, 2]).not.toIncludeSameMembers([2, 1]);
 });`}
 </TestFile>