LambdaTest Cypress CLI

3.0.50 · active · verified Wed Apr 22

The `lambdatest-cypress-cli` is a command-line interface developed by LambdaTest to facilitate running Cypress end-to-end tests on the LambdaTest cloud-based cross-browser testing platform. Currently stable at version 3.0.50, the package demonstrates an active release cadence with frequent minor updates and fixes, as seen in its detailed changelog, which often includes multiple releases within short periods. Its core functionality involves configuring and executing Cypress test suites across a vast array of browser and operating system combinations provided by LambdaTest's online Selenium Grid, differentiating it from local Cypress test runners by offering scalable cloud execution and comprehensive test analytics. Users interact with the CLI to initialize configuration files, set up authentication credentials, define target browsers, and manage test execution parameters like parallel sessions and Cypress versions.

Common errors

```
LT_USERNAME and LT_ACCESS_KEY are not set. Please set the environment variables.
```
cause The LambdaTest username or access key environment variables (`LT_USERNAME`, `LT_ACCESS_KEY`) are not defined in the shell where the CLI is being executed.

fix Before running `lambdatest-cypress`, execute `export LT_USERNAME="your_username"` and `export LT_ACCESS_KEY="your_access_key"` (replace placeholders with actual credentials) or use a `.env` file loader.
```
Error: Configuration file (lambdatest-cypress.json) not found. Please run 'lambdatest-cypress init' to create one.
```
cause The required `lambdatest-cypress.json` configuration file is missing from the current working directory.

fix Run `lambdatest-cypress init` in your project's root directory to generate the default configuration file, then customize it as needed.
```
command not found: lambdatest-cypress
```
cause The `lambdatest-cypress` command is not available in your system's PATH, typically because the package was not installed globally or `npx` is not being used.

fix Install the package globally using `npm install -g lambdatest-cypress-cli` or execute the command using `npx lambdatest-cypress run` (for local installation).
```
Error: tunneling socket could not be established, cause=self signed certificate in certificate chain
```
cause This error often indicates issues with proxy configuration, specifically when a corporate proxy uses a self-signed certificate that Node.js does not trust by default.

fix Upgrade to `lambdatest-cypress-cli@3.0.50-prod` or higher, which defaults `reject_unauthorized` to `false` for proxy compatibility. Alternatively, configure your Node.js environment to trust the proxy's certificate, or set `NODE_TLS_REJECT_UNAUTHORIZED=0` (use with caution in production).

Warnings

gotcha Authentication to LambdaTest requires setting `LT_USERNAME` and `LT_ACCESS_KEY` environment variables. Failing to set these will prevent tests from running on the platform.
Fix: Ensure `LT_USERNAME` and `LT_ACCESS_KEY` are properly exported in your environment before invoking `lambdatest-cypress run`. Consider using a CI/CD secret management system for these credentials.
gotcha The `lambdatest-cypress.json` configuration file is crucial for defining browsers, OS, Cypress versions, and other test parameters. Running `lambdatest-cypress run` without this file, or with an improperly configured one, will lead to errors.
Fix: Always run `lambdatest-cypress init` first to generate a template configuration. Carefully review and update the `auth`, `browsers`, and `run_settings` sections according to your project's requirements and LambdaTest's documentation.
breaking Support for authenticated proxies and resilience for feature flags were improved in version `3.0.50-prod`. Specifically, `reject_unauthorized` now defaults to `false` for proxy compatibility. This change might subtly alter behavior for users with custom proxy configurations, potentially resolving or introducing certificate-related issues depending on their setup.
Fix: If experiencing proxy issues, review your proxy configuration and LambdaTest's documentation on proxy support. For older versions, manual proxy configuration might be required. If upgrading, test thoroughly to ensure existing proxy setups are not negatively impacted by the `reject_unauthorized` change.
gotcha The `cypress_version` specified in your `lambdatest-cypress.json`'s `run_settings` must be compatible with or match the Cypress version used in your local project for accurate test execution on the LambdaTest grid. Mismatches can lead to unexpected failures or behavior.
Fix: Verify that the `cypress_version` in your `lambdatest-cypress.json` accurately reflects the Cypress version dependency in your `package.json` file. Update it if there's a discrepancy.

Install

npm install lambdatest-cypress-cli npm
yarn add lambdatest-cypress-cli yarn
pnpm add lambdatest-cypress-cli pnpm

Imports

lambdatest-cypress run
wrong:
```
node path/to/cli.js
```
correct:
```
lambdatest-cypress run
```
This CLI is invoked directly from the command line after global installation or via `npx`. Programmatic `require()` or `import` of internal modules is not officially supported or intended.
lambdatest-cypress init
wrong:
```
npx lambdatest-cypress setup
```
correct:
```
lambdatest-cypress init
```
Used to create the initial `lambdatest-cypress.json` configuration file in your project directory.
npx lambdatest-cypress
wrong:
```
lambdatest-cypress run (if not globally installed)
```
correct:
```
npx lambdatest-cypress run
```
While global installation (`npm install -g`) is common, `npx` allows running the CLI without global installation, using the version defined in your project's `node_modules`.

Quickstart

Demonstrates global installation, setting up authentication, initializing the configuration, and executing Cypress tests on the LambdaTest platform.

npm install -g lambdatest-cypress-cli

# Set LambdaTest credentials as environment variables
export LT_USERNAME="$LT_USERNAME"
export LT_ACCESS_KEY="$LT_ACCESS_KEY"

# Initialize the configuration file (lambdatest-cypress.json)
lambdatest-cypress init

# Edit lambdatest-cypress.json to configure browsers, OS, and test settings.
# Example modification (after init creates the file):
# Ensure your project's Cypress version matches 'cypress_version' in run_settings.

# Run your Cypress tests on LambdaTest
lambdatest-cypress run

view raw JSON →