Cypress plugin to handle multi environment

Easily manage and streamline your Cypress test scripts across multiple environments with the cypress-env npm library. This lightweight utility simplifies the process of handling different environments (such as test, staging, and production) by providing environment-specific settings in your Cypress tests.

---

Install

1$ npm install cypress-env --save-dev

or as a global module

1$ npm install -g cypress-env

Configuration

1. Code in cypress.config.js

In your cypress.config.js file:

1module.exports = defineConfig({
2  e2e: {
3    setupNodeEvents(on, config) {
4      require('cypress-env')(on, config, __dirname)
5    }
6  }
7})

2. Create the env.config folder

Then configure a folder named env.config with your environments JSON files:

1├── cypress
2│   ├── e2e
3│   ├── fixtures
4│   └── support
5├── cypress.config.js
6├── env.config
7│   ├── test.json
8│   ├── stage.json
9│   └── prod.json
10├── node_modules
11├── README.md
12├── package-lock.json
13├── package.json
14└── .gitignore

3. Add your environment JSON files

JSON files must respect this syntax:

1// environment.json
2{
3  "baseUrl": "https://www.google.com",
4  "specPattern": "cypress/e2e/**/**.js",
5  "excludeSpecPattern": "cypress/e2e/**/toExclude.js",
6  "supportFile": "cypress/support/customName.js",
7  "env": {
8    "var1": "value1",
9    "var2": "value2",
10    "var3": "value3",
11    "envName": "environment"
12  }
13}

Parameter	Mandatory	Overwrites value in cypress.config.js	Notes
baseUrl	FALSE	TRUE	Overwrites value in cypress.config.js
specPattern	FALSE	TRUE	Overwrites value in cypress.config.js
excludeSpecPattern	FALSE	TRUE	Overwrites value in cypress.config.js
supportFile	FALSE	TRUE	Requires supportFile in the main e2e or component object set to false
env	FALSE	FALSE	Merged into env object in cypress.config.js

4. Control Log Verbosity with ENV_LOG_MODE

The plugin supports different log modes controlled by the ENV_LOG_MODE environment variable. By default, full logs are displayed. To restrict output and show only summary messages, set:

1# Open Cypress in silent mode
2npx cypress open -e envName=stage -e ENV_LOG_MODE=silent

When ENV_LOG_MODE is set to 'silent', detailed logs such as configuration extraction paths and parameter listings are suppressed. Only the final success message is shown.

Default verbose logs:

1Extracting local configurations from: path/to/environment.json
2 - baseUrl: "https://www.google.com"
3 - specPattern: "cypress/e2e/**/**.js"
4 - excludeSpecPattern: "cypress/e2e/**/toExclude.js"
5 - supportFile: "cypress/support/customName.js"
6 - env: {
7     "var1": "value1",
8     "var2": "value2",
9     "var3": "value3",
10     "envName": "test"
11   }
12
13√ Configurations loaded correctly for the environment: < TEST >

Silent mode logs:

1√ Configurations loaded correctly for the environment: < TEST >

5. Open or run Cypress with the correct environment variables

Open Cypress and inject the envName and optional ENV_LOG_MODE:

1npx cypress open -e envName=test
2# or silent:
3npx cypress open -e envName=test -e ENV_LOG_MODE=silent

or run Cypress tests:

1npx cypress run -e envName=test
2# or silent:
3npx cypress run -e envName=test -e ENV_LOG_MODE=silent

Results example

Correct configuration

1====================================================================================================
2
3Starting plugin: cypress-env
4
5Extracting local configurations from: "path/to/environment.json"
6
7 - baseUrl: "https://www.google.com"
8 - specPattern: "cypress/e2e/**/**.js"
9 - excludeSpecPattern: "cypress/e2e/**/toExclude.js"
10 - supportFile: "cypress/support/customName.js"
11 - env: "{\n    \"var1\": \"value1\",\n    \"var2\": \"value2\",\n    \"var3\": \"value3\",\n    \"envName\": \"test\"\n  }"
12
13√ Configurations loaded correctly for the environment: < TEST >
14
15====================================================================================================

No configuration specified

1====================================================================================================
2
3Starting plugin: cypress-env
4
5√ No environment configuration specified, using basic configuration!
6
7====================================================================================================

Wrong configuration (missing __dirname)

1====================================================================================================
2
3Starting plugin: cypress-env
4
5ConfigurationError!
6You must specify the "__dirname" element in the config, change the require to:
7require("cypress-env")(on, config, __dirname)
8
9====================================================================================================

Little tip for you

In your package.json file create scripts like this:

1// package.json
2{
3  "scripts": {
4    "cy:test": "npx cypress open -e envName=test",
5    "cy:stage": "npx cypress open -e envName=stage",
6    "cy:prod": "npx cypress open -e envName=prod",
7    "cy:stage:silent": "npx cypress open -e envName=stage -e ENV_LOG_MODE=silent"
8  }
9}

So you'll only have to type:

1npm run cy:test

Compatibility with cypress-aws-secrets-manager

cypress-aws-secrets-manager is a plugin that allows secrets stored in AWS Secrets Manager to be loaded into Cypress as environment variables. To make life easier, you can include the key AWS_SECRET_MANAGER_CONFIG inside env.

Parameter	Mandatory	Overwrites value in cypress.config.js	Notes
AWS_SECRET_MANAGER_CONFIG	FALSE	TRUE	Object used by cypress-aws-secrets-manager

1// environment.json
2{
3  "baseUrl": "https://www.google.com",
4  "specPattern": "cypress/e2e/**/**.js",
5  "excludeSpecPattern": "cypress/e2e/**/toExclude.js",
6  "supportFile": "cypress/support/customName.js",
7  "env": {
8    "var1": "value1",
9    "var2": "value2",
10    "var3": "value3",
11    "envName": "test",
12    "AWS_SECRET_MANAGER_CONFIG": {
13      "secretName": "...",
14      "profile": "...",
15      "region": "..."
16    }
17  }
18}

---

THE JOB IS DONE!

Happy testing to everyone! 🎉

ALEC-JS

🙌 Donate to support my work & further development! 🙌