[pull] main from microsoft:main

.github/workflows/create_test_report.yml

@@ -121,6 +121,7 @@ jobs:
               title: 'Test results for "${{ github.event.workflow_run.name }}"',
               summary: [
                 reportMd,
+                '',
                 '---',
                 `Full [HTML report](${reportUrl}). Merge [workflow run](${mergeWorkflowUrl}).`
               ].join('\n'),

.github/workflows/tests_primary.yml

@@ -158,10 +158,26 @@ jobs:
       env:
         DEBUG: pw:install
     - run: npm run build
+
     - run: npx playwright install --with-deps
     - run: npm run test-html-reporter
+      env:
+        PWTEST_BLOB_REPORT_NAME: "web-components-html-reporter"
+    - name: Upload blob report
+      if: always()
+      uses: ./.github/actions/upload-blob-report
+      with:
+        report_dir: packages/html-reporter/blob-report
+
     - run: npm run test-web
       if: always()
+      env:
+        PWTEST_BLOB_REPORT_NAME: "web-components-web"
+    - name: Upload blob report
+      if: always()
+      uses: ./.github/actions/upload-blob-report
+      with:
+        report_dir: packages/web/blob-report
 
   test_vscode_extension:
     name: VSCode Extension
@@ -189,9 +205,16 @@ jobs:
       working-directory: ./playwright-vscode
     - name: Run extension tests
       run: npm run test -- --workers=1
+      env:
+        PWTEST_BLOB_REPORT_NAME: "vscode-extension"
       working-directory: ./playwright-vscode
+    - name: Upload blob report
+      if: always()
+      uses: ./.github/actions/upload-blob-report
+      with:
+        report_dir: ./playwright-vscode/blob-report
 
-  test-package-installations:
+  test_package_installations:
     name: "Installation Test ${{ matrix.os }}"
     runs-on: ${{ matrix.os  }}
     strategy:
@@ -214,8 +237,17 @@ jobs:
     - run: npx playwright install-deps
     - run: npm run itest
       if: matrix.os != 'ubuntu-latest'
+      env:
+        PWTEST_BLOB_REPORT_NAME: "package-installations-${{ matrix.os }}"
     - run: xvfb-run --auto-servernum --server-args="-screen 0 1280x960x24" -- npm run itest
       if: matrix.os == 'ubuntu-latest'
+      env:
+        PWTEST_BLOB_REPORT_NAME: "package-installations-${{ matrix.os }}"
     - run: ./utils/upload_flakiness_dashboard.sh ./test-results/report.json
       if: always()
       shell: bash
+    - name: Upload blob report
+      if: always()
+      uses: ./.github/actions/upload-blob-report
+      with:
+        report_dir: blob-report

CONTRIBUTING.md

@@ -15,6 +15,8 @@
 
 ## How to Contribute
 
+We strongly recommend that you open an issue before beginning any code modifications. This is particularly important if the changes involve complex logic or if the existing code isn't immediately clear. By doing so, we can discuss and agree upon the best approach to address a bug or implement a feature, ensuring that our efforts are aligned.
+
 ### Getting Code
 
 Make sure you're running Node.js 16+ and NPM 8+, to verify and upgrade NPM do:

README.md

@@ -1,14 +1,14 @@
 # 🎭 Playwright
 
-[![npm version](https://img.shields.io/npm/v/playwright.svg)](https://www.npmjs.com/package/playwright) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-116.0.5845.82-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-115.0-blue.svg?logo=firefoxbrowser)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> <!-- GEN:webkit-version-badge -->[![WebKit version](https://img.shields.io/badge/webkit-17.0-blue.svg?logo=safari)](https://webkit.org/)<!-- GEN:stop -->
+[![npm version](https://img.shields.io/npm/v/playwright.svg)](https://www.npmjs.com/package/playwright) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-117.0.5938.22-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-115.0-blue.svg?logo=firefoxbrowser)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> <!-- GEN:webkit-version-badge -->[![WebKit version](https://img.shields.io/badge/webkit-17.0-blue.svg?logo=safari)](https://webkit.org/)<!-- GEN:stop -->
 
 ## [Documentation](https://playwright.dev) | [API reference](https://playwright.dev/docs/api/class-playwright)
 
 Playwright is a framework for Web Testing and Automation. It allows testing [Chromium](https://www.chromium.org/Home), [Firefox](https://www.mozilla.org/en-US/firefox/new/) and [WebKit](https://webkit.org/) with a single API. Playwright is built to enable cross-browser web automation that is **ever-green**, **capable**, **reliable** and **fast**.
 
 |          | Linux | macOS | Windows |
 |   :---   | :---: | :---: | :---:   |
-| Chromium <!-- GEN:chromium-version -->116.0.5845.82<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| Chromium <!-- GEN:chromium-version -->117.0.5938.22<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 | WebKit <!-- GEN:webkit-version -->17.0<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 | Firefox <!-- GEN:firefox-version -->115.0<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 

docs/src/api/class-snapshotassertions.md

@@ -2,20 +2,75 @@
 * since: v1.20
 * langs: js
 
-Playwright provides methods for comparing page and element screenshots with
-expected values stored in files.
+:::tip
+For visual regression testing, use [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`] instead.
+:::
+
+Playwright provides methods for comparing text values with expected values stored in snapshot files.
 
 ```js
-expect(screenshot).toMatchSnapshot('landing-page.png');
+expect(text).toMatchSnapshot('snapshot.txt');
 ```
 
 ## method: SnapshotAssertions.toMatchSnapshot#1
 * since: v1.22
 
+Ensures that the passed [string] matches the expected snapshot stored in the test snapshots directory.
+
+**Usage**
+
+```js
+// Basic usage.
+expect(await page.title()).toMatchSnapshot('page-title.txt');
+
+// Bring some structure to your snapshot files by passing file path segments.
+expect(await page.title()).toMatchSnapshot(['page-title', 'step1.txt']);
+expect(await page.title()).toMatchSnapshot(['page-title', 'step2.txt']);
+```
+
+Note that matching snapshots only work with Playwright test runner.
+
+### param: SnapshotAssertions.toMatchSnapshot#1.name
+* since: v1.22
+- `name` <[string]|[Array]<[string]>>
+
+Snapshot name.
+
+## method: SnapshotAssertions.toMatchSnapshot#2
+* since: v1.22
+
 Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test snapshots directory.
 
 **Usage**
 
+```js
+// Basic usage.
+expect(await page.title()).toMatchSnapshot();
+
+// Configure the snapshot name.
+expect(await page.title()).toMatchSnapshot({
+  name: 'page-title.txt',
+});
+```
+
+Note that matching snapshots only work with Playwright test runner.
+
+### option: SnapshotAssertions.toMatchSnapshot#2.name
+* since: v1.22
+- `name` <[string]|[Array]<[string]>>
+
+Snapshot name. If not passed, the test name and ordinals are used when called multiple times.
+
+
+
+## method: SnapshotAssertions.toMatchSnapshot#3
+* deprecated: To avoid flakiness, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
+* since: v1.22
+
+Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
+
+**Usage**
+
 ```js
 // Basic usage.
 expect(await page.screenshot()).toMatchSnapshot('landing-page.png');
@@ -37,25 +92,26 @@ Learn more about [visual comparisons](../test-snapshots.md).
 
 Note that matching snapshots only work with Playwright test runner.
 
-### param: SnapshotAssertions.toMatchSnapshot#1.name
+### param: SnapshotAssertions.toMatchSnapshot#3.name
 * since: v1.22
 - `name` <[string]|[Array]<[string]>>
 
 Snapshot name.
 
-### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixels = %%-assertions-max-diff-pixels-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#1.threshold = %%-assertions-threshold-%%
+### option: SnapshotAssertions.toMatchSnapshot#3.threshold = %%-assertions-threshold-%%
 * since: v1.22
 
-## method: SnapshotAssertions.toMatchSnapshot#2
+## method: SnapshotAssertions.toMatchSnapshot#4
+* deprecated: To avoid flakiness, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
 * since: v1.22
 
-Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test snapshots directory.
+Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
 
 **Usage**
 
@@ -79,17 +135,18 @@ Learn more about [visual comparisons](../test-snapshots.md).
 
 Note that matching snapshots only work with Playwright test runner.
 
-### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixels = %%-assertions-max-diff-pixels-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#2.name
+### option: SnapshotAssertions.toMatchSnapshot#4.name
 * since: v1.22
 - `name` <[string]|[Array]<[string]>>
 
 Snapshot name. If not passed, the test name and ordinals are used when called multiple times.
 
-### option: SnapshotAssertions.toMatchSnapshot#2.threshold = %%-assertions-threshold-%%
+### option: SnapshotAssertions.toMatchSnapshot#4.threshold = %%-assertions-threshold-%%
 * since: v1.22
+

docs/src/best-practices-js.md

@@ -288,7 +288,7 @@ npx playwright test --shard=1/3
 
 ### Use Soft assertions
 
-If your test fails, Playwright will give you an error message showing what part of the test failed which you can see either in VS Code, the terminal, the HTML report, or the trace viewer. However, you can also use [soft assertions](/test-assertions.md#soft-assertions) these do not immediately terminate the test execution, but rather compile and display a list of failed assertions once the test ended.
+If your test fails, Playwright will give you an error message showing what part of the test failed which you can see either in VS Code, the terminal, the HTML report, or the trace viewer. However, you can also use [soft assertions](/test-assertions.md#soft-assertions). These do not immediately terminate the test execution, but rather compile and display a list of failed assertions once the test ended.
 
 ```js
 // Make a few checks that will not stop the test when failed...

docs/src/browsers.md

@@ -468,31 +468,17 @@ Sometimes companies maintain an internal proxy that blocks direct access to the
 resources. In this case, Playwright can be configured to download browsers via a proxy server.
 
 ```bash tab=bash-bash lang=js
-# For Playwright Test
 HTTPS_PROXY=https://192.0.2.1 npx playwright install
-
-# For Playwright Library
-HTTPS_PROXY=https://192.0.2.1 npm install playwright
 ```
 
 ```batch tab=bash-batch lang=js
-# For Playwright Test
 set HTTPS_PROXY=https://192.0.2.1
 npx playwright install
-
-# For Playwright Library
-set HTTPS_PROXY=https://192.0.2.1
-npm install playwright
 ```
 
 ```powershell tab=bash-powershell lang=js
-# For Playwright Test
 $Env:HTTPS_PROXY="https://192.0.2.1"
 npx playwright install
-
-# For Playwright Library
-$Env:HTTPS_PROXY="https://192.0.2.1"
-npm install playwright
 ```
 
 ```bash tab=bash-bash lang=python
@@ -614,6 +600,7 @@ pwsh bin/Debug/netX/playwright.ps1 install
 $Env:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT="120000"
 pwsh bin/Debug/netX/playwright.ps1 install
 ```
+
 ## Download from artifact repository
 
 By default, Playwright downloads browsers from Microsoft's CDN.
@@ -623,31 +610,17 @@ binaries. In this case, Playwright can be configured to download from a custom
 location using the `PLAYWRIGHT_DOWNLOAD_HOST` env variable.
 
 ```bash tab=bash-bash lang=js
-# For Playwright Test
 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install
-
-# For Playwright Library
-PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm install playwright
 ```
 
 ```batch tab=bash-batch lang=js
-# For Playwright Test
 set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
 npx playwright install
-
-# For Playwright Library
-set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
-npm install playwright
 ```
 
 ```powershell tab=bash-powershell lang=js
-# For Playwright Test
 $Env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
 npx playwright install
-
-# For Playwright Library
-$Env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
-npm install playwright
 ```
 
 ```bash tab=bash-bash lang=python
@@ -699,35 +672,19 @@ It is also possible to use a per-browser download hosts using `PLAYWRIGHT_CHROMI
 take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`.
 
 ```bash tab=bash-bash lang=js
-# For Playwright Test
 PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install
-
-# For Playwright Library
-PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm install playwright
 ```
 
 ```batch tab=bash-batch lang=js
-# For Playwright Test
 set PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3
 set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
 npx playwright install
-
-# For Playwright Library
-set PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3
-set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
-npm install playwright
 ```
 
 ```powershell tab=bash-powershell lang=js
-# For Playwright Test
 $Env:PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST="203.0.113.3"
 $Env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
 npx playwright install
-
-# For Playwright Library
-$Env:PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST="203.0.113.3"
-$Env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
-npm install playwright
 ```
 
 ```bash tab=bash-bash lang=python