strong-mock 7.2.1 → 8.0.0-beta.1

package/README.md

@@ -6,7 +6,7 @@
 </div>
 
 ```typescript
-import { mock, when, instance } from 'strong-mock';
+import { mock, when } from 'strong-mock';
 
 interface Foo {
   bar: (x: number) => string;
@@ -14,9 +14,9 @@ interface Foo {
 
 const foo = mock<Foo>();
 
-when(foo.bar(23)).thenReturn('I am strong!');
+when(() => foo.bar(23)).thenReturn('I am strong!');
 
-console.log(instance(foo).bar(23)); // 'I am strong!'
+console.log(foo.bar(23)); // 'I am strong!'
 ```
 
 ----
@@ -27,12 +27,12 @@ console.log(instance(foo).bar(23)); // 'I am strong!'
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [Installation](#installation)
-- [Requirements](#requirements)
 - [Features](#features)
   - [Type safety](#type-safety)
   - [Useful error messages](#useful-error-messages)
   - [Type safe argument matchers](#type-safe-argument-matchers)
+- [Installation](#installation)
+- [Requirements](#requirements)
 - [API](#api)
   - [Setting expectations](#setting-expectations)
   - [Setting multiple expectations](#setting-multiple-expectations)
@@ -44,75 +44,85 @@ console.log(instance(foo).bar(23)); // 'I am strong!'
   - [Verifying expectations](#verifying-expectations)
   - [Resetting expectations](#resetting-expectations)
   - [Argument matchers](#argument-matchers)
+  - [Mock options](#mock-options)
+    - [Strictness](#strictness)
+    - [Concrete matcher](#concrete-matcher)
+    - [Defaults](#defaults)
 - [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 instance?](#can-i-spreadenumerate-a-mock-instance)
+  - [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)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Installation
-
-```
-npm i -D strong-mock
-```
-
-```
-yarn 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.
-
 ## Features
 
 ### 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.
 
-![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
 
-![type safe matchers](./media/type-safe-matchers.png)
+Optional argument matchers allow you to create complex expectations, while still maintaining type safety.
 
-## API
+![Type safe matcher showing a type error](media/type-safe-matchers.png)
 
-### Setting expectations
+## Installation
 
-Expectations are set by calling the mock inside a `when()` call and finishing it by setting a return value.
+```shell
+npm i -D strong-mock
+```
 
-```typescript
-when(foo.bar(23)).thenReturn('awesome');
+```shell
+yarn add -D strong-mock
 ```
 
-After expectations have been set you need to get an instance of the mock by calling `instance()`.
+## 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
+
+### Setting expectations
+
+Expectations are set by calling the mock inside a `when` callback and finishing it by setting a return value.
 
 ```typescript
-instance(foo)
+when(() => foo.bar(23)).thenReturn('awesome');
 ```
 
 ### Setting multiple expectations
 
-You can set as many expectations as you want by calling `when()` multiple times. If you have multiple expectations with the same arguments they will be consumed in the order they were created.
+You can set as many expectations as you want by calling `when` multiple times. If you have multiple expectations with the same arguments they will be consumed in the order they were created.
 
 ```typescript
-when(foo.bar(23)).thenReturn('awesome');
-when(foo.bar(23)).thenReturn('even more awesome');
+when(() => foo.bar(23)).thenReturn('awesome');
+when(() => foo.bar(23)).thenReturn('even more awesome');
 
-console.log(instance(foo).bar(23)); // awesome
-console.log(instance(foo).bar(23)); // even more awesome
+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.
@@ -124,12 +134,12 @@ You can expect a call to be made multiple times by using the invocation count he
 ```typescript
 const fn = mock<(x: number) => number>();
 
-when(fn(1)).thenReturn(1).between(2, 3);
+when(() => fn(1)).thenReturn(1).between(2, 3);
 
-console.log(instance(fn)(1)); // 1
-console.log(instance(fn)(1)); // 1
-console.log(instance(fn)(1)); // 1
-console.log(instance(fn)(1)); // throws because the expectation is finished
+console.log(fn(1)); // 1
+console.log(fn(1)); // 1
+console.log(fn(1)); // 1
+console.log(fn(1)); // throws because the expectation is finished
 ```
 
 ### Mocking interfaces
@@ -144,11 +154,11 @@ interface Foo {
 
 const foo = mock<Foo>();
 
-when(foo.bar(23)).thenReturn('awesome');
-when(foo.baz).thenReturn(100);
+when(() => foo.bar(23)).thenReturn('awesome');
+when(() => foo.baz).thenReturn(100);
 
-console.log(instance(foo).bar(23)); // 'awesome'
-console.log(instance(foo).baz); // 100
+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.
@@ -162,9 +172,9 @@ type Fn = (x: number) => number;
 
 const fn = mock<Fn>();
 
-when(fn(1)).thenReturn(2);
+when(() => fn(1)).thenReturn(2);
 
-console.log(instance(fn)(1)); // 2
+console.log(fn(1)); // 2
 ```
 
 ### Mocking promises
@@ -176,9 +186,9 @@ type Fn = (x: number) => Promise<number>;
 
 const fn = mock<Fn>();
 
-when(fn(1)).thenResolve(2);
+when(() => fn(1)).thenResolve(2);
 
-console.log(await instance(fn)()); // 2
+console.log(await fn()); // 2
 ```
 
 ### Throwing errors
@@ -190,8 +200,8 @@ type FnWithPromise = (x: number) => Promise<void>;
 const fn = mock<Fn>();
 const fnWithPromise = mock<FnWithPromise>();
 
-when(fn(1)).thenThrow();
-when(fnWithPromise(1)).thenReject();
+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.
@@ -203,7 +213,7 @@ Calling `verify(mock)` will make sure that all expectations set on `mock` have b
 ```typescript
 const fn = mock<(x: number) => number>();
 
-when(fn(1)).thenReturn(1).between(2, 10);
+when(() => fn(1)).thenReturn(1).between(2, 10);
 
 verify(fn); // throws
 ```
@@ -214,7 +224,7 @@ It will also throw if any unexpected calls happened that were maybe caught in th
 const fn = mock<() => void>();
 
 try {
-  instance(fn)(); // throws because the call is unexpected
+  fn(); // throws because the call is unexpected
 } catch(e) {
   // your code might transition to an error state here
 }
@@ -222,7 +232,7 @@ try {
 verify(fn); // throws
 ```
 
-It is recommended that 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 hasn't silently caught 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 e.g. in an `afterEach` hook.
 
 ![verify error](./media/verify.png)
 
@@ -233,11 +243,11 @@ You can remove all expectations from a mock by using the `reset()` method:
 ```typescript
 const fn = mock<(x: number) => number>();
 
-when(fn(1)).thenReturn(1);
+when(() => fn(1)).thenReturn(1);
 
 reset(fn);
 
-instance(fn)(1); // throws
+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.
@@ -251,18 +261,26 @@ const fn = mock<
   (x: number, data: { values: number[]; labels: string[] }) => string
 >();
 
-when(fn(
+when(() => fn(
   It.isAny(),
   It.isObject({ values: [1, 2, 3] })
 )).thenReturn('matched!');
 
-console.log(instance(fn)(
+console.log(fn(
   123, 
   { values: [1, 2, 3], labels: ['a', 'b', 'c'] })
 ); // '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,
 - `isAny` - matches anything,
 - `isNumber` - matches any number,
 - `isString` - matches any string, can search for substrings and patterns,
@@ -271,6 +289,15 @@ Available matchers:
 - `matches` - build your own matcher,
 - `willCapture` - matches anything and stores the received value.
 
+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: "bar" }`   | `{ foo: "bar" }`     | not equal | equal           | equal                              |
+| `{ }`              | `{ 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:
 
 ```typescript
@@ -286,9 +313,9 @@ You can create arbitrarily complex and type safe matchers with `It.matches(cb)`:
 ```typescript
 const fn = mock<(x: number, y: number[]) => string>();
 
-when(fn(
+when(() => fn(
   It.matches(x => x > 0),
-  It.matches(y => y.values.includes(42))
+  It.matches(y => y.includes(42))
 )).thenReturn('matched');
 ```
 
@@ -300,25 +327,86 @@ type Cb = (value: number) => number;
 const fn = mock<(cb: Cb) => number>();
 
 const matcher = It.willCapture<Cb>();
-when(fn(matcher)).thenReturn(42);
+when(() => fn(matcher)).thenReturn(42);
 
-console.log(instance(fn)(23, (x) => x + 1)); // 42
+console.log(fn(23, (x) => x + 1)); // 42
 console.log(matcher.value?.(3)); // 4
 ```
 
+### Mock options
+
+#### Strictness
+
+strong-mock has a few levels of "strictness" that control what values are returned when an unexpected property is accessed or an unexpected call is made. The strictness can be configured for each mock, or for all mocks with `setDefaults`.
+
+```typescript
+import { mock, when } from 'strong-mock';
+import { Strictness } from './options';
+
+type Foo = {
+  bar: (value: number) => number;
+}
+
+// This is the default.
+const strictFoo = mock<Foo>({ strictness: Strictness.STRICT });
+
+// Accessing properties with no expectations is fine.
+strictFoo.bar;
+// Throws "Didn't expect bar(42) to be called".
+strictFoo.bar(42);
+
+const superStrictFoo = mock<Foo>({ strictness: Strictness.SUPER_STRICT });
+
+// Throws "Didn't expect property bar to be accessed".
+superStrictFoo.bar;
+// Throws "Didn't expect property bar to be accessed".
+superStrictFoo.bar(42);
+```
+
+#### 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
+```
+
+#### Defaults
+
+Mock options can be set for all mocks with `setDefaults`.
+
+```typescript
+import { mock, when, setDefaults, Strictness } from 'strong-mock';
+
+setDefaults({
+  strictness: Strictness.SUPER_STRICT
+});
+
+// Uses the new default.
+const superStrictMock = mock<() => void>();
+// Overrides the default.
+const strictMock = mock<() => void>({ strictness: Strictness.STRICT });
+```
+
 ## FAQ
 
 ### Why do I have to set all expectations first?
 
 This library is different from other mocking/spying libraries you might have used before such as [sinon](https://sinonjs.org) or [jest](https://jestjs.io/docs/en/mock-functions). Whereas those libraries are focused on recording calls to the mocks and always returning something, strong-mock requires you to set your expectations upfront. If a call happens that is not expected the mock will throw an error.
 
-This design decision has a few reasons behind it. First of all, 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.
+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.
 
-### 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?
 
@@ -326,11 +414,11 @@ 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 would have 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?
 
-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:
+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:
 
 ```typescript
 interface Foo {
@@ -339,73 +427,47 @@ interface Foo {
 
 const foo = mock<Foo>();
 
-when(foo.bar).thenReturn(x => `called ${x}`);
+when(() => foo.bar).thenReturn(x => `called ${x}`);
 
-console.log(instance(foo).bar(23)); // 'called 23'
+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)
+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).
 
-### Why does accessing an unused method throw?
+### Can I spread/enumerate a mock?
 
-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.
+Yes, and you will only get the properties that have expectations on them.
 
 ```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();
+const foo = mock<{ bar: number; baz: number }>();
+when(() => foo.bar).thenReturn(42);
 
-  if (callBaz) {
-    baz();
-  }
-}
+console.log(Object.keys(foo)); // ['bar']
 
-const foo = mock<Foo>();
-when(foo.bar()).thenReturn(42);
+const foo2 = { ...foo };
 
-// Throws with unexpected access on `baz`.
-doFoo(instance(foo), { callBaz: false });
+console.log(foo2.bar); // 42
+console.log(foo2.baz); // undefined
 ```
 
-To work around this, either change your code to avoid destructuring
+### How can I ignore `undefined` keys when setting expectations on objects?
 
-```typescript
-function doFoo(foo: Foo, callBaz: boolean) {
-  foo.bar();
+Use the `It.deepEquals` matcher explicitly inside `when` and pass `{ strict: false }`:
 
-  if (callBaz) {
-    foo.baz();
-  }
-}
-```
+```ts
+const fn = mock<(x: { foo: string }) => boolean>();
 
-or set a dummy expectation on the methods you're not interested in during the test.
+when(() => fn(
+  It.deepEquals({ foo: "bar" }, { strict: false }))
+).thenReturn(true);
 
-```typescript
-when(foo.baz()).thenThrow('should not be called').anyTimes();
+fn({ foo: "bar", baz: undefined }) === true
 ```
 
-### Can I spread/enumerate a mock instance?
-
-Yes, and you will only get the properties that have expectations on them.
-
-```typescript
-const foo = mock<{ bar: number; baz: number }>();
-when(foo.bar).thenReturn(42);
-
-console.log(Object.keys(instance(foo))); // ['bar']
-
-const foo2 = { ...instance(foo) };
+You can set this behavior to be the default by configuring the [concrete matcher](#concrete-matcher), and set it on all mocks using [setDefaults](#defaults):
 
-console.log(foo2.bar); // 42
-console.log(foo2.baz); // undefined
+```ts
+setDefaults({
+  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 { PendingExpectation } from './when/pending-expectation';
 import { Property } from './proxy';
+import { PendingExpectation } from './when/pending-expectation';
 export declare class UnfinishedExpectation extends Error {
     constructor(pendingExpectation: PendingExpectation);
 }

package/dist/expectation/expectation.d.ts

@@ -1,16 +1,20 @@
 import { Property } from '../proxy';
+import { Matcher } from './matcher';
 export declare type ReturnValue = {
     value: any;
     isPromise?: boolean;
     isError?: boolean;
 };
+/**
+ * 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: any[] | undefined;
+    args: Matcher[] | undefined;
     returnValue: ReturnValue;
     min: number;
     max: number;

package/dist/expectation/it.d.ts

@@ -0,0 +1,29 @@
+import { Matcher, TypeMatcher } from './matcher';
+declare type DeepPartial<T> = T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * Contains argument matchers that can be used to ignore arguments in an
+ * expectation or to match complex arguments.
+ */
+export declare const It: {
+    matches: <T>(cb: (actual: T) => boolean, { toJSON }?: {
+        toJSON?: (() => string) | undefined;
+    }) => TypeMatcher<T>;
+    deepEquals: <T_1>(expected: T_1, { strict }?: {
+        strict?: boolean | undefined;
+    }) => TypeMatcher<T_1>;
+    is: <T_2 = unknown>(expected: T_2) => TypeMatcher<T_2>;
+    isAny: () => TypeMatcher<any>;
+    isObject: <T_3 extends object, K extends DeepPartial<T_3>>(partial?: K | undefined) => TypeMatcher<T_3>;
+    isNumber: () => TypeMatcher<number>;
+    isString: ({ matching, containing, }?: {
+        matching?: RegExp | undefined;
+        containing?: string | undefined;
+    }) => TypeMatcher<string>;
+    isArray: <T_4 extends any[]>(containing?: T_4 | undefined) => TypeMatcher<T_4>;
+    willCapture: <T_5 = unknown>(name?: string) => T_5 & Matcher & {
+        value: T_5 | undefined;
+    };
+};
+export {};

package/dist/expectation/matcher.d.ts

@@ -1,57 +1,21 @@
-export declare type Matcher<T> = T & {
+export declare const MATCHER_SYMBOL: unique symbol;
+export declare type Matcher = {
     /**
      * Will be called with a value to match against.
      */
-    matches: (arg: unknown) => boolean;
-    /**
-     * TODO: turn into a symbol
-     */
-    __isMatcher: boolean;
+    matches: (arg: any) => boolean;
+    [MATCHER_SYMBOL]: boolean;
     /**
      * Used by `pretty-format`.
      */
     toJSON(): string;
 };
 /**
- * Use to test if an expectation on an argument is a custom matcher.
+ * This takes the shape of T to satisfy call sites, but strong-mock will only
+ * care about the matcher type.
  */
-export declare function isMatcher(f: unknown): f is Matcher<unknown>;
+export declare type TypeMatcher<T> = T & Matcher;
 /**
- * The default matcher that checks for deep equality.
+ * Used to test if an expectation on an argument is a custom matcher.
  */
-export declare const deepEquals: <T>(expected: T) => Matcher<T>;
-declare type DeepPartial<T> = T extends object ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : T;
-/**
- * Contains argument matchers that can be used to ignore arguments in an
- * expectation or to match complex arguments.
- */
-export declare const It: {
-    isAny: () => Matcher<any>;
-    matches: <T>(cb: (arg: T) => boolean) => Matcher<T>;
-    isObject: <T_1 extends object, K extends DeepPartial<T_1>>(partial?: K | undefined) => Matcher<T_1>;
-    isNumber: () => Matcher<number>;
-    isString: ({ matching, containing, }?: {
-        matching?: RegExp | undefined;
-        containing?: string | undefined;
-    }) => Matcher<string>;
-    isArray: <T_2 extends any[]>(containing?: T_2 | undefined) => Matcher<T_2>;
-    willCapture: <T_3 = unknown>(name?: string | undefined) => T_3 & {
-        /**
-         * Will be called with a value to match against.
-         */
-        matches: (arg: unknown) => boolean;
-        /**
-         * TODO: turn into a symbol
-         */
-        __isMatcher: boolean;
-        /**
-         * Used by `pretty-format`.
-         */
-        toJSON(): string;
-    } & {
-        value: T_3 | undefined;
-    };
-};
-export {};
+export declare function isMatcher(f: unknown): f is Matcher;