expect: Add matcher toBeInRange() to validate if array elements are…

… within the specified range (#461)

* Add matcher export

* Add toBeWithinRange function

* Add unit test for toBeWithinRange

* Add snapshot

* define type declaration

* Update documentation

* Update README.md to document both the numbers are inclusive in .toBeWithinRange

* Replace ampersand with "and"

* Update snapshot

* Replace any with Result

* Make max exclusive

* rename toBeWithinRange to toBeInRange

* Update README.md

* add toBeInRange() matcher in the matchers interface

* add toBeInRange() matcher

* add TestFile for toBeInRange()

* update description

Co-authored-by: Keegan Witt <keeganwitt@gmail.com>

src/matchers/index.js

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

src/matchers/toBeInRange.js

@@ -0,0 +1,22 @@
+export function toBeInRange(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.toBeInRange') +
+    '\n\n' +
+    `Expected Array to not be in range ${printExpected(min)}, ${printExpected(max)}\n` +
+    'Received:\n' +
+    `  ${printReceived(actual)}`;
+
+  const failMessage =
+    matcherHint('.toBeInRange') +
+    '\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__/toBeInRange.test.js.snap

@@ -0,0 +1,16 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toBeInRange fails when given array is in the given range 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toBeInRange(</intensity><green>expected</color><dim>)</intensity>
+
+Expected Array to not be in range <green>4</color>, <green>10</color>
+Received:
+  <red>[4, 5, 7, 9]</color>"
+`;
+
+exports[`.toBeInRange fails when given array is not in a given range 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toBeInRange(</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/toBeInRange.test.js

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

types/index.d.ts

@@ -219,6 +219,14 @@ declare namespace jest {
      */
     toBeWithin(start: number, end: number): R;
 
+    /**
+     * Use `.toBeInRange` when checking if an array has elements in range min (inclusive) and max (inclusive).
+     *
+     * @param min
+     * @param max
+     */
+    toBeInRange(min: number, max: number): R;
+
     /**
      * Use `.toBeInteger` when checking if a value is an integer.
      */
@@ -649,6 +657,14 @@ declare namespace jest {
      */
     toBeWithin(start: number, end: number): any;
 
+    /**
+     * Use `.toBeInRange` when checking if an array has elements in range min (inclusive) and max (inclusive).
+     *
+     * @param min
+     * @param max
+     */
+    toBeInRange(min: number, max: number): any;
+
     /**
      * Use `.toBeObject` when checking if a value is an `Object`.
      */

website/docs/matchers/Array.mdx

@@ -105,3 +105,14 @@ Use `.toSatisfyAny` when you want to use a custom matcher by supplying a predica
   expect([2, 4, 8, 12]).not.toSatisfyAny(isOdd);
 });`}
 </TestFile>
+
+### .toBeInRange(min, max)
+
+Use `.toBeInRange` when checking if an array has elements in range min (inclusive) and max (inclusive).
+
+<TestFile name="toBeInRange">
+  {`test('passes when given array is in range', () => {
+  expect([4, 5, 7, 9]).toBeInRange(4, 10);
+  expect([12, 13, 15, 17]).not.toBeInRange(4, 9);
+});`}
+</TestFile>

website/docs/matchers/index.md

@@ -22,6 +22,7 @@ sidebar_position: 1
 - [.toPartiallyContain(member)](/docs/matchers/array/#topartiallycontainmember)
 - [.toSatisfyAll(predicate)](/docs/matchers/array/#tosatisfyallpredicate)
 - [.toSatisfyAny(predicate)](/docs/matchers/array/#tosatisfyanypredicate)
+- [.toBeInRange(min, max)](/docs/matchers/array/#tobeinrangemin-max)
 
 ## [Boolean](/docs/matchers/boolean)