How to Configure Cypress Test Execution on TestMu AI
When you run Cypress tests on TestMu AI, you control how each build behaves through run settings such as the config file, spec paths, geolocation, resolution, timeouts, and dependencies. Setting these correctly targets the right specs, matches your local environment, and keeps build times down. You configure them in the run_settings object of lambdatest-config.json, and most also have an equivalent Cypress CLI flag.
You can specify Cypress CLI flags to run on TestMu AI in two ways:
- Adding the CLI flag details in the
lambdatest-config.jsonfile - Using the CLI
If a glob pattern path is passed in the specs flag using the CLI, enclose it within double quotes as shown:
lambdatest-cypress-cli run --env=stage --verbose --specs "./cypress/integration/examples/*"
Set the Cypress Config File
Point TestMu AI at your Cypress configuration file so the run uses the settings your project expects. You can set it in lambdatest-config.json or pass it as a CLI flag.
Using lambdatest-config.json
Use the cypress_config_file key in the run_settings option to specify the Cypress configuration file.
Cypress 10 and above automatically identify the cypress.config.js file in the project, so you do not need to specify the cypress_config.js capability.
- Cypress v9
- Cypress v10
{
"run_settings": {
"cypress_config_file": "cypress.json",
"video": true
}
}
// In case of Cypress 10 and above, you can specify your custom config files by using the --cy flag.
lambdatest-cypress-cli run --env=stage,video=true --verbose --specs "./cypress/integration/examples/*"
Using the CLI
Specify the Cypress configuration file using the CLI flag below with the run command.
| Flag | Purpose | Type |
|---|---|---|
| --ccf, --cypress-config-file | Path of the config file | String |
Specify the Spec Files to Run
Choose which spec files a build executes so you run only the tests you need. Set the paths in lambdatest-config.json or pass them on the CLI.
Using lambdatest-config.json
Use the specs key in the run_settings option to specify the spec files.
- Cypress v10
- Cypress v9
{
"run_settings": {
"specs": "**/*.cy.js",
}
}
{
"run_settings": {
"specs": "./cypress/integration/examples/*.spec.js",
}
}
Using the CLI
Specify the spec files using the CLI flag below with the run command.
| Flag | Purpose | Type |
|---|---|---|
| -s, --specs | Path of the spec file or directory or pattern | String |
Exclude Spec Files From a Run
Skip specific spec files without deleting them from your project. Use the exclude_specs key in the run_settings option to list the spec files you want to leave out of the test execution.
- Cypress v10
- Cypress v9
{
"run_settings": {
"exclude_specs": "./examples/assertion.spec.js, ./examples/connectors.spec.js",
}
}
{
"run_settings": {
"exclude_specs": "./examples/assertion.spec.js, ./examples/connectors.spec.js",
}
}
Set the Test Geolocation
Run your tests from a specific country to check geo-targeted behavior. Set the location in lambdatest-config.json or pass it on the CLI.
Using lambdatest-config.json
Use the geo_location key in the run_settings option to specify the country to run from.
- Cypress v10
- Cypress v9
{
"run_settings": {
"geo_location": "<country_code>",
}
}
{
"run_settings": {
"geo_location": "<country_code>",
}
}
Using the CLI
Specify the geolocation using the CLI flag below with the run command.
| Flag | Purpose | Type |
|---|---|---|
| --geo, --geo_location | Pass the Geo country code | String |
Set the Screen Resolution
Control the screen resolution of the machine your tests run on. Set it in lambdatest-config.json or pass it on the CLI.
Using lambdatest-config.json
Use the resolution key in the run_settings option to specify the resolution.
- Cypress v10
- Cypress v9
{
"run_settings": {
"resolution": "1024x768",
}
}
{
"run_settings": {
"resolution": "1024x768",
}
}
Using the CLI
Specify the system's resolution using the CLI flag below with the run command.
| Flag | Purpose | Type |
|---|---|---|
| --res | Pass the resolution | String |
This changes the resolution of the system, but the viewport in which Cypress launches the website is controlled by Cypress.
Supported resolutions: 1024x768, 1280x960, 1280x1024, 1600x1200, 1920x1080, 2048x1536, 2560x1440
The resolution capability above sets the VM's screen resolution. To control the browser viewport that Cypress renders the app in (which resolution does not change), use Cypress's own viewport and full-screen options.
Test on viewports
When you define a viewport, Cypress uses the browser's scaling to size the app: a large viewport scales the app down, a small one scales it up. Set the viewport globally with viewportWidth and viewportHeight in the Cypress config, or per test:
cy.viewport(550, 750) // Set viewport to 550px x 750px
cy.viewport('iphone-6') // Set viewport to 375px x 667px
For more details, see the Cypress viewport command reference.
Test in full-screen mode
Full-screen mode together with viewports gives the best results for screen-resolution testing.
Use the before:browser:launch event to change the browser options.
For Cypress v9 and below, use the following script in the plugin/index.js file:
module.exports = (on, config) => {
on('before:browser:launch', (browser = {}, launchOptions) => {
if (browser.family === 'chromium' && browser.name !== 'electron') {
launchOptions.args.push('--start-fullscreen')
return launchOptions
}
if (browser.name === 'electron') {
launchOptions.preferences.fullscreen = true
return launchOptions
}
})
}
For Cypress v10 and above, add the below code in the cypress.config.js file:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
on('before:browser:launch', (browser = {}, launchOptions) => {
if (browser.family === 'chromium' && browser.name !== 'electron') {
launchOptions.args.push('--start-fullscreen')
return launchOptions
}
if (browser.name === 'electron') {
launchOptions.preferences.fullscreen = true
return launchOptions
}
})
}
}
})
Exclude Files From Test Uploads
Keep files out of the project archive that gets uploaded to TestMu AI, which trims upload size and build time. Set the paths in lambdatest-config.json or pass them on the CLI.
Using lambdatest-config.json
Use the ignore_files key in the run_settings option to exclude particular files while uploading your tests.
- Cypress v10
- Cypress v9
{
"run_settings": {
"ignore_files": "<glob_pattern>",
}
}
{
"run_settings": {
"ignore_files": "<glob_pattern>",
}
}
Using the CLI
Specify the files you want to exclude using the CLI flag below with the run command.
| Flag | Purpose | Type |
|---|---|---|
| --if, --ignore_files | Files to ignore in the zip project | String |
Set a Max Duration for Session Timeout
When a single test runs for an extended period, it can block other parallel tests from executing. Use the max_duration flag to set a maximum time limit after which the test is automatically stopped, freeing up resources for other tests.
The valid input for max_duration must be an integer within the range of 2 to 240 minutes.
Using lambdatest-config.json
Use the max_duration key in the run_settings option to specify the session timeout.
- Cypress v10
- Cypress v9
{
"run_settings": {
"max_duration":2
}
}
{
"run_settings": {
"max_duration":2
}
}
Using the CLI
Specify the timeout using the CLI flag below with the run command.
| Flag | Purpose | Type |
|---|---|---|
| --max_duration | idle timeout of a test session | Integer |
Organize Builds With Names and Tags
Name your test cases and categorize your Cypress builds by build name, project name, and tags for easier analysis. Use the following keys to organize your tests.
| Key | Description | Type |
|---|---|---|
| build-name | Represent the name of the build for your test | String |
| project-name | Represents the name of your project | String |
| tags | Group your tests | String |
Example:
Verified{
"run_settings": {
"build-name": "Cypress 10 Demo",
"project-name": "DemoTest",
"tags": "Sprint1",
}
}
Run Tests in Headless Mode
Run your Cypress tests without a visible browser UI to speed up execution. Set the headless key to true.
| Key | Description | Type |
|---|---|---|
| headless | Run test in Headless mode | Boolean |
Example:
Verified{
"run_settings": {
"headless": "true",
}
}
Capture Network Logs
Record the network packets exchanged during a run so you can debug requests and responses after the test. Set the network key to true.
| Key | Description | Type |
|---|---|---|
| headless | Record network packets while the test is running | Boolean |
Example:
Verified{
"run_settings": {
"network": "true",
}
}
Install NPM Package Dependencies
To run your tests on TestMu AI, the platform reads your package.json and installs its dependencies and devDependencies. Because package.json can list several packages that your Cypress tests do not need, listing only the required packages in npm_dependencies reduces build time on TestMu AI.
TestMu AI detects the dependencies to install before running the test in the following ways.
Using npm_dependencies
Inside run_settings of lambdatest-config.json, provide the list of NPM dependencies:
"run_settings": {
"npm_dependencies": {
"cypress": "9.0.0",
},
},
Using package.json
TestMu AI automatically detects the dependencies to install from package.json.
"devDependencies": {
"cypress": "9.2.1",
"eslint": "7.0.0",
"eslint-plugin-json-format": "2.0.1",
"eslint-plugin-mocha": "5.3.0",
},
It's recommended to use npm_dependencies instead of package.json because package.json may contain the dependencies which are not actually used while running the Cypress tests and also, installing these unwanted dependencies will increase the build time.
Install npm packages via a tunnel
Use the npm_via_tunnel flag to route npm install traffic through a tunnel. This helps when installing packages from a private registry, or in a restricted environment where the public npm registry is not directly reachable. Add it to run_settings:
"npm_via_tunnel": true
Once enabled, npm automatically routes all of its traffic through the tunnel.
Why use npm_via_tunnel?
- Security: When installing from a private registry, the tunnel protects your traffic from being intercepted.
- Reliability: In a restricted environment, the tunnel helps ensure npm can still reach the registry and download the packages you need.
- Flexibility: You can access npm packages from any source, including public registries, private registries, and local repositories.
You must already have a tunnel configured and running. To download private dependencies, see how to use private dependencies in Cypress.
Troubleshooting
If npm_via_tunnel is not working, ensure the tunnel is properly configured and running, verify that the npm registry is reachable from within the tunnel, and disable any proxy servers or firewalls that may interfere with the tunnel connection.
Set a Specific Node Version
Pin the Node.js version your tests run on to match your project's dependencies and environment. Use the useNodeVersion capability in the run_settings section of the lambdatest-config.json file.
Supported versions are 18, 20, and 22. The exact versions used are 18.17.1, 20.18.0, and 22.11.0 respectively.
"run_settings": {
"useNodeVersion":"20"
}
Set Environment Variables
Pass environment variables to your Cypress tests so specs can read runtime values such as base URLs and endpoints. You can set them in three ways: via the Cypress config file, via cypress.env.json, or via the TestMu AI Cypress CLI. If you set variables via both the CLI and cypress.env.json, the cypress.env.json file is ignored and only the CLI values are used.
Via the config file
For Cypress 9, use a sample cypress.json:
{
......
"env":{
"CYPRESS_BASE_URL":"https://example.cypress.io/",
"ACTIONS_URL": "commands/actions",
"WINDOW_URL": "commands/window"
},
......
}
For Cypress 10, use a sample cypress.config.js:
module.exports = defineConfig({
env: {
'CYPRESS_BASE_URL':'https://example.cypress.io/',
'ACTIONS_URL' : 'commands/actions',
'WINDOW_URL': 'commands/window'
},
Use them in your test spec:
Verifieddescribe('Sample test', () => {
it('test case - actions', () => {
cy.visit(Cypress.env('CYPRESS_BASE_URL') + Cypress.env('ACTIONS_URL'))
cy.wait(3000)
})
it('test case - window', () => {
cy.visit(Cypress.env('CYPRESS_BASE_URL') + Cypress.env('WINDOW_URL'))
cy.wait(3000)
})
})
Via cypress.env.json
Define the variables in a cypress.env.json file in your project root:
{
"CYPRESS_BASE_URL":"https://example.cypress.io/",
"ACTIONS_URL" : "commands/actions",
"WINDOW_URL": "commands/window"
}
Via the Cypress CLI
Add variables with the --envs parameter:
lambdatest-cypress run --envs "CYPRESS_BASE_URL=https://example.cypress.io/,ACTIONS_URL=commands/actions,WINDOW_URL=commands/window"
Related Cypress Guides
Continue with the guides below to run and manage your Cypress tests on TestMu AI.
- Reference the Cypress CLI commands documents every CLI command and flag in one place.
- Choose supported browsers and operating systems lists the browsers, versions, and platforms you can test on.
- Use private dependencies in Cypress runs tests that need packages from a private registry.
