Connect and get help from 7,000+ developers on our Discord community.

Pass custom run command flags

Use runCommand to pass native test-runner CLI flags through to your BrowserStack load test for Playwright, Selenium, and WebdriverIO.

runCommand is a single YAML field that accepts a string of CLI flags you would normally pass to your test runner locally, such as --grep "@critical", -Dgroups=smoke, -k "checkout and not slow", or --suite smoke --bail 0. BrowserStack tokenizes the string, validates it against a per-framework safe list, and forwards the flags to the runner inside the load test pod.

Use runCommand when you need:

Multiple filters in one run, such as --grep "@critical|@smoke" for Playwright, -Dgroups=smoke -DexcludedGroups=slow for TestNG, or -k "login" -m smoke for PyTest.
Execution-control flags such as --repeat-each, --max-failures, --maxfail, --timeout, or --bail.
Flag combinations that the simpler testSelector field cannot express.

If you only need to pick tests by a single tag, package, or class, testSelector is still the simplest option. See Configure multiple scenarios for testSelector usage.

runCommand is supported for Playwright, Selenium with JUnit, Selenium with TestNG (including Cucumber), Selenium with Java (Gradle), Selenium with Python (unittest), Selenium with PyTest, and WebdriverIO. It is not supported for Nightwatch or k6.

Prerequisites

Before you start, confirm the following:

You have an active BrowserStack Load Testing account.
Your project uses one of the supported frameworks listed above.
You can access the BrowserStack Load Testing dashboard, or the BrowserStack CLI if you prefer YAML-driven runs.

Configure the run command

Depending on your preferred method, select one of the following:

UI Builder
CLI

Configure runCommand in UI Builder

Open the BrowserStack Load Testing dashboard and start the Create Load Test flow, or select Edit on an existing load test.

Select your Test Type (Selenium or WebdriverIO), the language, and the framework. The dashboard uses these selections to choose which run-command flags are valid for this test.

On the Test Configuration step, expand the Custom run command (optional) section. The section title also names your runner, for example “Custom Maven flags”, “Custom pytest flags”, or “Custom WebdriverIO flags”.

Add flags in one of two ways:

Guided picker: Select a flag from the dropdown, fill in its value, and press Add. The dropdown shows only flags that are valid for the framework you picked in the previous step. Blocked flags are hidden.
Paste a command: Paste a multi-flag string into the Paste command field. The dashboard splits it into rows, fills in values, and flags any unsupported entries.

Repeat to add as many flags as you need, up to a combined limit of 4096 characters.

Save your changes. The composed run command is shown in the test summary so you can verify exactly what will run inside the pod. Select Run test to start the load test.

The dashboard validates the run command as you type. If a flag is on the block list or is unknown, an inline error appears under the field and the Run test button stays disabled until you remove the offending flag.

Configure runCommand in YAML

Add runCommand to your browserstack-load.yml at the top level, next to vus, duration, and the other load test parameters. The value is a single-line string of CLI flags formatted exactly the way you would pass them to the test runner on your machine.

Playwright

Selenium with JUnit (Maven)

Selenium with TestNG (Maven)

For TestNG with Cucumber, set framework: cucumber-testng and use the same runCommand syntax. Cucumber-specific flags such as --tags and --glue are also supported.

Selenium with Java (Gradle)

Selenium with Python (unittest)

Selenium with PyTest

WebdriverIO

Combine with testSelector

You can use runCommand together with testSelector in a multi-scenario test. The flags from runCommand are appended after the args generated by testSelector, so they win on conflicts.

Run your test

After you update the YAML file, run the load test with the BrowserStack CLI:

Terminal

browserstack-load run --config browserstack-load.yml

Supported flags by framework

Every framework has its own safe list and block list. Safe flags are commonly used CLI options that pass validation; blocked flags are rejected because they break the load test pod, conflict with the load profile, or bypass BrowserStack instrumentation.

Playwright

Pass Playwright CLI flags exactly as you would with npx playwright test locally. Filtering flags such as --grep and --project compose freely with execution-control flags such as --repeat-each and --max-failures. Worker count, reporter, and output path are managed by BrowserStack and cannot be overridden.

Safe flags

Flag	Purpose
`--grep "pattern"`	Run only tests whose names match the pattern. Accepts a regex such as `"@critical\\|@smoke"`.
`--grep-invert "pattern"`	Skip tests whose names match the pattern.
`-g @tag`	Short form of `--grep`. Repeat the flag to add more matches (`-g @smoke -g @critical`).
`--project chromium`	Run only the named project from your `playwright.config.ts`.
`--repeat-each N`	Run every test N times. `N` is capped at 100.
`--retries N`	Retry failed tests up to N times. `N` is capped at 10.
`--max-failures N`	Stop after N failures.
`--timeout=N`	Per-test timeout in milliseconds.
`--global-timeout=N`	Global timeout in milliseconds for the whole run.
`--fully-parallel`	Force every test to run in parallel within a worker.
`--no-deps`	Skip running dependency projects.
`--pass-with-no-tests`	Do not fail the run when no tests match the filter.
`--forbid-only`	Fail the run if any test is marked with `test.only`.
`--fail-on-flaky-tests`	Treat flaky tests as failures.
`--ignore-snapshots`	Ignore snapshot expectations for this run.
`--quiet`	Suppress test output.
`--headed`	Run browsers in headed mode (use with caution; only useful for visual debugging).

Blocked flags

Flag	Why it is blocked
`--workers N` / `-j N`	Conflicts with the worker count that BrowserStack derives from `vus`. Use the top-level `vus` field instead.
`--reporter NAME`	Replaces the BrowserStack reporter that feeds the dashboard and report ingestion.
`--output DIR`	Redirects traces and artifacts away from the BrowserStack-managed storage path.
`--config PATH` / `-c PATH`	Bypasses the Playwright config that BrowserStack injects for the load test pod.
`--ui`, `--ui-host`, `--ui-port`	Interactive UI mode keeps the pod alive forever.
`--debug`	Attaches a Node inspector that the pod cannot connect to.
`--list`	Lists tests without running them; no load is generated.
`--shard X/Y`	BrowserStack already distributes work across virtual users; user-controlled sharding breaks the distribution.
`--browser chromium\\|firefox\\|webkit`	Conflicts with the `projects[]` section in standard BrowserStack Playwright configs. Use `--project <name>` instead.
`--only-changed`	Requires a `.git` directory in the project; load test pods only see the extracted zip.
`--last-failed`	Requires a `last-run.json` from a previous local run; pods are ephemeral, so the file never exists.
`--update-snapshots` / `-u`	Writes snapshots to the ephemeral pod filesystem; the results are lost when the pod terminates.
`--trace=on`	Forces trace capture for every test; BrowserStack manages trace policy to keep artifact volume sane.
`--global-setup PATH` / `--global-teardown PATH`	Runs arbitrary code outside the declared test scripts list.

Selenium with JUnit (Maven)

Use runCommand to pass Maven Surefire flags such as -Dtest, -Dgroups, and -DfailIfNoTests. The full safe list and the reasons for blocked flags are below.

Safe flags

Flag	Purpose
`-Dtest=ClassName`	Run a single test class.
`-Dtest=ClassName#methodName`	Run a single test method.
`-Dtest=Login,Checkout`	Run tests whose class names match these patterns.
`-Dgroups=smoke,regression`	Run tests in the listed JUnit groups.
`-DexcludedGroups=slow`	Skip tests in the listed groups.
`-DfailIfNoTests=false`	Do not fail the build if no tests match the selector.
`-DskipTests=false`	Force tests to run even if `skipTests` is set elsewhere.
`-DskipITs=false`	Force integration tests to run.
`-DtestFailureIgnore=false`	Fail the run when a test fails.
`-Dsurefire.skipAfterFailureCount=N`	Stop after N test failures (`N` between 1 and 50).
`-DtrimStackTrace=false`	Keep full stack traces in reports.
`-DenableAssertions=true`	Enable JVM assertions in test execution.
`-DrunOrder=alphabetical`	Set Surefire run order (`alphabetical`, `reversealphabetical`, `hourly`, `random`, `filesystem`).
`-DrunOrderRandomSeed=12345`	Pin a seed for `runOrder=random`.
`-DincludesFile=path/to/file`	Read class-name patterns to include from a file in the project zip.
`-DexcludesFile=path/to/file`	Read class-name patterns to exclude from a file in the project zip.
`-Dsurefire.failIfNoSpecifiedTests=false`	Do not fail when `-Dtest` matches nothing.
`-DshutdownTimeout=60`	Seconds to wait for the JVM to shut down at the end of the run.
`-DskipExec=false`	Do not skip the execution phase.
`-DuseFile=true`	Write reports to file (default behavior).
`-DprintSummary=true`	Print the summary at the end of the run.
`-DreportFormat=brief`	Set report format (`brief` or `plain`).
`-Dmaven.test.skip=false`	Make sure tests are not skipped.
`--batch-mode` / `-B`	Run Maven in non-interactive mode.
`--quiet` / `-q`	Reduce Maven log output.
`--errors` / `-e`	Show full error stack traces from Maven.

Blocked flags

Flag	Why it is blocked
`-DforkCount=N` (where N is greater than 1 or uses `C` notation)	Multiplies JVM processes against your virtual users and exhausts pod memory.
`-DreuseForks=false`	Starts a new JVM for every test class, which slows the run and drains pod memory.
`-DuseUnlimitedThreads=true`	Removes the Surefire thread cap and leads to runaway thread counts.
`-Dparallel=classes` (also `methods`, `suites`, `all`)	Layers Surefire parallelism on top of your virtual users; the load profile becomes unpredictable.
`-DthreadCount=N`	Conflicts with the thread count chosen by your load profile.
`-DthreadCountClasses=N`, `-DthreadCountMethods=N`, `-DthreadCountSuites=N`	Same parallelism conflict as above.
`-DperCoreThreadCount=true`	Makes thread count depend on pod CPU count, which is not under your control.
`-Dmaven.surefire.debug`	Attaches a debugger that the pod cannot connect to, so the run hangs.
`-DargLine=-Xmx...`	Overrides JVM heap settings and can run the pod out of memory.
`-Djvm=/some/path`	Points to a JVM binary that does not exist on the pod.
`-DdisableXmlReport=true`	Suppresses the XML output that BrowserStack uses to read test results.
`-T N` / `--threads`	Runs the Maven build itself in parallel and conflicts with the load profile.
`--debug` / `-X`	Produces very large logs and makes the pod slower to write reports.
`-Dsurefire.timeout=N`	Surefire enforces this as a wall-clock limit and can stop the run early.
`-Dmaven.test.failure.ignore=true`	Reports failed tests as passed at the Maven level, which corrupts your load test results.
`--fail-never`	Same issue: hides build failures from BrowserStack.
`-Dsurefire.rerunFailingTestsCount=N`	Reruns are unsupported because they inflate the load profile invisibly.
`--offline`	Prevents Maven from downloading missing dependencies on the pod.

Selenium with TestNG (Maven)

TestNG inherits every JUnit block, plus its own TestNG-specific blocks for parallelism and listeners. Cucumber flags such as --tags, --glue, and --plugin are safe to add when you use cucumber-testng.

Safe flags

Flag	Purpose
`-Dtest=ClassName`	Run a single test class.
`-Dtest=ClassName#methodName`	Run a single test method.
`-Dgroups=smoke,regression`	Include tests in the listed TestNG groups.
`-DexcludedGroups=slow,flaky`	Exclude tests in the listed groups.
`-Dsurefire.suiteXmlFiles=testng-smoke.xml`	Run with a specific TestNG suite XML from the project zip.
`-DfailIfNoTests=false`	Do not fail when nothing matches the selector.
`-DtestFailureIgnore=false`	Fail the run when a test fails.
`-Dsurefire.skipAfterFailureCount=N`	Stop after N failures (`N` between 1 and 50).
`-DtrimStackTrace=false`	Keep full stack traces in reports.
`-DenableAssertions=true`	Enable JVM assertions.
`-DrunOrder=alphabetical`	Set Surefire run order.
`-DrunOrderRandomSeed=12345`	Pin a seed for `runOrder=random`.
`-Dsurefile.failIfNoSpecifiedTests=false`	Do not fail when `-Dtest` matches nothing.
`-DshutdownTimeout=60`	Seconds to wait for the JVM to shut down.
`-DreportFormat=brief`	Set report format (`brief` or `plain`).
`-Dmaven.test.skip=false`	Make sure tests are not skipped.
`--batch-mode` / `-B`	Run Maven in non-interactive mode.
`--quiet` / `-q`	Reduce Maven log output.
`--errors` / `-e`	Show full error stack traces from Maven.
`-testjar path/to/tests.jar`	Pass tests in a JAR file.
`-testname "Smoke run"`	Override the default TestNG run name shown in reports.
`-suitename "RegressionSuite"`	Override the default TestNG suite name.
`-testRunFactory ClassName`	Use a custom TestNG test run factory.
`-objectfactory ClassName`	Use a custom TestNG object factory.
`-methodselectors ClassName`	Add TestNG method selectors.
`-randomizesuites`	Randomize suite execution order.
`-mixed true`	Allow mixed test methods in a suite.
`-skipfailedinvocationcounts true`	Skip remaining invocations of a method on first failure.
`-configfailurepolicy continue`	Continue after a `@BeforeClass`/`@BeforeMethod` failure.
`-overrideincludedmethods true`	Let CLI-included methods override XML configuration.
`--tags @smoke`	Cucumber: run scenarios with the given tag. Applies to `cucumber-testng`.
`--glue com.example.steps`	Cucumber: load step definitions from a package. Applies to `cucumber-testng`.
`--plugin pretty`	Cucumber: add a non-reporting plugin (`pretty`, `progress`, `summary`). Applies to `cucumber-testng`.
`--strict`	Cucumber: fail on undefined or pending steps.

Blocked flags

Flag	Why it is blocked
All Selenium-JUnit blocks	TestNG inherits the JUnit block list in full. See the JUnit table above.
`-parallel methods` (also `classes`, `tests`, `instances`)	Layers TestNG parallelism on top of your virtual users; the load profile becomes unpredictable.
`-threadcount N`	Conflicts with the thread count chosen by your load profile.
`-dataproviderthreadcount N`	The default is 10 and is too high inside the pod.
`-suitethreadpoolsize N`	Enables suite-level parallelism, which conflicts with the load profile.
`-listener ClassName`	Replaces the BrowserStack listener that reports test results.
`-reporter ClassName`	Overrides the BrowserStack reporter pipeline.
`-usedefaultlisteners false`	Disables the listeners BrowserStack needs to report results.

Selenium with Java (Gradle)

Gradle DSL properties such as maxParallelForks and heap settings live in your build.gradle file, not on the CLI. runCommand cannot catch those. For CLI flags, the safe and blocked lists are below.

Safe flags

Flag	Purpose
`--tests ClassName`	Run a single test class.
`--tests "ClassName.methodName"`	Run a single test method.
`--tests "Login"`	Run tests whose class names match a pattern. Repeat the flag to add more patterns.
`-PincludeTags=smoke`	Forward a tag list to your `build.gradle` (requires a matching `useJUnitPlatform { includeTags ... }` block).
`-PexcludeTags=slow`	Forward an exclude list to `build.gradle`.
`-PtestGroups=smoke,regression`	Forward a TestNG group list.
`-PtestExcludeGroups=flaky`	Forward a TestNG excluded-group list.
`--rerun`	Force the `test` task to run even if Gradle has cached a previous result.
`--continue`	Continue running tasks after a failure.
`--info`	Print verbose Gradle logs.
`--warn`	Print warning-level Gradle logs.
`--stacktrace` / `-s`	Print stack traces for failures.
`--full-stacktrace` / `-S`	Print full stack traces for failures.
`--quiet` / `-q`	Print error-level Gradle logs only.
`--console=plain`	Disable rich console output (useful in CI-style runs).

Blocked flags

Flag	Why it is blocked
`--max-workers N`	Runs Gradle tasks in parallel and multiplies the load against your virtual users.
`--parallel`	Enables Gradle’s parallel project execution; conflicts with the load profile.
`--debug` / `-d`	Produces very large logs and slows the pod.
`--dry-run` / `-m`	Lists tasks without running them; no load is generated.

Note: Gradle DSL settings such as maxParallelForks, JVM heap, and forkEvery are configured inside your build.gradle file, not on the CLI. runCommand cannot detect or block them. Make sure these are set sensibly in your build script before you upload the project.

Selenium with Python (unittest)

Pass standard unittest flags such as -k and -v. Test-runner replacements and partial-VU flags are blocked.

Safe flags

Flag	Purpose
`-k pattern`	Run only test names that contain the pattern.
`-v` / `--verbose`	Increase verbosity.
`-q` / `--quiet`	Reduce verbosity.
`-b` / `--buffer`	Buffer stdout and stderr during tests.
`-f` / `--failfast`	Stop on the first failure. Allowed but discouraged because partial VUs report misleading metrics.
`--locals`	Show local variables in tracebacks.
`tests.module.SubModule`	Positional argument selecting a module, test case class, or method.
`discover -s start_dir -p "test_*.py"`	Use `unittest discover` with a start directory and pattern.
`--top-level-directory dir`	Set the top-level directory for `discover`.

Blocked flags

Flag	Why it is blocked
`--testrunner ClassName`	Replaces the test runner used by BrowserStack, so results cannot be reported.
`--catch` / `-c`	Installs a SIGINT handler that interferes with how the pod terminates.

Selenium with PyTest

PyTest exposes a rich CLI. The safe list covers selection (-k, -m), execution control (--maxfail, --timeout, --reruns), and output verbosity. The block list covers debuggers, parallelism plugins, and config-override flags.

Safe flags

Flag	Purpose
`-k "expression"`	Run tests whose names match a Python expression, such as `-k "login and not slow"`.
`-m "expression"`	Run tests with markers matching the expression, such as `-m "smoke and not slow"`.
`--markers`	List all registered markers (for one-off discovery; not useful in load runs).
`--strict-markers`	Fail on unknown markers.
`--maxfail=N`	Stop after N failures. `N` is capped at 100.
`--timeout=N`	Per-test timeout in milliseconds. `N` is capped at 300000.
`--timeout-method=signal`	Choose timeout enforcement method (`signal` or `thread`).
`--reruns N`	Rerun failed tests N times. `N` is capped at 10.
`--reruns-delay=N`	Seconds between reruns.
`--only-rerun=pattern`	Only rerun tests matching the pattern.
`-v` / `--verbose`	Increase verbosity.
`-vv`	Increase verbosity further.
`-q` / `--quiet`	Reduce verbosity.
`--tb=short`	Set traceback format (`auto`, `long`, `short`, `line`, `native`, `no`).
`--showlocals` / `-l`	Show local variables in tracebacks.
`--no-header`	Hide the pytest header.
`--no-summary`	Hide the pytest summary.
`-r N`	Show short test summary for the given outcomes (for example, `-r fE`).
`--durations=N`	Show the N slowest tests.
`--durations-min=N`	Minimum duration in seconds to include in the durations report.
`--capture=fd`	Capture mode (`fd`, `sys`, `tee-sys`, `no`).
`--log-cli-level=INFO`	Log level for the CLI logger.
`--log-level=INFO`	Log level for the test session logger.
`--log-file=path`	Write logs to a file path inside the project.
`--log-format=fmt`	Format string for log records.
`--log-date-format=fmt`	Format string for log timestamps.
`--basetemp=path`	Base directory for temp files created by pytest fixtures.
`--ignore=path`	Ignore a file or directory. Can be repeated.
`--ignore-glob=pattern`	Ignore files matching a glob. Can be repeated.
`--deselect=nodeid`	Deselect a specific test by node id. Can be repeated.
`--randomly-seed=N`	Pin a seed for `pytest-randomly`.
`--continue-on-collection-errors`	Continue when collection has errors.
`--strict-config`	Fail if `pytest.ini` has unknown options.
`tests/path::test_name`	Positional node IDs select specific tests.
`-p no:cacheprovider`	Disable a plugin for this run.

Blocked flags

Flag	Why it is blocked
`--pdb`, `--pdbcls`, `--trace`	Drops into a debugger that the pod cannot connect to, so the run hangs.
`-n N` / `--numprocesses N`	The pytest-xdist worker count multiplies browsers against your virtual users.
`--dist=...`	Enables pytest-xdist distribution; conflicts with the load profile.
`--forked`, `--boxed`	Forks each test into a new process; exhausts pod memory.
`--noconftest`	Disables the BrowserStack `conftest.py` that wires up reporting.
`--pastebin=all`	Uploads the session output to bpaste.net, which leaks test data outside BrowserStack.
`--collect-only`, `--setup-only`, `--setup-plan`	Collects or sets up tests but never runs them; no load is generated.
`-c file` / `--config file`	Replaces the BrowserStack pytest config and breaks reporting.
`--rootdir=path`	Changes how pytest resolves files; the project zip layout no longer matches.
`--junit-xml=path`	Routes JUnit XML to an arbitrary path; BrowserStack expects the default location.
`--html=path`	Same: replaces the default report path.
`-o key=value`	Overrides any ini option, including ones BrowserStack relies on.
`--confcutdir=path`	Restricts `conftest.py` discovery and can disable BrowserStack hooks.
`--lf` / `--ff` / `--nf` / `--sw`	Uses the local pytest cache, which does not exist in fresh pods.
`--cov`, `--cov-report`	Coverage measurement adds heavy CPU overhead that distorts the load profile.
`--alluredir=path`	Writes Allure output, which is not part of the standard report pipeline.
`--benchmark-enable`	Enables pytest-benchmark, which inflates run duration.
`-s` / `--capture=no`	Disables output capture and creates very large logs.

WebdriverIO

WebdriverIO flags such as --spec, --suite, and --mochaOpts.grep are supported across the Mocha, Cucumber, and Jasmine sub-frameworks. Remote-grid flags and parallelism multipliers are blocked.

Safe flags

Flag	Purpose
`--spec path/to/file.spec.js`	Run a single spec file. Repeat the flag to add more.
`--exclude path/to/file.spec.js`	Skip a spec file.
`--suite smoke`	Run a named suite from `wdio.conf.js`.
`--mochaOpts.grep "@critical"`	Mocha: run tests whose names or tags match this pattern.
`--mochaOpts.invert true`	Mocha: invert the grep match.
`--mochaOpts.timeout=N`	Mocha: per-test timeout in milliseconds (`N` is capped at 300000).
`--mochaOpts.retries=N`	Mocha: retry failed tests N times.
`--mochaOpts.bail true`	Mocha: stop on the first failure.
`--mochaOpts.require path`	Mocha: preload a setup file.
`--mochaOpts.ui bdd`	Mocha: interface (`bdd`, `tdd`, `qunit`, or `exports`).
`--cucumberOpts.tags "@smoke"`	Cucumber: run scenarios with the given tags.
`--cucumberOpts.scenarioLevelReporter true`	Cucumber: report at the scenario level.
`--cucumberOpts.timeout=N`	Cucumber: per-step timeout in milliseconds.
`--cucumberOpts.retry=N`	Cucumber: retry failed scenarios N times.
`--cucumberOpts.retryTagFilter "@flaky"`	Cucumber: only retry scenarios with this tag.
`--cucumberOpts.strict true`	Cucumber: fail on undefined steps.
`--cucumberOpts.failFast true`	Cucumber: stop on the first failure (allowed but discouraged).
`--cucumberOpts.tagsInTitle true`	Cucumber: include tags in scenario titles.
`--cucumberOpts.profile name`	Cucumber: run a specific profile from `cucumber.js`.
`--cucumberOpts.format "pretty"`	Cucumber: add a non-reporting formatter.
`--jasmineOpts.grep pattern`	Jasmine: filter by spec name.
`--jasmineOpts.invertGrep true`	Jasmine: invert the grep filter.
`--jasmineOpts.defaultTimeoutInterval=N`	Jasmine: default spec timeout in milliseconds.
`--jasmineOpts.stopOnSpecFailure true`	Jasmine: stop on the first failure.
`--jasmineOpts.stopSpecOnExpectationFailure true`	Jasmine: stop a spec on the first expectation failure.
`--bail N`	Stop the run after N failures.
`--logLevel info`	Set runner log level (`info`, `warn`, `error`, or `silent`; `trace` and `debug` are blocked).
`--baseUrl https://staging.example.com`	Override the base URL configured in `wdio.conf.js`.
`--framework mocha` / `cucumber` / `jasmine`	Set the WebdriverIO framework.
`--waitforTimeout=N`	Default WebDriver wait timeout in milliseconds.
`--connectionRetryTimeout=N`	WebDriver connection retry timeout in milliseconds.

Blocked flags

Flag	Why it is blocked
`--watch`	Puts WebdriverIO into watch mode; the pod never terminates.
`--inspect`, `--inspect-brk`	Attaches a Node debugger that the pod cannot connect to.
`--user`, `--key`	Redirects the run to a remote WebDriver grid; BrowserStack runs the browser locally inside the pod.
`--hostname` (when not the pod’s local host)	Same: points WebDriver away from the pod’s local driver.
`--port` (when not the default)	Connection refused because no driver is listening on the requested port.
`--protocol https`	The pod’s local driver does not present a TLS certificate.
`--path` (when not the default WebDriver path)	Breaks the WebDriver protocol handshake.
`--services browserstack`, `--services sauce`, `--services testingbot`	Remote-service drivers redirect the run to an external grid.
`--maxInstances N` (where N is greater than 1)	Runs multiple browser instances per pod and exhausts pod memory.
`--capabilities path`	Replaces the capabilities that match the pod’s headless browser.
`--config path` / `-c path`	Replaces the BrowserStack-generated WebdriverIO config.
`--shard X/Y`	Spec sharding produces incomplete coverage per virtual user.
`--multi-run N`	Replays the test set N times; conflicts with the load profile.
`--cucumberOpts.dryRun true`	Walks the scenarios without running them, so no load is generated.
`--region eu`, `--region apac`	Region selection only applies to a remote grid; ignored locally and likely a mistake.
`wdio config`, `wdio install`, `wdio repl`	Interactive subcommands that hang the pod.
`--headless false`	The pod has no display; running headed makes the browser fail to start.
`--coverage`	Coverage measurement adds heavy CPU overhead.
`--reporters json-stream`, `--reporters dot` (heavy outputs)	Replaces the BrowserStack reporter pipeline or produces very large logs.
`--mochaOpts.failFast true`	Stops the run early in a way that under-reports load metrics.
`--automationProtocol devtools`	Uses Chrome DevTools instead of WebDriver; not supported on the pod.
`--runner browser`	The browser runner is unsupported; only the local runner is available.
`--execArgv "..."`	Passes Node arguments such as `--max-old-space-size`, which can exhaust pod memory.
`--logLevel trace`, `--logLevel debug`	Produces very large logs and slows the pod.

How runCommand works with testSelector

You can use runCommand and testSelector in the same load test. When both are present, the flags from runCommand are appended after the args generated by testSelector on the runner command line, so runCommand wins on conflicts.

runCommand is a job-level field in version 1. It applies to the whole load test, not to an individual scenario in a multi-scenario test. If your YAML defines runCommand inside a scenarios entry, the run is rejected.

Validation errors

If the value of runCommand does not pass validation, the run is rejected before any pod is started. The error is returned with one of the following codes:

Error code	When it appears	How to fix
`RUN_COMMAND_UNSUPPORTED_FLAG`	A flag in `runCommand` is on the block list for this framework.	Remove the flag or replace it with a supported alternative listed above.
`RUN_COMMAND_TOO_LONG`	The value of `runCommand` exceeds 4096 characters.	Shorten the string, or split work across separate runs.
`RUN_COMMAND_UNKNOWN_FLAG`	A flag is not in the safe list and does not match a known block. The closest known flag is suggested.	Check the suggestion in the error message and fix typos.
`RUN_COMMAND_MALFORMED`	The string cannot be parsed (unclosed quotes, stray backslash, embedded newline).	Make sure quotes are balanced and the value is on a single YAML line.
`FLAG_VALUE_INVALID_TYPE`	A flag value is the wrong type (for example, a string where a number is expected).	Check the documented type for the flag and adjust the value.
`FLAG_VALUE_OUT_OF_RANGE`	A numeric value is outside the supported range (`--maxfail` greater than 100, `--timeout` greater than 300000, `--reruns` greater than 10).	Lower the value to fit the documented cap.
`FLAG_VALUE_INVALID_REGEX`	A regex value (for example, in `--mochaOpts.grep` or PyTest `-k`) fails the `safe-regex` check or exceeds 256 characters.	Simplify the regex, avoid catastrophic backtracking patterns, or shorten it.

Limits

runCommand is a single line of up to 4096 characters. YAML block scalars are rejected.
The string is tokenized; shell substitutions such as `cmd`, $(cmd), and pipes are not evaluated.
Numeric flag values are capped: Playwright --repeat-each<=100 and --retries<=10; PyTest --maxfail<=100, --timeout<=300000 (ms), and --reruns<=10; WebdriverIO --mochaOpts.timeout<=300000 (ms).
Regex values in flags such as Playwright --grep, WebdriverIO --mochaOpts.grep, and PyTest -k are checked with safe-regex and capped at 256 characters to prevent ReDoS.
Unicode in flag names is normalized (NFKC) before matching.
runCommand is not supported for Nightwatch or for k6.

Configure load parameters - Overview of all available load configuration options.
Configure multiple scenarios - Includes testSelector usage that composes with runCommand.
Environment variables - Pass runtime values without putting them on the command line.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!

Pass custom run command flags

Prerequisites

Configure the run command

Configure runCommand in UI Builder

Configure runCommand in YAML

Playwright

Selenium with JUnit (Maven)

Selenium with TestNG (Maven)

Selenium with Java (Gradle)

Selenium with Python (unittest)

Selenium with PyTest

WebdriverIO

Combine with testSelector

Run your test

Supported flags by framework

Playwright

Selenium with JUnit (Maven)

Selenium with TestNG (Maven)

Selenium with Java (Gradle)

Selenium with Python (unittest)

Selenium with PyTest

WebdriverIO

How runCommand works with testSelector

Validation errors

Limits

Related topics

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked