strong-mock 8.0.1 → 9.0.0-beta.1

package/README.md

@@ -2,7 +2,7 @@
 <div align="center">
 <h1>💪 strong-mock</h1>
 
-<p>Simple type safe mocking library</p>
+<p>Type safe mocking library for TypeScript</p>
 </div>
 
 ```typescript
@@ -29,8 +29,9 @@ console.log(foo.bar(23)); // 'I am strong!'
 
 - [Features](#features)
   - [Type safety](#type-safety)
-  - [Useful error messages](#useful-error-messages)
-  - [Type safe argument matchers](#type-safe-argument-matchers)
+  - [Matchers](#matchers)
+  - [Awesome error messages](#awesome-error-messages)
+  - [Works with Promises and Errors](#works-with-promises-and-errors)
 - [Installation](#installation)
 - [Requirements](#requirements)
 - [API](#api)
@@ -43,19 +44,23 @@ console.log(foo.bar(23)); // 'I am strong!'
   - [Throwing errors](#throwing-errors)
   - [Verifying expectations](#verifying-expectations)
   - [Resetting expectations](#resetting-expectations)
-  - [Argument matchers](#argument-matchers)
+  - [Matchers](#matchers-1)
+    - [Creating your own matcher](#creating-your-own-matcher)
 - [Mock options](#mock-options)
   - [Unexpected property return value](#unexpected-property-return-value)
   - [Exact params](#exact-params)
   - [Concrete matcher](#concrete-matcher)
 - [FAQ](#faq)
   - [Why do I have to set all expectations first?](#why-do-i-have-to-set-all-expectations-first)
-  - [Can I partially mock an existing object/function?](#can-i-partially-mock-an-existing-objectfunction)
-  - [How do I set expectations on setters?](#how-do-i-set-expectations-on-setters)
   - [Why do I have to set a return value even if it's `undefined`?](#why-do-i-have-to-set-a-return-value-even-if-its-undefined)
+  - [Why do I get a `Didn't expect mock to be called` error?](#why-do-i-get-a-didnt-expect-mock-to-be-called-error)
+  - [Can I partially mock a concrete implementation?](#can-i-partially-mock-a-concrete-implementation)
+  - [How do I set expectations on setters?](#how-do-i-set-expectations-on-setters)
   - [How do I provide a function for the mock to call?](#how-do-i-provide-a-function-for-the-mock-to-call)
-  - [Can I spread/enumerate a mock?](#can-i-spreadenumerate-a-mock)
+  - [Can I spread or enumerate a mock?](#can-i-spread-or-enumerate-a-mock)
+  - [Why does `typeof mock()` return `function`?](#why-does-typeof-mock-return-function)
   - [How can I ignore `undefined` keys when setting expectations on objects?](#how-can-i-ignore-undefined-keys-when-setting-expectations-on-objects)
+  - [How can I verify order of calls?](#how-can-i-verify-order-of-calls)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -63,31 +68,57 @@ console.log(foo.bar(23)); // 'I am strong!'
 
 ### Type safety
 
-The mock expectations will share the same type guarantees as your production code, and you can safely refactor in an IDE knowing that all usages will be updated.
+The mocks will share the same types as your production code, and you can safely refactor in an IDE knowing that all usages will be updated.
 
 ![Renaming production code and test code](media/rename-refactor.gif)
 
-### Useful error messages
+### Matchers
+
+You can use matchers to partially match values, or create complex expectations, while still maintaining type safety.
+
+![Type safe matchers](media/type-safe-matchers.png)
 
-Error messages include the property that has been accessed, any arguments passed to it and any remaining unmet expectations.
+### Awesome error messages
+
+Failed expectations will print a visual diff, and even integrate with the IDE.
 
 ```typescript
 import { mock, when } from 'strong-mock';
 
-const fn = mock<(a: number, b: number, c: number) => number>();
+const fn = mock<(pos: { x: number; y: number }) => boolean>();
 
-when(() => fn(1, 2, 3)).thenReturn(42);
+when(() =>
+  fn(
+    It.isPartial({
+      x: It.isNumber(),
+      y: It.matches<number>((y) => y > 0)
+    })
+  )
+).thenReturn(true);
 
-fn(4, 5, 6);
+fn({ x: 1, y: -1 });
 ```
 
-![Test output showing details about mock expectations](media/error-messages.png)
+![Test output from the IDE showing details about a failed mock expectation](media/error-messages.png)
+
+### Works with Promises and Errors
+
+```typescript
+import { mock, when } from 'strong-mock';
 
-### Type safe argument matchers
+const fn = mock<(id: number) => Promise<string>>();
 
-You can use argument matchers to partially match values, or create complex expectations, while still maintaining type safety.
+when(() => fn(42)).thenResolve('foo');
+when(() => fn(-1)).thenReject('oops');
 
-![Type safe matcher showing a type error](media/type-safe-matchers.png)
+console.log(await fn(42)); // foo
+
+try {
+  await fn(-1);
+} catch (e) {
+  console.log(e.message); // oops
+}
+```
 
 ## Installation
 
@@ -99,6 +130,10 @@ npm i -D strong-mock
 yarn add -D strong-mock
 ```
 
+```shell
+pnpm add -D strong-mock
+```
+
 ## Requirements
 
 strong-mock requires an environment that supports the [ES6 Proxy object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). This is necessary to create dynamic mocks from types because TypeScript does not support reflection i.e. exposing the type info at runtime.
@@ -107,7 +142,7 @@ strong-mock requires an environment that supports the [ES6 Proxy object](https:/
 
 ### Setting expectations
 
-Expectations are set by calling the mock inside a `when` callback and finishing it by setting a return value.
+Expectations are set by calling the mock inside a `when` callback and setting a return value.
 
 ```typescript
 when(() => foo.bar(23)).thenReturn('awesome');
@@ -186,7 +221,7 @@ const fn = mock<Fn>();
 
 when(() => fn(1)).thenResolve(2);
 
-console.log(await fn()); // 2
+console.log(await fn(1)); // 2
 ```
 
 ### Throwing errors
@@ -239,10 +274,10 @@ It is recommended that you call `verify()` on your mocks at the end of every tes
 ```typescript
 afterEach(() => {
   verifyAll();
-})
+});
 ```
 
-![verify error](./media/verify.png)
+![verify error](media/verify.png)
 
 ### Resetting expectations
 
@@ -263,10 +298,10 @@ If you create common mocks that are shared by multiple tests you should reset th
 ```typescript
 beforeEach(() => {
   resetAll();
-})
+});
 ```
 
-### Argument matchers
+### Matchers
 
 Sometimes you're not interested in specifying all the arguments in an expectation. Maybe they've been covered in another test, maybe they're hard to specify e.g. callbacks, or maybe you want to match just a property from an argument.
 
@@ -277,7 +312,7 @@ const fn = mock<
 
 when(() => fn(
   It.isAny(),
-  It.isObject({ values: [1, 2, 3] })
+  It.isPartial({ values: [1, 2, 3] })
 )).thenReturn('matched!');
 
 console.log(fn(
@@ -286,10 +321,10 @@ console.log(fn(
 ); // 'matched!'
 ```
 
-You can mix argument matchers with concrete arguments:
+You can mix matchers with concrete arguments:
 
 ```typescript
-when(() => fn(42, It.isObject())).thenReturn('matched');
+when(() => fn(42, It.isPlainObject())).thenReturn('matched');
 ```
 
 Available matchers:
@@ -299,9 +334,10 @@ Available matchers:
 - `isNumber` - matches any number,
 - `isString` - matches any string, can search for substrings and patterns,
 - `isArray` - matches any array, can search for subsets,
-- `isObject` - matches any object, can search for partial objects,
-- `matches` - build your own matcher,
-- `willCapture` - matches anything and stores the received value.
+- `isPlainObject` - matches any plain object,
+- `isPartial` - recursively matches a subset of an object,
+- `willCapture` - matches anything and stores the received value,
+- `matches` - [build your own matcher](#creating-your-own-matcher).
 
 The following table illustrates the differences between the equality matchers:
 
@@ -312,27 +348,16 @@ The following table illustrates the differences between the equality matchers:
 | `{ }`              | `{ foo: undefined }` | not equal | not equal       | equal                              |
 | `new (class {})()` | `new (class {})()`   | not equal | not equal       | equal                              |
 
-Some matchers, like `isObject` and `isArray` support nesting matchers:
+Some matchers, like `isPartial` and `isArray` support nesting matchers:
 
 ```typescript
-It.isObject({ foo: It.isString() })
+It.isPartial({ foo: It.isString() })
 
-It.isArray([ It.isObject({
+It.isArray([ It.isPartial({
   foo: It.isString({ matching: /foo/ })
 })])
 ```
 
-You can create arbitrarily complex and type safe matchers with `It.matches(cb)`:
-
-```typescript
-const fn = mock<(x: number, y: number[]) => string>();
-
-when(() => fn(
-  It.matches(x => x > 0),
-  It.matches(y => y.includes(42))
-)).thenReturn('matched');
-```
-
 `It.willCapture` is a special matcher that will match any value and store it, so you can access it outside an expectation. This could be useful to capture a callback and then test it separately.
 
 ```ts
@@ -347,6 +372,57 @@ console.log(fn(23, (x) => x + 1)); // 42
 console.log(matcher.value?.(3)); // 4
 ```
 
+#### Creating your own matcher
+
+You can create arbitrarily complex and type safe matchers with `It.matches()`:
+
+```typescript
+const fn = mock<(x: number, y: string) => string>();
+
+when(() => fn(
+  It.matches(x => x > 0),
+  It.matches(y => y.startsWith('foo'))
+)).thenReturn('matched');
+```
+
+The types are automatically inferred, but you can also specify them explicitly through the generic parameter, which is useful if you want to create reusable matchers:
+
+```typescript
+const startsWith = (expected: string) => It.matches<string>(
+  actual => actual.startsWith(expected)
+);
+
+when(() => fn(42, startsWith('foo'))).thenReturn('matched');
+
+fn(42, 'foobar') // 'matched'
+```
+
+You can also customize how the matcher is printed in error messages, and how the diff is printed:
+
+```typescript
+const closeTo = (expected: number, precision = 0.01) => It.matches<number>(
+  actual => Math.abs(expected - actual) <= precision,
+  {
+    toString: () => `closeTo(${expected}, ${precision})`,
+    getDiff: (actual) => {
+      const diff = Math.abs(expected - actual);
+      const sign = diff < 0 ? '-' : '+';
+      
+      return {
+        actual: `${actual} (${sign}${diff})`,
+        expected: `${expected} ±${precision}`,
+      };
+    }
+  }
+);
+
+when(() => fn(closeTo(1), 'foo')).thenReturn('matched');
+
+fn(2, 'foo');
+```
+
+![Error message for custom matcher](media/custom-matcher.png)
+
 ## Mock options
 
 The following options can be set per mock, or globally with `setDefaults`.
@@ -397,7 +473,7 @@ propertiesThrow.bar(42);
 
 ### Exact params
 
-By default, function/method expectations will allow more arguments to be received than expected. Since the expectations are type safe, the TypeScript compiler will never allow expecting less arguments than required. Unspecified optional arguments will be considered ignored, as if they've been replaced with [argument matchers](#argument-matchers).
+By default, function/method expectations will allow more arguments to be received than expected. Since the expectations are type safe, the TypeScript compiler will never allow expecting less arguments than required. Unspecified optional arguments will be considered ignored, as if they've been replaced with [matchers](#matchers-1).
 
 ```typescript
 import { mock } from 'strong-mock';
@@ -429,7 +505,7 @@ console.log(fn(1)); // throws
 
 ### Concrete matcher
 
-You can configure the [matcher](#argument-matchers) that will be used in expectations with concrete values e.g. `42` or `{ foo: "bar" }`. This matcher can always be overwritten inside an expectation with another matcher.
+You can configure the [matcher](#matchers-1) that will be used in expectations with concrete values e.g. `42` or `{ foo: "bar" }`. This matcher can always be overwritten inside an expectation with another matcher.
 
 ```typescript
 import { mock, when, It } from 'strong-mock';
@@ -458,7 +534,19 @@ This design decision has a few reasons behind it. First, it forces you to be awa
 
 Secondly, it will highlight potential design problems such as violations of the SOLID principles. If you find yourself duplicating expectations between tests and passing dummy values to them because your test is not concerned with them, then you might want to look into splitting the code to only depend on things it really needs.
 
-### Can I partially mock an existing object/function?
+### Why do I have to set a return value even if it's `undefined`?
+
+To make side effects explicit and to prevent future refactoring headaches. If you had just `when(() => fn())`, and you later changed `fn()` to return a `number`, then your expectation would become incorrect and the compiler couldn't check that for you.
+
+### Why do I get a `Didn't expect mock to be called` error?
+
+This error happens when your code under test calls a mock that didn't have a matching expectation. It could be that the arguments received didn't match the ones set in the expectation (see [matchers](#matchers-1)), or the call was made more than the allowed number of times (see [invocation count expectations](#setting-invocation-count-expectations)).
+
+In rare cases, the code under test may try to inspect the mock by accessing special properties on it. For instance, wrapping a mock in `Promise.resolve()` will try to access a `.then` property on it. strong-mock returns stub values for most of these, but if you find another one feel free to [open an issue](https://github.com/NiGhTTraX/strong-mock/issues) with a minimal reproduction.
+
+Unfortunately, not all of these cases can be covered with stub values, and you may have to slightly adjust your code to work around this issue.
+
+### Can I partially mock a concrete implementation?
 
 No, passing a concrete implementation to `mock()` will be the same as passing a type: all properties will be mocked, and you have to set expectations on the ones that will be accessed.
 
@@ -466,10 +554,6 @@ No, passing a concrete implementation to `mock()` will be the same as passing a
 
 You currently can't do that. Please use a normal method instead e.g. `setFoo()` vs `set foo()`.
 
-### Why do I have to set a return value even if it's `undefined`?
-
-To make side effects explicit and to prevent future refactoring headaches. If you had just `when(() => fn())`, and you later changed `fn()` to return a `number`, then your expectation would become incorrect and the compiler couldn't check that for you.
-
 ### How do I provide a function for the mock to call?
 
 There is no `thenCall()` method because it can't be safely typed - the type for `thenReturn()` is inferred from the return type in `when`, meaning that the required type would be the return value for the function, not the function itself. However, we can leverage this by setting an expectation on the function property instead:
@@ -488,7 +572,7 @@ console.log(foo.bar(23)); // 'called 23'
 
 The function in `thenReturn()` will be type checked against the actual interface, so you can make sure you're passing in an implementation that makes sense. Moreover, refactoring the interface will also refactor the expectation (in a capable IDE).
 
-### Can I spread/enumerate a mock?
+### Can I spread or enumerate a mock?
 
 Yes, and you will only get the properties that have expectations on them.
 
@@ -504,6 +588,10 @@ console.log(foo2.bar); // 42
 console.log(foo2.baz); // undefined
 ```
 
+### Why does `typeof mock()` return `function`?
+
+All mocks and methods on them are functions in order to intercept function calls.
+
 ### How can I ignore `undefined` keys when setting expectations on objects?
 
 Use the `It.deepEquals` matcher explicitly inside `when` and pass `{ strict: false }`:
@@ -525,3 +613,7 @@ setDefaults({
   concreteMatcher: (expected) => It.deepEquals(expected, { strict: false })
 });
 ```
+
+### How can I verify order of calls?
+
+`when()` expectations can be satisfied in any order. If your code under test depends on a specific order of execution, consider redesigning it to remove the coupling before the different calls.

package/dist/errors/api.d.ts

@@ -0,0 +1,13 @@
+import type { Property } from '../proxy';
+export declare class UnfinishedExpectation extends Error {
+    constructor(property: Property, args: any[] | undefined);
+}
+export declare class MissingWhen extends Error {
+    constructor();
+}
+export declare class NotAMock extends Error {
+    constructor();
+}
+export declare class NestedWhen extends Error {
+    constructor(parentProp: Property, childProp: Property);
+}

package/dist/errors/diff.d.ts

@@ -0,0 +1,4 @@
+import type { Expectation } from '../expectation/expectation';
+export declare const printArgsDiff: (expected: unknown[], actual: unknown[]) => string;
+export declare const printExpectationDiff: (e: Expectation, args: unknown[]) => string;
+export declare const printDiffForAllExpectations: (expectations: Expectation[], actual: unknown[]) => string;

package/dist/errors/unexpected-access.d.ts

@@ -0,0 +1,5 @@
+import type { Expectation } from '../expectation/expectation';
+import type { Property } from '../proxy';
+export declare class UnexpectedAccess extends Error {
+    constructor(property: Property, expectations: Expectation[]);
+}

package/dist/errors/unexpected-call.d.ts

@@ -0,0 +1,14 @@
+import type { Expectation } from '../expectation/expectation';
+import type { Property } from '../proxy';
+type MatcherResult = {
+    expected: unknown;
+    actual: unknown;
+};
+interface MatcherError {
+    matcherResult?: MatcherResult;
+}
+export declare class UnexpectedCall extends Error implements MatcherError {
+    matcherResult?: MatcherResult;
+    constructor(property: Property, args: unknown[], expectations: Expectation[]);
+}
+export {};

package/dist/errors/verify.d.ts

@@ -0,0 +1,8 @@
+import type { Expectation } from '../expectation/expectation';
+import type { CallMap } from '../expectation/repository/expectation-repository';
+export declare class UnmetExpectations extends Error {
+    constructor(expectations: Expectation[]);
+}
+export declare class UnexpectedCalls extends Error {
+    constructor(unexpectedCalls: CallMap, expectations: Expectation[]);
+}

package/dist/expectation/expectation.d.ts

@@ -1,30 +1,27 @@
-import type { Property } from '../proxy';
-import type { Matcher } from './matcher';
-import type { ReturnValue } from './repository/return-value';
-/**
- * Compare received arguments against matchers.
- */
-export interface Expectation {
-    property: Property;
-    /**
-     * `undefined` means this is a property expectation.
-     * `[]` means this is a function call with no arguments.
-     */
-    args: Matcher[] | undefined;
-    returnValue: ReturnValue;
-    min: number;
-    max: number;
-    /**
-     * How many times should this expectation match?
-     */
-    setInvocationCount(min: number, max: number): void;
-    matches(args: any[] | undefined): boolean;
-    /**
-     * Used by `pretty-format`.
-     */
-    toJSON(): string;
-}
-/**
- * Special symbol denoting the call of a function.
- */
-export declare const ApplyProp: unique symbol;
+import type { Matcher } from '../matchers/matcher';
+import type { Property } from '../proxy';
+import type { ReturnValue } from './repository/return-value';
+/**
+ * Compare received arguments against matchers.
+ */
+export interface Expectation {
+    property: Property;
+    /**
+     * `undefined` means this is a property expectation.
+     * `[]` means this is a function call with no arguments.
+     */
+    args: Matcher[] | undefined;
+    returnValue: ReturnValue;
+    min: number;
+    max: number;
+    /**
+     * How many times should this expectation match?
+     */
+    setInvocationCount: (min: number, max: number) => void;
+    matches: (args: unknown[] | undefined) => boolean;
+    toString: () => string;
+}
+/**
+ * Special symbol denoting the call of a function.
+ */
+export declare const ApplyProp: unique symbol;

package/dist/expectation/repository/expectation-repository.d.ts

@@ -1,90 +1,90 @@
-import type { Property } from '../../proxy';
-import type { Expectation } from '../expectation';
-export type Call = {
-    arguments: any[] | undefined;
-};
-/**
- * Method calls should be recorded both as a property access and a method call.
- *
- * @example
- * // foo.bar(1, 2, 3) should generate
- * {
- *   foo: [
- *     { arguments: undefined },
- *     { arguments: [1, 2, 3] }
- *   ]
- * }
- */
-export type CallMap = Map<Property, Call[]>;
-export type CallStats = {
-    /**
-     * Calls that matched existing expectations.
-     */
-    expected: CallMap;
-    /**
-     * Calls that didn't match any existing expectation.
-     */
-    unexpected: CallMap;
-};
-export interface ExpectationRepository {
-    add(expectation: Expectation): void;
-    /**
-     * Get a return value for the given property.
-     *
-     * The value might be a non-callable e.g. a number or a string, or it might
-     * be a function that, upon receiving arguments, will start a new search and
-     * return a value again.
-     *
-     * The list of expectations should be consulted from first to last when
-     * getting a return value. If none of them match it is up to the
-     * implementation to decide what to do.
-     *
-     * @example
-     * add(new Expectation('getData', [1, 2], 23);
-     * get('getData')(1, 2) === 23
-     *
-     * @example
-     * add(new Expectation('hasData', undefined, true);
-     * get('hasData') === true
-     *
-     * @example
-     * add(new Expectation('getData', undefined, () => 42);
-     * get('getData')(1, 2, '3', false, NaN) === 42
-     */
-    get(property: Property): unknown;
-    /**
-     * Get a return value for a function call.
-     *
-     * Note: this will only be invoked if the mocked type is a function. For
-     * method property calls {@link get} will be called instead.
-     *
-     * The list of expectations should be consulted from first to last when
-     * getting a return value. If none of them match it is up to the
-     * implementation to decide what to do.
-     *
-     * @example
-     * add(new Expectation(ApplyProp, [1, 2], 23);
-     * apply(1, 2) === 23
-     */
-    apply(args: unknown[]): unknown;
-    /**
-     * Get all the properties that have expectations.
-     *
-     * @example
-     * add(new Expectation('foo', undefined, 23));
-     * getAllProperties() === ['foo']
-     */
-    getAllProperties(): Property[];
-    /**
-     * Remove any expectations and clear the call stats.
-     */
-    clear(): void;
-    /**
-     * Return all unmet expectations.
-     */
-    getUnmet(): Expectation[];
-    /**
-     * Return all the calls that have been made so far.
-     */
-    getCallStats(): CallStats;
-}
+import type { Property } from '../../proxy';
+import type { Expectation } from '../expectation';
+export type Call = {
+    arguments: any[] | undefined;
+};
+/**
+ * Method calls should be recorded both as a property access and a method call.
+ *
+ * @example
+ * // foo.bar(1, 2, 3) should generate
+ * {
+ *   foo: [
+ *     { arguments: undefined },
+ *     { arguments: [1, 2, 3] }
+ *   ]
+ * }
+ */
+export type CallMap = Map<Property, Call[]>;
+export type CallStats = {
+    /**
+     * Calls that matched existing expectations.
+     */
+    expected: CallMap;
+    /**
+     * Calls that didn't match any existing expectation.
+     */
+    unexpected: CallMap;
+};
+export interface ExpectationRepository {
+    add: (expectation: Expectation) => void;
+    /**
+     * Get a return value for the given property.
+     *
+     * The value might be a non-callable e.g. a number or a string, or it might
+     * be a function that, upon receiving arguments, will start a new search and
+     * return a value again.
+     *
+     * The list of expectations should be consulted from first to last when
+     * getting a return value. If none of them match it is up to the
+     * implementation to decide what to do.
+     *
+     * @example
+     * add(new Expectation('getData', [1, 2], 23);
+     * get('getData')(1, 2) === 23
+     *
+     * @example
+     * add(new Expectation('hasData', undefined, true);
+     * get('hasData') === true
+     *
+     * @example
+     * add(new Expectation('getData', undefined, () => 42);
+     * get('getData')(1, 2, '3', false, NaN) === 42
+     */
+    get: (property: Property) => unknown;
+    /**
+     * Get a return value for a function call.
+     *
+     * Note: this will only be invoked if the mocked type is a function. For
+     * method property calls {@link get} will be called instead.
+     *
+     * The list of expectations should be consulted from first to last when
+     * getting a return value. If none of them match it is up to the
+     * implementation to decide what to do.
+     *
+     * @example
+     * add(new Expectation(ApplyProp, [1, 2], 23);
+     * apply(1, 2) === 23
+     */
+    apply: (args: unknown[]) => unknown;
+    /**
+     * Get all the properties that have expectations.
+     *
+     * @example
+     * add(new Expectation('foo', undefined, 23));
+     * getAllProperties() === ['foo']
+     */
+    getAllProperties: () => Property[];
+    /**
+     * Remove any expectations and clear the call stats.
+     */
+    clear: () => void;
+    /**
+     * Return all unmet expectations.
+     */
+    getUnmet: () => Expectation[];
+    /**
+     * Return all the calls that have been made so far.
+     */
+    getCallStats: () => CallStats;
+}