feat: add setBrowserConfig universal hook

One call to apply a bag of overrides — `browser`, `show`, `windowSize` are
dispatched through their dedicated hooks so per-helper key translation is
correct (Puppeteer gets `product` instead of `browser`, WebDriver gets
`--headless` injected/stripped, etc). Any other key is shallow-merged onto
every browser helper present in config.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DavertMik

CHANGELOG.md

@@ -1,6 +1,7 @@
 4.0.0
 
 * ESM-only release targeting CodeceptJS 4.x. Convert package + all hooks + bridge to native ESM (`type: module`).
+* Added `setBrowserConfig({ browser, show, windowSize, ... })` — universal helper that dispatches options through the right primitive (so Puppeteer gets `product`, Playwright gets `browser`, WebDriver gets `--headless` chrome args, etc.) and shallow-merges any extra keys onto every browser helper.
 * Fix Config singleton sharing: bridge now imports `codeceptjs` via ESM, so hooks register on the host's Config instance instead of a stale CJS-resolved copy.
 * Mark the `codeceptjs` peer dependency as optional so npm doesn't pull a parallel 3.x copy alongside a 4.x host.
 * Drop the `tryTo` / `retryTo` plugin enable in `setCommonPlugins` — in CodeceptJS 4 those are imported from `codeceptjs/effects`, not enabled as plugins.

README.md

@@ -145,6 +145,21 @@ exports.config = {
 }
 ```
 
+### setBrowserConfig
+
+Apply a bag of browser-helper overrides in one call. Routes `browser`, `show`, and `windowSize` through their dedicated hooks (so per-helper key translation like Puppeteer's `product` vs Playwright's `browser`, and WebDriver `--headless` capability args, are handled correctly). Any other key is shallow-merged onto every browser helper present in config.
+
+```js
+import { setBrowserConfig } from '@codeceptjs/configure'
+
+setBrowserConfig({
+  browser: process.env.BROWSER,        // -> setBrowser
+  show: !process.env.HEADLESS,         // -> setHeadedWhen / setHeadlessWhen
+  windowSize: '1280x720',              // -> setWindowSize
+  waitForTimeout: 10000,               // -> merged onto each helper
+})
+```
+
 ### setTestHost
 
 Changes url in config for Playwright, Puppeteer, WebDriver & TestCafe:

hooks/setBrowserConfig.js

@@ -0,0 +1,52 @@
+import { config } from '../codeceptjs.js'
+import setBrowser from './setBrowser.js'
+import setWindowSize from './setWindowSize.js'
+import setHeadedWhen from './setHeadedWhen.js'
+import setHeadlessWhen from './setHeadlessWhen.js'
+
+const BROWSER_HELPERS = ['Playwright', 'Puppeteer', 'WebDriver', 'Appium', 'TestCafe', 'Protractor', 'Nightmare']
+
+/**
+ * Apply a bag of browser helper overrides in a single call. Dispatches the
+ * options that have dedicated hooks (browser, show, windowSize) through them
+ * — so per-helper key translation (e.g. Puppeteer `product` vs Playwright
+ * `browser`) and capability-arg surgery (WebDriver `--headless` chrome args)
+ * are handled correctly. Anything else is shallow-merged onto every browser
+ * helper present in config.
+ *
+ * @example
+ *   setBrowserConfig({
+ *     browser: process.env.BROWSER,        // -> setBrowser
+ *     show: !process.env.HEADLESS,         // -> setHeadedWhen / setHeadlessWhen
+ *     windowSize: '1280x720',              // -> setWindowSize
+ *     waitForTimeout: 10000,               // -> Object.assign onto each helper
+ *   })
+ *
+ * @param {object} [opts]
+ */
+export default function setBrowserConfig(opts) {
+  if (!opts || typeof opts !== 'object') return
+
+  const { browser, show, windowSize, ...rest } = opts
+
+  if (browser !== undefined && browser !== null && browser !== '') {
+    setBrowser(browser)
+  }
+
+  if (show === true) setHeadedWhen(true)
+  else if (show === false) setHeadlessWhen(true)
+
+  if (windowSize) {
+    const m = /^(\d+)x(\d+)$/.exec(String(windowSize))
+    if (m) setWindowSize(Number(m[1]), Number(m[2]))
+  }
+
+  if (Object.keys(rest).length === 0) return
+
+  config.addHook(cfg => {
+    if (!cfg.helpers) return
+    for (const helperName of BROWSER_HELPERS) {
+      if (cfg.helpers[helperName]) Object.assign(cfg.helpers[helperName], rest)
+    }
+  })
+}

index.js

@@ -3,5 +3,6 @@ export { default as setHeadedWhen } from './hooks/setHeadedWhen.js'
 export { default as setSharedCookies } from './hooks/setSharedCookies.js'
 export { default as setWindowSize } from './hooks/setWindowSize.js'
 export { default as setBrowser } from './hooks/setBrowser.js'
+export { default as setBrowserConfig } from './hooks/setBrowserConfig.js'
 export { default as setTestHost } from './hooks/setTestHost.js'
 export { default as setCommonPlugins } from './hooks/setCommonPlugins.js'

test/index.test.js

@@ -7,6 +7,7 @@ import {
   setSharedCookies,
   setWindowSize,
   setBrowser,
+  setBrowserConfig,
   setTestHost,
   setCommonPlugins,
 } from '../index.js'
@@ -161,6 +162,77 @@ describe('Hooks tests', () => {
     }
   })
 
+  describe('#setBrowserConfig', () => {
+    test('no-ops when called with no args / non-object', () => {
+      Config.reset()
+      const config = { helpers: { Playwright: { show: true } } }
+      setBrowserConfig()
+      setBrowserConfig(null)
+      Config.create(config)
+      assert.equal(Config.get().helpers.Playwright.show, true)
+    })
+
+    test('routes browser through setBrowser (Puppeteer gets product, not browser)', () => {
+      Config.reset()
+      const config = { helpers: { Puppeteer: {}, Playwright: {} } }
+      setBrowserConfig({ browser: 'firefox' })
+      Config.create(config)
+      assert.equal(Config.get().helpers.Puppeteer.product, 'firefox')
+      assert.equal(Config.get().helpers.Puppeteer.browser, undefined)
+      assert.equal(Config.get().helpers.Playwright.browser, 'firefox')
+    })
+
+    test('show:true -> headed; show:false -> headless on Playwright/Puppeteer', () => {
+      Config.reset()
+      let config = { helpers: { Playwright: { show: false }, Puppeteer: { show: false } } }
+      setBrowserConfig({ show: true })
+      Config.create(config)
+      assert.equal(Config.get().helpers.Playwright.show, true)
+      assert.equal(Config.get().helpers.Puppeteer.show, true)
+
+      Config.reset()
+      config = { helpers: { Playwright: { show: true }, WebDriver: { browser: 'chrome' } } }
+      setBrowserConfig({ show: false })
+      Config.create(config)
+      assert.equal(Config.get().helpers.Playwright.show, false)
+      assert.ok(Config.get().helpers.WebDriver.desiredCapabilities.chromeOptions.args.includes('--headless'))
+    })
+
+    test('windowSize string is parsed and setWindowSize fires', () => {
+      Config.reset()
+      const config = { helpers: { Playwright: {}, WebDriver: {} } }
+      setBrowserConfig({ windowSize: '1280x720' })
+      Config.create(config)
+      assert.equal(Config.get().helpers.Playwright.windowSize, '1280x720')
+      assert.ok(Config.get().helpers.Playwright.chromium.args.includes('--window-size=1280,720'))
+      assert.equal(Config.get().helpers.WebDriver.windowSize, '1280x720')
+    })
+
+    test('extra keys are shallow-merged onto every browser helper', () => {
+      Config.reset()
+      const config = { helpers: { Playwright: {}, Puppeteer: {}, WebDriver: {}, REST: {} } }
+      setBrowserConfig({ video: false, waitForTimeout: 9000 })
+      Config.create(config)
+      assert.equal(Config.get().helpers.Playwright.video, false)
+      assert.equal(Config.get().helpers.Playwright.waitForTimeout, 9000)
+      assert.equal(Config.get().helpers.Puppeteer.video, false)
+      assert.equal(Config.get().helpers.WebDriver.waitForTimeout, 9000)
+      assert.equal(Config.get().helpers.REST.video, undefined)
+    })
+
+    test('combined options applied in one call', () => {
+      Config.reset()
+      const config = { helpers: { Playwright: { show: false } } }
+      setBrowserConfig({ browser: 'webkit', show: true, windowSize: '800x600', video: true })
+      Config.create(config)
+      const pw = Config.get().helpers.Playwright
+      assert.equal(pw.browser, 'webkit')
+      assert.equal(pw.show, true)
+      assert.equal(pw.windowSize, '800x600')
+      assert.equal(pw.video, true)
+    })
+  })
+
   describe('#setCommonPlugins', () => {
     test('create standard plugins', () => {
       Config.reset()