diff --git a/docs/guide/extending-matchers.md b/docs/guide/extending-matchers.md index bc6255d3a..c0cc1bdc7 100644 --- 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` 4.1.4 {#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 index 4b8e22bc5..43b56264a 100644 --- 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 index eeaf681d3..c2716caa2 100644 --- 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 index 050bda821..7b998a9ee 100644 --- a/packages/vitest/src/integrations/snapshot/chai.ts +++ b/packages/vitest/src/integrations/snapshot/chai.ts @@ -302,7 +302,7 @@ export const Snapshots = { hint?: string, ): SyncExpectationResult { return toMatchSnapshotImpl({ - assertion: this.__vitest_assertion__, + assertion: this.assertion, received, ...normalizeArguments(propertiesOrHint, hint), }) @@ -335,7 +335,7 @@ export const Snapshots = { hint?: string, ): SyncExpectationResult { return toMatchSnapshotImpl({ - assertion: this.__vitest_assertion__, + assertion: this.assertion, received, isInline: true, ...normalizeInlineArguments(propertiesOrInlineSnapshot, inlineSnapshotOrHint, hint), @@ -368,7 +368,7 @@ export const Snapshots = { hint?: string, ): AsyncExpectationResult { return toMatchFileSnapshotImpl({ - assertion: this.__vitest_assertion__, + assertion: this.assertion, received, filepath, hint,