Support Headless Mode for Vitest Runner Integration

[alan-agius4]

Command

test

Description

Currently, the new Vitest runner does not support running tests in browsers in headless mode.

Describe the solution you'd like

An option to run tests in a headless mode.

[teoeter]

Headless mode is currently supported only for karma via browsers: [ 'ChromeHeadless', 'FirefoxHeadless' ]. However, it is not supported for Vitest browser mode. See Headless for more information.

Ideas:

Solution 1:

This solution is compatible with how Karma handles headless mode, allowing for migration without configuration changes:

"options": {
  "tsConfig": "tsconfig.spec.json",
  "buildTarget": "::development",
  "runner": "vitest",
  "browsers": ["ChromiumHeadless"]
}

Solution 2:

Introduce a new headless property in the schema. This approach is not compatible with Karma without a breaking API change:

"options": {
  "tsConfig": "tsconfig.spec.json",
  "buildTarget": "::development",
  "runner": "vitest",
  "headless": true,
  "browsers": ["chromium"]
}

The issue with Solution 2 is that it is not compatible with Karma, which uses 'ChromiumHeadless' / 'FirefoxHeadless' to enable headless mode.

A PoC for Solution 1 is in the following PR:
#30685

[wein2011]

An alternative or additional option would be to extend the browsers property to not only accept:

"browsers": ["chromium"]

but also:

"browsers": [["chromium", { headless: true }]]
"browsers": [["chromium", { headless: true, viewport: { width: 1920, height: 1080 } }]]

The additional properties are properties of the browser.instance.

This would allow the user to not only configure headless but configure all the available browser options

https://vitest.dev/guide/browser/config.html#browser-instances

browser.headless
browser.locators
browser.viewport
browser.testerHtmlPath
browser.screenshotDirectory
browser.screenshotFailures

In our case, we have to configure both headless and viewport.

This pattern would follow the pattern of the new code coverage reporters property:

codeCoverage: {
   exclude: string[] | undefined;
   reporters: [string, Record<string, unknown>][] | undefined;
} | undefined;

[teoeter]

Karma browsers - Possible Values:

Chrome (launcher requires karma-chrome-launcher plugin)
ChromeCanary (launcher requires karma-chrome-launcher plugin)
ChromeHeadless (launcher requires karma-chrome-launcher plugin ^2.1.0)
PhantomJS (launcher requires karma-phantomjs-launcher plugin)
Firefox (launcher requires karma-firefox-launcher plugin)
Opera (launcher requires karma-opera-launcher plugin)
IE (launcher requires karma-ie-launcher plugin)
Safari (launcher requires karma-safari-launcher plugin)

---

Vitest

webdriverio supports these browsers:
firefox
chrome
edge
safari

playwright supports these browsers:
firefox
webkit
chromium

The viewport would be a bit hard to make it compatible with karma so probably out of scope for this ticket ?

if karma browsers are used it will be easier to migrate. The vitest API is better and it can be ported to karma but it will prevent auto config migration to vitest of karma configs by just changing the runner.

Third way is to stick to a standardized browserlist and then convert it to vitest or karma via method factory. This would be the cleanest way so:

1. compatibility (karma first) - keep the current format and convert to vitest config - easier migration to vitest
2. tradeoff (vitest first) - we take the vitest headless:true api and the pragmatic browser list and convert karma to it
3. clean API - first - new clean API with a standardized browserlist and headless: true (issue not al browsers support it)