feat: make playwright package not install browsers automatically (m…

…icrosoft#26672)

Additionally introduce `@playwright/browser-<browser>` packages that
just download the respective browser, but do not export anything.

References microsoft#26614.

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

docs/src/library-js.md

@@ -99,8 +99,8 @@ The key differences to note are as follows:
 | | Library | Test |
 | - | - | - |
 | Installation | `npm install playwright` | `npm init playwright@latest` - note `install` vs. `init` |
-| Install browsers | Chromium, Firefox, WebKit are installed by default | `npx playwright install` or `npx playwright install chromium` for a single one |
-| `import`/`require` name | `playwright` | `@playwright/test` |
+| Install browsers | Install `@playwright/browser-chromium`, `@playwright/browser-firefox` and/or `@playwright/browser-webkit` | `npx playwright install` or `npx playwright install chromium` for a single one |
+| `import` from | `playwright` | `@playwright/test` |
 | Initialization | Explicitly need to: <ol><li>Pick a browser to use, e.g. `chromium`</li><li>Launch browser with [`method: BrowserType.launch`]</li><li>Create a context with [`method: Browser.newContext`], <em>and</em> pass any context options explicitly, e.g. `devices['iPhone 11']`</li><li>Create a page with [`method: BrowserContext.newPage`]</li></ol> | An isolated `page` and `context` are provided to each test out-of the box, along with other [built-in fixtures](./test-fixtures.md#built-in-fixtures). No explicit creation. If referenced by the test in it's arguments, the Test Runner will create them for the test. (i.e. lazy-initialization) |
 | Assertions | No built-in Web-First Assertions | [Web-First assertions](./test-assertions.md) like: <ul><li>[`method: PageAssertions.toHaveTitle`]</li><li>[`method: PageAssertions.toHaveScreenshot#1`]</li></ul> which auto-wait and retry for the condition to be met.|
 | Cleanup | Explicitly need to: <ol><li>Close context with [`method: BrowserContext.close`]</li><li>Close browser with [`method: Browser.close`]</li></ol> | No explicit close of [built-in fixtures](./test-fixtures.md#built-in-fixtures); the Test Runner will take care of it.
@@ -124,9 +124,19 @@ Use npm or Yarn to install Playwright library in your Node.js project. See [syst
 npm i -D playwright
 ```
 
-This single command downloads the Playwright NPM package and browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [managing browsers](./browsers.md#managing-browser-binaries).
+You will also need to install browsers - either manually or by adding a package that will do it for you automatically.
 
-Once installed, you can `require` Playwright in a Node.js script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
+```bash
+# Download the Chromium, Firefox and WebKit browser
+npx playwright install chromium firefox webkit
+
+# Alternatively, add packages that will download a browser upon npm install
+npm i -D @playwright/browser-chromium @playwright/browser-firefox @playwright/browser-webkit
+```
+
+See [managing browsers](./browsers.md#managing-browser-binaries) for more options.
+
+Once installed, you can import Playwright in a Node.js script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
 
 ```js
 const { chromium } = require('playwright');
@@ -179,25 +189,114 @@ npx playwright codegen wikipedia.org
 
 ## Browser downloads
 
-By default, `playwright` automatically downloads Chromium, Firefox and WebKit during package installation.
+To download Playwright browsers run:
+
+```bash
+# Explicitly download browsers
+npx playwright install
+```
+
+Alternatively, you can add `@playwright/browser-chromium`, `@playwright/browser-firefox` and `@playwright/browser-webkit` packages to automatically download the respective browser during the package installation.
+
+```bash
+# Use a helper package that downloads a browser on npm install
+npm install @playwright/browser-chromium
+```
+
+**Download behind a firewall or a proxy**
+
+Pass `HTTPS_PROXY` environment variable to download through a proxy.
+
+```bash tab=bash-bash lang=js
+# Manual
+HTTPS_PROXY=https://192.0.2.1 npx playwright install
+
+# Through @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
+HTTPS_PROXY=https://192.0.2.1 npm install
+```
+
+```batch tab=bash-batch lang=js
+# Manual
+set HTTPS_PROXY=https://192.0.2.1
+npx playwright install
+
+# Through @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
+set HTTPS_PROXY=https://192.0.2.1
+npm install
+```
+
+```powershell tab=bash-powershell lang=js
+# Manual
+$Env:HTTPS_PROXY=https://192.0.2.1
+npx playwright install
+
+# Through @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
+$Env:HTTPS_PROXY=https://192.0.2.1
+npm install
+```
+
+**Download from artifact repository**
+
+By default, Playwright downloads browsers from Microsoft's CDN. Pass `PLAYWRIGHT_DOWNLOAD_HOST` environment variable to download from an internal artifacts repository instead.
+
+```bash tab=bash-bash lang=js
+# Manual
+PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install
+
+# Through @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
+PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm install
+```
+
+```batch tab=bash-batch lang=js
+# Manual
+set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
+npx playwright install
+
+# Through @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
+set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
+npm install
+```
+
+```powershell tab=bash-powershell lang=js
+# Manual
+$Env:PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
+npx playwright install
+
+# Through @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
+$Env:PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
+npm install
+```
+
+**Skip browser download**
 
 In certain cases, it is desired to avoid browser downloads altogether because browser binaries are managed separately. This can be done by setting `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` variable before installing packages.
 
 ```bash tab=bash-bash lang=js
+# When using @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
 ```
 
 ```batch tab=bash-batch lang=js
+# When using @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
 set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
 npm install
 ```
 
 ```powershell tab=bash-powershell lang=js
+# When using @playwright/browser-chromium, @playwright/browser-firefox
+# and @playwright/browser-webkit helper packages
 $Env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
 npm install
 ```
 
-
 ## TypeScript support
 
 Playwright includes built-in support for TypeScript. Type definitions will be imported automatically. It is recommended to use type-checking to improve the IDE experience.

packages/playwright-browser-chromium/README.md

@@ -0,0 +1,3 @@
+# @playwright/browser-chromium
+
+This package automatically installs [Chromium](https://www.chromium.org/) browser for [Playwright](http://github.com/microsoft/playwright) library. If you want to write end-to-end tests, we recommend [@playwright/test](https://playwright.dev/docs/intro).

packages/playwright-browser-chromium/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+
+export {};

packages/playwright-browser-chromium/index.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */