Type safe assertions

[krzkaczor]

Clear and concise description of the problem

Right now it's possible to construct assertions (let's say using expect api) that will always fail because they compare values of different types, yet there are not type errors.

Consider this:

expect(123).toBe('123')

This is obviously a mistake that will fail in runtime but will pass happily in compile time.

Having type safe assertions becomes very handy during refactorings when compiler can guide the developer through all required changes. Consider slightly more complex example:

const returnValue = functionCall()
expect(returnValue).toEqual({ a: 1, b: 2 })

Once functionCall return type changes in the future, TypeScript type checker would point the developer to all assertions that need to be updated. Right now this has to be done by executing tests which results in worse DX.

In bun test runner same code will result in a type error in a compile time, clearly visible to developer.

Suggested solution

I propose making assertions api type safe. This can be done by parameterizing matchers by a type represented by actual value. Most likely due to various edge cases in comparison of complex TS objects that would be a breaking change.

Alternative

No response

Additional context

In the past I created earl which takes this idea to extreme: https://github.com/l2beat/earl#example

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[AriPerkkio]

Is this essentially same as #2883?

[krzkaczor]

#2883 is a little bit different because it's about type narrowing ie. changing a type of a variable after a given statement, in this example ensuring that something is truthy. From my experience with earl this is really hard with expect style API, on the other hand, having type-safe assertions is doable.

In the original issue I mention only toBe and toEqual cases but you can imagine this working for all different matchers.

expect(false).toBeTruthy(); // type error because false is can never be truthy

[AriPerkkio]

While this could definitely be nice in some cases, it could also make tests hard to work on. Discussion from earlier mentioned Bun: oven-sh/bun#6934

This could likely be solved by third party package that overwrites the typings to more strict ones. Making the built-in default ones strict would break Jest compatibility as well.