diff --git a/README.md b/README.md
index c81727a02711..68c196a86567 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
-
+
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index c5bbc2a3f67f..6ffb9ed8ea57 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -63,6 +63,15 @@ export default ({ mode }: { mode: string }) => {
['link', { rel: 'me', href: 'https://m.webtoo.ls/@vitest' }],
['link', { rel: 'mask-icon', href: '/logo.svg', color: '#ffffff' }],
['link', { rel: 'apple-touch-icon', href: '/apple-touch-icon.png', sizes: '180x180' }],
+ [
+ 'script',
+ {
+ 'src': 'https://cdn.usefathom.com/script.js',
+ 'data-site': 'BEAFAKYG',
+ 'data-spa': 'auto',
+ 'defer': '',
+ },
+ ],
],
lastUpdated: true,
vite: {
diff --git a/docs/.vitepress/scripts/transformHead.ts b/docs/.vitepress/scripts/transformHead.ts
index ac0a014d21c1..63b48a294315 100644
--- a/docs/.vitepress/scripts/transformHead.ts
+++ b/docs/.vitepress/scripts/transformHead.ts
@@ -13,13 +13,6 @@ export async function transformHead({ pageData }: TransformContext): Promise3.2.0]
+```ts
import 'vitest'
-interface CustomMatchers {
- toBeFoo: () => R
-}
-
declare module 'vitest' {
- interface Matchers extends CustomMatchers {}
-}
-```
-```ts [3.0.0]
-import 'vitest'
-
-interface CustomMatchers {
- toBeFoo: () => R
-}
-
-declare module 'vitest' {
- interface Assertion extends CustomMatchers {}
- interface AsymmetricMatchersContaining extends CustomMatchers {}
+ interface Matchers {
+ toBeFoo: () => R
+ }
}
```
-:::
::: tip
-Since Vitest 3.2, you can extend the `Matchers` interface to have type-safe assertions in `expect.extend`, `expect().*`, and `expect.*` methods at the same time. Previously, you had to define separate interfaces for each of them.
+Importing `vitest` makes TypeScript think this is an ES module file, type declaration won't work without it.
:::
+Extending the `Matchers` interface will add a type to `expect.extend`, `expect().*`, and `expect.*` methods at the same time.
+
::: warning
Don't forget to include the ambient declaration file in your `tsconfig.json`.
:::
@@ -62,7 +48,7 @@ Don't forget to include the ambient declaration file in your `tsconfig.json`.
The return value of a matcher should be compatible with the following interface:
```ts
-interface ExpectationResult {
+interface MatcherResult {
pass: boolean
message: () => string
// If you pass these, they will automatically appear inside a diff when
@@ -73,7 +59,7 @@ interface ExpectationResult {
```
::: warning
-If you create an asynchronous matcher, don't forget to `await` the result (`await expect('foo').toBeFoo()`) in the test itself::
+If you create an asynchronous matcher, don't forget to `await` the result (`await expect('foo').toBeFoo()`) in the test itself:
```ts
expect.extend({
@@ -86,13 +72,46 @@ await expect().toBeAsyncAssertion()
```
:::
-The first argument inside a matcher's function is the received value (the one inside `expect(received)`). The rest are arguments passed directly to the matcher.
+The first argument inside a matcher's function is the received value (the one inside `expect(received)`). The rest are arguments passed directly to the matcher. Since version 4.1, Vitest exposes several types that can be used by your custom matcher:
+
+```ts
+import type {
+ // the function type
+ Matcher,
+ // the return value
+ MatcherResult,
+ // state available as `this`
+ MatcherState,
+} from 'vitest'
+import { expect } from 'vitest'
+
+// a simple matcher, using "function" to have access to "this"
+const customMatcher: Matcher = function (received) {
+ // ...
+}
+
+// a matcher with arguments
+const customMatcher: Matcher = function (received, arg1, arg2) {
+ // ...
+}
+
+// a matcher with custom annotations
+function customMatcher(this: MatcherState, received: unknown, arg1: unknown, arg2: unknown): MatcherResult {
+ // ...
+ return {
+ pass: false,
+ message: () => 'something went wrong!',
+ }
+}
+
+expect.extend({ customMatcher })
+```
Matcher function has access to `this` context with the following properties:
### `isNot`
-Returns true, if matcher was called on `not` (`expect(received).not.toBeFoo()`).
+Returns true, if matcher was called on `not` (`expect(received).not.toBeFoo()`). You do not need to respect it, Vitest will reverse the value of `pass` automatically.
### `promise`
@@ -112,7 +131,7 @@ This contains a set of utility functions that you can use to display messages.
Full name of the current test (including describe block).
-### `task` 4.0.11 {#task}
+### `task` 4.1.0 {#task}
Contains a reference to [the `Test` runner task](/api/advanced/runner#tasks) when available.
@@ -122,4 +141,16 @@ When using the global `expect` with concurrent tests, `this.task` is `undefined`
### `testPath`
-Path to the current test.
+File path to the current test.
+
+### `environment`
+
+The name of the current [`environment`](/config/environment) (for example, `jsdom`).
+
+### `soft`
+
+Was assertion called as a [`soft`](/api/expect#soft) one. You don't need to respect it, Vitest will always catch the error.
+
+::: tip
+These are not all of the available properties, only the most useful ones. The other state values are used by Vitest internally.
+:::
diff --git a/docs/guide/ide.md b/docs/guide/ide.md
index 0a9cb35dc3f6..eaa502346ef8 100644
--- a/docs/guide/ide.md
+++ b/docs/guide/ide.md
@@ -2,12 +2,17 @@
title: IDE Integrations | Guide
---
+
+
# IDE Integrations
## VS Code Official {#vs-code}
-
+
[GitHub](https://github.com/vitest-dev/vscode) | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=vitest.explorer)
@@ -19,7 +24,7 @@ title: IDE Integrations | Guide
WebStorm, PhpStorm, IntelliJ IDEA Ultimate, and other JetBrains IDEs come with built-in support for Vitest.
-
+
[WebStorm Help](https://www.jetbrains.com/help/webstorm/vitest.html) | [IntelliJ IDEA Ultimate Help](https://www.jetbrains.com/help/idea/vitest.html) | [PhpStorm Help](https://www.jetbrains.com/help/phpstorm/vitest.html)
@@ -33,7 +38,7 @@ Created by [The Wallaby Team](https://wallabyjs.com)
[Wallaby.js](https://wallabyjs.com) runs your Vitest tests immediately as you type, highlighting results in your IDE right next to your code.
+ 
+
+
+