feat: added chai style assertions by ronnakamoto · Pull Request #8842 · vitest-dev/vitest

ronnakamoto · 2025-10-27T16:26:41Z

Description

This PR adds Chai-style assertion names for spy matchers, enabling users migrating from Mocha+Chai+Sinon to use familiar assertion syntax without rewriting their tests.

Resolves #8819

Users migrating from Mocha/Chai/Sinon to Vitest currently need to rewrite all their spy assertions from Chai-style (e.g., expect(spy).to.have.been.called) to Jest-style (e.g., expect(spy).toHaveBeenCalled()). This creates friction during migration and requires significant test refactoring.

This implementation provides Chai-style assertion names that delegate to existing Jest-style implementations, allowing both styles to coexist.

Added the following assertions that delegate to existing Jest-style implementations:

Property Assertions (no parentheses):

called -> toHaveBeenCalled
calledOnce -> toHaveBeenCalledOnce
calledTwice -> toHaveBeenCalledTimes(2)
calledThrice -> toHaveBeenCalledTimes(3)
returned -> toHaveReturned

Method Assertions (with parentheses):

callCount(n) -> toHaveBeenCalledTimes(n)
calledWith(...args) -> toHaveBeenCalledWith(...args)
calledOnceWith(...args) -> toHaveBeenCalledExactlyOnceWith(...args)
lastCalledWith(...args) -> toHaveBeenLastCalledWith(...args)
nthCalledWith(n, ...args) -> toHaveBeenNthCalledWith(n, ...args)
returnedWith(value) -> toHaveReturnedWith(value)
returnedTimes(n) -> toHaveReturnedTimes(n)
lastReturnedWith(value) -> toHaveLastReturnedWith(value)
nthReturnedWith(n, value) -> toHaveNthReturnedWith(n, value)
calledBefore(spy) -> toHaveBeenCalledBefore(spy)
calledAfter(spy) -> toHaveBeenCalledAfter(spy)

Tests

Run the tests with pnpm test:ci.

Documentation

Updated documentation

netlify · 2025-10-27T16:28:29Z

✅ Deploy Preview for vitest-dev ready!

Name	Link
🔨 Latest commit	`436a4fd`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69666f9cce8d570008649ef2
😎 Deploy Preview	https://deploy-preview-8842--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

sheremet-va · 2025-11-05T19:08:28Z

docs/api/expect.md

 })
 ```

+## Chai-Style Spy Assertions


This is a guide, not an API.

For an API we need all methods to be described similar to other to* assertions

The current doc can be moved to guides

sheremet-va · 2025-11-05T19:09:25Z

docs/guide/migration.md

+```
+
+::: tip
+Vitest supports both `before`/`after` (Mocha-style) and `beforeAll`/`afterAll` (Jest-style) - they're aliases!


Vitest does not support before/after

sheremet-va · 2025-11-05T19:09:50Z

docs/guide/migration.md

+
+### Assertions
+
+Vitest includes Chai assertions by default, so most Chai assertions work without changes:


Let's remove the "most" part, all of them work the same way

sheremet-va · 2025-11-05T19:11:04Z

docs/guide/migration.md

+```
+
+::: tip
+Notice the only difference: Chai-style assertions in Vitest use method calls `called()` instead of properties `called`. This is because Vitest implements these as methods that delegate to Jest-style matchers.


I think we still want them to be defined in the same way that sinon-chai does:

expect(spy).to.have.been.called expect(spy).to.have.been.calledOnce expect(spy).to.have.been.calledWith('arg1', 'arg2')

Refactored to that format

sheremet-va · 2025-11-05T19:12:29Z

docs/guide/migration.md

+vi.useRealTimers()
+```
+
+### Async Testing


I think this can be removed

sheremet-va · 2025-11-05T19:15:00Z

packages/expect/src/chai-style-assertions.ts

+
+  // Chai-style assertion: called
+  // Delegates to: toHaveBeenCalled
+  def('called', 'toHaveBeenCalled')


this should be a property

sheremet-va · 2025-11-05T19:15:10Z

packages/expect/src/chai-style-assertions.ts

+    }
+  }
+
+  // Chai-style assertion: called


All of the comments can be removed, they do not provide any value

sheremet-va · 2025-11-05T19:15:34Z

packages/expect/src/chai-style-assertions.ts

+
+  // Chai-style assertion: calledTwice
+  // Wrapper that calls toHaveBeenCalledTimes(2)
+  utils.addMethod(


Why can't we use def for this? Maybe enhance it to support a property with specified arguments

sheremet-va · 2025-11-05T19:17:01Z

packages/expect/src/types.ts

+   * Chai-style equivalent of `toHaveBeenCalledTimes(2)`.
+   *
+   * @example
+   * expect(spy).to.have.been.calledTwice


All the examples show it as a property...

sheremet-va · 2025-11-05T19:17:29Z

packages/expect/src/types.ts

+ * Chai-style assertions for spy/mock testing.
+ * These provide sinon-chai compatible assertion names that delegate to Jest-style implementations.
+ */
+export interface ChaiStyleAssertion {


Let's name it something like ChaiMockAssertion or something

…to/8842

ronnakamoto added 3 commits October 27, 2025 21:17

feat: added chai style assertions

d45cea7

feat: added more chai assertions

b7978a4

docs: added documentation for chai assertions

e4343ea

fix: fixed linting issues with the doc

9f4cf1b

sheremet-va requested changes Nov 5, 2025

View reviewed changes

ronnakamoto added 3 commits November 8, 2025 23:49

fix: updated with suggestions from the review

f906e96

docs: updated docs with the chai mock assertions info

9e4a213

docs: updated migration guide

b5ce96f

ronnakamoto requested a review from sheremet-va November 8, 2025 18:45

sheremet-va added this to the 4.1.0 milestone Nov 17, 2025

sheremet-va added 3 commits January 13, 2026 17:11

Merge branch 'main' of github.com:vitest-dev/vitest into pr/ronnakamo…

695675f

…to/8842

chore: remove redundant info

42f90ef

chore: note

436a4fd

sheremet-va merged commit 841df9a into vitest-dev:main Jan 13, 2026
15 of 16 checks passed

chrisbbreuer mentioned this pull request Jan 14, 2026

chore(deps): update dependency vitest to 4.0.18 stacksjs/eslint-plugin#72

Closed

1 task

github-actions bot mentioned this pull request Mar 16, 2026

[depSync] Dependency Update: vitest danielrispler/depSync#4

Closed

hi-ogawa mentioned this pull request Mar 22, 2026

fix(expect): fix sinon-chai style API #9943

Merged

7 tasks


		### Assertions

		Vitest includes Chai assertions by default, so most Chai assertions work without changes:

Uh oh!

Conversation

ronnakamoto commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Tests

Documentation

Uh oh!

netlify bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vitest-dev ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ronnakamoto commented Oct 27, 2025 •

edited

Loading

netlify bot commented Oct 27, 2025 •

edited

Loading