Add that toMatchObject can match arrays (#3994)

https://repl.it/JT0C

docs/en/ExpectAPI.md

@@ -707,7 +707,11 @@ describe('grapefruits are healthy', () => {
 
 ### `.toMatchObject(object)`
 
-Use `.toMatchObject` to check that a JavaScript object matches a subset of the properties of an object. You can match properties against values or against matchers.
+Use `.toMatchObject` to check that a JavaScript object matches a subset of the properties of an object. It will match received objects with properties that are **not** in the expected object.
+
+You can also pass an array of objects, in which case the method will return true only if each object in the received array matches (in the `toMatchObject` sense described above) the corresponding object in the expected array. This is useful if you want to check that two arrays match in their number of elements, as opposed to `arrayContaining`, which allows for extra elements in the received array.
+
+You can match properties against values or against matchers.
 
 ```js
 const houseForSale = {
@@ -732,6 +736,40 @@ test('the house has my desired features', () => {
 });
 ```
 
+```js
+describe('toMatchObject applied to arrays arrays', () => {
+  test('the number of elements must match exactly', () => {
+    expect([
+      { foo: 'bar' },
+      { baz: 1 }
+    ]).toMatchObject([
+      { foo: 'bar' },
+      { baz: 1 }
+    ]);
+  });
+
+  // .arrayContaining "matches a received array which contains elements that are *not* in the expected array"
+  test('.toMatchObject does not allow extra elements', () => {
+    expect([
+      { foo: 'bar' },
+      { baz: 1 }
+    ]).toMatchObject([
+      { foo: 'bar' }
+    ]);
+  });
+
+  test('.toMatchObject is called for each elements, so extra object properties are okay', () => {
+    expect([
+      { foo: 'bar' },
+      { baz: 1, extra: 'quux' }
+    ]).toMatchObject([
+      { foo: 'bar' },
+      { baz: 1 }
+    ]);
+  });
+});
+```
+
 ### `.toHaveProperty(keyPath, value)`
 
 Use `.toHaveProperty` to check if property at provided reference `keyPath` exists for an object.