{"id":12917,"library":"browserstack-node-sdk","title":"BrowserStack Node.js SDK","description":"The `browserstack-node-sdk` is a Node.js library designed to facilitate running Selenium WebDriver tests on the BrowserStack cloud platform using popular JavaScript test runners like Jest, Mocha, and Cucumber. Currently at version 1.52.0, it primarily offers a command-line interface (CLI) to configure and execute tests against various browser and OS combinations defined in a `browserstack.yml` configuration file. While the SDK supports programmatic integration, its common usage pattern involves an `npx setup` command to initialize project configuration and wrapper CLI commands (e.g., `browserstack-node-sdk jest`) to orchestrate test execution on BrowserStack. Release cadence is frequent, indicated by minor version increments, focusing on compatibility and new platform support rather than major breaking changes. Its key differentiator is simplifying the integration of existing Node.js test suites with BrowserStack's extensive device farm through a streamlined setup and execution workflow, abstracting away much of the boilerplate associated with configuring remote Selenium grids.","status":"active","version":"1.52.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install browserstack-node-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add browserstack-node-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add browserstack-node-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used for programmatic initialization of the browserstack.yml configuration file.","wrong":"const setup = require('browserstack-node-sdk').setup;","symbol":"setup","correct":"import { setup } from 'browserstack-node-sdk';"},{"note":"Allows programmatic execution of the BrowserStack CLI commands for test runners, mirroring `browserstack-node-sdk <runner>`. Typically not needed for standard CLI usage.","wrong":"const runCLI = require('browserstack-node-sdk').runCLI;","symbol":"runCLI","correct":"import { runCLI } from 'browserstack-node-sdk';"},{"note":"Retrieves the parsed contents of the `browserstack.yml` file, useful for custom integrations or validation.","wrong":"const getBrowserstackConfig = require('browserstack-node-sdk').getBrowserstackConfig;","symbol":"getBrowserstackConfig","correct":"import { getBrowserstackConfig } from 'browserstack-node-sdk';"}],"quickstart":{"code":"npm i -D browserstack-node-sdk\n\nnpx setup --username process.env.BROWSERSTACK_USERNAME ?? '' --key process.env.BROWSERSTACK_ACCESS_KEY ?? ''\n\n# This command adds a new script to your package.json, e.g., 'browserstack-jest-test'\n# It also creates a browserstack.yml file with configuration.\n\n# Example of running Jest tests via the SDK:\nnpm run browserstack-jest-test","lang":"javascript","description":"Demonstrates installation, initial setup with environment variables, and execution of tests on BrowserStack via the generated CLI commands."},"warnings":[{"fix":"Set `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` environment variables, or verify them in `browserstack.yml`. Run `npx setup` again if the `browserstack.yml` is missing or corrupted.","message":"Authentication failures are common if `BROWSERSTACK_USERNAME` or `BROWSERSTACK_ACCESS_KEY` are incorrect or not provided via environment variables or the `browserstack.yml` file. Ensure these credentials are valid and accessible.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure outbound access to `*.browserstack.com` is allowed. Validate proxy settings and try running tests on an alternative network to rule out local environment issues.","message":"Network connectivity issues, such as VPN/proxy misconfigurations or corporate firewall restrictions, can prevent the SDK from communicating with BrowserStack cloud services, leading to `SDK-GEN-002` errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the `.browserstack` folder exists and has read/write permissions. On Linux/macOS, use `chmod -R 755 ~/.browserstack`.","message":"The SDK relies on a `.browserstack` directory in the user's home directory for session and cache information. Permissions issues or its absence can cause `SDK-GEN-001` errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Check for recent updates to your test framework. If issues persist, revert to a known-working version or compare your project's dependencies against BrowserStack's sample projects.","message":"Compatibility issues can arise if the test framework (Jest, Mocha, Cucumber) or its dependencies are recently updated or incorrectly installed, leading to `SDK-TRA-006` errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the official BrowserStack documentation and sample `browserstack.yml` files (e.g., in `jest-js-browserstack` repo) to ensure correct formatting and required fields. Use the SDK Config Generator if available.","message":"The `browserstack.yml` configuration file is crucial for defining platforms and capabilities. Incorrect syntax, missing required fields, or an invalid structure will lead to test execution failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Set `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` as environment variables or update the `browserstack.yml` file.","cause":"Incorrect or missing BrowserStack credentials.","error":"Authentication failed. Please check your BrowserStack Username and Access Key."},{"fix":"Run `npx setup --username <your_username> --key <your_access_key>` to generate the `browserstack.yml` file. Ensure it's in the project root.","cause":"The SDK configuration file is missing or misplaced.","error":"browserstack.yml file not found at the root of your project."},{"fix":"Install the required test runner as a dev dependency (e.g., `npm i -D jest`) and ensure it's runnable from your project's scripts.","cause":"The specified test runner (e.g., Jest, Mocha, Cucumber) is not installed or not in the PATH.","error":"Error: Test runner 'jest' not found. Please ensure it's installed and accessible."},{"fix":"Check proxy settings, firewall rules, and ensure `browserstack-local` is correctly configured and can establish a connection. Consult BrowserStackLocal documentation for advanced troubleshooting.","cause":"Issues with `BrowserStackLocal` binary or network configuration preventing local testing.","error":"Local tunnel connection failed. Please check BrowserStackLocal logs for details."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"browserstack-node-sdk"}