strong-mock 9.0.1 → 9.2.0

package/README.md

@@ -33,7 +33,6 @@ console.log(foo.bar(23)); // 'I am strong!'
   - [Awesome error messages](#awesome-error-messages)
   - [Works with Promises and Errors](#works-with-promises-and-errors)
 - [Installation](#installation)
-- [Requirements](#requirements)
 - [API](#api)
   - [Mock](#mock)
     - [Mocking types and interfaces](#mocking-types-and-interfaces)
@@ -42,7 +41,7 @@ console.log(foo.bar(23)); // 'I am strong!'
     - [Setting expectations](#setting-expectations)
     - [Setting multiple expectations](#setting-multiple-expectations)
     - [Matchers](#matchers-1)
-    - [Creating your own matcher](#creating-your-own-matcher)
+    - [Custom matchers](#custom-matchers)
   - [Then](#then)
     - [Setting invocation count expectations](#setting-invocation-count-expectations)
     - [Returning promises](#returning-promises)
@@ -52,6 +51,7 @@ console.log(foo.bar(23)); // 'I am strong!'
   - [Reset](#reset)
     - [Resetting expectations](#resetting-expectations)
 - [Mock options](#mock-options)
+  - [Name](#name)
   - [Unexpected property return value](#unexpected-property-return-value)
   - [Exact params](#exact-params)
   - [Concrete matcher](#concrete-matcher)
@@ -127,6 +127,8 @@ try {
 
 ## Installation
 
+strong-mock supports the latest LTS and Maintenance [Node.js versions](https://nodejs.org/en/about/previous-releases). It may work on older versions, but it's not guaranteed.
+
 ```shell
 npm i -D strong-mock
 ```
@@ -139,10 +141,6 @@ yarn add -D strong-mock
 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.
-
 ## API
 
 ### Mock
@@ -212,7 +210,7 @@ const fn = mock<
 >();
 
 when(() => fn(
-  It.isAny(),
+  It.isNumber(),
   It.containsObject({ values: [1, 2, 3] })
 )).thenReturn('matched!');
 
@@ -229,7 +227,7 @@ when(() => fn(42, It.isPlainObject())).thenReturn('matched');
 ```
 
 Available matchers:
-- `deepEquals` - the default, uses deep equality,
+- `deepEquals` - the default ([can be changed](#concrete-matcher), uses deep equality,
 - `is` - uses `Object.is` for comparison,
 - `isAny` - matches anything,
 - `isNumber` - matches any number,
@@ -237,8 +235,8 @@ Available matchers:
 - `isArray` - matches any array, can search for subsets,
 - `isPlainObject` - matches any plain object,
 - `containsObject` - recursively matches a subset of an object,
-- `willCapture` - matches anything and stores the received value,
-- `matches` - [build your own matcher](#creating-your-own-matcher).
+- `willCapture` - matches anything and [stores](#custom-matchers) the received value,
+- `matches` - [build your own matcher](#custom-matchers).
 
 The following table illustrates the differences between the equality matchers:
 
@@ -249,21 +247,26 @@ 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 `containsObject` and `isArray` support nesting matchers:
+You can nest matchers in `deepEquals`, `containsObject` and `isArray`:
 
 ```typescript
-It.containsObject({
-  foo: It.isString()
-})
+type Point = { label: string; value: number };
+const fn = mock<(data: { points: Point[]; title: string }) => number>();
 
-It.isArray([
-  It.containsObject({
-    foo: It.isString(/foo/)
-  })
-])
+// deepEquals is the default matcher so you can omit it.
+when(() => fn({
+  points: It.isArray([
+    It.containsObject({
+      value: It.matches(x => x > 0)
+    })
+  ]),
+  title: It.isString(/foo/)
+})).thenReturn(100);
 ```
 
-`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.
+#### Custom matchers
+
+`It.willCapture` 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
 type Cb = (value: number) => number;
@@ -277,9 +280,7 @@ 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()`:
+With `It.matches` you can create arbitrarily complex and type safe matchers:
 
 ```typescript
 const fn = mock<(x: number, y: string) => string>();
@@ -465,6 +466,21 @@ const superStrictMock = mock<() => void>();
 const strictMock = mock<() => void>({ exactParams: false });
 ```
 
+### Name
+
+The name of a mock appears in error messages e.g., when an unexpected call happens. By default, all mocks are simply named `mock`, but you can set a custom name to make the error messages more descriptive.
+
+```typescript
+import { mock, when } from 'strong-mock';
+
+interface Service { /* ... */}
+const service = mock<Service>({ name: 'ServiceMock' });
+
+when(() => service.foo(1)).thenReturn(2);
+
+service.foo(3); // throws "Didn't expect ServiceMock.foo(3) to be called"
+```
+
 ### Unexpected property return value
 
 You can control what happens whenever an unexpected property is accessed, or an unexpected call is made.
@@ -498,7 +514,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 [matchers](#matchers-1).
+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 fewer 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';
@@ -577,7 +593,7 @@ No, passing a concrete implementation to `mock()` will be the same as passing a
 
 ### 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()`.
+Calling setters inside `when` is not currently supported. If you can redesign the code under test, you should consider using a setter method e.g. `setFoo(value)` instead of `set foo(value)`.
 
 ### How do I provide a function for the mock to call?