Add support for TypeScript's Assertion Functions

🚀 Feature Proposal

Originally posted at: https://github.com/facebook/jest/issues/9146

Support TypeScript 3.7's new assertion functions.

Motivation

Jest should support this TypeScript language feature to make authoring tests simpler.

Example

Let's say I have a function under test that returns a nullable value:

export interface Data {
  anotherCoolProp: any
  somethingNeat: any
}

export function gimmeData(): Data | null {
  // Implementation details
  // ...
}

Currently, testing the results requires null checks for every assertion:

test('gimme that data', () => {
  const data = gimmeData()

  expect(data).toBeTruthy()

  expect(data!.anotherCoolProp).toEqual('coolio')
  expect(data!.somethingNeat).toEqual('neato')
})

// or:
test('gimme that data', () => {
  const data = gimmeData()

  if (!data) {
    throw new Error('Expected data to be non-null')
  }

  expect(data.anotherCoolProp).toEqual('coolio')
  expect(data.somethingNeat).toEqual('neato')
})

The first uses the ! non-null operator, which opts out of type safety and can lead to confusing error reports. The second seems non-idiomatic: why not write expect(data).toBeTruthy()?

With TypeScript 3.7 you can now define Jest's global expect to behave this way:

declare function <T>expect(value: T): asserts value is NonNullable<T>

(Although typing w/ the Jest's chaining will be a bit more involved.)

Lots of people have worked on these types, but I will start with @sandersn to see what he thinks about this.

Start by reading Jest's global expect typing and the linked TypeScript 3.7 assertion-functions release notes. Compare the requested narrowing behavior with Jest's chained expect typing; done means nullable values narrow after expect(data).toBeTruthy() while chaining remains correctly typed. The issue names no file or test, so locate the relevant DefinitelyTyped Jest declaration and type tests first.