[Feature]: typesafe assertions

[DetachHead]

🚀 Feature Proposal

this will always fail, but since typescript infers the type as unknown, there's no compile error:

expect('foo').toBe(1) // no error
expect<string>('foo').toBe(1) // no error

Motivation

it will allow you to identify errors in your tests much earlier, speeding up development 🚀🚀🚀

Example

// the new and improved expect 🚀:
declare const expect: <T>(actual: T) => { toBe: (expected: T) => void}

// usage:
expect('foo').toBe(1) // TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

Pitch

the current expect types make using typescript with jest pretty much useless. i think if jest is going to support typescript, it should support basic functionality like this

[mrazauskas]

Fix it. Just open a PR (;

[SimenB]

Would love toBe to work as type predicate 👍 Not sure how feasible it is, tho

[jesrodri]

Hi, can I try this?

[SimenB]

Yeah, go for it!

[jesrodri]

Hey guys!

I'm facing a problem here.
I've made the following changes in /jest/packages/expect/src/types.ts:

export type Expect = { <T = unknown>(actual: T): Matchers<void, T> & Inverse<Matchers<void, T>> & PromiseMatchers<T>; } & BaseExpect & AsymmetricMatchers & Inverse<Omit<AsymmetricMatchers, 'any' | 'anything'>>;
...
export interface Matchers<R extends void | Promise<void>, E = unknown>
...
toBe(expected: E): R;

and when I test in a local app using
import { type Expect } from '.../jest/packages/expect/build/index';
declare const expect:Expect;
...
expect(1).toBe('1');

it works fine and TypeScript gives me the error Argument of type 'string' is not assignable to parameter of type 'number'.ts(2345) as expected.

But when I add the same assertion to the /jest/examples/typescript/__tests__/calc.test.ts file, TypeScript keeps its current behavior and doesn't identify the type error. It keeps getting unkown as the type of Matchers:
(alias) expect<number>(actual: number): Matchers<void, unknown> & SnapshotMatchers<void, number> & Inverse<JestMatchers<void, number>> & PromiseMatchers<...>

Does anyone know what could be happening here?

[jesrodri]

here is git diff from /jest/packages/expect/src/types.ts

index e2fc97916..d7d6f7cfd 100644
--- a/packages/expect/src/types.ts
+++ b/packages/expect/src/types.ts
@@ -94,9 +94,9 @@ export interface BaseExpect {
 }
 
 export type Expect = {
-  <T = unknown>(actual: T): Matchers<void> &
-    Inverse<Matchers<void>> &
-    PromiseMatchers;
+  <T = unknown>(actual: T): Matchers<void, T> &
+    Inverse<Matchers<void, T>> &
+    PromiseMatchers<T>;
 } & BaseExpect &
   AsymmetricMatchers &
   Inverse<Omit<AsymmetricMatchers, 'any' | 'anything'>>;
@@ -118,20 +118,20 @@ export interface AsymmetricMatchers {
   stringMatching(sample: string | RegExp): AsymmetricMatcher;
 }
 
-type PromiseMatchers = {
+type PromiseMatchers<E = unknown> = {
   /**
    * Unwraps the reason of a rejected promise so any other matcher can be chained.
    * If the promise is fulfilled the assertion fails.
    */
-  rejects: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>>>;
+  rejects: Matchers<Promise<void>, E> & Inverse<Matchers<Promise<void>, E>>;
   /**
    * Unwraps the value of a fulfilled promise so any other matcher can be chained.
    * If the promise is rejected the assertion fails.
    */
-  resolves: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>>>;
+  resolves: Matchers<Promise<void>, E> & Inverse<Matchers<Promise<void>, E>>;
 };
 
-export interface Matchers<R extends void | Promise<void>> {
+export interface Matchers<R extends void | Promise<void>, E = unknown> {
   /**
    * Ensures the last call to a mock function was provided specific args.
    */
@@ -152,7 +152,7 @@ export interface Matchers<R extends void | Promise<void>> {
    * Checks that a value is what you expect. It calls `Object.is` to compare values.
    * Don't use `toBe` with floating-point numbers.
    */
-  toBe(expected: unknown): R;
+  toBe(expected: E): R;
   /**
    * Ensures that a mock function is called.
    */

[mrazauskas]

Most probably you should build the repo and all will work.

By the way, to test the change you should write type tests. The type tests for matchers live here: packages/jest-types/typetests/expect.test.ts

To run them, build the repo and run yarn test-types. Remember to rebuild after making changes.

---

One use case which looks problematic: expect('abc').not.toBe(123). I mean, the .not modifier is a problem. It would be possible to pass unknown to the inverse matchers as a type of received value. That solves the case, but why not to provide a mechanism of type safety for the inverse matchers as well?

For example, here is what @types/jest does: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/3fa56f312fa13d9546ba1745026ee009991bd3c8/types/jest/index.d.ts#L813

Usage example:

expect('abc').toBe<string>('abc');
expect('abc').not.toBe<number>(123);

This approach works for many other matchers too (just look through @types/jest code).

Is it really useful? Is it worth to spend time implementing? These are other questions.

[DetachHead]

Is it really useful? Is it worth to spend time implementing? These are other questions.

i can't really think of a use case where you'd want to explicitly specify the generics for non-matching types as i can't see how it provides any additional safety. imo in those cases using unknown is fine

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[DetachHead]

not stale