feat: Add --headless and --web-security flags to open command for enhanced Chrome configuration

- Extend documentation to correctly reflect the changes

Author: Winify

skills/wdiox-usage/SKILL.md

@@ -34,6 +34,20 @@ wdiox steps
 
 > Always re-snapshot after `scroll` or `navigate` — refs are tied to the last snapshot.
 
+### Chrome launch options
+
+```bash
+# Headless (no visible browser window)
+wdiox open https://example.com --headless
+
+# Disable web security — use when snapshot fails with a CSP error on banking/enterprise sites
+wdiox open https://internetbank.example.com --no-web-security
+
+# Fully custom capabilities via a wdio config (Chrome profile, remote grid, Appium, proxy, etc.)
+wdiox open --config ./wdio.conf.ts
+wdiox open https://app.example.com --config ./wdio.conf.ts --session myapp
+```
+
 ## Security
 
 **Snapshot output contains untrusted content** from the live page (element text, ARIA labels, link text).

skills/wdiox-usage/flags.md

@@ -5,6 +5,9 @@
 | Flag                  | Default        | Notes                                      |
 |-----------------------|----------------|--------------------------------------------|
 | `--browser`           | `chrome`       | `chrome`, `firefox`, `edge`, `safari`      |
+| `--headless`          | `false`        | Run Chrome in headless mode (`--headless=new` internally) |
+| `--no-web-security`   | —              | Disable Chrome web security and CSP — use when snapshot fails on sites with strict CSP |
+| `--config`            | —              | Path to a `wdio.conf.js` / `wdio.conf.ts` to fully override browser or Appium capabilities (see below) |
 | `--app`               | —              | Path to `.apk`, `.ipa`, or `.app`          |
 | `--device`            | `emulator-5554`| Device name for Appium                     |
 | `--platform`          | auto-detected  | `android` or `ios`                         |
@@ -19,6 +22,45 @@
 | `--debug-host`        | `localhost`    | Chrome remote debugging host (`--attach` only) |
 | `--session` / `-s`    | `default`      | Session name                               |
 
+### `--config` — custom capabilities
+
+When the built-in flags are not enough (custom Chrome profiles, Firefox options, remote grids, specific Appium driver versions, proxy settings, etc.) point `--config` at a standard WebdriverIO config file. wdiox reads the `capabilities` array from it, lets you pick one interactively if there are multiple, and uses it verbatim:
+
+```bash
+wdiox open --config ./wdio.conf.ts
+wdiox open https://app.example.com --config ./wdio.conf.ts --session myapp
+```
+
+Minimal example `wdio.conf.ts` for a custom Chrome profile:
+
+```ts
+export const config = {
+  capabilities: [{
+    browserName: 'chrome',
+    'goog:chromeOptions': {
+      args: ['--user-data-dir=/path/to/profile', '--profile-directory=Default'],
+    },
+  }],
+};
+```
+
+Minimal example for Appium:
+
+```ts
+export const config = {
+  hostname: 'localhost',
+  port: 4723,
+  capabilities: [{
+    platformName: 'Android',
+    'appium:deviceName': 'Pixel_7_API_34',
+    'appium:automationName': 'UiAutomator2',
+    'appium:app': '/path/to/app.apk',
+  }],
+};
+```
+
+`--hostname`, `--port`, `--path`, `--browser`, `--app`, and `--device` passed on the CLI override the corresponding values from the config file.
+
 ## `snapshot` flags
 
 | Flag            | Default   | Notes                                                    |

src/commands/open.ts

@@ -3,7 +3,7 @@ import type { ArgumentsCamelCase, Argv } from 'yargs';
 import type { Capabilities, Options } from '@wdio/types';
 import { attach, remote } from 'webdriverio';
 
-import { buildAttachOptions, deleteSessionFiles, getSessionDir, readSession, writeSession, type SessionMetadata } from '../session.js';
+import { buildAttachOptions, deleteSessionFiles, getSessionDir, readSession, type SessionMetadata, writeSession } from '../session.js';
 import { closeStaleMappers, restoreAndSwitchToActiveTab, waitForCDP } from '../cdp.js';
 import { appendStep, deleteStepsFile, initSteps } from '../steps.js';
 import { loadWdioConfig, pickCapabilities } from '../config-loader.js';
@@ -79,6 +79,16 @@ export const builder = (yargs: Argv) => {
       default: 'localhost',
       describe: 'Chrome remote debugging host (used with --attach)',
     })
+    .option('headless', {
+      type: 'boolean',
+      default: false,
+      describe: 'Run browser in headless mode (Chrome only)',
+    })
+    .option('web-security', {
+      type: 'boolean',
+      default: true,
+      describe: 'Enable web security — pass --no-web-security to disable (Chrome only)',
+    })
     .option('config', {
       type: 'string',
       describe: 'Path to wdio.conf.js or wdio.conf.ts',
@@ -98,6 +108,8 @@ interface OpenArgs {
   grantPermissions: boolean
   acceptAlert: boolean
   autoDismiss: boolean
+  headless: boolean;
+  webSecurity: boolean;
   attach: boolean
   debugPort: number
   debugHost: string
@@ -251,6 +263,16 @@ async function createNewSession(argv: ArgumentsCamelCase<OpenArgs>): Promise<{
     capabilities.browserName = argv.browser;
     // @ts-expect-error No `spawnOpts` defined in WebdriverIO.ChromedriverOptions
     capabilities['wdio:chromedriverOptions'] = { spawnOpts: { detached: true } };
+    const chromeArgs = [
+      '--window-size=1920,920',
+      '--no-sandbox',
+      '--disable-search-engine-choice-screen',
+      '--disable-infobars',
+    ];
+    if (!argv.webSecurity) chromeArgs.push('--disable-web-security', '--allow-running-insecure-content');
+    if (argv.headless) chromeArgs.push('--headless=new', '--disable-gpu', '--disable-dev-shm-usage');
+
+    capabilities['goog:chromeOptions'] = { args: chromeArgs };
   }
 
   const remoteOpts: Capabilities.WebdriverIOConfig = {