code · pull · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/.github/workflows/fix-flakes.yml b/.github/workflows/fix-flakes.yml
@@ -272,7 +272,7 @@ jobs:
       - uses: actions/create-github-app-token@v3
         id: app-token
         with:
-          app-id: ${{ vars.PLAYWRIGHT_APP_ID }}
+          client-id: ${{ vars.PLAYWRIGHT_APP_CLIENT_ID }}
           private-key: ${{ secrets.PLAYWRIGHT_PRIVATE_KEY }}
 
       - name: Apply commit and open PR

diff --git a/.github/workflows/publish_release.yml b/.github/workflows/publish_release.yml
@@ -58,7 +58,7 @@ jobs:
     - uses: actions/create-github-app-token@v3
       id: app-token
       with:
-        app-id: ${{ vars.PLAYWRIGHT_APP_ID }}
+        client-id: ${{ vars.PLAYWRIGHT_APP_CLIENT_ID }}
         private-key: ${{ secrets.PLAYWRIGHT_PRIVATE_KEY }}
         repositories: trace.playwright.dev
     - name: Deploy Canary

diff --git a/.github/workflows/roll_browser_into_playwright.yml b/.github/workflows/roll_browser_into_playwright.yml
@@ -55,7 +55,7 @@ jobs:
     - uses: actions/create-github-app-token@v3
       id: app-token
       with:
-        app-id: ${{ vars.PLAYWRIGHT_APP_ID }}
+        client-id: ${{ vars.PLAYWRIGHT_APP_CLIENT_ID }}
         private-key: ${{ secrets.PLAYWRIGHT_PRIVATE_KEY }}
     - name: Create Pull Request
       uses: actions/github-script@v9

diff --git a/.github/workflows/roll_nodejs.yml b/.github/workflows/roll_nodejs.yml
@@ -36,7 +36,7 @@ jobs:
       - uses: actions/create-github-app-token@v3
         id: app-token
         with:
-          app-id: ${{ vars.PLAYWRIGHT_APP_ID }}
+          client-id: ${{ vars.PLAYWRIGHT_APP_CLIENT_ID }}
           private-key: ${{ secrets.PLAYWRIGHT_PRIVATE_KEY }}
       - name: Create Pull Request
         if: ${{ steps.prepare-branch.outputs.HAS_CHANGES == '1' }}

diff --git a/.github/workflows/roll_stable_test_runner.yml b/.github/workflows/roll_stable_test_runner.yml
@@ -41,7 +41,7 @@ jobs:
       - uses: actions/create-github-app-token@v3
         id: app-token
         with:
-          app-id: ${{ vars.PLAYWRIGHT_APP_ID }}
+          client-id: ${{ vars.PLAYWRIGHT_APP_CLIENT_ID }}
           private-key: ${{ secrets.PLAYWRIGHT_PRIVATE_KEY }}
       - name: Create Pull Request
         if: ${{ steps.prepare-branch.outputs.HAS_CHANGES == '1' }}

diff --git a/.gitignore b/.gitignore
@@ -41,3 +41,4 @@ test-results
 playwright.env
 /firefox/
 .playwright/
+.npmrc
diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md
@@ -1069,8 +1069,6 @@ Attribute name to get the value for.
 
 ### option: Frame.getByRole.description = %%-locator-get-by-role-option-description-%%
 
-### option: Frame.getByRole.busy = %%-locator-get-by-role-option-busy-%%
-
 ## method: Frame.getByTestId
 * since: v1.27
 - returns: <[Locator]>

diff --git a/docs/src/api/class-framelocator.md b/docs/src/api/class-framelocator.md
@@ -144,8 +144,6 @@ in that iframe.
 
 ### option: FrameLocator.getByRole.description = %%-locator-get-by-role-option-description-%%
 
-### option: FrameLocator.getByRole.busy = %%-locator-get-by-role-option-busy-%%
-
 ## method: FrameLocator.getByTestId
 * since: v1.27
 - returns: <[Locator]>

diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
@@ -1488,8 +1488,6 @@ Attribute name to get the value for.
 
 ### option: Locator.getByRole.description = %%-locator-get-by-role-option-description-%%
 
-### option: Locator.getByRole.busy = %%-locator-get-by-role-option-busy-%%
-
 ## method: Locator.getByTestId
 * since: v1.27
 - returns: <[Locator]>

diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
@@ -2310,8 +2310,6 @@ Attribute name to get the value for.
 
 ### option: Page.getByRole.description = %%-locator-get-by-role-option-description-%%
 
-### option: Page.getByRole.busy = %%-locator-get-by-role-option-busy-%%
-
 ## method: Page.getByTestId
 * since: v1.27
 - returns: <[Locator]>

diff --git a/docs/src/api/params.md b/docs/src/api/params.md
@@ -1411,14 +1411,6 @@ Whether to find an exact match: case-sensitive and whole-string. Default to fals
 
 Required aria role.
 
-## locator-get-by-role-option-busy
-* since: v1.61
-- `busy` <[boolean]>
-
-An attribute that is usually set by `aria-busy`.
-
-Learn more about [`aria-busy`](https://www.w3.org/TR/wai-aria-1.2/#aria-busy).
-
 ## locator-get-by-role-option-checked
 * since: v1.27
 - `checked` <[boolean]>

diff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.md
@@ -517,11 +517,11 @@ export default defineConfig({
 
 ## property: TestConfig.retryStrategy
 * since: v1.62
-- type: ?<[RetryStrategy]<"immediate"|"deferred">>
+- type: ?<[RetryStrategy]<"immediate"|"isolated">>
 
 Controls when failed tests are retried. Defaults to `'immediate'`.
 * `'immediate'` - A failed test is retried as soon as a worker is available, interleaved with the rest of the run. This is the default.
-* `'deferred'` - Retries are run only after all tests have had their first attempt, in parallel up to the configured number of [workers](#test-config-workers).
+* `'isolated'` - Retries are run at the end, after all other tests have finished, one by one in a single worker. This minimizes the interference between retried tests and the rest of the suite, at the expense of the total run time.
 
 Learn more about [test retries](../test-retries.md#retries).
 
@@ -532,7 +532,7 @@ import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
   retries: 2,
-  retryStrategy: 'deferred',
+  retryStrategy: 'isolated',
 });
 ```
 

diff --git a/docs/src/test-reporter-api/class-reporter.md b/docs/src/test-reporter-api/class-reporter.md
@@ -298,25 +298,19 @@ Result of the test run.
 
 Whether this reporter uses stdio for reporting. When it does not, Playwright Test could add some output to enhance user experience. If your reporter does not print to the terminal, it is strongly recommended to return `false`.
 
-## optional async method: Reporter.preprocessSuite
-* since: v1.61
-- `result` ?<[Object]>
-  - `implementsSharding` ?<[boolean]> When `true`, Playwright skips its built-in shard filter for this run, leaving sharding to the reporter (typically implemented by calling [`method: TestCase.exclude`] on out-of-shard tests).
+## optional async method: Reporter.preprocess
+* since: v1.62
 
 Called after the configuration has been resolved and before [`method: Reporter.onBegin`]. Allows a reporter to mark individual tests as skipped, excluded, fixed or failing.
 
-### param: Reporter.preprocessSuite.config
-* since: v1.61
-- `config` <[FullConfig]>
-
-Resolved configuration.
-
-### param: Reporter.preprocessSuite.suite
-* since: v1.61
-- `suite` <[Suite]>
+### param: Reporter.preprocess.params
+* since: v1.62
+- `params` <[Object]>
+  - `config` <[FullConfig]> Resolved configuration.
+  - `suite` <[Suite]> The root suite that contains the projects, files and test cases that will run.
+  - `testRun` <[TestRun]> Control which tests will run and their expected status.
 
-The root suite that contains the projects, files and test cases that will run.
 
-The suite reflects `--project`, `--grep`/`--grep-invert` and `.only` filtering, so it only contains tests that match the current invocation. Setup and dependency projects are readonly and cannot be excluded from here.
+The suite reflects `--project`, `--grep`/`--grep-invert` and `.only` filtering, so it only contains tests that match the current invocation. Setup and dependency projects are readonly and cannot be changed through [TestRun].
 
-The suite ignores the `--shard` argument: it always contains the full, un-sharded corpus. Playwright applies its built-in sharding after [`method: Reporter.preprocessSuite`] returns, unless the returned `implementsSharding` is `true`.
+The suite ignores the `--shard` argument: it always contains the full, un-sharded corpus. Playwright applies its built-in sharding after [`method: Reporter.preprocess`] returns, unless the reporter calls [`method: TestRun.skipSharding`].
diff --git a/docs/src/test-reporter-api/class-suite.md b/docs/src/test-reporter-api/class-suite.md
@@ -85,41 +85,3 @@ Returns a list of titles from the root down to this suite.
 
 Returns the type of the suite. The Suites form the following hierarchy:
 `root` -> `project` -> `file` -> `describe` -> ...`describe` -> `test`.
-
-## method: Suite.skip
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`]. Mark every [TestCase] of this suite as skipped, see [`method: TestCase.skip`].
-
-### param: Suite.skip.reason
-* since: v1.61
-- `reason` ?<[string]>
-
-Optional explanation surfaced as the annotation description.
-
-## method: Suite.fixme
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`]. Mark every [TestCase] of this suite as fixme, see [`method: TestCase.fixme`].
-
-### param: Suite.fixme.reason
-* since: v1.61
-- `reason` ?<[string]>
-
-Optional explanation surfaced as the annotation description.
-
-## method: Suite.fail
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`]. Mark every [TestCase] of this suite as expected-to-fail, see [`method: TestCase.fail`].
-
-### param: Suite.fail.reason
-* since: v1.61
-- `reason` ?<[string]>
-
-Optional explanation surfaced as the annotation description.
-
-## method: Suite.exclude
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`], exclude this suite from the run. Excluded tests do not appear in the report and their body is not executed.
diff --git a/docs/src/test-reporter-api/class-testcase.md b/docs/src/test-reporter-api/class-testcase.md
@@ -107,41 +107,3 @@ Returns a list of titles from the root down to this test.
 - returns: <[TestCaseType]<"test">>
 
 Returns "test". Useful for detecting test cases in [`method: Suite.entries`].
-
-## method: TestCase.skip
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`], skip this test. The test body is not executed and the test is reported as skipped.
-
-### param: TestCase.skip.reason
-* since: v1.61
-- `reason` ?<[string]>
-
-Optional explanation surfaced as the annotation description.
-
-## method: TestCase.fixme
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`], mark this test as fixme. The test body is not executed and the test is reported as skipped, with the intention to fix it.
-
-### param: TestCase.fixme.reason
-* since: v1.61
-- `reason` ?<[string]>
-
-Optional explanation surfaced as the annotation description.
-
-## method: TestCase.fail
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`], mark this test as "should fail". Playwright runs the test and ensures it is actually failing, useful for documenting broken functionality until it is fixed.
-
-### param: TestCase.fail.reason
-* since: v1.61
-- `reason` ?<[string]>
-
-Optional explanation surfaced as the annotation description.
-
-## method: TestCase.exclude
-* since: v1.61
-
-Must be called from inside [`method: Reporter.preprocessSuite`], exclude this test from the run. Excluded tests do not appear in the report and their body is not executed.
diff --git a/docs/src/test-reporter-api/class-testrun.md b/docs/src/test-reporter-api/class-testrun.md
@@ -0,0 +1,72 @@
+# class: TestRun
+* 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.
+
+## method: TestRun.exclude
+* since: v1.62
+
+Excludes a test or suite from the run. Excluded tests do not appear in the report and their bodies are not executed.
+
+### param: TestRun.exclude.test
+* since: v1.62
+- `test` <[TestCase]|[Suite]>
+
+Test or suite to exclude. The root suite cannot be excluded.
+
+## method: TestRun.fail
+* since: v1.62
+
+Marks a test or every test in a suite as "should fail". Playwright runs the tests and ensures they are actually failing, useful for documenting broken functionality until it is fixed.
+
+### param: TestRun.fail.test
+* since: v1.62
+- `test` <[TestCase]|[Suite]>
+
+Test or suite to mark as expected-to-fail.
+
+### param: TestRun.fail.reason
+* since: v1.62
+- `reason` ?<[string]>
+
+Optional explanation surfaced as the annotation description.
+
+## method: TestRun.fixme
+* since: v1.62
+
+Marks a test or every test in a suite as fixme. The test bodies are not executed and the tests are reported as skipped, with the intention to fix them.
+
+### param: TestRun.fixme.test
+* since: v1.62
+- `test` <[TestCase]|[Suite]>
+
+Test or suite to mark as fixme.
+
+### param: TestRun.fixme.reason
+* since: v1.62
+- `reason` ?<[string]>
+
+Optional explanation surfaced as the annotation description.
+
+## method: TestRun.skip
+* since: v1.62
+
+Skips a test or every test in a suite. The test bodies are not executed and the tests are reported as skipped.
+
+### param: TestRun.skip.test
+* since: v1.62
+- `test` <[TestCase]|[Suite]>
+
+Test or suite to skip.
+
+### param: TestRun.skip.reason
+* since: v1.62
+- `reason` ?<[string]>
+
+Optional explanation surfaced as the annotation description.
+
+## method: TestRun.skipSharding
+* since: v1.62
+
+Disables Playwright's built-in shard filter for this run, leaving sharding to the reporter. Reporters typically implement their own sharding by calling [`method: TestRun.exclude`] on out-of-shard tests.
diff --git a/docs/src/test-reporter-api/class-teststep.md b/docs/src/test-reporter-api/class-teststep.md
@@ -2,7 +2,7 @@
 * since: v1.10
 * langs: js
 
-Represents a step in the [TestRun].
+Represents a step in a [TestResult].
 
 ## property: TestStep.category
 * since: v1.10

diff --git a/docs/src/test-reporters-js.md b/docs/src/test-reporters-js.md
@@ -275,6 +275,7 @@ HTML report supports the following configuration options and environment variabl
 | `PLAYWRIGHT_HTML_NO_COPY_PROMPT` | `noCopyPrompt` | If true, disable rendering of the Copy prompt for errors. Supports `true`, `1`, `false`, and `0`. | `false`
 | `PLAYWRIGHT_HTML_NO_SNIPPETS` | `noSnippets` | If true, disable rendering code snippets in the action log. If there is a top level error, that report section with code snippet will still render. Supports `true`, `1`, `false`, and `0`. | `false`
 | `PLAYWRIGHT_HTML_DO_NOT_INLINE_ASSETS` | `doNotInlineAssets` | If true, JavaScript, CSS and report data are written as separate files alongside `index.html` instead of being embedded inline. Use this when serving the report under a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) that disallows inline scripts and styles. Supports `true`, `1`, `false`, and `0`. | `false`
+| `PLAYWRIGHT_HTML_MERGE_FILES` | `mergeFiles` | If true, tests are grouped by their top-level `test.describe()` title instead of the file they belong to. Supports `true`, `1`, `false`, and `0`. | `false`
 
 ### Blob reporter
 

diff --git a/packages/html-reporter/src/headerView.tsx b/packages/html-reporter/src/headerView.tsx
@@ -26,7 +26,6 @@ import { filterWithQuery } from './filter';
 import { linkifyText } from '@web/renderUtils';
 import { Dialog } from '@web/shared/dialog';
 import { kThemeOptions, type Theme, useThemeSetting } from '@web/theme';
-import { useSetting } from '@web/uiUtils';
 
 export const HeaderView: React.FC<{
   title: string | undefined,
@@ -132,7 +131,6 @@ const SettingsButton: React.FC = () => {
   const settingsRef = React.useRef<HTMLDivElement>(null);
   const [settingsOpen, setSettingsOpen] = React.useState(false);
   const [theme, setTheme] = useThemeSetting();
-  const [mergeFiles, setMergeFiles] = useSetting('mergeFiles', false);
 
   return <>
     <div
@@ -165,11 +163,6 @@ const SettingsButton: React.FC = () => {
           ))}
         </select>
       </label>
-
-      <label style={{ cursor: 'pointer', display: 'flex', alignItems: 'center', gap: 4 }}>
-        <input type='checkbox' checked={mergeFiles} onChange={() => setMergeFiles(!mergeFiles)}></input>
-        Merge files
-      </label>
     </Dialog>
   </>;
 };

diff --git a/packages/html-reporter/src/reportView.tsx b/packages/html-reporter/src/reportView.tsx
@@ -26,7 +26,6 @@ import './reportView.css';
 import { TestCaseView } from './testCaseView';
 import { TestFilesHeader, TestFilesView } from './testFilesView';
 import './theme.css';
-import { useSetting } from '@web/uiUtils';
 import { Speedboard } from './speedboard';
 
 declare global {
@@ -54,7 +53,7 @@ export const ReportView: React.FC<{
   const [metadataVisible, setMetadataVisible] = React.useState(false);
   const [errorsVisible, setErrorsVisible] = React.useState(true);
   const speedboard = searchParams.has('speedboard');
-  const [mergeFiles] = useSetting('mergeFiles', false);
+  const mergeFiles = !!report?.json()?.options.mergeFiles;
   const testId = searchParams.get('testId');
   const q = searchParams.get('q')?.toString() || '';
   const filterParam = q ? '&q=' + q : '';

diff --git a/packages/html-reporter/src/types.d.ts b/packages/html-reporter/src/types.d.ts
@@ -40,6 +40,7 @@ export type HTMLReportOptions = {
   title?: string;
   noCopyPrompt?: boolean;
   noSnippets?: boolean;
+  mergeFiles?: boolean;
 };
 
 export type HTMLReport = {