docs: update docs about headless shell (#33604)
This commit is contained in:
Dmitry Gozman
GitHub
parent
31a2b7bbdc
commit
80ce205d81
|
|
@ -338,30 +338,85 @@ dotnet test --settings:webkit.runsettings
|
|||
|
||||
For Google Chrome, Microsoft Edge and other Chromium-based browsers, by default, Playwright uses open source Chromium builds. Since the Chromium project is ahead of the branded browsers, when the world is on Google Chrome N, Playwright already supports Chromium N+1 that will be released in Google Chrome and Microsoft Edge a few weeks later.
|
||||
|
||||
Playwright ships a regular Chromium build for headed operations and a separate [Chromium headless shell](https://developer.chrome.com/blog/chrome-headless-shell) for headless mode. These two behave differently in some edge cases, but the majority of testing scenarios are not affected. Note this behavior has changed in Playwright version 1.49, see [issue #33566](https://github.com/microsoft/playwright/issues/33566) for details.
|
||||
Playwright ships a regular Chromium build for headed operations and a separate [chromium headless shell](https://developer.chrome.com/blog/chrome-headless-shell) for headless mode. See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for details.
|
||||
|
||||
#### Save on download size
|
||||
#### Optimize download size on CI
|
||||
|
||||
If you are only running tests in headless, for example on CI, you can avoid downloading a headed version of Chromium by specifying `chromium-headless-shell` during installation.
|
||||
If you are only running tests in headless mode, for example on CI, you can avoid downloading a regular version of Chromium by passing `--only-shell` during installation.
|
||||
|
||||
```bash js
|
||||
# When only running tests headlessly
|
||||
npx playwright install chromium-headless-shell firefox webkit
|
||||
# only running tests headlessly
|
||||
npx playwright install --with-deps --only-shell
|
||||
```
|
||||
|
||||
```bash java
|
||||
# When only running tests headlessly
|
||||
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install chromium-headless-shell firefox webkit"
|
||||
# only running tests headlessly
|
||||
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps --only-shell"
|
||||
```
|
||||
|
||||
```bash python
|
||||
# When only running tests headlessly
|
||||
playwright install chromium-headless-shell firefox webkit
|
||||
# only running tests headlessly
|
||||
playwright install --with-deps --only-shell
|
||||
```
|
||||
|
||||
```bash csharp
|
||||
# When only running tests headlessly
|
||||
pwsh bin/Debug/netX/playwright.ps1 install chromium-headless-shell firefox webkit
|
||||
# only running tests headlessly
|
||||
pwsh bin/Debug/netX/playwright.ps1 install --with-deps --only-shell
|
||||
```
|
||||
|
||||
#### Opt-in to new headless mode
|
||||
|
||||
You can opt into the new headless mode by using `'chromium'` channel. As [official Chrome documentation puts it](https://developer.chrome.com/blog/chrome-headless-shell):
|
||||
|
||||
> New Headless on the other hand is the real Chrome browser, and is thus more authentic, reliable, and offers more features. This makes it more suitable for high-accuracy end-to-end web app testing or browser extension testing.
|
||||
|
||||
See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for details.
|
||||
|
||||
```js
|
||||
import { defineConfig, devices } from '@playwright/test';
|
||||
|
||||
export default defineConfig({
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { ...devices['Desktop Chrome'], channel: 'chromium' },
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
```java
|
||||
import com.microsoft.playwright.*;
|
||||
|
||||
public class Example {
|
||||
public static void main(String[] args) {
|
||||
try (Playwright playwright = Playwright.create()) {
|
||||
Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setChannel("chromium"));
|
||||
Page page = browser.newPage();
|
||||
// ...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash python
|
||||
pytest test_login.py --browser-channel chromium
|
||||
```
|
||||
|
||||
```xml csharp
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<RunSettings>
|
||||
<Playwright>
|
||||
<BrowserName>chromium</BrowserName>
|
||||
<LaunchOptions>
|
||||
<Channel>chromium</Channel>
|
||||
</LaunchOptions>
|
||||
</Playwright>
|
||||
</RunSettings>
|
||||
```
|
||||
|
||||
```bash csharp
|
||||
dotnet test -- Playwright.BrowserName=chromium Playwright.LaunchOptions.Channel=chromium
|
||||
```
|
||||
|
||||
### Google Chrome & Microsoft Edge
|
||||
|
|
|
|||
|
|
@ -40,61 +40,13 @@ Learn more in the [aria snapshots guide](./aria-snapshots).
|
|||
|
||||
### Breaking: `chrome` and `msedge` channels switch to new headless mode
|
||||
|
||||
Chromium recently introduced a new mode for [headless operation](https://developer.chrome.com/docs/chromium/headless). While Playwright was able to continue using the old, established mode in previous versions, the old mode got removed from the chromium binary and is now distributed separately.
|
||||
|
||||
|
||||
|
||||
To prevent breaking changes, Playwright continues making both modes available in the standard `chromium` channel for the foreseeable future by downloading both distributables.
|
||||
Since branded browser distributables are subject to the removal of the old mode, Playwright uses the new mode with them starting with this version. This keeps your tests running, but it comes with changes in behavior that might affect your test suite.
|
||||
|
||||
#### Am I affected?
|
||||
|
||||
This change affects you if you're using one of the following channels in your Playwright configuration:
|
||||
|
||||
This change affects you if you're using one of the following channels in your `playwright.config.ts`:
|
||||
- `chrome`, `chrome-dev`, `chrome-beta`, or `chrome-canary`
|
||||
- `msedge`, `msedge-dev`, `msedge-beta`, or `msedge-canary`
|
||||
|
||||
If your `playwright.config.ts` doesn't contain any `channel: '...'` options, or none of them specify one of the above channels, you're not affected by this change today.
|
||||
|
||||
#### What do I need to do?
|
||||
|
||||
After updating to Playwright 1.49, run your test suite. If it still passes, you're good to go. If not, you will probably need to update your snapshots, and adapt some of your test code around PDF viewers and extensions. See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for more details.
|
||||
|
||||
#### Saving CI resources
|
||||
|
||||
To keep both headless modes available, Playwright now downloads two different browser builds. One is regular headed chromium, and the other is a chromium headless shell. If you are running only headless tests, for example on CI, you can save resources by explictly specifying that you only need the headless shell:
|
||||
|
||||
```bash
|
||||
# only running tests headlessly
|
||||
npx playwright install chromium-headless-shell firefox webkit
|
||||
```
|
||||
|
||||
#### Opt-in to new headless mode
|
||||
|
||||
To prevent breaking changes in the future, we encourage you to try switching to the new headless mode today. You can do this by opting into the `chromium-next` channel.
|
||||
|
||||
First, install it prior to running tests.
|
||||
|
||||
```bash
|
||||
npx playwright install chromium-next firefox webkit # don't forget to list all browsers you use!
|
||||
```
|
||||
|
||||
Then update your config file to specify the `'chromium-next'` channel.
|
||||
|
||||
```js
|
||||
import { defineConfig, devices } from '@playwright/test';
|
||||
export default defineConfig({
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: {
|
||||
...devices['Desktop Chrome'],
|
||||
channel: 'chromium-next',
|
||||
},
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
After updating to Playwright v1.49, run your test suite. If it still passes, you're good to go. If not, you will probably need to update your snapshots, and adapt some of your test code around PDF viewers and extensions. See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for more details.
|
||||
|
||||
### Other breaking changes
|
||||
|
||||
|
|
@ -102,6 +54,27 @@ export default defineConfig({
|
|||
- Package `@playwright/experimental-ct-vue2` will no longer be updated.
|
||||
- Package `@playwright/experimental-ct-solid` will no longer be updated.
|
||||
|
||||
### Try new Chromium headless
|
||||
|
||||
You can opt into the new headless mode by using `'chromium'` channel. As [official Chrome documentation puts it](https://developer.chrome.com/blog/chrome-headless-shell):
|
||||
|
||||
> New Headless on the other hand is the real Chrome browser, and is thus more authentic, reliable, and offers more features. This makes it more suitable for high-accuracy end-to-end web app testing or browser extension testing.
|
||||
|
||||
See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for the list of possible breakages you could encounter and more details on Chromium headless. Please file an issue if you see any problems after opting in.
|
||||
|
||||
```js
|
||||
import { defineConfig, devices } from '@playwright/test';
|
||||
|
||||
export default defineConfig({
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { ...devices['Desktop Chrome'], channel: 'chromium' },
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
### Miscellaneous
|
||||
|
||||
- `<canvas>` elements inside a snapshot now draw a preview.
|
||||
|
|
|
|||
Loading…
Reference in New Issue