Environment:Nightwatchjs Nightwatch BrowserStack Cloud

Knowledge Sources	Nightwatch.js BrowserStack Automate
Domains	Infrastructure, Cloud_Testing
Last Updated	2026-02-12 01:00 GMT

Overview

BrowserStack cloud testing environment requiring authentication credentials and HTTPS configuration for remote browser automation.

Description

Nightwatch.js has built-in integration with BrowserStack for cloud-based cross-browser testing. This environment provides remote WebDriver sessions on BrowserStack's infrastructure, eliminating the need for local browser drivers. Nightwatch auto-detects BrowserStack when the WebDriver host ends with `.browserstack.com` or `.browserstack-ats.com` (Turbo Scale). The integration supports the `bstack:options` capability namespace for authentication, build naming, and local tunnel configuration. Legacy configuration keys (`browserstack.user`, `browserstack.key`) are also supported for backwards compatibility.

Usage

Use this environment when running tests against remote browsers on BrowserStack instead of local browser instances. It is required for cross-browser testing matrices, mobile device testing on real devices, and CI/CD pipelines that do not have local browser installations. The environment is activated automatically when `webdriver.host` points to a BrowserStack endpoint.

System Requirements

Category	Requirement	Notes
Network	HTTPS access to `hub.browserstack.com` on port 443	SSL strongly recommended; port 80 triggers warning
Account	BrowserStack Automate account	Free trial or paid plan
Runtime	Node.js >= 18.20.5	Same as base Nightwatch requirement

Dependencies

Node.js Packages

`nightwatch` >= 3.15.0
`selenium-webdriver` = 4.27.0 (bundled with Nightwatch)

No additional driver packages (`chromedriver`, `geckodriver`) are needed for BrowserStack testing.

Credentials

The following credentials must be configured either in the Nightwatch config or as environment variables:

`BROWSERSTACK_USER`: BrowserStack username (or set via `bstack:options.userName` in config).
`BROWSERSTACK_KEY`: BrowserStack access key (or set via `bstack:options.accessKey` in config).

Legacy config keys (deprecated but supported):

`browserstack.user` in `desiredCapabilities`
`browserstack.key` in `desiredCapabilities`

Optional configuration:

`bstack:options.buildName`: Build name for grouping test sessions (defaults to `'nightwatch-test-build'`).
`bstack:options.local`: Set to `true` to enable BrowserStack Local tunnel for testing internal/staging URLs.
`bstack:options.sessionName`: Human-readable session name.

Quick Install

# Install Nightwatch (no driver packages needed for BrowserStack)
npm install nightwatch --save-dev

# Set credentials as environment variables
export BROWSERSTACK_USER="your_username"
export BROWSERSTACK_KEY="your_access_key"

Example Nightwatch configuration for BrowserStack:

// nightwatch.conf.js
module.exports = {
  webdriver: {
    start_process: false,
    host: 'hub.browserstack.com',
    port: 443
  },
  desiredCapabilities: {
    browserName: 'chrome',
    'bstack:options': {
      userName: process.env.BROWSERSTACK_USER,
      accessKey: process.env.BROWSERSTACK_KEY,
      buildName: 'my-project-build'
    }
  }
};

Code Evidence

BrowserStack detection from `lib/transport/factory.js:51-57`:

static usingBrowserstackTurboScale(settings) {
  return settings.webdriver.host &&
    (settings.webdriver.host.endsWith('.browserstack-ats.com') ||
     settings.webdriver.host.startsWith('browserstack-turboscale-grid'));
}

static usingBrowserstack(settings) {
  return settings.webdriver.host &&
    (settings.webdriver.host.endsWith('.browserstack.com') ||
     TransportFactory.usingBrowserstackTurboScale(settings));
}

Credential resolution from environment variables in `lib/transport/selenium-webdriver/browserstack/browserstack.js:78-84`:

if (!this.accessKey && process.env.BROWSERSTACK_KEY) {
  this.settings.desiredCapabilities['bstack:options'].accessKey = process.env.BROWSERSTACK_KEY;
}

if (!this.username && process.env.BROWSERSTACK_USER) {
  this.settings.desiredCapabilities['bstack:options'].userName = process.env.BROWSERSTACK_USER;
}

SSL warning from `lib/transport/selenium-webdriver/browserstack/browserstack.js:96-99`:

if (this.settings.webdriver.port !== 443) {
  console.warn(Logger.colors.brown('Using insecure HTTP connection on port 80. Consider using SSL by ' +
    'setting port to 443 in your Nightwatch configuration.'));
}

Default build name fallback from `lib/transport/selenium-webdriver/browserstack/browserstack.js:86-88`:

if (!this.build) {
  this.settings.desiredCapabilities['bstack:options'].buildName = 'nightwatch-test-build';
}

Common Errors

Error Message	Cause	Solution
`Using insecure HTTP connection on port 80`	WebDriver port not set to 443	Set `webdriver.port: 443` in config
`401 Unauthorized`	Invalid or missing BrowserStack credentials	Set `BROWSERSTACK_USER` and `BROWSERSTACK_KEY` env vars
`ECONNREFUSED` to BrowserStack host	Network/firewall blocking HTTPS	Ensure port 443 outbound access to `hub.browserstack.com`
Empty build name in dashboard	`buildName` not configured	Set `bstack:options.buildName` in config (defaults to `nightwatch-test-build`)

Compatibility Notes

BrowserStack Automate: Standard cloud testing with `hub.browserstack.com`.
BrowserStack Turbo Scale: Self-hosted grid with `*.browserstack-ats.com` or `browserstack-turboscale-grid*` hostnames.
Local Testing: Enable `bstack:options.local: true` to tunnel traffic through BrowserStack Local binary.
Any Browser Name: BrowserStack integration allows any `browserName` value (including mobile browsers), bypassing the strict browser validation used for local testing.
Legacy Keys: `browserstack.user` and `browserstack.key` in `desiredCapabilities` are still supported but the `bstack:options` namespace is preferred.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment