@vitest/expect 2.1.3 → 2.1.5

package/README.md

@@ -5,12 +5,12 @@ Jest's expect matchers as a Chai plugin.
 ## Usage
 
 ```js
-import * as chai from 'chai'
 import {
   JestAsymmetricMatchers,
   JestChaiExpect,
   JestExtend,
 } from '@vitest/expect'
+import * as chai from 'chai'
 
 // allows using expect.extend instead of chai.use to extend plugins
 chai.use(JestExtend)

package/dist/index.d.ts

@@ -1,9 +1,14 @@
+import { stringify, Constructable } from '@vitest/utils';
 import * as tinyrainbow from 'tinyrainbow';
 import { Formatter } from 'tinyrainbow';
-import { stringify, Constructable } from '@vitest/utils';
 import { diff, printDiffOrStringify } from '@vitest/utils/diff';
 export { DiffOptions } from '@vitest/utils/diff';
 
+declare const MATCHERS_OBJECT: unique symbol;
+declare const JEST_MATCHERS_OBJECT: unique symbol;
+declare const GLOBAL_EXPECT: unique symbol;
+declare const ASYMMETRIC_MATCHERS_OBJECT: unique symbol;
+
 declare function matcherHint(matcherName: string, received?: string, expected?: string, options?: MatcherHintOptions): string;
 declare function printReceived(object: unknown): string;
 declare function printExpected(value: unknown): string;
@@ -92,55 +97,433 @@ interface ExpectStatic extends Chai.ExpectStatic, AsymmetricMatchersContaining {
     not: AsymmetricMatchersContaining;
 }
 interface AsymmetricMatchersContaining {
+    /**
+     * Matches if the received string contains the expected substring.
+     *
+     * @example
+     * expect('I have an apple').toEqual(expect.stringContaining('apple'));
+     * expect({ a: 'test string' }).toEqual({ a: expect.stringContaining('test') });
+     */
     stringContaining: (expected: string) => any;
+    /**
+     * Matches if the received object contains all properties of the expected object.
+     *
+     * @example
+     * expect({ a: '1', b: 2 }).toEqual(expect.objectContaining({ a: '1' }))
+     */
     objectContaining: <T = any>(expected: T) => any;
+    /**
+     * Matches if the received array contains all elements in the expected array.
+     *
+     * @example
+     * expect(['a', 'b', 'c']).toEqual(expect.arrayContaining(['b', 'a']));
+     */
     arrayContaining: <T = unknown>(expected: Array<T>) => any;
+    /**
+     * Matches if the received string or regex matches the expected pattern.
+     *
+     * @example
+     * expect('hello world').toEqual(expect.stringMatching(/^hello/));
+     * expect('hello world').toEqual(expect.stringMatching('hello'));
+     */
     stringMatching: (expected: string | RegExp) => any;
+    /**
+     * Matches if the received number is within a certain precision of the expected number.
+     *
+     * @param precision - Optional decimal precision for comparison. Default is 2.
+     *
+     * @example
+     * expect(10.45).toEqual(expect.closeTo(10.5, 1));
+     * expect(5.11).toEqual(expect.closeTo(5.12)); // with default precision
+     */
     closeTo: (expected: number, precision?: number) => any;
 }
 interface JestAssertion<T = any> extends jest.Matchers<void, T> {
+    /**
+     * Used when you want to check that two objects have the same value.
+     * This matcher recursively checks the equality of all fields, rather than checking for object identity.
+     *
+     * @example
+     * expect(user).toEqual({ name: 'Alice', age: 30 });
+     */
     toEqual: <E>(expected: E) => void;
+    /**
+     * Use to test that objects have the same types as well as structure.
+     *
+     * @example
+     * expect(user).toStrictEqual({ name: 'Alice', age: 30 });
+     */
     toStrictEqual: <E>(expected: E) => void;
+    /**
+     * Checks that a value is what you expect. It calls `Object.is` to compare values.
+     * Don't use `toBe` with floating-point numbers.
+     *
+     * @example
+     * expect(result).toBe(42);
+     * expect(status).toBe(true);
+     */
     toBe: <E>(expected: E) => void;
+    /**
+     * Check that a string matches a regular expression.
+     *
+     * @example
+     * expect(message).toMatch(/hello/);
+     * expect(greeting).toMatch('world');
+     */
     toMatch: (expected: string | RegExp) => void;
+    /**
+     * Used to check that a JavaScript object matches a subset of the properties of an object
+     *
+     * @example
+     * expect(user).toMatchObject({
+     *   name: 'Alice',
+     *   address: { city: 'Wonderland' }
+     * });
+     */
     toMatchObject: <E extends object | any[]>(expected: E) => void;
+    /**
+     * Used when you want to check that an item is in a list.
+     * For testing the items in the list, this uses `===`, a strict equality check.
+     *
+     * @example
+     * expect(items).toContain('apple');
+     * expect(numbers).toContain(5);
+     */
     toContain: <E>(item: E) => void;
+    /**
+     * Used when you want to check that an item is in a list.
+     * For testing the items in the list, this matcher recursively checks the
+     * equality of all fields, rather than checking for object identity.
+     *
+     * @example
+     * expect(items).toContainEqual({ name: 'apple', quantity: 1 });
+     */
     toContainEqual: <E>(item: E) => void;
+    /**
+     * Use when you don't care what a value is, you just want to ensure a value
+     * is true in a boolean context. In JavaScript, there are six falsy values:
+     * `false`, `0`, `''`, `null`, `undefined`, and `NaN`. Everything else is truthy.
+     *
+     * @example
+     * expect(user.isActive).toBeTruthy();
+     */
     toBeTruthy: () => void;
+    /**
+     * When you don't care what a value is, you just want to
+     * ensure a value is false in a boolean context.
+     *
+     * @example
+     * expect(user.isActive).toBeFalsy();
+     */
     toBeFalsy: () => void;
+    /**
+     * For comparing floating point numbers.
+     *
+     * @example
+     * expect(score).toBeGreaterThan(10);
+     */
     toBeGreaterThan: (num: number | bigint) => void;
+    /**
+     * For comparing floating point numbers.
+     *
+     * @example
+     * expect(score).toBeGreaterThanOrEqual(10);
+     */
     toBeGreaterThanOrEqual: (num: number | bigint) => void;
+    /**
+     * For comparing floating point numbers.
+     *
+     * @example
+     * expect(score).toBeLessThan(10);
+     */
     toBeLessThan: (num: number | bigint) => void;
+    /**
+     * For comparing floating point numbers.
+     *
+     * @example
+     * expect(score).toBeLessThanOrEqual(10);
+     */
     toBeLessThanOrEqual: (num: number | bigint) => void;
+    /**
+     * Used to check that a variable is NaN.
+     *
+     * @example
+     * expect(value).toBeNaN();
+     */
     toBeNaN: () => void;
+    /**
+     * Used to check that a variable is undefined.
+     *
+     * @example
+     * expect(value).toBeUndefined();
+     */
     toBeUndefined: () => void;
+    /**
+     * This is the same as `.toBe(null)` but the error messages are a bit nicer.
+     * So use `.toBeNull()` when you want to check that something is null.
+     *
+     * @example
+     * expect(value).toBeNull();
+     */
     toBeNull: () => void;
+    /**
+     * Ensure that a variable is not undefined.
+     *
+     * @example
+     * expect(value).toBeDefined();
+     */
     toBeDefined: () => void;
+    /**
+     * Ensure that an object is an instance of a class.
+     * This matcher uses `instanceof` underneath.
+     *
+     * @example
+     * expect(new Date()).toBeInstanceOf(Date);
+     */
     toBeInstanceOf: <E>(expected: E) => void;
-    toBeCalledTimes: (times: number) => void;
+    /**
+     * Used to check that an object has a `.length` property
+     * and it is set to a certain numeric value.
+     *
+     * @example
+     * expect([1, 2, 3]).toHaveLength(3);
+     * expect('hello').toHaveLength(5);
+     */
     toHaveLength: (length: number) => void;
+    /**
+     * Use to check if a property at the specified path exists on an object.
+     * For checking deeply nested properties, you may use dot notation or an array containing
+     * the path segments for deep references.
+     *
+     * Optionally, you can provide a value to check if it matches the value present at the path
+     * on the target object. This matcher uses 'deep equality' (like `toEqual()`) and recursively checks
+     * the equality of all fields.
+     *
+     * @example
+     * expect(user).toHaveProperty('address.city', 'New York');
+     * expect(config).toHaveProperty(['settings', 'theme'], 'dark');
+     */
     toHaveProperty: <E>(property: string | (string | number)[], value?: E) => void;
+    /**
+     * Using exact equality with floating point numbers is a bad idea.
+     * Rounding means that intuitive things fail.
+     * The default for `precision` is 2.
+     *
+     * @example
+     * expect(price).toBeCloseTo(9.99, 2);
+     */
     toBeCloseTo: (number: number, numDigits?: number) => void;
+    /**
+     * Ensures that a mock function is called an exact number of times.
+     *
+     * Also under the alias `expect.toBeCalledTimes`.
+     *
+     * @example
+     * expect(mockFunc).toHaveBeenCalledTimes(2);
+     */
     toHaveBeenCalledTimes: (times: number) => void;
+    /**
+     * Ensures that a mock function is called an exact number of times.
+     *
+     * Alias for `expect.toHaveBeenCalledTimes`.
+     *
+     * @example
+     * expect(mockFunc).toBeCalledTimes(2);
+     */
+    toBeCalledTimes: (times: number) => void;
+    /**
+     * Ensures that a mock function is called.
+     *
+     * Also under the alias `expect.toBeCalled`.
+     *
+     * @example
+     * expect(mockFunc).toHaveBeenCalled();
+     */
     toHaveBeenCalled: () => void;
+    /**
+     * Ensures that a mock function is called.
+     *
+     * Alias for `expect.toHaveBeenCalled`.
+     *
+     * @example
+     * expect(mockFunc).toBeCalled();
+     */
     toBeCalled: () => void;
+    /**
+     * Ensure that a mock function is called with specific arguments.
+     *
+     * Also under the alias `expect.toBeCalledWith`.
+     *
+     * @example
+     * expect(mockFunc).toHaveBeenCalledWith('arg1', 42);
+     */
     toHaveBeenCalledWith: <E extends any[]>(...args: E) => void;
+    /**
+     * Ensure that a mock function is called with specific arguments.
+     *
+     * Alias for `expect.toHaveBeenCalledWith`.
+     *
+     * @example
+     * expect(mockFunc).toBeCalledWith('arg1', 42);
+     */
     toBeCalledWith: <E extends any[]>(...args: E) => void;
+    /**
+     * Ensure that a mock function is called with specific arguments on an Nth call.
+     *
+     * Also under the alias `expect.nthCalledWith`.
+     *
+     * @example
+     * expect(mockFunc).toHaveBeenNthCalledWith(2, 'secondArg');
+     */
     toHaveBeenNthCalledWith: <E extends any[]>(n: number, ...args: E) => void;
+    /**
+     * Ensure that a mock function is called with specific arguments on an Nth call.
+     *
+     * Alias for `expect.toHaveBeenNthCalledWith`.
+     *
+     * @example
+     * expect(mockFunc).nthCalledWith(2, 'secondArg');
+     */
     nthCalledWith: <E extends any[]>(nthCall: number, ...args: E) => void;
+    /**
+     * If you have a mock function, you can use `.toHaveBeenLastCalledWith`
+     * to test what arguments it was last called with.
+     *
+     * Also under the alias `expect.lastCalledWith`.
+     *
+     * @example
+     * expect(mockFunc).toHaveBeenLastCalledWith('lastArg');
+     */
     toHaveBeenLastCalledWith: <E extends any[]>(...args: E) => void;
+    /**
+     * If you have a mock function, you can use `.lastCalledWith`
+     * to test what arguments it was last called with.
+     *
+     * Alias for `expect.toHaveBeenLastCalledWith`.
+     *
+     * @example
+     * expect(mockFunc).lastCalledWith('lastArg');
+     */
     lastCalledWith: <E extends any[]>(...args: E) => void;
+    /**
+     * Used to test that a function throws when it is called.
+     *
+     * Also under the alias `expect.toThrowError`.
+     *
+     * @example
+     * expect(() => functionWithError()).toThrow('Error message');
+     * expect(() => parseJSON('invalid')).toThrow(SyntaxError);
+     */
     toThrow: (expected?: string | Constructable | RegExp | Error) => void;
+    /**
+     * Used to test that a function throws when it is called.
+     *
+     * Alias for `expect.toThrow`.
+     *
+     * @example
+     * expect(() => functionWithError()).toThrowError('Error message');
+     * expect(() => parseJSON('invalid')).toThrowError(SyntaxError);
+     */
     toThrowError: (expected?: string | Constructable | RegExp | Error) => void;
+    /**
+     * Use to test that the mock function successfully returned (i.e., did not throw an error) at least one time
+     *
+     * Alias for `expect.toHaveReturned`.
+     *
+     * @example
+     * expect(mockFunc).toReturn();
+     */
     toReturn: () => void;
+    /**
+     * Use to test that the mock function successfully returned (i.e., did not throw an error) at least one time
+     *
+     * Also under the alias `expect.toReturn`.
+     *
+     * @example
+     * expect(mockFunc).toHaveReturned();
+     */
     toHaveReturned: () => void;
+    /**
+     * Use to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times.
+     * Any calls to the mock function that throw an error are not counted toward the number of times the function returned.
+     *
+     * Alias for `expect.toHaveReturnedTimes`.
+     *
+     * @example
+     * expect(mockFunc).toReturnTimes(3);
+     */
     toReturnTimes: (times: number) => void;
+    /**
+     * Use to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times.
+     * Any calls to the mock function that throw an error are not counted toward the number of times the function returned.
+     *
+     * Also under the alias `expect.toReturnTimes`.
+     *
+     * @example
+     * expect(mockFunc).toHaveReturnedTimes(3);
+     */
     toHaveReturnedTimes: (times: number) => void;
+    /**
+     * Use to ensure that a mock function returned a specific value.
+     *
+     * Alias for `expect.toHaveReturnedWith`.
+     *
+     * @example
+     * expect(mockFunc).toReturnWith('returnValue');
+     */
     toReturnWith: <E>(value: E) => void;
+    /**
+     * Use to ensure that a mock function returned a specific value.
+     *
+     * Also under the alias `expect.toReturnWith`.
+     *
+     * @example
+     * expect(mockFunc).toHaveReturnedWith('returnValue');
+     */
     toHaveReturnedWith: <E>(value: E) => void;
+    /**
+     * Use to test the specific value that a mock function last returned.
+     * If the last call to the mock function threw an error, then this matcher will fail
+     * no matter what value you provided as the expected return value.
+     *
+     * Also under the alias `expect.lastReturnedWith`.
+     *
+     * @example
+     * expect(mockFunc).toHaveLastReturnedWith('lastValue');
+     */
     toHaveLastReturnedWith: <E>(value: E) => void;
+    /**
+     * Use to test the specific value that a mock function last returned.
+     * If the last call to the mock function threw an error, then this matcher will fail
+     * no matter what value you provided as the expected return value.
+     *
+     * Alias for `expect.toHaveLastReturnedWith`.
+     *
+     * @example
+     * expect(mockFunc).lastReturnedWith('lastValue');
+     */
     lastReturnedWith: <E>(value: E) => void;
+    /**
+     * Use to test the specific value that a mock function returned for the nth call.
+     * If the nth call to the mock function threw an error, then this matcher will fail
+     * no matter what value you provided as the expected return value.
+     *
+     * Also under the alias `expect.nthReturnedWith`.
+     *
+     * @example
+     * expect(mockFunc).toHaveNthReturnedWith(2, 'nthValue');
+     */
     toHaveNthReturnedWith: <E>(nthCall: number, value: E) => void;
+    /**
+     * Use to test the specific value that a mock function returned for the nth call.
+     * If the nth call to the mock function threw an error, then this matcher will fail
+     * no matter what value you provided as the expected return value.
+     *
+     * Alias for `expect.toHaveNthReturnedWith`.
+     *
+     * @example
+     * expect(mockFunc).nthReturnedWith(2, 'nthValue');
+     */
     nthReturnedWith: <E>(nthCall: number, value: E) => void;
 }
 type VitestAssertion<A, T> = {
@@ -151,15 +534,79 @@ type Promisify<O> = {
 };
 type PromisifyAssertion<T> = Promisify<Assertion<T>>;
 interface Assertion<T = any> extends VitestAssertion<Chai.Assertion, T>, JestAssertion<T> {
+    /**
+     * Ensures a value is of a specific type.
+     *
+     * @example
+     * expect(value).toBeTypeOf('string');
+     * expect(number).toBeTypeOf('number');
+     */
     toBeTypeOf: (expected: 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'undefined') => void;
+    /**
+     * Asserts that a mock function was called exactly once.
+     *
+     * @example
+     * expect(mockFunc).toHaveBeenCalledOnce();
+     */
     toHaveBeenCalledOnce: () => void;
+    /**
+     * Checks that a value satisfies a custom matcher function.
+     *
+     * @param matcher - A function returning a boolean based on the custom condition
+     * @param message - Optional custom error message on failure
+     *
+     * @example
+     * expect(age).toSatisfy(val => val >= 18, 'Age must be at least 18');
+     */
     toSatisfy: <E>(matcher: (value: E) => boolean, message?: string) => void;
+    /**
+     * Checks that a promise resolves successfully at least once.
+     *
+     * @example
+     * await expect(promise).toHaveResolved();
+     */
     toHaveResolved: () => void;
+    /**
+     * Checks that a promise resolves to a specific value.
+     *
+     * @example
+     * await expect(promise).toHaveResolvedWith('success');
+     */
     toHaveResolvedWith: <E>(value: E) => void;
+    /**
+     * Ensures a promise resolves a specific number of times.
+     *
+     * @example
+     * expect(mockAsyncFunc).toHaveResolvedTimes(3);
+     */
     toHaveResolvedTimes: (times: number) => void;
+    /**
+     * Asserts that the last resolved value of a promise matches an expected value.
+     *
+     * @example
+     * await expect(mockAsyncFunc).toHaveLastResolvedWith('finalResult');
+     */
     toHaveLastResolvedWith: <E>(value: E) => void;
+    /**
+     * Ensures a specific value was returned by a promise on the nth resolution.
+     *
+     * @example
+     * await expect(mockAsyncFunc).toHaveNthResolvedWith(2, 'secondResult');
+     */
     toHaveNthResolvedWith: <E>(nthCall: number, value: E) => void;
+    /**
+     * Verifies that a promise resolves.
+     *
+     * @example
+     * await expect(someAsyncFunc).resolves.toBe(42);
+     */
     resolves: PromisifyAssertion<T>;
+    /**
+     * Verifies that a promise rejects.
+     *
+     * @example
+     * await expect(someAsyncFunc).rejects.toThrow('error');
+     */
     rejects: PromisifyAssertion<T>;
 }
 declare global {
@@ -227,6 +674,10 @@ declare class StringMatching extends AsymmetricMatcher<RegExp> {
 }
 declare const JestAsymmetricMatchers: ChaiPlugin;
 
+declare const JestChaiExpect: ChaiPlugin;
+
+declare const JestExtend: ChaiPlugin;
+
 declare function equals(a: unknown, b: unknown, customTesters?: Array<Tester>, strictCheck?: boolean): boolean;
 declare function isAsymmetric(obj: any): boolean;
 declare function hasAsymmetric(obj: any, seen?: Set<unknown>): boolean;
@@ -248,16 +699,7 @@ declare function getObjectSubset(object: any, subset: any, customTesters: Array<
     stripped: number;
 };
 
-declare const MATCHERS_OBJECT: unique symbol;
-declare const JEST_MATCHERS_OBJECT: unique symbol;
-declare const GLOBAL_EXPECT: unique symbol;
-declare const ASYMMETRIC_MATCHERS_OBJECT: unique symbol;
-
 declare function getState<State extends MatcherState = MatcherState>(expect: ExpectStatic): State;
 declare function setState<State extends MatcherState = MatcherState>(state: Partial<State>, expect: ExpectStatic): void;
 
-declare const JestChaiExpect: ChaiPlugin;
-
-declare const JestExtend: ChaiPlugin;
-
 export { ASYMMETRIC_MATCHERS_OBJECT, Any, Anything, ArrayContaining, type Assertion, AsymmetricMatcher, type AsymmetricMatcherInterface, type AsymmetricMatchersContaining, type AsyncExpectationResult, type ChaiPlugin, type ExpectStatic, type ExpectationResult, GLOBAL_EXPECT, JEST_MATCHERS_OBJECT, type JestAssertion, JestAsymmetricMatchers, JestChaiExpect, JestExtend, MATCHERS_OBJECT, type MatcherHintOptions, type MatcherState, type MatchersObject, ObjectContaining, type PromisifyAssertion, type RawMatcherFn, StringContaining, StringMatching, type SyncExpectationResult, type Tester, type TesterContext, addCustomEqualityTesters, arrayBufferEquality, equals, fnNameFor, generateToBeMessage, getObjectKeys, getObjectSubset, getState, hasAsymmetric, hasProperty, isA, isAsymmetric, isImmutableUnorderedKeyed, isImmutableUnorderedSet, iterableEquality, pluralize, setState, sparseArrayEquality, subsetEquality, typeEquality };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { getType, stringify, isObject, assertTypes } from '@vitest/utils';
-import c from 'tinyrainbow';
 import { diff, printDiffOrStringify } from '@vitest/utils/diff';
+import c from 'tinyrainbow';
 import { isMockFunction } from '@vitest/spy';
 import { processError } from '@vitest/utils/error';
 import { use, util } from 'chai';
@@ -12,39 +12,6 @@ const ASYMMETRIC_MATCHERS_OBJECT = Symbol.for(
   "asymmetric-matchers-object"
 );
 
-if (!Object.prototype.hasOwnProperty.call(globalThis, MATCHERS_OBJECT)) {
-  const globalState = /* @__PURE__ */ new WeakMap();
-  const matchers = /* @__PURE__ */ Object.create(null);
-  const customEqualityTesters = [];
-  const assymetricMatchers = /* @__PURE__ */ Object.create(null);
-  Object.defineProperty(globalThis, MATCHERS_OBJECT, {
-    get: () => globalState
-  });
-  Object.defineProperty(globalThis, JEST_MATCHERS_OBJECT, {
-    configurable: true,
-    get: () => ({
-      state: globalState.get(globalThis[GLOBAL_EXPECT]),
-      matchers,
-      customEqualityTesters
-    })
-  });
-  Object.defineProperty(globalThis, ASYMMETRIC_MATCHERS_OBJECT, {
-    get: () => assymetricMatchers
-  });
-}
-function getState(expect) {
-  return globalThis[MATCHERS_OBJECT].get(expect);
-}
-function setState(state, expect) {
-  const map = globalThis[MATCHERS_OBJECT];
-  const current = map.get(expect) || {};
-  const results = Object.defineProperties(current, {
-    ...Object.getOwnPropertyDescriptors(current),
-    ...Object.getOwnPropertyDescriptors(state)
-  });
-  map.set(expect, results);
-}
-
 const EXPECTED_COLOR = c.green;
 const RECEIVED_COLOR = c.red;
 const INVERTED_COLOR = c.inverse;
@@ -229,6 +196,7 @@ function eq(a, b, aStack, bStack, customTesters, hasKey2) {
       const numB = +b;
       return numA === numB || Number.isNaN(numA) && Number.isNaN(numB);
     }
+    // RegExps are compared by their source patterns and flags.
     case "[object RegExp]":
       return a.source === b.source && a.flags === b.flags;
   }
@@ -610,6 +578,39 @@ function getObjectSubset(object, subset, customTesters) {
   return { subset: getObjectSubsetWithContext()(object, subset), stripped };
 }
 
+if (!Object.prototype.hasOwnProperty.call(globalThis, MATCHERS_OBJECT)) {
+  const globalState = /* @__PURE__ */ new WeakMap();
+  const matchers = /* @__PURE__ */ Object.create(null);
+  const customEqualityTesters = [];
+  const assymetricMatchers = /* @__PURE__ */ Object.create(null);
+  Object.defineProperty(globalThis, MATCHERS_OBJECT, {
+    get: () => globalState
+  });
+  Object.defineProperty(globalThis, JEST_MATCHERS_OBJECT, {
+    configurable: true,
+    get: () => ({
+      state: globalState.get(globalThis[GLOBAL_EXPECT]),
+      matchers,
+      customEqualityTesters
+    })
+  });
+  Object.defineProperty(globalThis, ASYMMETRIC_MATCHERS_OBJECT, {
+    get: () => assymetricMatchers
+  });
+}
+function getState(expect) {
+  return globalThis[MATCHERS_OBJECT].get(expect);
+}
+function setState(state, expect) {
+  const map = globalThis[MATCHERS_OBJECT];
+  const current = map.get(expect) || {};
+  const results = Object.defineProperties(current, {
+    ...Object.getOwnPropertyDescriptors(current),
+    ...Object.getOwnPropertyDescriptors(state)
+  });
+  map.set(expect, results);
+}
+
 class AsymmetricMatcher {
   constructor(sample, inverse = false) {
     this.sample = sample;
@@ -907,9 +908,20 @@ const JestAsymmetricMatchers = (chai, utils) => {
   };
 };
 
-function recordAsyncExpect(test, promise) {
+function createAssertionMessage(util, assertion, hasArgs) {
+  const not = util.flag(assertion, "negate") ? "not." : "";
+  const name = `${util.flag(assertion, "_name")}(${hasArgs ? "expected" : ""})`;
+  const promiseName = util.flag(assertion, "promise");
+  const promise = promiseName ? `.${promiseName}` : "";
+  return `expect(actual)${promise}.${not}${name}`;
+}
+function recordAsyncExpect(_test, promise, assertion, error) {
+  const test = _test;
   if (test && promise instanceof Promise) {
     promise = promise.finally(() => {
+      if (!test.promises) {
+        return;
+      }
       const index = test.promises.indexOf(promise);
       if (index !== -1) {
         test.promises.splice(index, 1);
@@ -919,13 +931,43 @@ function recordAsyncExpect(test, promise) {
       test.promises = [];
     }
     test.promises.push(promise);
+    let resolved = false;
+    test.onFinished ?? (test.onFinished = []);
+    test.onFinished.push(() => {
+      var _a;
+      if (!resolved) {
+        const processor = ((_a = globalThis.__vitest_worker__) == null ? void 0 : _a.onFilterStackTrace) || ((s) => s || "");
+        const stack = processor(error.stack);
+        console.warn([
+          `Promise returned by \`${assertion}\` was not awaited. `,
+          "Vitest currently auto-awaits hanging assertions at the end of the test, but this will cause the test to fail in Vitest 3. ",
+          "Please remember to await the assertion.\n",
+          stack
+        ].join(""));
+      }
+    });
+    return {
+      then(onFullfilled, onRejected) {
+        resolved = true;
+        return promise.then(onFullfilled, onRejected);
+      },
+      catch(onRejected) {
+        return promise.catch(onRejected);
+      },
+      finally(onFinally) {
+        return promise.finally(onFinally);
+      },
+      [Symbol.toStringTag]: "Promise"
+    };
   }
   return promise;
 }
 function wrapAssertion(utils, name, fn) {
   return function(...args) {
     var _a;
-    utils.flag(this, "_name", name);
+    if (name !== "withTest") {
+      utils.flag(this, "_name", name);
+    }
     if (!utils.flag(this, "soft")) {
       return fn.apply(this, args);
     }
@@ -1464,7 +1506,7 @@ const JestChaiExpect = (chai, utils) => {
     ["toThrow", "toThrowError"],
     function(expected) {
       if (typeof expected === "string" || typeof expected === "undefined" || expected instanceof RegExp) {
-        return this.throws(expected);
+        return this.throws(expected === "" ? /^$/ : expected);
       }
       const obj = this._obj;
       const promise = utils.flag(this, "promise");
@@ -1723,6 +1765,7 @@ const JestChaiExpect = (chai, utils) => {
             return result instanceof chai.Assertion ? proxy : result;
           }
           return (...args) => {
+            utils.flag(this, "_name", key);
             const promise = obj.then(
               (value) => {
                 utils.flag(this, "object", value);
@@ -1743,7 +1786,12 @@ const JestChaiExpect = (chai, utils) => {
                 throw _error;
               }
             );
-            return recordAsyncExpect(test, promise);
+            return recordAsyncExpect(
+              test,
+              promise,
+              createAssertionMessage(utils, this, !!args.length),
+              error
+            );
           };
         }
       });
@@ -1777,6 +1825,7 @@ const JestChaiExpect = (chai, utils) => {
             return result instanceof chai.Assertion ? proxy : result;
           }
           return (...args) => {
+            utils.flag(this, "_name", key);
             const promise = wrapper.then(
               (value) => {
                 const _error = new AssertionError(
@@ -1800,7 +1849,12 @@ const JestChaiExpect = (chai, utils) => {
                 return result.call(this, ...args);
               }
             );
-            return recordAsyncExpect(test, promise);
+            return recordAsyncExpect(
+              test,
+              promise,
+              createAssertionMessage(utils, this, !!args.length),
+              error
+            );
           };
         }
       });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitest/expect",
   "type": "module",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "Jest's expect matchers as a Chai plugin",
   "license": "MIT",
   "funding": "https://opencollective.com/vitest",
@@ -30,15 +30,15 @@
     "dist"
   ],
   "dependencies": {
-    "chai": "^5.1.1",
+    "chai": "^5.1.2",
     "tinyrainbow": "^1.2.0",
-    "@vitest/spy": "2.1.3",
-    "@vitest/utils": "2.1.3"
+    "@vitest/utils": "2.1.5",
+    "@vitest/spy": "2.1.5"
   },
   "devDependencies": {
     "@types/chai": "4.3.6",
     "rollup-plugin-copy": "^3.5.0",
-    "@vitest/runner": "2.1.3"
+    "@vitest/runner": "2.1.5"
   },
   "scripts": {
     "build": "rimraf dist && rollup -c",