chore(tests): add types for tests (#915)

I enabled vscode autocomplete in our test files. Typechecking had too many errors to enable, but it caught some real bugs that I will fix in a follow up.

This patch contains:
* `test/types.d.ts` - d.ts file for our test runner.
* `test/tsconfig.json` - typescript project for our tests.
* JSDoc header in all specs to mark the describe as a TestSuite
* Drive-by fix of a launcher test that was using `if` instead of `it`
* Some drive-by fixes of unimpactful typos in tests.

test/accessibility.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT, MAC}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/browser.spec.js

@@ -16,6 +16,9 @@
 
 const utils = require('./utils');
 
+/**
+ * @type {BrowserTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/browsercontext.spec.js

@@ -17,6 +17,9 @@
 
 const utils = require('./utils');
 
+/**
+ * @type {BrowserTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/capabilities.spec.js

@@ -17,6 +17,9 @@
 const utils = require('./utils');
 const { waitEvent } = utils;
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, WIN, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/chromium.spec.js

@@ -16,6 +16,9 @@
 
 const { waitEvent } = require('../utils');
 
+/**
+ * @type {ChromiumTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/coverage.spec.js

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {ChromiumTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/headful.spec.js

@@ -24,6 +24,9 @@ const mkdtempAsync = util.promisify(fs.mkdtemp);
 
 const TMP_FOLDER = path.join(os.tmpdir(), 'pw_tmp_folder-');
 
+/**
+ * @type {TestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, defaultBrowserOptions, FFOX, CHROMIUM, WEBKIT, WIN}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/launcher.spec.js

@@ -25,6 +25,9 @@ const statAsync = util.promisify(fs.stat);
 
 const TMP_FOLDER = path.join(os.tmpdir(), 'pw_tmp_folder-');
 
+/**
+ * @type {TestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, WIN}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/oopif.spec.js

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {ChromiumTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/pdf.spec.js

@@ -17,6 +17,9 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * @type {ChromiumTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, headless, ASSETS_DIR}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/session.spec.js

@@ -16,6 +16,9 @@
 
 const { waitEvent } = require('../utils');
 
+/**
+ * @type {ChromiumTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/chromium/tracing.spec.js

@@ -17,6 +17,9 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * @type {ChromiumTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, ASSETS_DIR}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/click.spec.js

@@ -17,6 +17,9 @@
 
 const utils = require('./utils');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/cookies.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, defaultBrowserOptions, MAC, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/defaultbrowsercontext.spec.js

@@ -17,6 +17,9 @@
 
 const { makeUserDataDir, removeUserDataDir } = require('./utils');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function ({ testRunner, expect, defaultBrowserOptions, playwright }) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/dialog.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/elementhandle.spec.js

@@ -17,6 +17,9 @@
 
 const utils = require('./utils');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/emulation.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/evaluation.spec.js

@@ -19,6 +19,9 @@ const utils = require('./utils');
 
 const bigint = typeof BigInt !== 'undefined';
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/features/permissions.spec.js

@@ -18,6 +18,9 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/fixtures.spec.js

@@ -18,6 +18,9 @@
 const path = require('path');
 const {spawn, execSync} = require('child_process');
 
+/**
+ * @type {TestSuite}
+ */
 module.exports.describe = function({testRunner, expect, product, playwright, playwrightPath, defaultBrowserOptions, WIN, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/frame.spec.js

@@ -17,6 +17,9 @@
 
 const utils = require('./utils');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/geolocation.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function ({ testRunner, expect, FFOX, WEBKIT }) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/headful.spec.js

@@ -16,6 +16,9 @@
 
 const { makeUserDataDir, removeUserDataDir } = require('./utils');
 
+/**
+ * @type {TestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, defaultBrowserOptions, FFOX, CHROMIUM, WEBKIT, WIN}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/ignorehttpserrors.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {BrowserTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/input.spec.js

@@ -21,6 +21,9 @@ const formidable = require('formidable');
 
 const FILE_TO_UPLOAD = path.join(__dirname, '/assets/file-to-upload.txt');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/interception.spec.js

@@ -20,6 +20,9 @@ const path = require('path');
 const { helper } = require('../lib/helper');
 const utils = require('./utils');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/jshandle.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, CHROMIUM, FFOX, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/keyboard.spec.js

@@ -18,6 +18,9 @@
 const utils = require('./utils');
 const os = require('os');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT, MAC}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/launcher.spec.js

@@ -20,6 +20,9 @@ const fs = require('fs');
 const utils = require('./utils');
 const { makeUserDataDir, removeUserDataDir } = require('./utils');
 
+/**
+ * @type {TestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, playwrightPath, product, CHROMIUM, FFOX, WEBKIT, WIN}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;
@@ -42,7 +45,7 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
         await playwright.launch(options).catch(e => waitError = e);
         expect(waitError.message).toContain('Failed to launch');
       });
-      if('should have default URL when launching browser', async function() {
+      it('should have default URL when launching browser', async function() {
         const userDataDir = await makeUserDataDir();
         const browserContext = await playwright.launchPersistent(userDataDir, defaultBrowserOptions);
         const pages = (await browserContext.pages()).map(page => page.url());
@@ -172,7 +175,7 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
   });
 
   describe('Browser.close', function() {
-    it('should terminate network waiters', async({context, server}) => {
+    it('should terminate network waiters', async({server}) => {
       const browserServer = await playwright.launchServer({...defaultBrowserOptions });
       const remote = await playwright.connect({ wsEndpoint: browserServer.wsEndpoint() });
       const newPage = await remote.newPage();

test/mouse.spec.js

@@ -26,6 +26,9 @@ function dimensions() {
   };
 }
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT, MAC}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/multiclient.spec.js

@@ -17,6 +17,9 @@
 
 const utils = require('./utils');
 
+/**
+ * @type {TestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/navigation.spec.js

@@ -18,6 +18,9 @@
 const utils = require('./utils');
 const { performance } = require('perf_hooks');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, playwright, MAC, WIN, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/network.spec.js

@@ -19,6 +19,9 @@ const fs = require('fs');
 const path = require('path');
 const utils = require('./utils');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, MAC, WIN, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/page.spec.js

@@ -19,6 +19,9 @@ const path = require('path');
 const utils = require('./utils');
 const {waitEvent} = utils;
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, headless, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/playwright.spec.js

@@ -24,6 +24,9 @@ const {Matchers} = require('../utils/testrunner/');
 const YELLOW_COLOR = '\x1b[33m';
 const RESET_COLOR = '\x1b[0m';
 
+/**
+ * @type {TestSuite}
+ */
 module.exports.describe = ({testRunner, product, playwrightPath}) => {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/queryselector.spec.js

@@ -17,6 +17,9 @@
 
 const zsSelectorEngineSource = require('../lib/generated/zsSelectorEngineSource');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, selectors, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;
@@ -236,7 +239,7 @@ module.exports.describe = function({testRunner, expect, selectors, FFOX, CHROMIU
       const element = await page.$$('//html/body/non-existing-element');
       expect(element).toEqual([]);
     });
-    it('should return multiple elements', async({page, sever}) => {
+    it('should return multiple elements', async({page, server}) => {
       await page.setContent('<div></div><div></div>');
       const elements = await page.$$('xpath=/html/body/div');
       expect(elements.length).toBe(2);

test/screenshot.spec.js

@@ -15,6 +15,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, product, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "compilerOptions": {
+        "allowJs": true,
+        "checkJs": false,
+        "noEmit": true,
+        "moduleResolution": "node",
+        "target": "ESNext",
+        "strictNullChecks": false,
+    },
+    "include": ["*.spec.js", "types.d.ts"]
+  }

test/types.d.ts

@@ -0,0 +1,103 @@
+type ServerResponse = import('http').ServerResponse;
+type IncomingMessage = import('http').IncomingMessage;
+
+type Falsy = false|""|0|null|undefined;
+interface Expect<T> {
+    toBe(other: T, message?: string): void;
+    toBeFalsy(message?: string): void;
+    toBeTruthy(message?: string): void;
+    toContain(other: any, message?: string): void;
+    toEqual(other: T, message?: string): void;
+    toBeNull(message?: string): void;
+    toBeInstanceOf(other: Function, message?: string): void;
+
+    toBeGreaterThan(other: number, message?: string): void;
+    toBeGreaterThanOrEqual(other: number, message?: string): void;
+    toBeLessThan(other: number, message?: string): void;
+    toBeLessThanOrEqual(other: number, message?: string): void;
+    toBeCloseTo(other: number, precision: number, message?: string): void;
+
+    toBeGolden(path: string): void;
+
+    not: Expect<T>;
+}
+
+type DescribeFunction = ((name: string, inner: () => void) => void) & {skip(condition: boolean): DescribeFunction};
+
+type ItFunction<STATE> = ((name: string, inner: (state: STATE) => Promise<void>) => void) & {skip(condition: boolean): ItFunction<STATE>};
+
+type TestRunner<STATE> = {
+    describe: DescribeFunction;
+    xdescribe: DescribeFunction;
+    fdescribe: DescribeFunction;
+
+    it: ItFunction<STATE>;
+    xit: ItFunction<STATE>;
+    fit: ItFunction<STATE>;
+    dit: ItFunction<STATE>;
+
+    beforeAll, beforeEach, afterAll, afterEach, loadTests;
+};
+
+interface TestSetup<STATE> {
+    testRunner: TestRunner<STATE>;
+    product: 'Chromium'|'Firefox'|'WebKit';
+    FFOX: boolean;
+    WEBKIT: boolean;
+    CHROMIUM: boolean;
+    MAC: boolean;
+    LINUX: boolean;
+    WIN: boolean;
+    playwright: import('../src/server/browserType').BrowserType;
+    selectors: import('../src/selectors').Selectors;
+    expect<T>(value: T): Expect<T>;
+    defaultBrowserOptions: import('../src/server/browserType').LaunchOptions;
+    playwrightPath;
+    headless: boolean;
+    ASSETS_DIR: string;
+}
+
+type TestState = {
+    server: TestServer;
+    httpsServer: TestServer;
+    sourceServer: TestServer;
+};
+
+type BrowserState = TestState & {
+    browser: import('../src/browser').Browser;
+    browserServer: import('../src/server/browserServer').BrowserServer;
+    newPage: (options?: import('../src/browserContext').BrowserContextOptions) => Promise<import('../src/page').Page>;
+    newContext: (options?: import('../src/browserContext').BrowserContextOptions) => Promise<import('../src/browserContext').BrowserContext>;
+};
+
+type PageState = BrowserState & {
+    context: import('../src/browserContext').BrowserContext;
+    page: import('../src/page').Page;
+};
+type ChromiumPageState = PageState & {
+    browser: import('../src/chromium/crBrowser').CRBrowser;
+};
+type TestSuite = (setup: TestSetup<TestState>) => void;
+type BrowserTestSuite = (setup: TestSetup<BrowserState>) => void;
+type PageTestSuite = (setup: TestSetup<PageState>) => void;
+type ChromiumTestSuite = (setup: TestSetup<ChromiumPageState>) => void;
+
+
+interface TestServer {
+    enableHTTPCache(pathPrefix: string);
+    setAuth(path: string, username: string, password: string);
+    enableGzip(path: string);
+    setCSP(path: string, csp: string);
+    stop(): Promise<void>;
+    setRoute(path: string, handler: (message: IncomingMessage, response: ServerResponse) => void);
+    setRedirect(from: string, to: string);
+    waitForRequest(path: string): Promise<IncomingMessage>;
+    reset();
+    serveFile(request: IncomingMessage, response: ServerResponse, pathName: string);
+    
+    PORT: number;
+    PREFIX: string;
+    CROSS_PROCESS_PREFIX: string;
+    EMPTY_PAGE: string;
+  
+}

test/waittask.spec.js

@@ -17,6 +17,9 @@
 
 const utils = require('./utils');
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, product, playwright, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/web.spec.js

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, defaultBrowserOptions, playwright, product, CHROMIUM, FFOX}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/webkit/provisional.spec.js

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function ({ testRunner, expect }) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

test/workers.spec.js

@@ -18,6 +18,9 @@
 const utils = require('./utils');
 const { waitEvent } = utils;
 
+/**
+ * @type {PageTestSuite}
+ */
 module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT}) {
   const {describe, xdescribe, fdescribe} = testRunner;
   const {it, fit, xit, dit} = testRunner;

utils/testserver/index.js

@@ -28,7 +28,7 @@ class TestServer {
   /**
    * @param {string} dirPath
    * @param {number} port
-   * @return {!TestServer}
+   * @return {!Promise<TestServer>}
    */
   static async create(dirPath, port) {
     const server = new TestServer(dirPath, port);
@@ -39,7 +39,7 @@ class TestServer {
   /**
    * @param {string} dirPath
    * @param {number} port
-   * @return {!TestServer}
+   * @return {!Promise<TestServer>}
    */
   static async createHTTPS(dirPath, port) {
     const server = new TestServer(dirPath, port, {
@@ -70,7 +70,7 @@ class TestServer {
     this._startTime = new Date();
     this._cachedPathPrefix = null;
 
-    /** @type {!Set<!net.Socket>} */
+    /** @type {!Set<!NodeJS.Socket>} */
     this._sockets = new Set();
 
     /** @type {!Map<string, function(!IncomingMessage, !ServerResponse)>} */