Closes #253: Add change matchers, .toChange(), .toChangeBy(), .toChangeTo() (#521)

* Add change matchers: .toChange(), .toChangeBy(), and .toChangeTo()

* Add docs for change matchers

* Fix incomplete test description

* Applies notes from code review: improves typescript types and asserts support for non-numeric values

* Migrate to TypeScript

* Use unknown instead of any

---------

Co-authored-by: Keegan Witt <[email protected]>

Author: MrLeebo

src/matchers/index.ts

@@ -34,6 +34,9 @@ export { toBeSymbol } from './toBeSymbol';
 export { toBeTrue } from './toBeTrue';
 export { toBeValidDate } from './toBeValidDate';
 export { toBeWithin } from './toBeWithin';
+export { toChange } from './toChange';
+export { toChangeBy } from './toChangeBy';
+export { toChangeTo } from './toChangeTo';
 export { toContainAllEntries } from './toContainAllEntries';
 export { toContainAllKeys } from './toContainAllKeys';
 export { toContainAllValues } from './toContainAllValues';

src/matchers/toChange.ts

@@ -0,0 +1,23 @@
+/**
+ * Use `.toChange` when checking if a value has changed.
+ * @example
+ * expect(() => value--).toChange(() => value);
+ */
+export function toChange(mutator: () => unknown | void, checker: () => number) {
+  // @ts-expect-error OK to have implicit any for this.utils
+  const { printReceived: print, matcherHint: hint } = this.utils;
+
+  const before = checker();
+  mutator();
+  const received = checker();
+
+  const passMessage = `
+  ${hint('.not.toChange', 'received', '')}\n\nExpected value to not change, received:\n  ${print(received)}
+  `.trim();
+  const failMessage = `
+  ${hint('.toChange', 'received', '')}\n\nExpected value to change, received:\n  ${print(received)}
+  `.trim();
+
+  const pass = received !== before;
+  return { pass, message: () => (pass ? passMessage : failMessage) };
+}

src/matchers/toChangeBy.ts

@@ -0,0 +1,23 @@
+/**
+ * Use `.toChangeBy` when checking if a value changed by an amount.
+ * @example
+ * expect(() => value--).toChangeBy(() => value, -1);
+ */
+export function toChangeBy(mutator: () => unknown | void, checker: () => number, by: number = 1) {
+  // @ts-expect-error OK to have implicit any for this.utils
+  const { printReceived: print, matcherHint: hint } = this.utils;
+
+  const before = checker();
+  mutator();
+  const received = checker() - before;
+
+  const passMessage = `
+${hint('.not.toChangeBy', 'received', '')}\n\nExpected value to not change by ${by}, received:\n  ${print(received)}
+`.trim();
+  const failMessage = `
+${hint('.toChangeBy', 'received', '')}\n\nExpected value to change by ${by}, received:\n  ${print(received)}
+`.trim();
+
+  const pass = received === by;
+  return { pass, message: () => (pass ? passMessage : failMessage) };
+}

src/matchers/toChangeTo.ts

@@ -0,0 +1,33 @@
+/**
+ * Use `.toChangeTo` when checking if a value changed to a specific value.
+ * @example
+ * expect(() => Model.deleteAll()).toChangeTo(() => Model.count(), 0);
+ */
+export function toChangeTo(mutator: () => unknown | void, checker: () => number, to: number) {
+  // @ts-expect-error OK to have implicit any for this.utils
+  const { printReceived: print, matcherHint: hint } = this.utils;
+
+  const before = checker();
+
+  if (before === to) {
+    const noChangeMessage = `${hint(
+      '.toChangeTo',
+      'received',
+      '',
+    )}\n\nCannot expect a value to change to its original state, received:  ${print(before)}`;
+    return { pass: false, message: () => noChangeMessage };
+  }
+
+  mutator();
+  const received = checker();
+
+  const passMessage = `
+${hint('.not.toChangeTo', 'received', '')}\n\nExpected value to not change to ${to}, received:\n  ${print(received)}
+`.trim();
+  const failMessage = `
+${hint('.toChangeto', 'received', '')}\n\nExpected value to change to ${to}, received:\n  ${print(received)}
+`.trim();
+
+  const pass = received !== before && received === to;
+  return { pass, message: () => (pass ? passMessage : failMessage) };
+}

test/fixtures/counter.ts

@@ -0,0 +1,22 @@
+export class Counter {
+  private value: number;
+
+  constructor() {
+    this.increment = this.increment.bind(this);
+    this.count = this.count.bind(this);
+    this.reset = this.reset.bind(this);
+    this.value = 0;
+  }
+
+  increment() {
+    this.value++;
+  }
+
+  count() {
+    return this.value;
+  }
+
+  reset() {
+    this.value = 0;
+  }
+}

test/matchers/__snapshots__/toChange.test.ts.snap

@@ -0,0 +1,29 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toChange fails when a value expected not to change defies all expectations and changes 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toChange()</intensity>
+
+Expected value to not change, received:
+  <red>1</color>"
+`;
+
+exports[`.not.toChange fails when mutating a counter 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toChange()</intensity>
+
+Expected value to not change, received:
+  <red>1</color>"
+`;
+
+exports[`.toChange fails when a given value does not increment 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toChange()</intensity>
+
+Expected value to change, received:
+  <red>0</color>"
+`;
+
+exports[`.toChange fails when not mutating a counter 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toChange()</intensity>
+
+Expected value to change, received:
+  <red>0</color>"
+`;

test/matchers/__snapshots__/toChangeBy.test.ts.snap

@@ -0,0 +1,29 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toChangeBy fails when a value expected not to change defies all expectations and changes 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toChangeBy()</intensity>
+
+Expected value to not change by 1, received:
+  <red>1</color>"
+`;
+
+exports[`.not.toChangeBy fails when mutating a counter 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toChangeBy()</intensity>
+
+Expected value to not change by 1, received:
+  <red>1</color>"
+`;
+
+exports[`.toChangeBy fails when a given value does not increment 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toChangeBy()</intensity>
+
+Expected value to change by 1, received:
+  <red>0</color>"
+`;
+
+exports[`.toChangeBy fails when not mutating a counter 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toChangeBy()</intensity>
+
+Expected value to change by 1, received:
+  <red>0</color>"
+`;

test/matchers/__snapshots__/toChangeTo.test.ts.snap

@@ -0,0 +1,35 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toChange fails when a value expected not to change defies all expectations and changes 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toChangeTo()</intensity>
+
+Expected value to not change to 1, received:
+  <red>1</color>"
+`;
+
+exports[`.not.toChange fails when mutating a counter 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).not.toChangeTo()</intensity>
+
+Expected value to not change to 1, received:
+  <red>1</color>"
+`;
+
+exports[`.toChangeTo fails when a given value does not increment 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toChangeto()</intensity>
+
+Expected value to change to 1, received:
+  <red>0</color>"
+`;
+
+exports[`.toChangeTo fails when not mutating a counter 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toChangeto()</intensity>
+
+Expected value to change to 1, received:
+  <red>0</color>"
+`;
+
+exports[`.toChangeTo fails when resetting a counter back because a change cannot be the same as the initial value 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).toChangeTo()</intensity>
+
+Cannot expect a value to change to its original state, received:  <red>0</color>"
+`;

test/matchers/toChange.test.ts

@@ -0,0 +1,48 @@
+import * as matcher from 'src/matchers/toChange';
+import { Counter } from '../fixtures/counter';
+
+expect.extend(matcher);
+
+describe('.toChange', () => {
+  test('passes when given a value that the mutator increments', () => {
+    let value = 0;
+    expect(() => value++).toChange(() => value);
+  });
+
+  test('passes when mutating a counter', () => {
+    const counter = new Counter();
+    expect(counter.increment).toChange(counter.count);
+  });
+
+  test('fails when a given value does not increment', () => {
+    const value = 0;
+    expect(() => expect(() => value).toChange(() => value)).toThrowErrorMatchingSnapshot();
+  });
+
+  test('fails when not mutating a counter', () => {
+    const counter = new Counter();
+    expect(() => expect(counter.count).toChange(counter.count)).toThrowErrorMatchingSnapshot();
+  });
+});
+
+describe('.not.toChange', () => {
+  test('passes when given a mutator that does not increment the value', () => {
+    const value = 0;
+    expect(() => value).not.toChange(() => value);
+  });
+
+  test('passes when not mutating a counter', () => {
+    const counter = new Counter();
+    expect(counter.count).not.toChange(counter.count);
+  });
+
+  test('fails when mutating a counter', () => {
+    const counter = new Counter();
+    expect(() => expect(counter.increment).not.toChange(counter.count)).toThrowErrorMatchingSnapshot();
+  });
+
+  test('fails when a value expected not to change defies all expectations and changes', () => {
+    let value = 0;
+    expect(() => expect(() => value++).not.toChange(() => value)).toThrowErrorMatchingSnapshot();
+  });
+});

test/matchers/toChangeBy.test.ts

@@ -0,0 +1,75 @@
+import * as matcher from 'src/matchers/toChangeBy';
+import { Counter } from '../fixtures/counter';
+
+expect.extend(matcher);
+
+describe('.toChangeBy', () => {
+  test('passes when given a value that the mutator increments', () => {
+    let value = 0;
+    expect(() => value--).toChangeBy(() => value, -1);
+  });
+
+  test('passes when mutating a counter', () => {
+    const counter = new Counter();
+    expect(counter.increment).toChangeBy(counter.count);
+  });
+
+  test('passes when resetting a counter', () => {
+    const counter = new Counter();
+    counter.increment();
+    expect(() => {
+      counter.increment();
+      counter.increment();
+    }).toChangeBy(() => counter.count(), 2);
+  });
+
+  test('fails when a given value does not increment', () => {
+    const value = 0;
+    expect(() => expect(() => value).toChangeBy(() => value)).toThrowErrorMatchingSnapshot();
+  });
+
+  test('fails when not mutating a counter', () => {
+    const counter = new Counter();
+    expect(() => expect(counter.count).toChangeBy(counter.count)).toThrowErrorMatchingSnapshot();
+  });
+
+  test('passes when resetting a counter back', () => {
+    const counter = new Counter();
+    counter.increment();
+    counter.increment();
+    counter.increment();
+    expect(() => counter.reset()).toChangeBy(() => counter.count(), -3);
+  });
+});
+
+describe('.not.toChangeBy', () => {
+  test('passes when given a mutator that does not increment the value', () => {
+    const value = 0;
+    expect(() => value).not.toChangeBy(() => value, 1);
+  });
+
+  test('passes when not mutating a counter', () => {
+    const counter = new Counter();
+    expect(counter.count).not.toChangeBy(counter.count, 1);
+  });
+
+  test('fails when resetting a counter', () => {
+    const counter = new Counter();
+    expect(() => {
+      counter.increment();
+      counter.increment();
+      counter.increment();
+      counter.reset();
+    }).not.toChangeBy(() => counter.count(), -3);
+  });
+
+  test('fails when mutating a counter', () => {
+    const counter = new Counter();
+    expect(() => expect(counter.increment).not.toChangeBy(counter.count, 1)).toThrowErrorMatchingSnapshot();
+  });
+
+  test('fails when a value expected not to change defies all expectations and changes', () => {
+    let value = 0;
+    expect(() => expect(() => value++).not.toChangeBy(() => value, 1)).toThrowErrorMatchingSnapshot();
+  });
+});