For AI agents and LLMs: a machine-readable index is available at llms.txt. A plain-Markdown version of any documentation page is available by appending .md to its URL.
Skip to main content

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:

  1. Adding the CLI flag details in the lambdatest-config.json file
  2. Using the CLI
tip

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.

note

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.

Verified
lambdatest-config.json
{
"run_settings": {
"cypress_config_file": "cypress.json",
"video": true
}
}

Using the CLI

Specify the Cypress configuration file using the CLI flag below with the run command.

FlagPurposeType
--ccf, --cypress-config-filePath of the config fileString

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.

Verified
lambdatest-config.json
{
"run_settings": {
"specs": "**/*.cy.js",
}
}

Using the CLI

Specify the spec files using the CLI flag below with the run command.

FlagPurposeType
-s, --specsPath of the spec file or directory or patternString

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.

Verified
lambdatest-config.json
{
"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.

Verified
lambdatest-config.json
{
"run_settings": {
"geo_location": "<country_code>",
}
}

Using the CLI

Specify the geolocation using the CLI flag below with the run command.

FlagPurposeType
--geo, --geo_locationPass the Geo country codeString

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.

Verified
lambdatest-config.json
{
"run_settings": {
"resolution": "1024x768",
}
}

Using the CLI

Specify the system's resolution using the CLI flag below with the run command.

FlagPurposeType
--resPass the resolutionString

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:

Verified
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

tip

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:

Verified
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:

Verified
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.

Verified
lambdatest-config.json
{
"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.

FlagPurposeType
--if, --ignore_filesFiles to ignore in the zip projectString

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.

Verified
lambdatest-config.json
{
"run_settings": {
"max_duration":2
}
}

Using the CLI

Specify the timeout using the CLI flag below with the run command.

FlagPurposeType
--max_durationidle timeout of a test sessionInteger

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.

KeyDescriptionType
build-nameRepresent the name of the build for your testString
project-nameRepresents the name of your projectString
tagsGroup your testsString

Example:

Verified
lambdatest-config.json
{
"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.

KeyDescriptionType
headlessRun test in Headless modeBoolean

Example:

Verified
lambdatest-config.json
{
"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.

KeyDescriptionType
headlessRecord network packets while the test is runningBoolean

Example:

Verified
lambdatest-config.json
{
"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:

Verified
lambdatest-config.json
"run_settings": {
"npm_dependencies": {
"cypress": "9.0.0",
},
},

Using package.json

TestMu AI automatically detects the dependencies to install from package.json.

Verified
package.json
"devDependencies": {
"cypress": "9.2.1",
"eslint": "7.0.0",
"eslint-plugin-json-format": "2.0.1",
"eslint-plugin-mocha": "5.3.0",
},
note

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:

Verified
"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.

note

Supported versions are 18, 20, and 22. The exact versions used are 18.17.1, 20.18.0, and 22.11.0 respectively.

Verified
lambdatest-config.json
"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:

Verified
{
......
"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:

Verified
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:

Verified
describe('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:

Verified
{
"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:

Verified
lambdatest-cypress run --envs "CYPRESS_BASE_URL=https://example.cypress.io/,ACTIONS_URL=commands/actions,WINDOW_URL=commands/window"

Continue with the guides below to run and manage your Cypress tests on TestMu AI.

Terminal First Testing With Kane CLI

Natural language browser & mobile app tests right from terminal.

×
Schedule Your Personal Demo
Kane CLI terminal

Help and Support

Related Articles