docs: document how to enable new Chromium headless mode in Playwright provider

[Copilot]

Playwright's new Chromium headless mode uses the real Chrome browser instead of a dedicated headless shell, offering more authentic and reliable test execution. This wasn't documented in Vitest's Playwright provider docs.

Changes

• Added a tip block under launchOptions in docs/config/browser/playwright.md explaining how to opt into the new headless mode via launchOptions.channel: 'chromium'

provider: playwright({
  launchOptions: {
    channel: 'chromium',
  },
}),

No default behavior is changed — this is opt-in via config.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Enable new Playwright/Chromium headless mode by default</issue_title>
<issue_description>### Clear and concise description of the problem

I'm happy to create a PR for this change if agreed to.

Playwright has a new headless mode for Chromium, which no longer requires installing the special headless build of Chromium - enabling faster installs on CI, and locally with --no-shell. It's also meant to be better in a number of ways:

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.

https://playwright.dev/docs/browsers#chromium-new-headless-mode

Suggested solution

Right now, I can get this working with this config change, but I think it should just be the default behaviour for headless: true when using supported versions of Playwright.

defineConfig({
  test: {
    browser: {
      provider: playwright({
        launchOptions: { args: ["--headless=new"] },
      }),
      enabled: true,
      // Must be disabled
      // headless: true,
      instances: [{ browser: "chromium" }],
    },
  },
});

Alternative

No response

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that requests the same feature to avoid creating a duplicate.</issue_description>

<agent_instructions>We don't want to change the default, but we want to document how to enable the chromium channel in playwright. Please, add a section in playwright.md on how to enable the new headless mode (by setting laucnhOptions.channel)</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@sheremet-va > Right now, I can get this working with this config change, but I think it should just be the default behaviour for `headless: true` when using supported versions of Playwright.

Shouldn't you use a channel instead?

defineConfig({
  test: {
    browser: {
      provider: playwright({
        launchOptions: { channel: 'chromium' },
      }),
      enabled: true,
      // Must be disabled
      // headless: true,
      instances: [{ browser: "chromium" }],
    },
  },
});

Based on the same link:

You can opt into the new headless mode by using 'chromium' channel. As official Chrome documentation puts it:</comment_new>
<comment_new>@hi-ogawa
I don't think we should change the default. Probably we can wait playwright does that and then follow. From the look of microsoft/playwright#33566, it's supposed to be a breaking change affecting screenshot at least.</comment_new>
<comment_new>@sheremet-va
I would default to what playwright defaults to depending on its version (vitest supports many playwright versions).

Chomium channel is already supported and can be configured with launchOptions.channel, but maybe it should be properly documented on our side.</comment_new>

• Fixes Enable new Playwright/Chromium headless mode by default #9840

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[netlify]

✅ Deploy Preview for vitest-dev ready!

Name	Link
🔨 Latest commit	d301a06
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69c50b7f7172d80008f394a9
😎 Deploy Preview	https://deploy-preview-9974--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[mrmckeb]

Thanks @sheremet-va!