strong-mock 8.0.0-beta.0 → 8.0.0-beta.2

package/README.md

@@ -44,14 +44,16 @@ console.log(foo.bar(23)); // 'I am strong!'
   - [Verifying expectations](#verifying-expectations)
   - [Resetting expectations](#resetting-expectations)
   - [Argument matchers](#argument-matchers)
-  - [Overriding default matcher](#overriding-default-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 mock an existing object/function?](#can-i-mock-an-existing-objectfunction)
+  - [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)
   - [How do I provide a function for the mock to call?](#how-do-i-provide-a-function-for-the-mock-to-call)
-  - [Why does accessing an unused method throw?](#why-does-accessing-an-unused-method-throw)
   - [Can I spread/enumerate a mock?](#can-i-spreadenumerate-a-mock)
   - [How can I ignore `undefined` keys when setting expectations on objects?](#how-can-i-ignore-undefined-keys-when-setting-expectations-on-objects)
 
@@ -61,29 +63,39 @@ console.log(foo.bar(23)); // 'I am strong!'
 
 ### Type safety
 
-The created mock matches the mocked type so all expectations are type safe. Moreover, refactorings in an IDE will also cover your expectations.
+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.
 
-![rename-interface](media/rename-interface.gif)
+![Renaming production code and test code](media/rename-refactor.gif)
 
 ### Useful error messages
 
 Error messages include the property that has been accessed, any arguments passed to it and any remaining unmet expectations.
 
-![error messages](media/error-messages.png)
+```typescript
+import { mock, when } from 'strong-mock';
+
+const fn = mock<(a: number, b: number, c: number) => number>();
+
+when(() => fn(1, 2, 3)).thenReturn(42);
+
+fn(4, 5, 6);
+```
+
+![Test output showing details about mock expectations](media/error-messages.png)
 
 ### Type safe argument matchers
 
-Optional argument matchers allow you to create complex expectations, while still maintaining type safety.
+You can use argument matchers to partially match values, or create complex expectations, while still maintaining type safety.
 
-![type safe matchers](./media/type-safe-matchers.png)
+![Type safe matcher showing a type error](media/type-safe-matchers.png)
 
 ## Installation
 
-```
+```shell
 npm i -D strong-mock
 ```
 
-```
+```shell
 yarn add -D strong-mock
 ```
 
@@ -113,11 +125,9 @@ console.log(foo.bar(23)); // awesome
 console.log(foo.bar(23)); // even more awesome
 ```
 
-By default, each call is expected to be called only once. You can expect a call to be made multiple times using the [invocation count](#setting-invocation-count-expectations) helpers.
-
 ### Setting invocation count expectations
 
-You can expect a call to be made multiple times by using the invocation count helpers `between`, `atLeast`, `times`, `anyTimes` etc.:
+By default, each call is expected to be called only once. You can expect a call to be made multiple times by using the invocation count helpers `between`, `atLeast`, `times`, `anyTimes` etc.:
 
 ```typescript
 const fn = mock<(x: number) => number>();
@@ -130,6 +140,8 @@ console.log(fn(1)); // 1
 console.log(fn(1)); // throws because the expectation is finished
 ```
 
+You'll notice there is no `never()` helper - if you expect a call to not be made simply don't set an expectation on it and the mock will throw if the call happens.
+
 ### Mocking interfaces
 
 Pass in the interface to the generic argument of `mock`:
@@ -149,8 +161,6 @@ console.log(foo.bar(23)); // 'awesome'
 console.log(foo.baz); // 100
 ```
 
-Since the mock is type safe the compiler will guarantee that you're only mocking things that actually exist on the interface.
-
 ### Mocking functions
 
 You can also mock functions similarly to interfaces:
@@ -192,18 +202,16 @@ when(() => fn(1)).thenThrow();
 when(() => fnWithPromise(1)).thenReject();
 ```
 
-You'll notice there is no `never()` helper - if you expect a call to not be made simply don't set an expectation on it and the mock will throw if the call happens.
-
 ### Verifying expectations
 
-Calling `verify(mock)` will make sure that all expectations set on `mock` have been met. If not, the function will throw an error and print the unmet expectations.
+Calling `verify(myMock)` will make sure that all expectations set on the mock have been met, and that no additional calls have been made.
 
 ```typescript
 const fn = mock<(x: number) => number>();
 
 when(() => fn(1)).thenReturn(1).between(2, 10);
 
-verify(fn); // throws
+verify(fn); // throws UnmetExpectations
 ```
 
 It will also throw if any unexpected calls happened that were maybe caught in the code under test.
@@ -217,10 +225,16 @@ try {
   // your code might transition to an error state here
 }
 
-verify(fn); // throws
+verify(fn); // throws UnexpectedCalls
 ```
 
-It is recommended that you call `verify()` on your mocks at the end of every test. This will make sure you don't have any unused expectations in your tests and that your code did not silently catch any of the errors that are thrown when an unexpected call happens. You can use `verifyAll()` to check all existing mocks e.g. in an `afterEach` hook.
+It is recommended that you call `verify()` on your mocks at the end of every test. This will make sure you don't have any unused expectations in your tests and that your code did not silently catch any of the errors that are thrown when an unexpected call happens. You can use `verifyAll()` to check all existing mocks.
+
+```typescript
+afterEach(() => {
+  verifyAll();
+})
+```
 
 ![verify error](./media/verify.png)
 
@@ -238,11 +252,17 @@ reset(fn);
 fn(1); // throws
 ```
 
-If you create common mocks that are shared by multiple tests you should reset them before using them e.g. in a `beforeEach` hook. You can use `resetAll()` to reset all existing mocks.
+If you create common mocks that are shared by multiple tests you should reset them before each test. You can use `resetAll()` to reset all existing mocks.
+
+```typescript
+beforeEach(() => {
+  resetAll();
+})
+```
 
 ### Argument 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. In those cases you can use argument matchers to either ignore some arguments or use custom matchers to check them.
+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.
 
 ```typescript
 const fn = mock<
@@ -260,6 +280,12 @@ console.log(fn(
 ); // 'matched!'
 ```
 
+You can mix argument matchers with concrete arguments:
+
+```typescript
+when(() => fn(42, It.isObject())).thenReturn('matched');
+```
+
 Available matchers:
 - `deepEquals` - the default, uses deep equality,
 - `is` - uses `Object.is` for comparison,
@@ -275,7 +301,7 @@ The following table illustrates the differences between the equality matchers:
 
 | expected           | actual               | `It.is`   | `It.deepEquals` | `It.deepEquals({ strict: false })` |
 |--------------------|----------------------|-----------|-----------------|------------------------------------|
-| `"foo"`            | `"bar"`              | equal     | equal           | equal                              |
+| `"foo"`            | `"foo"`              | equal     | equal           | equal                              |
 | `{ foo: "bar" }`   | `{ foo: "bar" }`     | not equal | equal           | equal                              |
 | `{ }`              | `{ foo: undefined }` | not equal | not equal       | equal                              |
 | `new (class {})()` | `new (class {})()`   | not equal | not equal       | equal                              |
@@ -315,22 +341,100 @@ console.log(fn(23, (x) => x + 1)); // 42
 console.log(matcher.value?.(3)); // 4
 ```
 
-### Overriding default matcher
+## Mock options
 
-You can override the default matcher that will be used when setting expectations with non-matcher values e.g. `42` or `{ foo: "bar" }`.
+The following options can be set per mock, or globally with `setDefaults`.
 
-```ts
-import { mock, when, It, setDefaults } from 'strong-mock';
+```typescript
+import { mock, when, setDefaults } from 'strong-mock';
 
-// Use strict equality instead of deep equality.
 setDefaults({
-  matcher: It.is
-})
+  exactParams: true
+});
+
+// Uses the new default.
+const superStrictMock = mock<() => void>();
+// Overrides the default.
+const strictMock = mock<() => void>({ exactParams: false });
+```
+
+### Unexpected property return value
+
+You can control what happens whenever an unexpected property is accessed, or an unexpected call is made.
+
+```typescript
+import { mock, when, UnexpectedProperty } from 'strong-mock';
+
+type Foo = {
+  bar: (value: number) => number;
+}
+
+// This is the default.
+const callsThrow = mock<Foo>({
+  unexpectedProperty: UnexpectedProperty.CALL_THROW
+});
+
+// Accessing properties with no expectations is fine.
+callsThrow.bar;
+// Throws "Didn't expect bar(42) to be called".
+callsThrow.bar(42);
+
+const propertiesThrow = mock<Foo>({
+  unexpectedProperty: UnexpectedProperty.THROW
+});
+
+// Throws "Didn't expect property bar to be accessed".
+propertiesThrow.bar;
+// Throws "Didn't expect property bar to be accessed".
+propertiesThrow.bar(42);
+```
+
+### Exact params
 
-const fn = mock<(x: number[]) => boolean>();
+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).
+
+```typescript
+import { mock } from 'strong-mock';
+
+const fn = mock<(value?: number) => number>();
+
+when(() => fn()).thenReturn(42).twice();
+
+// Since the expectation doesn't expect any arguments,
+// both of the following are fine
+console.log(fn()); // 42
+console.log(fn(1)); // 42
+```
+
+If you're not using TypeScript, or you want to be super strict, you can set `exactParams: true`.
+
+```typescript
+import { mock } from 'strong-mock';
+
+const fn = mock<(optionalValue?: number) => number>({
+  exactParams: true
+});
+
+when(() => fn()).thenReturn(42).twice();
+
+console.log(fn()); // 42
+console.log(fn(1)); // throws
+```
+
+### Concrete matcher
+
+You can set the matcher that will be used in expectations with concrete values e.g. `42` or `{ foo: "bar" }`. Passing in a [matcher argument](#argument-matchers) will always take priority.
+
+```typescript
+import { mock, when, It } from 'strong-mock';
+
+// Use strict equality instead of deep equality.
+const fn = mock<(x: number[]) => boolean>({
+  concreteMatcher: It.is
+});
 when(() => fn([1, 2, 3])).thenReturn(true);
 
-fn([1, 2, 3]); // throws because different arrays
+fn([1, 2, 3]); // throws because different array instances
 ```
 
 ## FAQ
@@ -341,11 +445,11 @@ This library is different from other mocking/spying libraries you might have use
 
 This design decision has a few reasons behind it. First, it forces you to be aware of what your code needs from its dependencies. Spying libraries encourage checking those needs at the end of the test after the code has already called the mocks. This can lead to tests missing dependency calls that just happen to not throw any error at runtime with the dummy values that the spies return.
 
-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.
+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 mock an existing object/function?
+### Can I partially mock an existing object/function?
 
-No, although you can pass its type to `mock()` and set expectations on it as you would with a type.
+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?
 
@@ -353,7 +457,7 @@ You currently can't do that. Please use a normal method instead e.g. `setFoo()`
 
 ### 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.
+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?
 
@@ -373,54 +477,6 @@ 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).
 
-![call-rename](media/rename-args.gif)
-
-### Why does accessing an unused method throw?
-
-Any unexpected property access will throw an error, even if the property is a method, and you never call it. This can sometimes be inconvenient if your code e.g. destructures your mock and only calls parts of it inside your test.
-
-```typescript
-interface Foo {
-  bar: () => number;
-  baz: () => number;
-}
-
-function doFoo(foo: Foo, { callBaz }: { callBaz: boolean }) {
-  // Will throw here with unexpected access on `baz`.
-  const { bar, baz } = foo;
- 
-  bar();
-
-  if (callBaz) {
-    baz();
-  }
-}
-
-const foo = mock<Foo>();
-when(() => foo.bar()).thenReturn(42);
-
-// Throws with unexpected access on `baz`.
-doFoo(foo, { callBaz: false });
-```
-
-To work around this, either change your code to avoid destructuring
-
-```typescript
-function doFoo(foo: Foo, callBaz: boolean) {
-  foo.bar();
-
-  if (callBaz) {
-    foo.baz();
-  }
-}
-```
-
-or set a dummy expectation on the methods you're not interested in during the test.
-
-```typescript
-when(() => foo.baz()).thenThrow('should not be called').anyTimes();
-```
-
 ### Can I spread/enumerate a mock?
 
 Yes, and you will only get the properties that have expectations on them.
@@ -437,7 +493,6 @@ console.log(foo2.bar); // 42
 console.log(foo2.baz); // undefined
 ```
 
-
 ### How can I ignore `undefined` keys when setting expectations on objects?
 
 Use the `It.deepEquals` matcher explicitly inside `when` and pass `{ strict: false }`:
@@ -445,15 +500,17 @@ Use the `It.deepEquals` matcher explicitly inside `when` and pass `{ strict: fal
 ```ts
 const fn = mock<(x: { foo: string }) => boolean>();
 
-when(() => fn(It.deepEquals({ foo: "bar" }, { strict: false }))).thenReturn(true);
+when(() => fn(
+  It.deepEquals({ foo: "bar" }, { strict: false }))
+).thenReturn(true);
 
 fn({ foo: "bar", baz: undefined }) === true
 ```
 
-You can also set this behavior to be the default by using [`setDefaults`](#overriding-default-matcher):
+You can set this behavior to be the default by configuring the [concrete matcher](#concrete-matcher).
 
 ```ts
 setDefaults({
-  matcher: (expected) => It.deepEquals(expected, { strict: false })
+  concreteMatcher: (expected) => It.deepEquals(expected, { strict: false })
 });
 ```

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
-import { Expectation } from './expectation/expectation';
-import { CallMap } from './expectation/repository/expectation-repository';
-import { Property } from './proxy';
-import { PendingExpectation } from './when/pending-expectation';
+import type { Expectation } from './expectation/expectation';
+import type { CallMap } from './expectation/repository/expectation-repository';
+import type { Property } from './proxy';
+import type { PendingExpectation } from './when/pending-expectation';
 export declare class UnfinishedExpectation extends Error {
     constructor(pendingExpectation: PendingExpectation);
 }

package/dist/expectation/expectation.d.ts

@@ -1,10 +1,6 @@
-import { Property } from '../proxy';
-import { Matcher } from './matcher';
-export declare type ReturnValue = {
-    value: any;
-    isPromise?: boolean;
-    isError?: boolean;
-};
+import type { Property } from '../proxy';
+import type { Matcher } from './matcher';
+import type { ReturnValue } from './repository/return-value';
 /**
  * Compare received arguments against matchers.
  */

package/dist/expectation/it.d.ts

@@ -1,4 +1,4 @@
-import { Matcher, TypeMatcher } from './matcher';
+import type { Matcher, TypeMatcher } from './matcher';
 declare type DeepPartial<T> = T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;

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

@@ -1,5 +1,5 @@
-import { Expectation, ReturnValue } from '../expectation';
-import { Property } from '../../proxy';
+import type { Property } from '../../proxy';
+import type { Expectation } from '../expectation';
 export declare type Call = {
     arguments: any[] | undefined;
 };
@@ -31,7 +31,7 @@ export interface ExpectationRepository {
     /**
      * 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
+     * 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.
      *
@@ -41,17 +41,32 @@ export interface ExpectationRepository {
      *
      * @example
      * add(new Expectation('getData', [1, 2], 23);
-     * get('getData').value(1, 2) === 23
+     * get('getData')(1, 2) === 23
      *
      * @example
      * add(new Expectation('hasData', undefined, true);
-     * get('hasData').value === true
+     * get('hasData') === true
      *
      * @example
      * add(new Expectation('getData', undefined, () => 42);
-     * get('getData').value(1, 2, '3', false, NaN) === 42
+     * get('getData')(1, 2, '3', false, NaN) === 42
      */
-    get(property: Property): ReturnValue;
+    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.
      *

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

@@ -0,0 +1,38 @@
+import { UnexpectedProperty } from '../../mock/options';
+import type { Property } from '../../proxy';
+import type { Expectation } from '../expectation';
+import type { CallMap, ExpectationRepository } from './expectation-repository';
+declare 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

@@ -0,0 +1,13 @@
+export declare 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,6 +1,7 @@
-import { Property } from '../proxy';
-import { Expectation, ReturnValue } from './expectation';
-import { Matcher } from './matcher';
+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.
@@ -16,10 +17,11 @@ 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);
+    constructor(property: Property, args: Matcher[] | undefined, returnValue: ReturnValue, exactParams?: boolean);
     setInvocationCount(min: number, max?: number): void;
     matches(args: any[] | undefined): boolean;
     isUnmet(): boolean;

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export { verify, verifyAll } from './verify/verify';
 export { It } from './expectation/it';
 export { setDefaults } from './mock/defaults';
 export type { Matcher } from './expectation/matcher';
-export type { StrongMockDefaults } from './mock/defaults';
+export type { MockOptions } from './mock/options';
+export { UnexpectedProperty } from './mock/options';