expect configuration

14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Matchers interface now takes return type as first parameter

When extending matchers in Vitest 5, the Matchers interface now takes the return type as its first parameter and the received type as the second: interface Matchers<R, T>. R reflects how the matcher is used: void when called synchronously, Promise<void> through .resolves, .rejects, expect.poll, or expect.element. T is the type of the received value. Example: interface Matchers<R, T> { toBeFoo: () => R; toEqualTyped: (expected: T) => R }.

expect.addSnapshotSerializer signature

expect.addSnapshotSerializer has type (plugin: PrettyFormatPlugin) => void. This method adds custom serializers that are called when creating a snapshot.

expect.addSnapshotSerializer usage location

Custom snapshot serializers should be added by calling expect.addSnapshotSerializer inside setupFiles to affect every snapshot.

expect.extend signature

expect.extend has type (matchers: MatchersObject) => void. This function extends the matchers object with custom matchers.

expect.extend creates asymmetric matchers

When you define custom matchers using expect.extend, you also create asymmetric matchers that can be used like expect.stringContaining.

Custom matcher return object structure

A custom matcher defined with expect.extend must return an object with a message property (a function returning a string) and a pass property (a boolean). The this context provides an isNot property indicating negation.

expect.extend custom matcher example

Example of a custom matcher: expect.extend({ toBeFoo(received) { const { isNot } = this; return { message: () => `expected ${received} is${isNot ? ' not' : ''} foo`, pass: received === 'foo' } } }). Can be used as expect('foo').toBeFoo() or as asymmetric matcher expect({ foo: 'foo' }).toEqual({ foo: expect.toBeFoo() })

Custom matchers in setupFiles

To make custom matchers appear in every test, call expect.extend inside setupFiles.

expect.extend TypeScript declaration

To extend the Matchers interface in TypeScript, create an ambient declaration file (e.g. vitest.d.ts) with: import 'vitest'; declare module 'vitest' { interface Matchers<R, T> { toBeFoo: () => R } }. R is the assertion return type, and T is the type of the received value.

expect.extend Jest compatibility

expect.extend is compatible with Jest's expect.extend, so any library that uses it to create custom matchers will work with Vitest.

expect.addEqualityTesters signature

expect.addEqualityTesters has type (tester: Array<Tester>) => void. This method defines custom testers used by matchers to test if two objects are equal.

expect.addEqualityTesters Jest compatibility

expect.addEqualityTesters is compatible with Jest's expect.addEqualityTesters.

Custom equality tester function signature

A custom equality tester function receives two unknown values (a and b) and returns a boolean or undefined. It should return true if equal, false if not equal, or undefined if the tester cannot determine equality.

Custom equality tester example with AnagramComparator

Example of custom equality tester: function areAnagramsEqual(a: unknown, b: unknown): boolean | undefined { const isAAnagramComparator = isAnagramComparator(a); const isBAnagramComparator = isAnagramComparator(b); if (isAAnagramComparator && isBAnagramComparator) { return a.equals(b); } else if (isAAnagramComparator === isBAnagramComparator) { return undefined; } else { return false; } }. Then call expect.addEqualityTesters([areAnagramsEqual]) and use expect(new AnagramComparator('listen')).toEqual(new AnagramComparator('silent'))

Give your agent this brain