Changes in Chromium headless in Playwright v1.49

[dgozman]

Changes in Chromium headless in Playwright v1.49

Summary

• Chromium switches to new headless implementation.
• Users of channels chrome, msedge and similar are affected and will have to update the test suite.
• No action needed if you are not using browser channels.
• Playwright runs a separate chromium headless shell build for headless operation.

Breaking: channels chrome, msedge and similar will use new headless

With the removal of the old headless mode from Chromium, new version of Google Chrome and Microsoft Edge will only include the new headless mode. If you are using chrome, msedge or a similar browser channel, you will be affected.

Here are the largest areas that will need your attention:

• PDF documents are now rendered in the page, instead of being downloaded. We recommend to update your tests accordingly.
• Screenshots are different. We recommend to update all screenshot expectations.
• New headless is slightly slower on average in our testing. Note that it can be faster or slower on your particular test suite.
• GPU/WebGL availability, features and performance will vary.

If you encounter more cases where the new headless behaves differently from the old headless, please file an issue, and we'll carefully look into it.

Headless mode explained

Note that if you were testing in headless mode before, you were not actually running exactly the same browser as actual users. As headless documentation puts it:

Previously, Headless mode was a separate, alternate browser implementation that happened to be shipped as part of the same Chrome binary.

This means that headless was essentially a different browser. The web content was rendered in the same way, so there should have been no difference for testing a web page in the vast majority of cases. However, there were some differences, for example plugins, screenshots, pdf viewer, extensions, and more.

For a few releases now, Chromium had included a new headless implementation that is closer to a headed browser, instead of a separate headless browser. You can read the official explanation here. In a recent release, Chromium has completely switched to the new implementation, and removed the old one.

Chromium headless shell

Now that old headless mode is unavailable, Playwright additionally ships a separate browser build chromium-headless-shell that closely follows the old headless mode. You can read official Chromium documentation for more details.

This change should be transparent to you, there's no action needed. Playwright will automatically pick between headed and headless browser builds.

Download size

Note that download size increases, because Playwright now downloads both headed and headless builds by default.

However, you can mitigate this if you only run tests in headless mode, for example on CI. Simply update your download command as below.

# before
npx playwright install

# after for headless-only tests
npx playwright install --only-shell

Playwright will skip downloading headed chromium build, and will use chromium-headless-shell when running headless.

Opt-in to new headless

We encourage everyone to try and switch to the new headless. As official Chrome documentation puts it:

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.

Switching to new headless mode gives you a browser that closely follows the regular headed browser, at the cost of being a bit heavier on features you probably do not need and being slightly slower.

See the list of known breaking changes above. If you encounter issues when switching to new headless, please file an issue.

To switch, simply put channel: 'chromium' in your config file:

import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        channel: 'chromium',
      },
    },
  ],
});

Additionally, you can avoid downloading the chromium headless shell build to optimize your CI:

# before
npx playwright install

# after for new headless mode
npx playwright install --no-shell