feat(experimental): expose assertion as a public field

sheremet-va · sheremet-va · commit 9d6202decbb2 · 2026-04-07T21:29:51.000+02:00
diff --git a/docs/guide/extending-matchers.md b/docs/guide/extending-matchers.md
@@ -155,6 +155,10 @@ The name of the current [`environment`](/config/environment) (for example, `jsdo
 
 Was assertion called as a [`soft`](/api/expect#soft) one. You don't need to respect it, Vitest will always catch the error.
 
+## `assertion` <Advanced /> <Version type="experimental">4.1.4</Version> {#assertion}
+
+The underlying [Chai assertion](https://www.chaijs.com/guide/plugins/) object. This is the same instance that Chai plugins receive, giving you access to Chai's flag system and chainable methods. This can be useful for building custom matchers that need to interact with Chai's internals.
+
 ::: 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/packages/expect/src/jest-extend.ts b/packages/expect/src/jest-extend.ts
@@ -53,7 +53,7 @@ function getMatcherState(
     suppressedErrors: [],
     soft: util.flag(assertion, 'soft') as boolean | undefined,
     poll: util.flag(assertion, 'poll') as boolean | undefined,
-    __vitest_assertion__: assertion as any,
+    assertion: assertion as any,
   }
   Object.assign(matcherState, { task })
 
diff --git a/packages/expect/src/types.ts b/packages/expect/src/types.ts
@@ -83,12 +83,11 @@ export interface MatcherState {
   soft?: boolean
   poll?: boolean
   /**
-   * this allows `expect.extend`-based custom matcher
-   * to implement builtin vitest/chai assertion equivalent feature.
-   * this used for custom snapshot matcher API.
+   * The same assertion instance that chai plugins receive.
+   * @experimental
+   * @see {@link https://www.chaijs.com/guide/plugins/} Core Plugin Concepts
    */
-  /** @internal */
-  __vitest_assertion__: Assertion
+  readonly assertion: Assertion
 }
 
 export interface SyncExpectationResult {
diff --git a/packages/vitest/src/integrations/snapshot/chai.ts b/packages/vitest/src/integrations/snapshot/chai.ts
@@ -301,7 +301,7 @@ export const Snapshots = {
     hint?: string,
   ): SyncExpectationResult {
     return toMatchSnapshotImpl({
-      assertion: this.__vitest_assertion__,
+      assertion: this.assertion,
       received,
       ...normalizeArguments(propertiesOrHint, hint),
     })
@@ -334,7 +334,7 @@ export const Snapshots = {
     hint?: string,
   ): SyncExpectationResult {
     return toMatchSnapshotImpl({
-      assertion: this.__vitest_assertion__,
+      assertion: this.assertion,
       received,
       isInline: true,
       ...normalizeInlineArguments(propertiesOrInlineSnapshot, inlineSnapshotOrHint, hint),
@@ -367,7 +367,7 @@ export const Snapshots = {
     hint?: string,
   ): AsyncExpectationResult {
     return toMatchFileSnapshotImpl({
-      assertion: this.__vitest_assertion__,
+      assertion: this.assertion,
       received,
       filepath,
       hint,

Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@ function getMatcherState(`
`53`	`53`	`suppressedErrors: [],`
`54`	`54`	`soft: util.flag(assertion, 'soft') as boolean \| undefined,`
`55`	`55`	`poll: util.flag(assertion, 'poll') as boolean \| undefined,`
`56`		`- __vitest_assertion__: assertion as any,`
	`56`	`+ assertion: assertion as any,`
`57`	`57`	`}`
`58`	`58`	`Object.assign(matcherState, { task })`
`59`	`59`