strong-mock 8.0.1 → 9.0.0-beta.0

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,8 @@ 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)
 - [Installation](#installation)
 - [Requirements](#requirements)
 - [API](#api)
@@ -43,18 +43,19 @@ 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)
 - [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 get a `Didn't expect mock to be called` error?](#why-do-i-get-a-didnt-expect-mock-to-be-called-error)
   - [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)
+  - [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)
   - [How can I ignore `undefined` keys when setting expectations on objects?](#how-can-i-ignore-undefined-keys-when-setting-expectations-on-objects)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -67,27 +68,34 @@ The mock expectations will share the same type guarantees as your production cod
 
 ![Renaming production code and test code](media/rename-refactor.gif)
 
-### Useful error messages
+### Matchers
 
-Error messages include the property that has been accessed, any arguments passed to it and any remaining unmet expectations.
+You can use matchers to partially match values, or create complex expectations, while still maintaining type safety.
 
-```typescript
-import { mock, when } from 'strong-mock';
+![Type safe matcher showing a type error](media/type-safe-matchers.png)
 
-const fn = mock<(a: number, b: number, c: number) => number>();
+### Awesome error messages
 
-when(() => fn(1, 2, 3)).thenReturn(42);
+Failed expectations will print a visual diff, and even integrate with the IDE.
 
-fn(4, 5, 6);
-```
+```typescript
+import { mock, when } from 'strong-mock';
 
-![Test output showing details about mock expectations](media/error-messages.png)
+const fn = mock<(pos: { x: number; y: number }) => boolean>();
 
-### Type safe argument matchers
+when(() =>
+  fn(
+    It.isObject({
+      x: It.isNumber(),
+      y: It.matches<number>((y) => y > 0)
+    })
+  )
+).thenReturn(true);
 
-You can use argument matchers to partially match values, or create complex expectations, while still maintaining type safety.
+fn({ x: 1, y: -1 });
+```
 
-![Type safe matcher showing a type error](media/type-safe-matchers.png)
+![Test output from the IDE showing details about a failed mock expectation](media/error-messages.png)
 
 ## Installation
 
@@ -99,6 +107,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 +119,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 +198,7 @@ const fn = mock<Fn>();
 
 when(() => fn(1)).thenResolve(2);
 
-console.log(await fn()); // 2
+console.log(await fn(1)); // 2
 ```
 
 ### Throwing errors
@@ -266,7 +278,7 @@ beforeEach(() => {
 })
 ```
 
-### 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.
 
@@ -286,7 +298,7 @@ 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');
@@ -397,7 +409,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 +441,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,18 +470,28 @@ 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 get a `Didn't expect mock to be called` error?
 
-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.
+This error happens when your code under test calls a method from the mock, or the mock itself if it's a function, 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)).
 
-### How do I set expectations on setters?
+In rare cases, the code under test may try to inspect the mock by accessing special properties on it. For instance, React's `setState(state)` accepts 2 types of values: functions and everything else. To differentiate between the 2 types, React will internally do a `typeof` check. All mocks created by strong-mock return `'function'` for this check, so React will try to call them in case you pass them directly to `setState`. This might lead to the `Didn't expect mock(...) to be called` error, as the mock receives the previous state and doesn't find an expectation for it.
 
-You currently can't do that. Please use a normal method instead e.g. `setFoo()` vs `set foo()`.
+If you run into any of these cases, feel free to [open an issue](https://github.com/NiGhTTraX/strong-mock/issues) with a minimal reproduction. Most of the time the issue can be fixed by returning stubbed values for these special properties.
+
+Unfortunately, this is not always possible, such as with the React example above. You might have to adjust your code slightly to work around the checks your code, or some library, is doing. With React, simply putting the mock inside an object e.g. `setState({ foo: theMock })` will avoid the `typeof` check and work as expected.
 
 ### 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.
 
+### 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.
+
+### How do I set expectations on setters?
+
+You currently can't do that. Please use a normal method instead e.g. `setFoo()` vs `set foo()`.
+
 ### 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 +510,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.
 

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/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,17 @@
+import type { Expectation } from '../expectation/expectation';
+import type { Property } from '../proxy';
+type MatcherResult = {
+    expected: unknown;
+    actual: unknown;
+};
+interface MatcherError {
+    matcherResult?: MatcherResult;
+}
+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;
+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;
+}

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

@@ -1,38 +1,38 @@
-import { UnexpectedProperty } from '../../mock/options';
-import type { Property } from '../../proxy';
-import type { Expectation } from '../expectation';
-import type { CallMap, ExpectationRepository } from './expectation-repository';
-type CountableExpectation = {
-    expectation: Expectation;
-    matchCount: number;
-};
-/**
- * An expectation repository with a configurable behavior for
- * unexpected property access.
- */
-export declare class FlexibleRepository implements ExpectationRepository {
-    private unexpectedProperty;
-    constructor(unexpectedProperty?: UnexpectedProperty);
-    protected readonly expectations: Map<Property, CountableExpectation[]>;
-    private readonly expectedCallStats;
-    private readonly unexpectedCallStats;
-    add(expectation: Expectation): void;
-    clear(): void;
-    apply: (args: unknown[]) => unknown;
-    get(property: Property): any;
-    private handlePropertyWithMatchingExpectations;
-    private handlePropertyWithNoExpectations;
-    getAllProperties(): Property[];
-    getCallStats(): {
-        expected: CallMap;
-        unexpected: CallMap;
-    };
-    getUnmet(): Expectation[];
-    private recordExpected;
-    private recordUnexpected;
-    private countAndConsume;
-    private consumeExpectation;
-    private getValueForUnexpectedCall;
-    private getValueForUnexpectedAccess;
-}
-export {};
+import { UnexpectedProperty } from '../../mock/options';
+import type { Property } from '../../proxy';
+import type { Expectation } from '../expectation';
+import type { CallMap, ExpectationRepository } from './expectation-repository';
+type CountableExpectation = {
+    expectation: Expectation;
+    matchCount: number;
+};
+/**
+ * An expectation repository with a configurable behavior for
+ * unexpected property access.
+ */
+export declare class FlexibleRepository implements ExpectationRepository {
+    private unexpectedProperty;
+    constructor(unexpectedProperty?: UnexpectedProperty);
+    protected readonly expectations: Map<Property, CountableExpectation[]>;
+    private readonly expectedCallStats;
+    private readonly unexpectedCallStats;
+    add(expectation: Expectation): void;
+    clear(): void;
+    apply: (args: unknown[]) => unknown;
+    get(property: Property): any;
+    private handlePropertyWithMatchingExpectations;
+    private handlePropertyWithNoExpectations;
+    getAllProperties(): Property[];
+    getCallStats(): {
+        expected: CallMap;
+        unexpected: CallMap;
+    };
+    getUnmet(): Expectation[];
+    private recordExpected;
+    private recordUnexpected;
+    private countAndConsume;
+    private consumeExpectation;
+    private getValueForUnexpectedCall;
+    private getValueForUnexpectedAccess;
+}
+export {};

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

@@ -1,13 +1,13 @@
-export type ReturnValue = {
-    value: any;
-    isPromise?: boolean;
-    isError?: boolean;
-};
-/**
- * Unbox the expectation's return value.
- *
- * If the value is an error then throw it.
- *
- * If the value is a promise then resolve/reject it.
- */
-export declare const unboxReturnValue: ({ isError, isPromise, value, }: ReturnValue) => any;
+export type ReturnValue = {
+    value: any;
+    isPromise?: boolean;
+    isError?: boolean;
+};
+/**
+ * Unbox the expectation's return value.
+ *
+ * If the value is an error then throw it.
+ *
+ * If the value is a promise then resolve/reject it.
+ */
+export declare const unboxReturnValue: ({ isError, isPromise, value, }: ReturnValue) => any;

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

@@ -1,30 +1,30 @@
-import type { Property } from '../proxy';
-import type { Expectation } from './expectation';
-import type { Matcher } from './matcher';
-import type { ReturnValue } from './repository/return-value';
-/**
- * Matches a call with more parameters than expected because it is assumed the
- * compiler will check that those parameters are optional.
- *
- * @example
- * new StrongExpectation(
- *   'bar',
- *   deepEquals([1, 2, 3]),
- *   23
- * ).matches('bar', [1, 2, 3]) === true;
- */
-export declare class StrongExpectation implements Expectation {
-    property: Property;
-    args: Matcher[] | undefined;
-    returnValue: ReturnValue;
-    private exactParams;
-    private matched;
-    min: number;
-    max: number;
-    constructor(property: Property, args: Matcher[] | undefined, returnValue: ReturnValue, exactParams?: boolean);
-    setInvocationCount(min: number, max?: number): void;
-    matches(args: any[] | undefined): boolean;
-    isUnmet(): boolean;
-    private matchesArgs;
-    toJSON(): string;
-}
+import type { Matcher } from '../matchers/matcher';
+import type { Property } from '../proxy';
+import type { Expectation } from './expectation';
+import type { ReturnValue } from './repository/return-value';
+/**
+ * Matches a call with more parameters than expected because it is assumed the
+ * compiler will check that those parameters are optional.
+ *
+ * @example
+ * new StrongExpectation(
+ *   'bar',
+ *   deepEquals([1, 2, 3]),
+ *   23
+ * ).matches('bar', [1, 2, 3]) === true;
+ */
+export declare class StrongExpectation implements Expectation {
+    property: Property;
+    args: Matcher[] | undefined;
+    returnValue: ReturnValue;
+    private exactParams;
+    private matched;
+    min: number;
+    max: number;
+    constructor(property: Property, args: Matcher[] | undefined, returnValue: ReturnValue, exactParams?: boolean);
+    setInvocationCount(min: number, max?: number): void;
+    matches(args: any[] | undefined): boolean;
+    isUnmet(): boolean;
+    private matchesArgs;
+    toString(): string;
+}