browserstack-parallel-check

browserstack-parallel-check polls the BrowserStack parallel/queue usage API to dynamically allocate available workers for your test suites (e.g., Playwright, Cypress, Jest).

It intelligently waits until there is sufficient capacity based on your configured minimum requirements. Once capacity is found, it injects BROWSERSTACK_WORKERS and BROWSERSTACK_PARALLELS_PER_PLATFORM into the environment and seamlessly executes the test command you specify.

Installation

Globally (Recommended for CLI usage)

npm install -g browserstack-parallel-check

Locally in your project

npm install browserstack-parallel-check --save-dev

Usage

You can run browserstack-parallel-check followed by any Node-based test command. If no test command is provided, it will simply set up the environment variables, verify the capacity, and exit successfully (useful for dry runs).

Examples

Verifying Capacity Only (No Test Command): If you want to only verify capacity and set up environment variables (e.g. for a dry run), simply omit the test command:

npx browserstack-parallel-check -u YOUR_USERNAME -k YOUR_ACCESS_KEY

Running a Playwright Test:

npx browserstack-parallel-check -u YOUR_USERNAME -k YOUR_ACCESS_KEY browserstack-node-sdk playwright test

Running a Custom Test Command (e.g., Cypress):

npx browserstack-parallel-check -u YOUR_USERNAME -k YOUR_ACCESS_KEY cypress run --browser chrome

Using Environment Variables: You can set options using environment variables instead of flags:

BROWSERSTACK_USERNAME=yourUser BROWSERSTACK_ACCESS_KEY=yourKey BROWSERSTACK_MIN_WORKERS=2 npx browserstack-parallel-check npm run test:e2e

Configuration Options

You can configure the tool using command-line flags or environment variables. The script will automatically fall back to the environment variables if the flags are not provided.

| Option | Env Variable | Default | Description | |---|---|---|---| | -u, --username <type> | BROWSERSTACK_USERNAME | (Required) | BrowserStack username | | -k, --access-key <type> | BROWSERSTACK_ACCESS_KEY | (Required) | BrowserStack access key | | --min-workers <number> | BROWSERSTACK_MIN_WORKERS | 1 | Minimum parallels required | | --max-workers <number> | BROWSERSTACK_MAX_WORKERS | 2 | Maximum parallels to allocate | | --poll-timeout <number> | BROWSERSTACK_POLL_TIMEOUT_SEC | 1800 | Total seconds to keep polling before giving up | | -h, --help | N/A | N/A | Display help for command |

Behavior

Upon execution, the script will:

1. Print the considered minimum and maximum parallels.
2. Check the BrowserStack API for available capacity.
3. If capacity is below the minimum, it will poll every 5 minutes until the poll-timeout is reached.
4. Once capacity is found, it calculates the optimal worker count and executes your provided test command.