feat(reporter): expose suite execution modes during preprocess (#43758)

Co-authored-by: microsoft-playwright-automation[bot] <203992400+microsoft-playwright-automation[bot]@users.noreply.github.com>

Author: microsoft-playwright-automation[bot]

docs/src/test-reporter-api/class-testrun.md

@@ -2,7 +2,7 @@
 * since: v1.62
 * langs: js
 
-Controls which tests will run and their expected status. A [TestRun] is available during [`method: Reporter.preprocess`]. Setup and teardown projects cannot be changed.
+Controls which tests will run and their expected status, and provides information about suite execution modes. A [TestRun] is available during [`method: Reporter.preprocess`]. Setup and teardown projects cannot be changed.
 
 ## method: TestRun.exclude
 * since: v1.62
@@ -49,6 +49,23 @@ Test or suite to mark as fixme.
 
 Optional explanation surfaced as the annotation description.
 
+## method: TestRun.mode
+* since: v1.65
+- returns: "TestMode" <"serial"|"parallel"|"default">
+
+Returns the execution mode configured for a suite with [`method: Test.describe.configure`], [`method: Test.describe.serial`] or [`method: Test.describe.parallel`].
+If the suite does not configure a mode, it inherits its parent's mode. Project suites use `"parallel"` when [`property: TestProject.fullyParallel`] is enabled, and `"default"` otherwise. The root suite uses `"default"`.
+
+An explicit `"default"` suite does not inherit `"parallel"` from its parent: its tests run in order in the same worker. The mode alone does not describe complete test groups, which also depend on worker fixtures and hooks.
+
+This method can only be called during [`method: Reporter.preprocess`], and can also inspect setup and teardown projects.
+
+### param: TestRun.mode.suite
+* since: v1.65
+- `suite` <[Suite]>
+
+Suite to inspect.
+
 ## method: TestRun.skip
 * since: v1.62
 

packages/playwright/src/runner/reporterTestRun.ts

@@ -34,6 +34,16 @@ export class ReporterTestRunImpl implements ReporterTestRun {
     return this._skipSharding;
   }
 
+  mode(suite: ReporterSuite): 'serial' | 'parallel' | 'default' {
+    if (!this._active)
+      throw new Error(`TestRun.mode() can only be called from Reporter.preprocess().`);
+    for (let current: testNs.Suite | undefined = suite as testNs.Suite; current; current = current.parent) {
+      if (current._parallelMode !== 'none')
+        return current._parallelMode;
+    }
+    return 'default';
+  }
+
   skipSharding() {
     if (!this._active)
       throw new Error(`TestRun.skipSharding() can only be called from Reporter.preprocess().`);

packages/playwright/types/testReporter.d.ts

@@ -752,8 +752,8 @@ export interface TestResult {
 }
 
 /**
- * Controls which tests will run and their expected status. A [TestRun](https://playwright.dev/docs/api/class-testrun)
- * is available during
+ * Controls which tests will run and their expected status, and provides information about suite execution modes. A
+ * [TestRun](https://playwright.dev/docs/api/class-testrun) is available during
  * [reporter.preprocess(params)](https://playwright.dev/docs/api/class-reporter#reporter-preprocess). Setup and
  * teardown projects cannot be changed.
  */
@@ -781,6 +781,26 @@ export interface TestRun {
    */
   fixme(test: TestCase|Suite, reason?: string): void;
 
+  /**
+   * Returns the execution mode configured for a suite with
+   * [test.describe.configure([options])](https://playwright.dev/docs/api/class-test#test-describe-configure),
+   * [test.describe.serial([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-serial)
+   * or
+   * [test.describe.parallel([title, details, callback])](https://playwright.dev/docs/api/class-test#test-describe-parallel).
+   * If the suite does not configure a mode, it inherits its parent's mode. Project suites use `"parallel"` when
+   * [testProject.fullyParallel](https://playwright.dev/docs/api/class-testproject#test-project-fully-parallel) is
+   * enabled, and `"default"` otherwise. The root suite uses `"default"`.
+   *
+   * An explicit `"default"` suite does not inherit `"parallel"` from its parent: its tests run in order in the same
+   * worker. The mode alone does not describe complete test groups, which also depend on worker fixtures and hooks.
+   *
+   * This method can only be called during
+   * [reporter.preprocess(params)](https://playwright.dev/docs/api/class-reporter#reporter-preprocess), and can also
+   * inspect setup and teardown projects.
+   * @param suite Suite to inspect.
+   */
+  mode(suite: Suite): "serial"|"parallel"|"default";
+
   /**
    * Skips a test or every test in a suite. The test bodies are not executed and the tests are reported as skipped.
    * @param test Test or suite to skip.

tests/playwright-test/reporter-preprocess.spec.ts

@@ -194,7 +194,7 @@ test('TestRun methods throw outside preprocess, and the root suite cannot be exc
           const testCase = suite.allTests()[0];
           const fileSuite = testCase.parent;
           for (const [label, obj] of [['TestCase', testCase], ['Suite', fileSuite]]) {
-            for (const method of ['skip', 'fixme', 'fail', 'exclude']) {
+            for (const method of ['skip', 'fixme', 'fail', 'exclude', ...(label === 'Suite' ? ['mode'] : [])]) {
               try {
                 this.testRun[method](obj);
                 console.log('%% ' + label + '.' + method + ': no-throw');
@@ -225,6 +225,7 @@ test('TestRun methods throw outside preprocess, and the root suite cannot be exc
     'Suite.fixme: TestRun.fixme() can only be called from Reporter.preprocess().',
     'Suite.fail: TestRun.fail() can only be called from Reporter.preprocess().',
     'Suite.exclude: TestRun.exclude() can only be called from Reporter.preprocess().',
+    'Suite.mode: TestRun.mode() can only be called from Reporter.preprocess().',
   ]);
 });
 
@@ -436,6 +437,8 @@ test('plan.suite exposes setup/teardown dependency projects but they are read-on
             }
           }
           const setupProject = suite.suites.find(s => s.title === 'setup');
+          console.log('%% setup mode: ' + testRun.mode(setupProject));
+          console.log('%% teardown mode: ' + testRun.mode(suite.suites.find(s => s.title === 'teardown')));
           try {
             testRun.exclude(setupProject);
             console.log('%% dep-suite-exclude: no-throw');
@@ -491,6 +494,8 @@ test('plan.suite exposes setup/teardown dependency projects but they are read-on
     'dep-fixme: TestRun.fixme() cannot be called on a setup or teardown project test; these always run in full.',
     'dep-fail: TestRun.fail() cannot be called on a setup or teardown project test; these always run in full.',
     'dep-exclude: TestRun.exclude() cannot be called on a setup or teardown project test; these always run in full.',
+    'setup mode: default',
+    'teardown mode: default',
     'dep-suite-exclude: TestRun.exclude() cannot be called on a setup or teardown project; these always run in full.',
     'same test objects: true',
     'dep-after-preprocess: TestRun.skip() can only be called from Reporter.preprocess().',
@@ -547,18 +552,29 @@ test('plan.suite temporarily exposes dependencies without changing final project
   ]);
 });
 
-test('serial suites expose a serial annotation for custom sharding', async ({ runInlineTest }) => {
+test('suite modes and serial annotations are available for custom sharding', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/43602' } }, async ({ runInlineTest }) => {
   const result = await runInlineTest({
     'reporter.ts': `
       class Reporter {
-        async preprocess({ suite }) {
+        async preprocess({ suite, testRun }) {
+          console.log('%% root:' + testRun.mode(suite));
+          for (const project of suite.suites) {
+            console.log('%% project ' + project.title + ':' + testRun.mode(project));
+            console.log('%% file ' + project.title + ':' + testRun.mode(project.suites[0]));
+          }
           for (const t of suite.allTests())
-            console.log('%% ' + t.title + ':' + t.annotations.filter(a => a.type === 'serial').length);
+            console.log('%% ' + t.parent.project().name + '/' + t.title + ':' + t.annotations.filter(a => a.type === 'serial').length + ':' + testRun.mode(t.parent));
         }
       }
       export default Reporter;
     `,
-    'playwright.config.ts': `export default { reporter: './reporter.ts' };`,
+    'playwright.config.ts': `
+      export default {
+        reporter: './reporter.ts',
+        fullyParallel: true,
+        projects: [{ name: 'parallel' }, { name: 'default', fullyParallel: false }],
+      };
+    `,
     'a.test.ts': `
       import { test } from '@playwright/test';
       test('plain', async () => {});
@@ -570,17 +586,43 @@ test('serial suites expose a serial annotation for custom sharding', async ({ ru
         test('configure', async () => {});
       });
       test.describe.serial('outer', () => {
+        test.describe('inherited serial', () => {
+          test('inherited-serial', async () => {});
+        });
         test.describe.serial('inner', () => {
           test('nested', async () => {});
         });
       });
+      test.describe.parallel('parallel', () => {
+        test.describe('inherited parallel', () => {
+          test('inherited-parallel', async () => {});
+        });
+        test.describe('default', () => {
+          test.describe.configure({ mode: 'default' });
+          test('default-one', async () => {});
+          test.describe('inherited default', () => {
+            test('default-two', async () => {});
+          });
+        });
+      });
     `,
   }, { reporter: '', workers: 1 });
   expect(result.exitCode).toBe(0);
   expect(result.outputLines).toEqual([
-    'plain:0',
-    'serial:1',
-    'configure:1',
-    'nested:2',
+    'root:default',
+    'project parallel:parallel',
+    'file parallel:parallel',
+    'project default:default',
+    'file default:default',
+    ...['parallel', 'default'].flatMap(project => [
+      project + '/plain:0:' + project,
+      project + '/serial:1:serial',
+      project + '/configure:1:serial',
+      project + '/inherited-serial:1:serial',
+      project + '/nested:2:serial',
+      project + '/inherited-parallel:0:parallel',
+      project + '/default-one:0:default',
+      project + '/default-two:0:default',
+    ]),
   ]);
 });