feat(types): generate JSDoc for things like test.describe.only (#8663)

types/test.d.ts

@@ -1573,9 +1573,97 @@ export interface TestType<TestArgs extends KeyValue, WorkerArgs extends KeyValue
    * callback will belong to the group.
    */
   describe: SuiteFunction & {
-    only: SuiteFunction;
+    /**
-    serial: SuiteFunction & {
+   * Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing else.
-      only: SuiteFunction;
+   *
+   * ```js js-flavor=js
+   * test.describe.only('focused group', () => {
+   *   test('in the focused group', async ({ page }) => {
+   *     // This test will run
+   *   });
+   * });
+   * test('not in the focused group', async ({ page }) => {
+   *   // This test will not run
+   * });
+   * ```
+   *
+   * ```js js-flavor=ts
+   * test.describe.only('focused group', () => {
+   *   test('in the focused group', async ({ page }) => {
+   *     // This test will run
+   *   });
+   * });
+   * test('not in the focused group', async ({ page }) => {
+   *   // This test will not run
+   * });
+   * ```
+   *
+   * @param title Group title.
+   * @param callback A callback that is run immediately when calling [test.describe.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-only). Any tests added in
+   * this callback will belong to the group.
+   */
+  only: SuiteFunction;
+    /**
+   * Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are
+   * skipped. All tests in a group are retried together.
+   *
+   * > NOTE: Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
+   * independently.
+   *
+   * ```js js-flavor=js
+   * test.describe.serial('group', () => {
+   *   test('runs first', async ({ page }) => {
+   *   });
+   *   test('runs second', async ({ page }) => {
+   *   });
+   * });
+   * ```
+   *
+   * ```js js-flavor=ts
+   * test.describe.serial('group', () => {
+   *   test('runs first', async ({ page }) => {
+   *   });
+   *   test('runs second', async ({ page }) => {
+   *   });
+   * });
+   * ```
+   *
+   * @param title Group title.
+   * @param callback A callback that is run immediately when calling [test.describe.serial(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-serial). Any tests
+   * added in this callback will belong to the group.
+   */
+  serial: SuiteFunction & {
+      /**
+   * Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent tests
+   * are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of them will be
+   * run but nothing else.
+   *
+   * > NOTE: Using serial is not recommended. It is usually better to make your tests isolated, so they can be run
+   * independently.
+   *
+   * ```js js-flavor=js
+   * test.describe.serial.only('group', () => {
+   *   test('runs first', async ({ page }) => {
+   *   });
+   *   test('runs second', async ({ page }) => {
+   *   });
+   * });
+   * ```
+   *
+   * ```js js-flavor=ts
+   * test.describe.serial.only('group', () => {
+   *   test('runs first', async ({ page }) => {
+   *   });
+   *   test('runs second', async ({ page }) => {
+   *   });
+   * });
+   * ```
+   *
+   * @param title Group title.
+   * @param callback A callback that is run immediately when calling [test.describe.serial.only(title, callback)](https://playwright.dev/docs/api/class-test#test-describe-serial-only). Any
+   * tests added in this callback will belong to the group.
+   */
+  only: SuiteFunction;
     };
   };
   /**

utils/generate_types/parseOverrides.js

@@ -85,6 +85,8 @@ async function parseOverrides(filePath, commentForClass, commentForMethod, extra
           pos,
           text: commentForMethod(className, name, index),
         });
+        if (ts.isPropertySignature(declaration))
+          ts.forEachChild(declaration, child => visitProperties(className, name, child));
       }
     }
     replacers.push({
@@ -93,6 +95,27 @@ async function parseOverrides(filePath, commentForClass, commentForMethod, extra
     });
   }
 
+  /**
+   * @param {string} className
+   * @param {string} prefix
+   * @param {ts.Node} node
+   */
+  function visitProperties(className, prefix, node) {
+    // This function supports structs like "a: { b: string; c: number }"
+    // and inserts comments for "a.b" and "a.c"
+    if (ts.isPropertySignature(node)) {
+      const name = checker.getSymbolAtLocation(node.name).getName();
+      const pos = node.getStart(file, false);
+      replacers.push({
+        pos,
+        text: commentForMethod(className, `${prefix}.${name}`, 0),
+      });
+      ts.forEachChild(node, child => visitProperties(className, `${prefix}.${name}`, child));
+    } else if (!ts.isMethodSignature(node)) {
+      ts.forEachChild(node, child => visitProperties(className, prefix, child));
+    }
+  }
+
 }
 
 module.exports = {parseOverrides};