From 498b2d7ca006b4254cfae2d51b7adf2ac451e79d Mon Sep 17 00:00:00 2001
From: Max Schmitt <max@schmitt.mx>
Date: Mon, 21 Jun 2021 19:56:30 +0200
Subject: [PATCH] docs(test-runner): added JSDoc hints to code snippets (#7226)

---
 docs/src/intro-js.md           |  6 ++++-
 docs/src/pom.md                |  3 +++
 docs/src/test-advanced.md      | 20 +++++++++-----
 docs/src/test-configuration.md | 27 ++++++++++++++++---
 docs/src/test-intro.md         |  6 ++++-
 docs/src/test-parallel.md      |  7 ++++-
 docs/src/test-pom.md           |  3 +++
 docs/src/test-reporters.md     | 49 +++++++++++++++++++++++++++++-----
 docs/src/test-retries.md       |  7 ++++-
 9 files changed, 107 insertions(+), 21 deletions(-)

diff --git a/docs/src/intro-js.md b/docs/src/intro-js.md
index 0280cd53b4..5159805b17 100644
--- a/docs/src/intro-js.md
+++ b/docs/src/intro-js.md
@@ -369,9 +369,11 @@ Create `playwright.config.ts` (or `playwright.config.js`) to configure your test
 
 ```js js-flavor=js
 // playwright.config.js
+// @ts-check
 const { devices } = require('@playwright/test');
 
-module.exports = {
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   projects: [
     {
       name: 'Desktop Chromium',
@@ -406,6 +408,8 @@ module.exports = {
     },
   ],
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
diff --git a/docs/src/pom.md b/docs/src/pom.md
index 194f722f51..575ab16fa4 100644
--- a/docs/src/pom.md
+++ b/docs/src/pom.md
@@ -25,6 +25,9 @@ Page object models wrap over a Playwright [Page].
 ```js
 // models/Search.js
 class SearchPage {
+  /**
+   * @param {import('playwright').Page} page 
+   */
   constructor(page) {
     this.page = page;
   }
diff --git a/docs/src/test-advanced.md b/docs/src/test-advanced.md
index 0053f154cb..8d536ec6fd 100644
--- a/docs/src/test-advanced.md
+++ b/docs/src/test-advanced.md
@@ -64,7 +64,7 @@ const http = require('http');
 
 // Note how we mark the fixture as { scope: 'worker' }.
 // Also note that we pass empty {} first, since we do not declare any test fixtures.
-exports.test = base.test.extend<{}, { server: http.Server }>({
+exports.test = base.test.extend({
   server: [ async ({}, use, workerInfo) => {
     // Start the server.
     const server = http.createServer();
@@ -164,7 +164,7 @@ const base = require('@playwright/test');
 
 // Note how we mark the fixture as { auto: true }.
 // This way it is always instantiated, even if the test does not use it explicitly.
-exports.test = base.test.extend<{ saveLogs: void }>({
+exports.test = base.test.extend({
   saveLogs: [ async ({}, use, testInfo) => {
     const logs = [];
     debug.log = (...args) => logs.push(args.map(String).join(''));
@@ -249,9 +249,12 @@ Now add `globalSetup` option to the configuration file.
 
 ```js js-flavor=js
 // playwright.config.js
-module.export = {
+// @ts-check
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   globalSetup: require.resolve('./global-setup'),
 };
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -295,7 +298,7 @@ To make use of this feature, we will declare an "option fixture" for the backend
 const base = require('@playwright/test');
 const { startBackend } = require('./my-backend');
 
-exports.test = base.test.extend<{ version: string, backendUrl: string }>({
+exports.test = base.test.extend({
   // Default value for the version.
   version: '1.0',
 
@@ -364,7 +367,10 @@ test('test 2', async ({ version, page, backendUrl }) => {
 Now, we can run test in multiple configurations by using projects.
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   timeout: 20000,
   projects: [
     {
@@ -377,6 +383,8 @@ module.exports = {
     },
   ]
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -420,7 +428,7 @@ In this example we add a custom `toBeWithinRange` function in the configuration
 const { expect } = require('@playwright/test');
 
 expect.extend({
-  toBeWithinRange(received: number, floor: number, ceiling: number) {
+  toBeWithinRange(received, floor, ceiling) {
     const pass = received >= floor && received <= ceiling;
     if (pass) {
       return {
diff --git a/docs/src/test-configuration.md b/docs/src/test-configuration.md
index 6485a45fea..bc3f254607 100644
--- a/docs/src/test-configuration.md
+++ b/docs/src/test-configuration.md
@@ -34,7 +34,10 @@ You can specify any options either locally in a test file, or globally in the co
 Create `playwright.config.js` (or `playwright.config.ts`) and specify options in the `use` section.
 
 ```js js-flavor=js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   use: {
     // Browser options
     headless: false,
@@ -50,6 +53,8 @@ module.exports = {
     video: 'on-first-retry',
   },
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -162,7 +167,10 @@ You can specify these options in the configuration file.
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   // Look for test files in the "tests" directory, relative to this configuration file
   testDir: 'tests',
 
@@ -182,6 +190,8 @@ module.exports = {
     // Configure browser and context here
   },
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -217,7 +227,10 @@ To specify different options per browser, for example command line arguments for
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   // Put any shared options on the top level.
   use: {
     headless: true,
@@ -246,6 +259,8 @@ module.exports = {
     },
   ],
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -324,9 +339,11 @@ Here is an example configuration that runs tests in "Pixel 4" and "iPhone 11" em
 
 ```js js-flavor=js
 // playwright.config.js
+// @ts-check
 const { devices } = require('playwright');
 
-module.exports = {
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   projects: [
     // "Pixel 4" tests use Chromium browser.
     {
@@ -347,6 +364,8 @@ module.exports = {
     },
   ],
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
diff --git a/docs/src/test-intro.md b/docs/src/test-intro.md
index 158a886929..6eac614bdc 100644
--- a/docs/src/test-intro.md
+++ b/docs/src/test-intro.md
@@ -367,9 +367,11 @@ Create `playwright.config.ts` (or `playwright.config.js`) to configure your test
 
 ```js js-flavor=js
 // playwright.config.js
+// @ts-check
 const { devices } = require('@playwright/test');
 
-module.exports = {
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   projects: [
     {
       name: 'Desktop Chromium',
@@ -404,6 +406,8 @@ module.exports = {
     },
   ],
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
diff --git a/docs/src/test-parallel.md b/docs/src/test-parallel.md
index 2c474c8222..63fce51647 100644
--- a/docs/src/test-parallel.md
+++ b/docs/src/test-parallel.md
@@ -33,10 +33,15 @@ You can control the maximum number of parallel worker processes via [command lin
 - In the configuration file
   ```js js-flavor=js
   // playwright.config.js
-  module.exports = {
+  // @ts-check
+
+  /** @type {import('@playwright/test').PlaywrightTestConfig} */
+  const config = {
     // Limit the number of workers on CI, use default locally
     workers: process.env.CI ? 2 : undefined,
   };
+
+  module.exports = config;
   ```
 
   ```js js-flavor=ts
diff --git a/docs/src/test-pom.md b/docs/src/test-pom.md
index e9ba7945df..2130947372 100644
--- a/docs/src/test-pom.md
+++ b/docs/src/test-pom.md
@@ -10,6 +10,9 @@ We will create a `PlaywrightDevPage` helper class to encapsulate common operatio
 ```js js-flavor=js
 // playwright-dev-page.js
 exports.PlaywrightDevPage = class PlaywrightDevPage {
+  /**
+   * @param {import('playwright').Page} page 
+   */
   constructor(page) {
     this.page = page;
   }
diff --git a/docs/src/test-reporters.md b/docs/src/test-reporters.md
index 57e0e1fe35..0f794adaa3 100644
--- a/docs/src/test-reporters.md
+++ b/docs/src/test-reporters.md
@@ -18,9 +18,14 @@ For more control, you can specify reporters programmatically in the [configurati
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   reporter: 'line',
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -37,7 +42,10 @@ You can use different reporters locally and on CI.
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   reporter: !process.env.CI
     // Default 'list' reporter for the terminal
     ? 'list'
@@ -46,6 +54,8 @@ module.exports = {
     // - comprehensive json report
     : [ ['dot'], [ 'json', {  outputFile: 'test-results.json' }] ],
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -78,9 +88,14 @@ npx playwright test --reporter=list
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   reporter: 'list',
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -120,9 +135,14 @@ npx playwright test --reporter=line
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   reporter: 'line',
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -159,9 +179,14 @@ npx playwright test --reporter=dot
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   reporter: 'dot',
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -193,9 +218,14 @@ PLAYWRIGHT_JSON_OUTPUT_NAME=results.json npx playwright test --reporter=json,dot
 In configuration file, pass options directly:
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   reporter: [ ['json', { outputFile: 'results.json' }] ],
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
@@ -220,9 +250,14 @@ PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junit,li
 In configuration file, pass options directly:
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   reporter: [ ['junit', { outputFile: 'results.xml' }] ],
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts
diff --git a/docs/src/test-retries.md b/docs/src/test-retries.md
index bcafd83fb1..62da755f6b 100644
--- a/docs/src/test-retries.md
+++ b/docs/src/test-retries.md
@@ -11,9 +11,14 @@ npx playwright test --retries=3
 
 ```js js-flavor=js
 // playwright.config.js
-module.exports = {
+// @ts-check
+
+/** @type {import('@playwright/test').PlaywrightTestConfig} */
+const config = {
   retries: 3,
 };
+
+module.exports = config;
 ```
 
 ```js js-flavor=ts