Cypress - Environment Variables

Cypress - Environment Variables

Environment variables in Cypress allow you to store and manage configuration values that can be accessed throughout your test suite. This is useful for defining base URLs, API keys, user credentials, or any other data that might change between different environments (e.g., development, staging, production) or test runs.

Defining Environment Variables

There are several ways to define environment variables in Cypress:

1. Configuration File (cypress.config.js or cypress.config.ts)

You can define environment variables within the env object in your Cypress configuration file. This is the most common and recommended way for project-specific variables.

Example in cypress.config.js:

const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
    baseUrl: 'http://localhost:3000',
    env: {
      apiUrl: 'https://api.example.com/v1',
      username: 'testUser',
      // Add other environment variables here
    },
  },
});

2. Command Line Interface (CLI)

You can pass environment variables directly via the command line when running Cypress using the --env flag (or -e). This is useful for overriding values from the configuration file or for CI/CD pipelines.

npx cypress run --env username=admin,password=secret123

Or for a single variable:

npx cypress open -e apiUrl=https://staging-api.example.com

Values passed via CLI will override those set in the configuration file.

3. Operating System Environment Variables

Cypress automatically recognizes operating system environment variables prefixed with CYPRESS_. For example, if you set an OS environment variable CYPRESS_API_KEY=yourkey123, it will be available in your tests as Cypress.env('API_KEY').

# In your terminal (Linux/macOS)
export CYPRESS_API_KEY=yourkey123
npx cypress run

# In your terminal (Windows PowerShell)
$env:CYPRESS_API_KEY = "yourkey123"
npx cypress run

This method is particularly useful for sensitive data like API keys that you don’t want to commit to your repository.

Accessing Environment Variables in Tests

You can access environment variables in your test files using the Cypress.env() command:

describe('Environment Variable Test', () => {
  it('should use environment variables', () => {
    const apiUrl = Cypress.env('apiUrl');
    const username = Cypress.env('username');

    cy.visit(Cypress.config('baseUrl')); // Accessing baseUrl from config
    cy.log(`API URL: ${apiUrl}`);
    cy.log(`Username: ${username}`);

    // Example usage:
    // cy.request(`${apiUrl}/users?username=${username}`).then((response) => {
    //   expect(response.status).to.eq(200);
    // });
  });
});

Precedence of Environment Variables

Cypress determines the value of an environment variable based on the following order of precedence (highest to lowest):

1. CLI arguments (--env).
2. CYPRESS_ prefixed OS environment variables.
3. Variables defined in the env object within cypress.config.js or cypress.config.ts.

Use Cases

• Base URLs: Define different baseUrl or API endpoints for different environments.
• Credentials: Store test user credentials (though consider cy.session() for login flows).
• Feature Flags: Control test execution based on feature flags.
• API Keys: Securely provide API keys, especially when using OS environment variables for CI.

Effectively using environment variables makes your Cypress tests more flexible, configurable, and maintainable across different testing stages and setups.