docs: document FullReporter API (#30186)

* FullConfig split into FullConfig and ConfigInWorker
* FullProject split into FullProject and ProjectInWorker
* Tests can only access {Config, Project}InWorker, while reporters can
only access Full{Config,Project}. This will allow in the future to
change the reporter API independently from the tests.
* Added documentation for the 4 classes.

docs/src/test-api/class-configinworker.md

@@ -0,0 +1,135 @@
+# class: ConfigInWorker
+* since: v1.10
+* langs: js
+
+Resolved configuration available via [`property: TestInfo.config`] and [`property: WorkerInfo.config`].
+
+## property: ConfigInWorker.configFile
+* since: v1.20
+- type: ?<[string]>
+
+Path to the configuration file (if any) used to run the tests.
+
+## property: ConfigInWorker.forbidOnly
+* since: v1.10
+- type: <[boolean]>
+
+See [`property: TestConfig.forbidOnly`].
+
+## property: ConfigInWorker.fullyParallel
+* since: v1.20
+- type: <[boolean]>
+
+See [`property: TestConfig.fullyParallel`].
+
+## property: ConfigInWorker.globalSetup
+* since: v1.10
+- type: <[null]|[string]>
+
+See [`property: TestConfig.globalSetup`].
+
+## property: ConfigInWorker.globalTeardown
+* since: v1.10
+- type: <[null]|[string]>
+
+See [`property: TestConfig.globalTeardown`].
+
+## property: ConfigInWorker.globalTimeout
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestConfig.globalTimeout`].
+
+## property: ConfigInWorker.grep
+* since: v1.10
+- type: <[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestConfig.grep`].
+
+## property: ConfigInWorker.grepInvert
+* since: v1.10
+- type: <[null]|[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestConfig.grepInvert`].
+
+## property: ConfigInWorker.maxFailures
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestConfig.maxFailures`].
+
+## property: ConfigInWorker.metadata
+* since: v1.10
+- type: <[Metadata]>
+
+See [`property: TestConfig.metadata`].
+
+## property: ConfigInWorker.preserveOutput
+* since: v1.10
+- type: <[PreserveOutput]<"always"|"never"|"failures-only">>
+
+See [`property: TestConfig.preserveOutput`].
+
+## property: ConfigInWorker.projects
+* since: v1.10
+- type: <[Array]<[ProjectInWorker]>>
+
+List of resolved projects.
+
+## property: ConfigInWorker.quiet
+* since: v1.10
+- type: <[boolean]>
+
+See [`property: TestConfig.quiet`].
+
+## property: ConfigInWorker.reporter
+* since: v1.10
+- type: <[string]|[Array]<[Object]>|[BuiltInReporter]<"list"|"dot"|"line"|"github"|"json"|"junit"|"null"|"html">>
+  - `0` <[string]> Reporter name or module or file path
+  - `1` <[Object]> An object with reporter options if any
+
+See [`property: TestConfig.reporter`].
+
+## property: ConfigInWorker.reportSlowTests
+* since: v1.10
+- type: <[null]|[Object]>
+  - `max` <[int]> The maximum number of slow test files to report. Defaults to `5`.
+  - `threshold` <[float]> Test duration in milliseconds that is considered slow. Defaults to 15 seconds.
+
+See [`property: TestConfig.reportSlowTests`].
+
+## property: ConfigInWorker.rootDir
+* since: v1.20
+- type: <[string]>
+
+## property: ConfigInWorker.shard
+* since: v1.10
+- type: <[null]|[Object]>
+  - `total` <[int]> The total number of shards.
+  - `current` <[int]> The index of the shard to execute, one-based.
+
+See [`property: TestConfig.shard`].
+
+## property: ConfigInWorker.updateSnapshots
+* since: v1.10
+- type: <[UpdateSnapshots]<"all"|"none"|"missing">>
+
+See [`property: TestConfig.updateSnapshots`].
+
+## property: ConfigInWorker.version
+* since: v1.20
+- type: <[string]>
+
+Playwright version.
+
+## property: ConfigInWorker.webServer
+* since: v1.10
+- type: <[null]|[Object]>
+
+See [`property: TestConfig.webServer`].
+
+## property: ConfigInWorker.workers
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestConfig.workers`].

docs/src/test-api/class-projectinworker.md

@@ -0,0 +1,96 @@
+# class: ProjectInWorker
+* since: v1.10
+* langs: js
+
+Runtime representation of the test project configuration that can be accessed
+in the tests via [`property: TestInfo.project`] and [`property: WorkerInfo.project`].
+
+## property: ProjectInWorker.dependencies
+* since: v1.31
+- type: <[Array]<[string]>>
+
+See [`property: TestProject.dependencies`].
+
+## property: ProjectInWorker.grep
+* since: v1.10
+- type: <[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestProject.grep`].
+
+## property: ProjectInWorker.grepInvert
+* since: v1.10
+- type: <[null]|[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestProject.grepInvert`].
+
+## property: ProjectInWorker.metadata
+* since: v1.10
+- type: <[Metadata]>
+
+See [`property: TestProject.metadata`].
+
+## property: ProjectInWorker.name
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.name`].
+
+## property: ProjectInWorker.snapshotDir
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.snapshotDir`].
+
+## property: ProjectInWorker.outputDir
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.outputDir`].
+
+## property: ProjectInWorker.repeatEach
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestProject.repeatEach`].
+
+## property: ProjectInWorker.retries
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestProject.retries`].
+
+## property: ProjectInWorker.teardown
+* since: v1.34
+- type: ?<[string]>
+
+See [`property: TestProject.teardown`].
+
+## property: ProjectInWorker.testDir
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.testDir`].
+
+## property: ProjectInWorker.testIgnore
+* since: v1.10
+- type: <[string]|[RegExp]|[Array]<[string]|[RegExp]>>
+
+See [`property: TestProject.testIgnore`].
+
+## property: ProjectInWorker.testMatch
+* since: v1.10
+- type: <[string]|[RegExp]|[Array]<[string]|[RegExp]>>
+
+See [`property: TestProject.testMatch`].
+
+## property: ProjectInWorker.timeout
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestProject.timeout`].
+
+## property: ProjectInWorker.use
+* since: v1.10
+- type: <[Fixtures]>
+
+See [`property: TestProject.use`].

docs/src/test-api/class-testinfo.md

@@ -106,7 +106,7 @@ Column number where the currently running test is declared.
 
 ## property: TestInfo.config
 * since: v1.10
-- type: <[TestConfig]>
+- type: <[ConfigInWorker]>
 
 Processed configuration from the [configuration file](../test-configuration.md).
 
@@ -279,7 +279,7 @@ Also available as `process.env.TEST_PARALLEL_INDEX`. Learn more about [paralleli
 
 ## property: TestInfo.project
 * since: v1.10
-- type: <[TestProject]>
+- type: <[ProjectInWorker]>
 
 Processed project configuration from the [configuration file](../test-configuration.md).
 

docs/src/test-api/class-workerinfo.md

@@ -6,7 +6,7 @@
 
 ## property: WorkerInfo.config
 * since: v1.10
-- type: <[TestConfig]>
+- type: <[ConfigInWorker]>
 
 Processed configuration from the [configuration file](../test-configuration.md).
 
@@ -22,7 +22,7 @@ Also available as `process.env.TEST_PARALLEL_INDEX`. Learn more about [paralleli
 
 ## property: WorkerInfo.project
 * since: v1.10
-- type: <[TestProject]>
+- type: <[ProjectInWorker]>
 
 Processed project configuration from the [configuration file](../test-configuration.md).
 

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

@@ -0,0 +1,135 @@
+# class: FullConfig
+* since: v1.10
+* langs: js
+
+Resolved configuration passed to [`method: Reporter.onBegin`].
+
+## property: FullConfig.configFile
+* since: v1.20
+- type: ?<[string]>
+
+Path to the configuration file (if any) used to run the tests.
+
+## property: FullConfig.forbidOnly
+* since: v1.10
+- type: <[boolean]>
+
+See [`property: TestConfig.forbidOnly`].
+
+## property: FullConfig.fullyParallel
+* since: v1.20
+- type: <[boolean]>
+
+See [`property: TestConfig.fullyParallel`].
+
+## property: FullConfig.globalSetup
+* since: v1.10
+- type: <[null]|[string]>
+
+See [`property: TestConfig.globalSetup`].
+
+## property: FullConfig.globalTeardown
+* since: v1.10
+- type: <[null]|[string]>
+
+See [`property: TestConfig.globalTeardown`].
+
+## property: FullConfig.globalTimeout
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestConfig.globalTimeout`].
+
+## property: FullConfig.grep
+* since: v1.10
+- type: <[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestConfig.grep`].
+
+## property: FullConfig.grepInvert
+* since: v1.10
+- type: <[null]|[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestConfig.grepInvert`].
+
+## property: FullConfig.maxFailures
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestConfig.maxFailures`].
+
+## property: FullConfig.metadata
+* since: v1.10
+- type: <[Metadata]>
+
+See [`property: TestConfig.metadata`].
+
+## property: FullConfig.preserveOutput
+* since: v1.10
+- type: <[PreserveOutput]<"always"|"never"|"failures-only">>
+
+See [`property: TestConfig.preserveOutput`].
+
+## property: FullConfig.projects
+* since: v1.10
+- type: <[Array]<[FullProject]>>
+
+List of resolved projects.
+
+## property: FullConfig.quiet
+* since: v1.10
+- type: <[boolean]>
+
+See [`property: TestConfig.quiet`].
+
+## property: FullConfig.reporter
+* since: v1.10
+- type: <[string]|[Array]<[Object]>|[BuiltInReporter]<"list"|"dot"|"line"|"github"|"json"|"junit"|"null"|"html">>
+  - `0` <[string]> Reporter name or module or file path
+  - `1` <[Object]> An object with reporter options if any
+
+See [`property: TestConfig.reporter`].
+
+## property: FullConfig.reportSlowTests
+* since: v1.10
+- type: <[null]|[Object]>
+  - `max` <[int]> The maximum number of slow test files to report. Defaults to `5`.
+  - `threshold` <[float]> Test duration in milliseconds that is considered slow. Defaults to 15 seconds.
+
+See [`property: TestConfig.reportSlowTests`].
+
+## property: FullConfig.rootDir
+* since: v1.20
+- type: <[string]>
+
+## property: FullConfig.shard
+* since: v1.10
+- type: <[null]|[Object]>
+  - `total` <[int]> The total number of shards.
+  - `current` <[int]> The index of the shard to execute, one-based.
+
+See [`property: TestConfig.shard`].
+
+## property: FullConfig.updateSnapshots
+* since: v1.10
+- type: <[UpdateSnapshots]<"all"|"none"|"missing">>
+
+See [`property: TestConfig.updateSnapshots`].
+
+## property: FullConfig.version
+* since: v1.20
+- type: <[string]>
+
+Playwright version.
+
+## property: FullConfig.webServer
+* since: v1.10
+- type: <[null]|[Object]>
+
+See [`property: TestConfig.webServer`].
+
+## property: FullConfig.workers
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestConfig.workers`].

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

@@ -0,0 +1,98 @@
+# class: FullProject
+* since: v1.10
+* langs: js
+
+Runtime representation of the test project configuration that is passed
+to [Reporter]. It exposes some of the resolved fields declared in
+[TestProject]. You can get [FullProject] instance from [`property: FullConfig.projects`]
+or [`method: Suite.project`].
+
+## property: FullProject.dependencies
+* since: v1.31
+- type: <[Array]<[string]>>
+
+See [`property: TestProject.dependencies`].
+
+## property: FullProject.grep
+* since: v1.10
+- type: <[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestProject.grep`].
+
+## property: FullProject.grepInvert
+* since: v1.10
+- type: <[null]|[RegExp]|[Array]<[RegExp]>>
+
+See [`property: TestProject.grepInvert`].
+
+## property: FullProject.metadata
+* since: v1.10
+- type: <[Metadata]>
+
+See [`property: TestProject.metadata`].
+
+## property: FullProject.name
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.name`].
+
+## property: FullProject.snapshotDir
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.snapshotDir`].
+
+## property: FullProject.outputDir
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.outputDir`].
+
+## property: FullProject.repeatEach
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestProject.repeatEach`].
+
+## property: FullProject.retries
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestProject.retries`].
+
+## property: FullProject.teardown
+* since: v1.34
+- type: ?<[string]>
+
+See [`property: TestProject.teardown`].
+
+## property: FullProject.testDir
+* since: v1.10
+- type: <[string]>
+
+See [`property: TestProject.testDir`].
+
+## property: FullProject.testIgnore
+* since: v1.10
+- type: <[string]|[RegExp]|[Array]<[string]|[RegExp]>>
+
+See [`property: TestProject.testIgnore`].
+
+## property: FullProject.testMatch
+* since: v1.10
+- type: <[string]|[RegExp]|[Array]<[string]|[RegExp]>>
+
+See [`property: TestProject.testMatch`].
+
+## property: FullProject.timeout
+* since: v1.10
+- type: <[int]>
+
+See [`property: TestProject.timeout`].
+
+## property: FullProject.use
+* since: v1.10
+- type: <[Fixtures]>
+
+See [`property: TestProject.use`].

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

@@ -103,7 +103,7 @@ Called once before running tests. All tests have been already discovered and put
 
 ### param: Reporter.onBegin.config
 * since: v1.10
-- `config` <[TestConfig]>
+- `config` <[FullConfig]>
 
 Resolved configuration.
 

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

@@ -4,7 +4,7 @@
 
 `Suite` is a group of tests. All tests in Playwright Test form the following hierarchy:
 
-* Root suite has a child suite for each [TestProject].
+* Root suite has a child suite for each [FullProject].
   * Project suite #1. Has a child suite for each test file in the project.
     * File suite #1
       * [TestCase] #1
@@ -46,7 +46,7 @@ Parent suite, missing for the root suite.
 
 ## method: Suite.project
 * since: v1.10
-- returns: ?<[TestProject]>
+- returns: <[FullProject]|[undefined]>
 
 Configuration of the project this suite belongs to, or [void] for the root suite.
 

packages/playwright-ct-core/src/cliOverrides.ts

@@ -19,8 +19,7 @@ import { removeFolder } from 'playwright/lib/program';
 import { affectedTestFiles, cacheDir } from 'playwright/lib/transform/compilationCache';
 import { buildBundle } from './vitePlugin';
 import { resolveDirs } from './viteUtils';
-import type { Suite } from 'playwright/lib/common/test';
+import type { FullConfig, Suite } from 'playwright/types/testReporter';
-import type { FullConfig } from 'playwright/test';
 
 export async function clearCacheCommand(config: FullConfig, configDir: string) {
   const dirs = await resolveDirs(configDir, config);

packages/playwright-ct-core/src/vitePlugin.ts

@@ -22,8 +22,7 @@ import { assert, calculateSha1, getPlaywrightVersion, isURLAvailable } from 'pla
 import { debug } from 'playwright-core/lib/utilsBundle';
 import { internalDependenciesForTestFile, setExternalDependencies } from 'playwright/lib/transform/compilationCache';
 import { stoppable } from 'playwright/lib/utilsBundle';
-import type { FullConfig } from 'playwright/test';
+import type { FullConfig, Suite } from 'playwright/types/testReporter';
-import type { Suite } from 'playwright/types/testReporter';
 import type { PluginContext } from 'rollup';
 import type { Plugin, ResolveFn, ResolvedConfig } from 'vite';
 import type { TestRunnerPlugin } from '../../playwright/src/plugins';

packages/playwright-ct-core/src/viteUtils.ts

@@ -18,7 +18,8 @@ import fs from 'fs';
 import path from 'path';
 import { debug } from 'playwright-core/lib/utilsBundle';
 import { getUserData } from 'playwright/lib/transform/compilationCache';
-import type { PlaywrightTestConfig as BasePlaywrightTestConfig, FullConfig } from 'playwright/test';
+import type { PlaywrightTestConfig as BasePlaywrightTestConfig } from 'playwright/types/test';
+import type { FullConfig } from 'playwright/types/testReporter';
 import type { InlineConfig, Plugin, TransformResult, UserConfig } from 'vite';
 import type { ImportInfo } from './tsxTransform';
 import { resolveHook } from 'playwright/lib/transform/transform';

packages/playwright/src/common/config.ts

@@ -23,7 +23,7 @@ import type { TestRunnerPluginRegistration } from '../plugins';
 import { getPackageJsonPath, mergeObjects } from '../util';
 import type { Matcher } from '../util';
 import type { ConfigCLIOverrides } from './ipc';
-import type { FullConfig, FullProject } from '../../types/test';
+import type { FullConfig, FullProject } from '../../types/testReporter';
 import { setTransformConfig } from '../transform/transform';
 
 export type ConfigLocation = {
@@ -46,7 +46,7 @@ export class FullConfigInternal {
   readonly configCLIOverrides: ConfigCLIOverrides;
   readonly ignoreSnapshots: boolean;
   readonly preserveOutputDir: boolean;
-  readonly webServers: Exclude<FullConfig['webServer'], null>[];
+  readonly webServers: NonNullable<FullConfig['webServer']>[];
   readonly plugins: TestRunnerPluginRegistration[];
   readonly projects: FullProjectInternal[] = [];
   cliArgs: string[] = [];
@@ -182,7 +182,7 @@ export class FullProjectInternal {
       // project is top-level vs dependency. See collectProjectsAndTestFiles in loadUtils.
       repeatEach: takeFirst(projectConfig.repeatEach, config.repeatEach, 1),
       retries: takeFirst(configCLIOverrides.retries, projectConfig.retries, config.retries, 0),
-      metadata: takeFirst(projectConfig.metadata, config.metadata, undefined),
+      metadata: takeFirst(projectConfig.metadata, config.metadata, {}),
       name: takeFirst(projectConfig.name, config.name, ''),
       testDir,
       snapshotDir: takeFirst(pathResolve(configDir, projectConfig.snapshotDir), pathResolve(configDir, config.snapshotDir), testDir),

packages/playwright/src/common/test.ts

@@ -19,8 +19,7 @@ import type * as reporterTypes from '../../types/testReporter';
 import type { TestTypeImpl } from './testType';
 import { rootTestType } from './testType';
 import type { Annotation, FixturesWithLocation, FullProjectInternal } from './config';
-import type { FullProject } from '../../types/test';
+import type { Location, FullProject } from '../../types/testReporter';
-import type { Location } from '../../types/testReporter';
 
 class Base {
   title: string;

packages/playwright/src/isomorphic/teleReceiver.ts

@@ -15,7 +15,7 @@
  */
 
 import type { Annotation } from '../common/config';
-import type { FullProject, Metadata } from '../../types/test';
+import type { Metadata } from '../../types/test';
 import type * as reporterTypes from '../../types/testReporter';
 import type { ReporterV2 } from '../reporters/reporterV2';
 
@@ -590,7 +590,7 @@ class TeleTestResult implements reporterTypes.TestResult {
   }
 }
 
-export type TeleFullProject = FullProject;
+export type TeleFullProject = reporterTypes.FullProject;
 
 export const baseFullConfig: reporterTypes.FullConfig = {
   forbidOnly: false,

packages/playwright/src/worker/testInfo.ts

@@ -17,7 +17,7 @@
 import fs from 'fs';
 import path from 'path';
 import { captureRawStack, monotonicTime, zones, sanitizeForFilePath, stringifyStackFrames } from 'playwright-core/lib/utils';
-import type { TestInfoError, TestInfo, TestStatus, FullProject, FullConfig } from '../../types/test';
+import type { TestInfoError, TestInfo, TestStatus, ProjectInWorker, ConfigInWorker } from '../../types/test';
 import type { AttachmentPayload, StepBeginPayload, StepEndPayload, WorkerInitParams } from '../common/ipc';
 import type { TestCase } from '../common/test';
 import { TimeoutManager, TimeoutManagerError, kMaxDeadline } from './timeoutManager';
@@ -81,8 +81,8 @@ export class TestInfoImpl implements TestInfo {
   readonly retry: number;
   readonly workerIndex: number;
   readonly parallelIndex: number;
-  readonly project: FullProject;
+  readonly project: ProjectInWorker;
-  readonly config: FullConfig;
+  readonly config: ConfigInWorker;
   readonly title: string;
   readonly titlePath: string[];
   readonly file: string;

packages/playwright/types/testReporter.d.ts

@@ -15,12 +15,221 @@
  * limitations under the License.
  */
 
-import type { FullConfig, FullProject, TestStatus, Metadata } from './test';
+import type { TestStatus, Metadata, PlaywrightTestOptions, PlaywrightWorkerOptions, ReporterDescription, ConfigInWorker } from './test';
-export type { FullConfig, TestStatus, FullProject } from './test';
+export type { TestStatus } from './test';
+
+type UseOptions<TestArgs, WorkerArgs> = Partial<WorkerArgs> & Partial<TestArgs>;
+
+/**
+ * Resolved configuration passed to
+ * [reporter.onBegin(config, suite)](https://playwright.dev/docs/api/class-reporter#reporter-on-begin).
+ */
+export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
+  /**
+   * List of resolved projects.
+   */
+  projects: FullProject<TestArgs, WorkerArgs>[];
+  /**
+   * See [testConfig.reporter](https://playwright.dev/docs/api/class-testconfig#test-config-reporter).
+   */
+  reporter: ReporterDescription[];
+  /**
+   * See [testConfig.webServer](https://playwright.dev/docs/api/class-testconfig#test-config-web-server).
+   */
+  webServer: ConfigInWorker['webServer'];
+  /**
+   * Path to the configuration file (if any) used to run the tests.
+   */
+  configFile?: string;
+
+  /**
+   * See [testConfig.forbidOnly](https://playwright.dev/docs/api/class-testconfig#test-config-forbid-only).
+   */
+  forbidOnly: boolean;
+
+  /**
+   * See [testConfig.fullyParallel](https://playwright.dev/docs/api/class-testconfig#test-config-fully-parallel).
+   */
+  fullyParallel: boolean;
+
+  /**
+   * See [testConfig.globalSetup](https://playwright.dev/docs/api/class-testconfig#test-config-global-setup).
+   */
+  globalSetup: null|string;
+
+  /**
+   * See [testConfig.globalTeardown](https://playwright.dev/docs/api/class-testconfig#test-config-global-teardown).
+   */
+  globalTeardown: null|string;
+
+  /**
+   * See [testConfig.globalTimeout](https://playwright.dev/docs/api/class-testconfig#test-config-global-timeout).
+   */
+  globalTimeout: number;
+
+  /**
+   * See [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep).
+   */
+  grep: RegExp|Array<RegExp>;
+
+  /**
+   * See [testConfig.grepInvert](https://playwright.dev/docs/api/class-testconfig#test-config-grep-invert).
+   */
+  grepInvert: null|RegExp|Array<RegExp>;
+
+  /**
+   * See [testConfig.maxFailures](https://playwright.dev/docs/api/class-testconfig#test-config-max-failures).
+   */
+  maxFailures: number;
+
+  /**
+   * See [testConfig.metadata](https://playwright.dev/docs/api/class-testconfig#test-config-metadata).
+   */
+  metadata: Metadata;
+
+  /**
+   * See [testConfig.preserveOutput](https://playwright.dev/docs/api/class-testconfig#test-config-preserve-output).
+   */
+  preserveOutput: "always"|"never"|"failures-only";
+
+  /**
+   * See [testConfig.quiet](https://playwright.dev/docs/api/class-testconfig#test-config-quiet).
+   */
+  quiet: boolean;
+
+  /**
+   * See [testConfig.reportSlowTests](https://playwright.dev/docs/api/class-testconfig#test-config-report-slow-tests).
+   */
+  reportSlowTests: null|{
+    /**
+     * The maximum number of slow test files to report. Defaults to `5`.
+     */
+    max: number;
+
+    /**
+     * Test duration in milliseconds that is considered slow. Defaults to 15 seconds.
+     */
+    threshold: number;
+  };
+
+  rootDir: string;
+
+  /**
+   * See [testConfig.shard](https://playwright.dev/docs/api/class-testconfig#test-config-shard).
+   */
+  shard: null|{
+    /**
+     * The total number of shards.
+     */
+    total: number;
+
+    /**
+     * The index of the shard to execute, one-based.
+     */
+    current: number;
+  };
+
+  /**
+   * See [testConfig.updateSnapshots](https://playwright.dev/docs/api/class-testconfig#test-config-update-snapshots).
+   */
+  updateSnapshots: "all"|"none"|"missing";
+
+  /**
+   * Playwright version.
+   */
+  version: string;
+
+  /**
+   * See [testConfig.workers](https://playwright.dev/docs/api/class-testconfig#test-config-workers).
+   */
+  workers: number;
+}
+
+/**
+ * Runtime representation of the test project configuration that is passed to {@link Reporter}. It exposes some of the
+ * resolved fields declared in {@link TestProject}. You can get {@link FullProject} instance from
+ * [fullConfig.projects](https://playwright.dev/docs/api/class-fullconfig#full-config-projects) or
+ * [suite.project()](https://playwright.dev/docs/api/class-suite#suite-project).
+ */
+export interface FullProject<TestArgs = {}, WorkerArgs = {}> {
+  /**
+   * See [testProject.use](https://playwright.dev/docs/api/class-testproject#test-project-use).
+   */
+  use: UseOptions<PlaywrightTestOptions & TestArgs, PlaywrightWorkerOptions & WorkerArgs>;
+  /**
+   * See [testProject.dependencies](https://playwright.dev/docs/api/class-testproject#test-project-dependencies).
+   */
+  dependencies: Array<string>;
+
+  /**
+   * See [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep).
+   */
+  grep: RegExp|Array<RegExp>;
+
+  /**
+   * See [testProject.grepInvert](https://playwright.dev/docs/api/class-testproject#test-project-grep-invert).
+   */
+  grepInvert: null|RegExp|Array<RegExp>;
+
+  /**
+   * See [testProject.metadata](https://playwright.dev/docs/api/class-testproject#test-project-metadata).
+   */
+  metadata: Metadata;
+
+  /**
+   * See [testProject.name](https://playwright.dev/docs/api/class-testproject#test-project-name).
+   */
+  name: string;
+
+  /**
+   * See [testProject.outputDir](https://playwright.dev/docs/api/class-testproject#test-project-output-dir).
+   */
+  outputDir: string;
+
+  /**
+   * See [testProject.repeatEach](https://playwright.dev/docs/api/class-testproject#test-project-repeat-each).
+   */
+  repeatEach: number;
+
+  /**
+   * See [testProject.retries](https://playwright.dev/docs/api/class-testproject#test-project-retries).
+   */
+  retries: number;
+
+  /**
+   * See [testProject.snapshotDir](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-dir).
+   */
+  snapshotDir: string;
+
+  /**
+   * See [testProject.teardown](https://playwright.dev/docs/api/class-testproject#test-project-teardown).
+   */
+  teardown?: string;
+
+  /**
+   * See [testProject.testDir](https://playwright.dev/docs/api/class-testproject#test-project-test-dir).
+   */
+  testDir: string;
+
+  /**
+   * See [testProject.testIgnore](https://playwright.dev/docs/api/class-testproject#test-project-test-ignore).
+   */
+  testIgnore: string|RegExp|Array<string|RegExp>;
+
+  /**
+   * See [testProject.testMatch](https://playwright.dev/docs/api/class-testproject#test-project-test-match).
+   */
+  testMatch: string|RegExp|Array<string|RegExp>;
+
+  /**
+   * See [testProject.timeout](https://playwright.dev/docs/api/class-testproject#test-project-timeout).
+   */
+  timeout: number;
+}
 
 /**
  * `Suite` is a group of tests. All tests in Playwright Test form the following hierarchy:
- * - Root suite has a child suite for each {@link TestProject}.
+ * - Root suite has a child suite for each {@link FullProject}.
  *   - Project suite #1. Has a child suite for each test file in the project.
  *     - File suite #1
  *       - {@link TestCase} #1
@@ -45,10 +254,6 @@ export interface Suite {
    * -> ...`describe` -> `test`.
    */
   type: 'root' | 'project' | 'file' | 'describe';
-  /**
-   * Configuration of the project this suite belongs to, or [void] for the root suite.
-   */
-  project(): FullProject | undefined;
   /**
    * Returns the list of all test cases in this suite and its descendants, as opposite to
    * [suite.tests](https://playwright.dev/docs/api/class-suite#suite-tests).
@@ -63,6 +268,11 @@ export interface Suite {
    */
   entries(): Array<TestCase|Suite>;
 
+  /**
+   * Configuration of the project this suite belongs to, or [void] for the root suite.
+   */
+  project(): FullProject|undefined;
+
   /**
    * Returns a list of titles from the root down to this suite.
    */
@@ -454,13 +664,6 @@ export interface FullResult {
  *   [reporter.onBegin(config, suite)](https://playwright.dev/docs/api/class-reporter#reporter-on-begin).
  */
 export interface Reporter {
-  /**
-   * Called once before running tests. All tests have been already discovered and put into a hierarchy of {@link
-   * Suite}s.
-   * @param config Resolved configuration.
-   * @param suite The root suite that contains all projects, files and test cases.
-   */
-  onBegin?(config: FullConfig, suite: Suite): void;
   /**
    * Called after all tests have been run, or testing has been interrupted. Note that this method may return a [Promise]
    * and Playwright Test will await it. Reporter is allowed to override the status and hence affect the exit code of the
@@ -474,6 +677,14 @@ export interface Reporter {
    * - `'interrupted'` - Interrupted by the user.
    */
   onEnd?(result: FullResult): Promise<{ status?: FullResult['status'] } | undefined | void> | void;
+  /**
+   * Called once before running tests. All tests have been already discovered and put into a hierarchy of {@link
+   * Suite}s.
+   * @param config Resolved configuration.
+   * @param suite The root suite that contains all projects, files and test cases.
+   */
+  onBegin?(config: FullConfig, suite: Suite): void;
+
   /**
    * Called on some global error, for example unhandled exception in the worker process.
    * @param error The error.

tests/playwright-test/global-setup.spec.ts

@@ -280,8 +280,8 @@ const authFiles = {
     export default config;
   `,
   'auth.ts': `
-    import { chromium, FullConfig } from '@playwright/test';
+    import { chromium, ConfigInWorker } from '@playwright/test';
-    async function globalSetup(config: FullConfig) {
+    async function globalSetup(config: ConfigInWorker) {
       const { baseURL, storageState } = config.projects[0].use;
       const browser = await chromium.launch();
       const page = await browser.newPage();

utils/doclint/generateFullConfigDoc.js

@@ -0,0 +1,121 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// @ts-check
+
+const path = require('path');
+const fs = require('fs');
+const PROJECT_DIR = path.join(__dirname, '..', '..');
+
+function generateFullConfigClass(fromClassName, toClassName, allowList) {
+  const allowedNames = new Set(allowList);
+
+  const content = fs.readFileSync(path.join(PROJECT_DIR, `docs/src/test-api/class-${fromClassName.toLowerCase()}.md`)).toString();
+  let sections = content.split('\n## ');
+  sections = filterAllowedSections(sections, allowedNames);
+  if (allowedNames.size)
+    console.log(`Undocumented properties for ${fromClassName}:\n  ${[...allowedNames].join('\n  ')}`);
+  sections = changeClassName(sections, fromClassName, toClassName);
+  sections = replacePropertyDescriptions(sections, fromClassName);
+  const fullconfig = sections.join('\n## ');
+  fs.writeFileSync(path.join(PROJECT_DIR, `docs/src/test-api/class-${toClassName.toLowerCase()}.md`), fullconfig);
+}
+
+function propertyNameFromSection(section) {
+  section = section.split('\n')[0];
+  const match = /\.(\w+)/.exec(section);
+  if (!match)
+    return null;
+  return match[1];
+}
+
+function filterAllowedSections(sections, allowedNames) {
+  return sections.filter(section => {
+    section = section.split('\n')[0];
+    const name = propertyNameFromSection(section);
+    if (!name)
+      return true;
+    return allowedNames.delete(name);
+  });
+}
+
+function changeClassName(sections, from, to) {
+  return sections.map(section => {
+    const lines = section.split('\n');
+    lines[0] = lines[0].replace(from, to);
+    return lines.join('\n');
+  });
+}
+
+function replacePropertyDescriptions(sections, configClassName) {
+  return sections.map(section => {
+    const parts = section.split('\n\n');
+    section = parts[0];
+    const name = propertyNameFromSection(section);
+    if (!name)
+      return `${section}\n`;
+    return `${section}\n\nSee [\`property: ${configClassName}.${name}\`].\n`;
+  });
+}
+
+function generateFullConfig() {
+  generateFullConfigClass('TestConfig', 'FullConfig', [
+    'forbidOnly',
+    'fullyParallel',
+    'globalSetup',
+    'globalTeardown',
+    'globalTimeout',
+    'grep',
+    'grepInvert',
+    'maxFailures',
+    'metadata',
+    'version',
+    'preserveOutput',
+    'projects',
+    'reporter',
+    'reportSlowTests',
+    'rootDir',
+    'quiet',
+    'shard',
+    'updateSnapshots',
+    'workers',
+    'webServer',
+    'configFile',
+  ]);
+}
+
+function generateFullProject() {
+  generateFullConfigClass('TestProject', 'FullProject', [
+    'grep',
+    'grepInvert',
+    'metadata',
+    'name',
+    'dependencies',
+    'snapshotDir',
+    'outputDir',
+    'repeatEach',
+    'retries',
+    'teardown',
+    'testDir',
+    'testIgnore',
+    'testMatch',
+    'timeout',
+    'use',
+  ]);
+}
+
+generateFullConfig();
+generateFullProject();

utils/generate_types/index.js

@@ -553,9 +553,7 @@ class TypesGenerator {
       overridesToDocsClassMapping: new Map([
         ['TestType', 'Test'],
         ['Config', 'TestConfig'],
-        ['FullConfig', 'TestConfig'],
         ['Project', 'TestProject'],
-        ['FullProject', 'TestProject'],
         ['PlaywrightWorkerOptions', 'TestOptions'],
         ['PlaywrightTestOptions', 'TestOptions'],
         ['PlaywrightWorkerArgs', 'Fixtures'],
@@ -563,9 +561,6 @@ class TypesGenerator {
         ['AsymmetricMatchers', 'GenericAssertions'],
       ]),
       ignoreMissing: new Set([
-        'FullConfig.configFile',
-        'FullConfig.version',
-        'FullConfig.rootDir',
         'SuiteFunction',
         'TestFunction',
         'PlaywrightWorkerOptions.defaultBrowserType',

utils/generate_types/overrides-test.d.ts

@@ -29,33 +29,15 @@ export type ReporterDescription =
   ['null'] |
   [string] | [string, any];
 
-type UseOptions<TestArgs, WorkerArgs> = { [K in keyof WorkerArgs]?: WorkerArgs[K] } & { [K in keyof TestArgs]?: TestArgs[K] };
+type UseOptions<TestArgs, WorkerArgs> = Partial<WorkerArgs> & Partial<TestArgs>;
 
 export interface Project<TestArgs = {}, WorkerArgs = {}> extends TestProject {
   use?: UseOptions<TestArgs, WorkerArgs>;
 }
 
-// [internal] !!! DO NOT ADD TO THIS !!!
+export interface ProjectInWorker<TestArgs = {}, WorkerArgs = {}> {
-// [internal] It is part of the public API and is computed from the user's config.
-// [internal] If you need new fields internally, add them to FullProjectInternal instead.
-export interface FullProject<TestArgs = {}, WorkerArgs = {}> {
-  grep: RegExp | RegExp[];
-  grepInvert: RegExp | RegExp[] | null;
-  metadata: Metadata;
-  name: string;
-  dependencies: string[];
-  snapshotDir: string;
-  outputDir: string;
-  repeatEach: number;
-  retries: number;
-  teardown?: string;
-  testDir: string;
-  testIgnore: string | RegExp | (string | RegExp)[];
-  testMatch: string | RegExp | (string | RegExp)[];
-  timeout: number;
   use: UseOptions<PlaywrightTestOptions & TestArgs, PlaywrightWorkerOptions & WorkerArgs>;
 }
-// [internal] !!! DO NOT ADD TO THIS !!! See prior note.
 
 type LiteralUnion<T extends U, U = string> = T | (U & { zz_IGNORE_ME?: never });
 
@@ -71,46 +53,14 @@ export interface Config<TestArgs = {}, WorkerArgs = {}> extends TestConfig {
 
 export type Metadata = { [key: string]: any };
 
-// [internal] !!! DO NOT ADD TO THIS !!!
+export interface ConfigInWorker<TestArgs = {}, WorkerArgs = {}> {
-// [internal] It is part of the public API and is computed from the user's config.
+  projects: ProjectInWorker<TestArgs, WorkerArgs>[];
-// [internal] If you need new fields internally, add them to FullConfigInternal instead.
-export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
-  forbidOnly: boolean;
-  fullyParallel: boolean;
-  globalSetup: string | null;
-  globalTeardown: string | null;
-  globalTimeout: number;
-  grep: RegExp | RegExp[];
-  grepInvert: RegExp | RegExp[] | null;
-  maxFailures: number;
-  metadata: Metadata;
-  version: string;
-  preserveOutput: 'always' | 'never' | 'failures-only';
-  projects: FullProject<TestArgs, WorkerArgs>[];
   reporter: ReporterDescription[];
-  reportSlowTests: { max: number, threshold: number } | null;
-  rootDir: string;
-  quiet: boolean;
-  shard: { total: number, current: number } | null;
-  updateSnapshots: 'all' | 'none' | 'missing';
-  workers: number;
   webServer: TestConfigWebServer | null;
-  configFile?: string;
-  // [internal] !!! DO NOT ADD TO THIS !!! See prior note.
 }
 
 export type TestStatus = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
 
-export interface WorkerInfo {
-  config: FullConfig;
-  project: FullProject;
-}
-
-export interface TestInfo {
-  config: FullConfig;
-  project: FullProject;
-}
-
 type TestDetailsAnnotation = {
   type: string;
   description?: string;

utils/generate_types/overrides-testReporter.d.ts

@@ -14,12 +14,23 @@
  * limitations under the License.
  */
 
-import type { FullConfig, FullProject, TestStatus, Metadata } from './test';
+import type { TestStatus, Metadata, PlaywrightTestOptions, PlaywrightWorkerOptions, ReporterDescription, ConfigInWorker } from './test';
-export type { FullConfig, TestStatus, FullProject } from './test';
+export type { TestStatus } from './test';
+
+type UseOptions<TestArgs, WorkerArgs> = Partial<WorkerArgs> & Partial<TestArgs>;
+
+export interface FullConfig<TestArgs = {}, WorkerArgs = {}> {
+  projects: FullProject<TestArgs, WorkerArgs>[];
+  reporter: ReporterDescription[];
+  webServer: ConfigInWorker['webServer'];
+}
+
+export interface FullProject<TestArgs = {}, WorkerArgs = {}> {
+  use: UseOptions<PlaywrightTestOptions & TestArgs, PlaywrightWorkerOptions & WorkerArgs>;
+}
 
 export interface Suite {
   type: 'root' | 'project' | 'file' | 'describe';
-  project(): FullProject | undefined;
 }
 
 export interface TestCase {
@@ -56,7 +67,6 @@ export interface FullResult {
 }
 
 export interface Reporter {
-  onBegin?(config: FullConfig, suite: Suite): void;
   onEnd?(result: FullResult): Promise<{ status?: FullResult['status'] } | undefined | void> | void;
 }