How to create a libdef for something that extend's Jest's 'expect' global?

Jest provides expect.extend, which lets you add custom extensions to its expect global.

A library called expect-puppeteer uses this feature to add new assertions useful for integration testing with Puppeteer, like expect(page).toClick(...).

But this causes Flow to complain that .toClick is not a thing. Flow knows the return value of expect() is a JestExpectType object (because of the Jest libdef), which means you can do things like expect(x).toBeDefined() and Flow understands it. But any custom extensions don’t work.

So I want to write a new libdef for expect-puppeteer (or possibly its parent jest-puppeteer) that somehow augments the expect global that’s originally declared by the Jest libdef.

Is this possible? If the same global (expect) is declared in two different libdefs, is there some way to merge them? Or would I need to redeclare everything that already gets declared by the Jest libdef?

[callumlocke]

The enzyme plugin does the same thing (augmenting the global expect), and I’ve just noticed something.

The enzyme type definitions are simply bundled into the Jest definition (along with those of another plugin I haven’t heard of called dom-testing-library).

Are flow-typed maintainers aware of this pattern? The downsides I can see are:

• These plugin-added types will apply to anyone using Jest, even people who don’t use these plugins. So their Flow autocomplete will suggest methods they can’t use.
• Two plugins might add expectation methods with the same name but clashing type signatures.
• This pattern makes some plugins ‘first class’ without any clear criteria

[pascalduez]

Dupe of #948