fix(jest-environment-puppeteer): Class & Exports (#37647)

* fix(jest-environment-puppeteer): Class & Exports

This makes the typings actually compatible to create your own test
environment and not just as part of the bigger jest-puppeteer package.
How to do this is pretty much what the test covers. One of the reasons
to do this is to write a handler where Puppeteer takes screenshots after
each failed test, as discussed [here](argos-ci/jest-puppeteer#131)

* Change to `export =` syntax

Co-Authored-By: Pranav Senthilnathan <pranav.senthilnathan@live.com>

* Fix the last stuff requested

types/jest-environment-puppeteer/index.d.ts

@@ -2,10 +2,16 @@
 // Project: https://github.com/smooth-code/jest-puppeteer/tree/master/packages/jest-environment-puppeteer
 // Definitions by: Josh Goldberg <https://github.com/joshuakgoldberg>
 //                 Ifiok Jr. <https://github.com/ifiokjr>
+//                 Jeroen Claassens <https://github.com/favna>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// TypeScript Version: 2.8
+// TypeScript Version: 3.4
 
+import { JestEnvironment } from '@jest/environment';
+import { JestFakeTimers as FakeTimers } from '@jest/fake-timers';
+import { Circus, Global as GlobalType, Config } from '@jest/types';
+import { ModuleMocker } from 'jest-mock';
 import { Browser, Page, BrowserContext } from 'puppeteer';
+import { Script, Context } from 'vm';
 
 interface JestPuppeteer {
     /**
@@ -44,11 +50,47 @@ interface JestPuppeteer {
     debug(): Promise<void>;
 }
 
+interface Timer {
+    id: number;
+    ref: () => Timer;
+    unref: () => Timer;
+}
+
+interface Global extends GlobalType.Global {
+    browser: Browser;
+    context: Context;
+    page: Page;
+    jestPuppeteer: JestPuppeteer;
+}
+
+/** Note: TestEnvironment is sandboxed. Each test suite will trigger setup/teardown in their own TestEnvironment. */
+declare class PuppeteerEnvironment implements JestEnvironment {
+  context: Context | null;
+  fakeTimers: FakeTimers<Timer> | null;
+  global: Global;
+  moduleMocker: ModuleMocker | null;
+  constructor(config: Config.ProjectConfig);
+
+  /**
+   * Setup runs when the environment is being spun up, generally before each test suite
+   * You should always call `await super.setup()` in here
+   */
+  setup(): Promise<void>;
+
+  /**
+   * Teardowns runs as the environment is being torn down, generally after each test suite.
+   * You should always call `await super.tearDown()` in here
+   */
+  teardown(): Promise<void>;
+  runScript(script: Script): any;
+  handleTestEvent?(event: Circus.Event, state: Circus.State): void;
+}
+
 declare global {
     const browser: Browser;
     const context: BrowserContext;
     const page: Page;
     const jestPuppeteer: JestPuppeteer;
 }
 
-export {};
+export = PuppeteerEnvironment;

types/jest-environment-puppeteer/jest-environment-puppeteer-tests.ts

@@ -1,8 +1,42 @@
-import * as puppeteer from "puppeteer";
+import { Browser, Page, BrowserContext } from 'puppeteer';
+import JestEnvironmentPuppeteer from 'jest-environment-puppeteer';
+import { Config, Circus } from '@jest/types';
+import { Script } from 'vm';
 
-const myBrowser: puppeteer.Browser = browser;
-const myPage: puppeteer.Page = page;
-const myContext: puppeteer.BrowserContext = context;
+const myBrowser: Browser = browser; // $ExpectType Browser
+const myPage: Page = page; // $ExpectType Page
+const myContext: BrowserContext = context; // $ExpectType BrowserContext
 
 jestPuppeteer.debug();
 jestPuppeteer.resetPage();
+
+// Creating a custom Jest environment
+class CustomJestEnvironment extends JestEnvironmentPuppeteer {
+    constructor(config: Config.ProjectConfig) {
+        super(config);
+    }
+
+    async setup() {
+        await super.setup();
+        await this.global.page.goto('https://www.google.com');
+    }
+
+    async teardown() {
+        await this.global.page.waitFor(2000);
+        await super.teardown();
+    }
+
+    runScript(script: Script) {
+        return super.runScript(script);
+    }
+
+    async handleTestEvent(event: Circus.Event, state: Circus.State) {
+        if (event.name === 'test_fn_failure') {
+            console.error('woaw your test failed, you should feel bad!');
+        }
+    }
+}
+
+type JestEnvironmentPuppeteerGlobal = JestEnvironmentPuppeteer['global']; // $ExpectType Global
+type JestEnvironmentPuppeteerGlobalPuppeteer = JestEnvironmentPuppeteer['global']['jestPuppeteer']; // $ExpectType JestPuppeteer
+type JestEnvironmentPuppeteerFakeTimers = JestEnvironmentPuppeteer['fakeTimers']; // $ExpectType FakeTimers<Timer> | null

types/jest-environment-puppeteer/package.json

@@ -0,0 +1,9 @@
+{
+    "private": true,
+    "dependencies": {
+        "@jest/environment": "^24",
+        "@jest/fake-timers": "^24",
+        "@jest/types": "^24",
+        "jest-mock": "^24"
+    }
+}

types/jest-environment-puppeteer/tsconfig.json

@@ -15,7 +15,8 @@
         ],
         "types": [],
         "noEmit": true,
-        "forceConsistentCasingInFileNames": true
+        "forceConsistentCasingInFileNames": true,
+        "esModuleInterop": true
     },
     "files": [
         "index.d.ts",