expect: Add matcher toBeInRange() to validate if array elements are within the specified range

README.md

@@ -56,6 +56,7 @@ If you've come here to help contribute - Thanks! Take a look at the [contributin
     - [.toPartiallyContain(member)](#topartiallycontainmember)
     - [.toSatisfyAll(predicate)](#tosatisfyallpredicate)
     - [.toSatisfyAny(predicate)](#tosatisfyanypredicate)
+    - [.toBeWithinRange(min, max)](#tobewithinrangemin-max)
   - [Boolean](#boolean)
     - [.toBeBoolean()](#tobeboolean)
     - [.toBeTrue()](#tobetrue)
@@ -389,6 +390,17 @@ test('passes when any value in array pass given predicate', () => {
 });
 ```
 
+#### .toBeWithinRange(min, max)
+
+Use `.toBeWithinRange` when you want to check if array contains elements between min (inclusive) and max (inclusive).
+
+```js
+test('passes when array contains elements within a given range', () => {
+  expect([3, 5, 8, 9]).toBeWithinRange(3, 9);
+  expect([3, 5, 8, 9]).not.toBeWithinRange(12, 15);
+});
+```
+
 ### Boolean
 
 #### .toBeBoolean()

src/matchers/index.js

@@ -67,3 +67,4 @@ export { toStartWith } from './toStartWith';
 export { toThrowWithMessage } from './toThrowWithMessage';
 export { toEqualIgnoringWhitespace } from './toEqualIgnoringWhitespace';
 export { toPartiallyContain } from './toPartiallyContain';
+export { toBeWithinRange } from './toBeWithinRange';

src/matchers/toBeWithinRange.js

@@ -0,0 +1,22 @@
+export function toBeWithinRange(actual, min, max) {
+  const { printReceived, printExpected, matcherHint } = this.utils;
+
+  const element = actual.find(option => option < min || option > max);
+
+  const pass = element === undefined;
+
+  const passMessage =
+    matcherHint('.not.toBeWithinRange') +
+    '\n\n' +
+    `Expected Array to not be in range ${printExpected(min)}, ${printExpected(max)}\n` +
+    'Received:\n' +
+    `  ${printReceived(actual)}`;
+
+  const failMessage =
+    matcherHint('.toBeWithinRange') +
+    '\n\n' +
+    `Expected: Array elements to be in range (${printExpected(min)}, ${printExpected(max)})\n` +
+    `Received: Array element out of range ${printReceived(element)}`;
+
+  return { pass, message: () => (pass ? passMessage : failMessage) };
+}

test/matchers/__snapshots__/toBeWithinRange.test.js.snap

@@ -0,0 +1,16 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toBeWithinRange fails when given array is within the given range 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toBeWithinRange(</intensity><green>expected</color><dim>)</intensity>
+
+Expected Array to not be in range <green>4</color>, <green>9</color>
+Received:
+  <red>[4, 5, 7, 9]</color>"
+`;
+
+exports[`.toBeWithinRange fails when given array is not within a given range 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeWithinRange(</intensity><green>expected</color><dim>)</intensity>
+
+Expected: Array elements to be in range (<green>4</color>, <green>8</color>)
+Received: Array element out of range <red>9</color>"
+`;

test/matchers/toBeWithinRange.test.js

@@ -0,0 +1,23 @@
+import * as matcher from 'src/matchers/toBeWithinRange';
+
+expect.extend(matcher);
+
+describe('.toBeWithinRange', () => {
+  test('passes when given array is within range', () => {
+    expect([4, 5, 7, 9]).toBeWithinRange(4, 9);
+  });
+
+  test('fails when given array is not within a given range', () => {
+    expect(() => expect([4, 5, 7, 9]).toBeWithinRange(4, 8)).toThrowErrorMatchingSnapshot();
+  });
+});
+
+describe('.not.toBeWithinRange', () => {
+  test('passes when given array is not within the given range', () => {
+    expect([12, 13, 15, 17]).not.toBeWithinRange(4, 9);
+  });
+
+  test('fails when given array is within the given range', () => {
+    expect(() => expect([4, 5, 7, 9]).not.toBeWithinRange(4, 9)).toThrowErrorMatchingSnapshot();
+  });
+});

types/index.d.ts

@@ -644,6 +644,14 @@ declare namespace jest {
      */
     toBeWithin(start: number, end: number): Result;
 
+    /**
+     * Use `.toBeWithinRange` when checking if an array has elements in range min (inclusive) and max (inclusive).
+     *
+     * @param min
+     * @param max
+     */
+    toBeWithinRange(min: number, max: number): Result;
+
     /**
      * Use `.toBeObject` when checking if a value is an `Object`.
      */