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.

Table of Contents

• Install
• Breaking Changes in v2.x
• Configuration
  • 1. Code in cypress.config.js
  • 2. Create the env.config folder
  • 3. Add your environment JSON files
  • 4. Control Log Verbosity with ENV_LOG_MODE
  • 5. Open or run Cypress with the correct environment variables
• Shared Configurations Feature
• Configuration Priority Order
• Results example
  • Correct configuration
  • Correct configuration with shared settings
  • No configuration specified
  • Wrong configuration (missing __dirname)
• Little tip for you
• Compatibility with cypress-aws-secrets-manager

Install

$ npm install cypress-env --save-dev

or as a global module

$ npm install -g cypress-env

Breaking Changes in v2.x

Starting from version 2.0, cypress-env uses async/await syntax for better compatibility with modern Cypress and other plugins. Update your configuration as follows:

Old syntax (v1.x):

// cypress.config.js - OLD
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require("cypress-env")(on, config, __dirname)
    },
  },
})

New syntax (v2.x):

// cypress.config.js - NEW
module.exports = defineConfig({
  e2e: {
    async setupNodeEvents(on, config) {
      const { setCypressEnv } = require("cypress-env")
      config = await setCypressEnv(config, __dirname)
      return config
    },
  },
})

The new syntax provides:

• Better compatibility with async plugins like cypress-aws-secrets-manager
• Explicit function naming for clarity
• Proper async/await support

Configuration

1. Code in cypress.config.js

In your cypress.config.js file:

module.exports = defineConfig({
  e2e: {
    async setupNodeEvents(on, config) {
      const { setCypressEnv } = require("cypress-env")
      config = await setCypressEnv(config, __dirname)
      return config
    },
  },
})

2. Create the env.config folder

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

├── cypress
│   ├── e2e
│   ├── fixtures
│   └── support
├── cypress.config.js
├── env.config
│   ├── test.json
│   ├── stage.json
│   └── prod.json
├── node_modules
├── README.md
├── package-lock.json
├── package.json
└── .gitignore

3. Add your environment JSON files

JSON files must respect this syntax:

// environment.json
{
  "baseUrl": "https://www.google.com",
  "specPattern": "cypress/e2e/**/**.js",
  "excludeSpecPattern": "cypress/e2e/**/toExclude.js",
  "supportFile": "cypress/support/customName.js",
  "env": {
    "var1": "value1",
    "var2": "value2",
    "var3": "value3",
    "envName": "environment"
  }
}

| 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 | | shared | FALSE | N/A | Boolean: enables loading of shared configurations from _shared.json | | 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:

# Open Cypress in silent mode
npx 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:

Extracting local configurations from: path/to/environment.json
 - baseUrl: "https://www.google.com"
 - specPattern: "cypress/e2e/**/**.js"
 - excludeSpecPattern: "cypress/e2e/**/toExclude.js"
 - supportFile: "cypress/support/customName.js"
 - env: {
     "var1": "value1",
     "var2": "value2",
     "var3": "value3",
     "envName": "test"
   }

√ Configurations loaded correctly for the environment: < TEST >

Silent mode logs:

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

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

or run Cypress tests:

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

Shared Configurations Feature

You can now use shared configurations across multiple environments! Add a _shared.json file in your env.config folder to define common settings that can be reused across environments.

Structure with shared configurations:

├── env.config
│   ├── _shared.json    # ← Common configurations
│   ├── test.json
│   ├── stage.json
│   └── prod.json

Example _shared.json:

{
  "viewportWidth": 1920,
  "viewportHeight": 1080,
  "supportFile": "cypress/support/env.js",
  "env": {
    "commonApiUrl": "https://api.example.com",
    "defaultTimeout": 10000,
    "retries": 2,
    "sharedVariable": "This value is shared across environments",
    "specificTestVar": "This value is overwritten buy env configurations"
  }
}

Example environment with shared configurations:

// test.json
{
  "shared": true,
  "baseUrl": "https://test.example.com",
  "specPattern": ["**/*.test.js"],
  "env": {
    "specificTestVar": "This overrides shared settings"
  }
}

When "shared": true is set in an environment file:

1. Shared configurations are loaded first from _shared.json
2. Environment-specific settings override shared ones
3. Environment variables are merged, with environment-specific taking precedence

Configuration Priority Order:

The plugin respects a strict priority order in two different way:

Environment Variables Priority (env object):

1. CLI arguments (highest priority) - Cannot be overridden
2. Environment JSON files - Environment-specific settings
3. Shared configurations - Common settings from _shared.json
4. Default config - Base cypress.config.js settings (lowest priority)

Cypress Configurations Priority (baseUrl, specPattern, etc.):

1. CLI arguments (highest priority) - Cannot be overridden
2. Default config - Base cypress.config.js settings
3. Environment JSON files - Environment-specific settings
4. Shared configurations - Common settings from _shared.json (lowest priority)

Why the difference?

• Environment variables have Cypress built-in support to detect CLI vs config source, allowing the plugin to respect the intuitive priority order
• Cypress configurations (baseUrl, specPattern, etc.) don't provide source detection, so the plugin cannot establish intuitive priority order

This means:

• CLI parameters like -e var=value will never be overwritten for both types
• For env variables: Environment-specific > Shared > Default
• For configurations: Default > Shared > Environment-specific

Benefits:

• Reuse common configurations across multiple environments
• Override only what's different per environment
• Cleaner environment files with less duplication
• Easier maintenance of shared settings
• Predictable configuration precedence with CLI always taking priority

Results example

Correct configuration

====================================================================================================

Starting plugin: cypress-env

Extracting local configurations from: "path/to/environment.json"

 - baseUrl: "https://www.google.com"
 - specPattern: "cypress/e2e/**/**.js"
 - excludeSpecPattern: "cypress/e2e/**/toExclude.js"
 - supportFile: "cypress/support/customName.js"
 - env: "{\n    \"var1\": \"value1\",\n    \"var2\": \"value2\",\n    \"var3\": \"value3\",\n    \"envName\": \"test\"\n  }"

√ Configurations loaded correctly for the environment: < TEST >

====================================================================================================

Correct configuration with shared settings

====================================================================================================

Starting plugin: cypress-env

Extracting local configurations from: "path/to/test.json"

Loading shared configurations from: "path/to/_shared.json"

 - baseUrl: "https://test.example.com"
 - specPattern: ["**/*.test.js"]
 - viewportWidth: 1920
 - viewportHeight: 1080
 - supportFile: "cypress/support/env.js"
 - env: {
     "commonApiUrl": "https://api.example.com",
     "defaultTimeout": 10000,
     "retries": 2,
     "sharedVariable": "This value is shared across environments",
     "envName": "test",
     "specificTestVar": "This overrides shared settings"
}

√ Configurations loaded correctly for the environment: < TEST > (with shared configurations)

====================================================================================================

No configuration specified

====================================================================================================

Starting plugin: cypress-env

√ No environment configuration specified, using basic configuration!

====================================================================================================

Wrong configuration (missing __dirname)

====================================================================================================

Starting plugin: cypress-env

ConfigurationError!
You must specify the "__dirname" element in the config, change the require to:
      const { setCypressEnv } = require("cypress-env")
      config = await setCypressEnv(config, __dirname)
      return config

====================================================================================================

Little tip for you

In your package.json file create scripts like this:

// package.json
{
  "scripts": {
    "cy:test": "npx cypress open -e envName=test",
    "cy:stage": "npx cypress open -e envName=stage",
    "cy:prod": "npx cypress open -e envName=prod",
    "cy:stage:silent": "npx cypress open -e envName=stage -e ENV_LOG_MODE=silent"
  }
}

So you'll only have to type:

npm 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 |

Example cypress.config.js with both plugins:

// cypress.config.js
module.exports = defineConfig({
  e2e: {
    async setupNodeEvents(on, config) {
      // Load cypress-env FIRST to set up environment configurations
      const { setCypressEnv } = require("cypress-env")
      config = await setCypressEnv(config, __dirname)

      // Then load AWS secrets using the environment configuration
      const { getSecretFromAWS } = require("cypress-aws-secrets-manager")
      config.env = await getSecretFromAWS(config.env, __dirname)
      require("cypress-aws-secrets-manager/tasks")(on, config)

      return config
    },
  },
})

Example environment.json with AWS configuration:

// environment.json
{
  "baseUrl": "https://www.google.com",
  "specPattern": "cypress/e2e/**/**.js",
  "excludeSpecPattern": "cypress/e2e/**/toExclude.js",
  "supportFile": "cypress/support/customName.js",
  "env": {
    "var1": "value1",
    "var2": "value2",
    "var3": "value3",
    "envName": "test",
    "AWS_SECRET_MANAGER_CONFIG": {
      "secretName": "...",
      "profile": "...",
      "region": "..."
    }
  }
}

Important: Always import cypress-env before cypress-aws-secrets-manager to ensure environment configurations are loaded first.

THE JOB IS DONE!

Happy testing to everyone! 🎉

ALEC-JS