Sunčica Kojić

Tired of manual test updates for different environments? Learn how to configure Cypress for scalable, multi-environment testing and speed up your QA process.

How to Configure Cypress for Multi-Environment Testing (Guide)

Tired of manually updating test configurations for different environments? Learn how to set up a maintainable, scalable Cypress configuration that your team will thank you for.


The Challenge of Environment Management in Cypress

As a QA engineer, you're likely familiar with this scenario: Your Cypress tests run perfectly in your local environment, but then something breaks in staging. Or perhaps you're managing multiple test suites across development, staging, and production environments, each with their own URLs, credentials, and API endpoints. Sound familiar?

While Cypress provides tools for managing different environments, turning these capabilities into a practical, maintainable configuration requires careful planning. Without the right approach, you might find yourself:

 * Constantly updating hardcoded URLs and credentials
 * Wrestling with merge conflicts from environment-specific changes
 * Struggling to maintain consistency across your CI/CD pipeline
 * Dealing with configuration drift between environments

In this guide (Part 1 of our two-part series), we'll cut through the complexity and show you exactly how to set up a robust Cypress configuration that scales across environments.

Part 2 will deal with additional challenges of testing multi-domain applications.

Let's start with environment configuration, from basic setups to production-grade solutions.


Managing cypress.config.js manually

Let’s look at a simple configuration file below.

For instance, to run tests in a local environment, we must specify a local baseUrl. Transitioning to development or staging requires manually adjusting this value, especially if the staging environment has unique settings, such as basic authentication.

//cypress.config.js

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

module.exports = defineConfig({
    e2e: {
        setupNodeEvents() {},
        baseUrl: 'http://localhost:8000',
        // baseUrl: 'https://development.example.com',
        // baseUrl: 'https://staging.example.com',
        supportFile: 'cypress/support/e2e.js',
    },
});

Pros:

 * Quick and Flexible Setup — This method allows for easy setup and quick adjustments.

Cons:

 * Human Error — When configurations are changed manually, mistakes that affect the testing process can easily be made.
 * Merge Conflicts — When multiple team members make changes to the configuration, it can create conflicts that disrupt teamwork.
 * Limited CI/CD Effectiveness — Manual updates can reduce the effectiveness of CI/CD processes by introducing complications that make it harder to maintain smooth, efficient pipelines.
 * Increased Complexity in Testing — While they might seem like a quick fix, manual updates can make the testing process more complicated and less stable overall.

In conclusion, while manually updating configuration files may address immediate testing needs, it ultimately complicates the testing process and undermines stability. Adopting automated configuration management solutions is crucial for building a more robust and adaptable testing environment.


Using separate configuration files for each environment

Separate configuration files can be used to set up different environments in Cypress. For local testing, specify the baseUrl directly in cypress.config.js. To run tests on various environments, we create distinct configuration files in the project’s root directory.

For instance, in the staging environment, we create a file named cypress.staging.js that defines the baseUrl and other environment-specific variables. We do the same for development and production with their respective settings. If staging requires basic authentication, we include the necessary credentials in this configuration file.

//cypress.staging.js

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

module.exports = defineConfig({
    e2e: {
        setupNodeEvents() {
        },
        supportFile: 'cypress/support/e2e.js',
        baseUrl: 'https://staging.example.com',
        auth: {
            username: 'your-username',
            password: 'your-password',
        },
    },
});

When the above configuration for each environment is set up, we need to add custom scripts in our package.json file.

//package.json 

"cy:open": "cypress open",
"cy:run": "cypress run",
"cy:run:staging": "cypress run --config-file cypress.staging.js",
"cy:open:staging": "cypress run --config-file cypress.staging.js",

Now you can switch environments by running yarn cy:staging:run or yarn cy:staging:open command in your terminal.

Pros:

 * Better Organization — Keeping configurations separate for each environment helps maintain clarity and organization.
 * Easy Environment Switching — You can quickly switch between different environments by referencing the right configuration file, which saves time and reduces the need for manual changes.
 * Consistent Test Execution — With environment-specific settings, tests are more likely to run consistently and as expected across different environments.
 * More Flexible — Having separate configuration files for each environment makes it easier to adapt to changes without affecting other setups.

Cons:

 * More Complexity — Managing multiple configuration files can make things more complicated, especially as the project grows.
 * Risk of Misconfigurations — The more configuration files there are, the greater the chance for misconfigurations, which can lead to unreliable tests.
 * Multiple File Maintenance — Keeping all configurations in sync and up-to-date can be time-consuming, particularly as the number of environments increases.
 * Lack of Clarity — With multiple files to keep track of, it can be hard to know which one to modify, increasing the risk of making mistakes.
 * Troubleshooting Complexity — When tests fail, having multiple configurations to check can make it more difficult to pinpoint the issue.

In summary, using separate configuration files for each Cypress environment improves clarity, enables easy switching between environments, and ensures consistent test execution.

However, this approach can also add complexity, raising the risk of misconfigurations and necessitating diligent maintenance. While it allows for tailored settings, careful management is crucial to avoid issues as the number of environments increases.


Managing environment configurations in a single Cypress configuration file

Running Cypress tests across multiple domains and environments introduced specific challenges, such as managing varying configurations, maintaining consistency across different setups, and ensuring seamless execution across domains.

Existing solutions couldn’t fully address these complexities, so we adjusted our approach to meet these unique demands by customizing our testing framework to ensure reliability, scalability, and reduced maintenance overhead.

The key to implementing this solution is creating a cypress.env.json file, which centralizes environment-specific variables like base URLs, API endpoints, and authentication credentials. This allows us to dynamically adjust the configuration for development, staging, or production tests.

For example, instead of hardcoding the base URL for each test suite, you can simply reference an environment variable that points to the correct URL for the active environment.

//cypressEnvConfig.json

const envConfig = {
  development: {
    default: "https://development.example.com",
  },
  staging: {
    default: "https://staging.example.com",
  },
  production: {
    default: "https://production.example.com",
  },
};
module.exports = { envConfig };

Next, in our configuration file cypress.config.json, we need to implement dynamic configuration based on the CYPRESS_ENV environment variable.

//cypress.config.js

const { defineConfig } = require('cypress');
const { envConfig } = require('./cypressEnvConfig');

module.exports = defineConfig({
    e2e: {
        setupNodeEvents(on, config) {
            const environment = process.env.CYPRESS_ENV || 'local';
            const currentEnvConfig = envConfig[environment];
            config.baseUrl = currentEnvConfig.dahefault;
            config.env.urls = currentEnvConfig;

            return config;
        },
        supportFile: 'cypress/support/e2e.js',
    },
});

Let's break down this setup. The setupNodeEvents function is pivotal in Cypress configuration, ensuring tests are properly set up based on the environment defined by the CYPRESS_ENV variable. If the variable is not specified, it defaults to local.

The function retrieves environment-specific settings from the cypressEnvConfig.json file, including baseURL, and updates the configuration accordingly.

The function then returns the modified config object, ensuring that Cypress tests are executed with the precise configuration tailored to the specified or default environment.

Next, each environment is managed through a dedicated run command that utilizes the CYPRESS_ENV variable to precisely configure the test execution environment.

//package.json
 	     
 	      "cy:open": "cypress open",
        "cy:run": "cypress run",
        "cy:open:development": "CYPRESS_ENV=development yarn cypress open",
        "cy:run:development": "CYPRESS_ENV=development yarn cypress run",
        "cy:open:staging": "CYPRESS_ENV=staging yarn cypress open",
        "cy:run:staging": "CYPRESS_ENV=staging yarn cypress run"

To use the centralized configuration from the cypress.env.json file in your test suite, access the environment variables with the Cypress.env() function. For instance, you can retrieve the default URL by using the following code:

//test.cy.js

const requestUrl = Cypress.env('urls').default;

Pros:

 * Single Source of Truth — By using a single file for environment variables, you avoid handling multiple configuration files, and keeping things organized.
 * Easy to Switch Environments — Environment variables allow dynamic switching, simplifying the process for different environments.
 * Reduced Risk of Errors — Referencing environment variables reduces the chance of accidentally running tests in the wrong environment.
 * Scalability — If you need to add a new environment, you only need to update one file, not create new ones for each environment.
 * Consistency — A single configuration file ensures uniform settings across all environments, reducing discrepancies and improving test reliability.
 * Simplified Maintenance — A single file is easier to maintain than multiple configuration files, reducing the potential for inconsistencies.

Cons:

 * Security Risks — Sensitive data in a single file (e.g., credentials) may expose risks if not secured properly.
 * Configuration Mistakes — Mistakes in the cypress.env.json file can affect all environments if not handled carefully.

This approach allows you to reference the correct URL based on the active environment without hardcoding any values in your tests.


Simplify Environment Management with a Unified Configuration Approach

Handling multiple environments in Cypress is essential for effective testing across various configurations. Relying on manual updates or separate settings can lead to mistakes and make things more complicated, but using one configuration with dynamic environment variables is a more efficient solution.

This method reduces errors and makes it easy to adapt to new environments. It also keeps things simple, so teams can focus on building strong tests and ensuring the app works properly during deployment.

Ultimately, this makes Cypress a powerful tool for end-to-end testing, helping create a faster and more reliable workflow as applications grow.

Continue reading the 2nd part of this series, where we’ll talk about managing multiple domains in Cypress. Just like with environments, testing across different domains can be tricky. But with the right approach, you can handle it easily and keep your tests running smoothly.

Are Your Cypress Tests a Configuration Mess?

Learn to test multiple domains in Cypress using cy.visit(), cy.origin(), and environment variables. Solve session, CORS, and configuration challenges.

How to Test Multiple Domains in Cypress: A Complete Guide

Your Cypress tests work great within a single domain, but what happens when your application spans multiple domains?

Whether you're dealing with microservices, third-party integrations, or localized versions of your site, testing across domains can quickly become complicated.


Why Multi-Domain Testing in Cypress Can Be Tricky

If you're a QA engineer working with modern web applications, you've likely encountered these scenarios:

 * Your tests break when crossing domain boundaries
 * Session management becomes unreliable between different domains
 * CORS issues keep popping up in your test runs
 * Your configuration becomes unwieldy when handling multiple domains

In Part 1 of this series, we covered how to set up Cypress for different environments. Now in Part 2, we'll tackle the specific challenges of testing applications that span multiple domains. You'll learn practical approaches using cy.visit(), cy.origin(), and environment variables to create a robust, maintainable test suite that works seamlessly across domains.

Let's explore the different solutions and find the right approach for your testing needs.


Simplifying Multi-Domain Tests with cy.visit()

When testing an application across multiple domains, Cypress's cy.visit() allows you to navigate to different URLs, ensuring consistent application behavior. This is particularly valuable for applications that interact with external services, APIs, or localized versions.

In the example below, cy.visit() is used in separate it blocks to load various domains within a Cypress test suite. Each test case interacts with a specific domain, performing assertions to validate functionality independently. This method facilitates multi-domain testing, ensuring consistent behavior across different websites within a single test file.

//test.cy.js


describe('Multi-Domain Testing with cy.visit()', () => {
  it('Testing functionality on https://example.eu', () => {
    cy.visit('https://example.eu');

   //Your tests here
  });

  it('Testing functionality on https://example.us', () => {
    cy.visit('https://example.us');

    //Your tests here
  });
});

Pros:

 * Simplified Test Writing — You can streamline the process of writing tests by managing domain navigation with a single command.
 * Early Issue Detection: — Helps identify domain-specific issues early in the testing phase.
 * Simplified Navigation — Enables easy transitions between domains in a single command.

Cons:

 * CORS Issues — Cross-origin requests can be blocked, causing functionality issues between domains.
 * Increased Complexity — Jumping between domains in tests can introduce more complexity, making tests harder to maintain.
 * Slower Test Execution — Multi-domain navigation can slow down test execution.
 * Harder Debugging — The added complexity can make pinpointing issues and debugging more challenging.
 * More Maintenance Effort— Any changes to the configuration might require updates across multiple test specs, increasing maintenance work.
 * Session Management Complexity — Managing authentication tokens and cookies across domains is challenging.

In conclusion, although cy.visit() simplifies multi-domain testing in Cypress, it’s important to consider the challenges that may emerge during the process.


How to Test Multiple Domains with cy.origin()

The cy.origin() command in Cypress is essential for testing applications that span multiple domains. This command enables you to run test commands within the context of different origins, making it particularly useful for applications with varied behaviors based on the domain accessed.

The example demonstrates how to use cy.origin() to run tests across two different domains: https://example.eu and https://example.us. Each block begins with cy.visit('/') to navigate to the root of the specified domain, allowing you to add test code to interact with elements on each site.

This approach ensures that tests remain isolated by domain, promoting clear and organized multi-origin testing.

//test.cy.js

describe('Multi-Domain Testing', () => {
  it('should navigate and perform actions on example.eu', () => {
    cy.origin('https://example.eu', () => {
      cy.visit('/');
      // your test code for the EU site
    });
  });

  it('should navigate and perform actions on example.us', () => {
    cy.origin('https://example.us', () => {
      cy.visit('/');
      // your test code for the US site
    });
  });

Pros:

 * Session Persistence — Maintains user sessions across different domains, ensuring seamless interactions.
 * Realistic Testing — Reflects real-world user behavior by allowing actions like logging in or retrieving user data without losing authentication.
 * Context-Specific Execution — Executes commands within the relevant domain's context, improving the precision and reliability of test results.

Cons:

 * Added Complexity — Each test block runs independently, which can make the overall test structure harder to follow and manage.
 * Debugging Difficulties — A more complex setup can make identifying and fixing issues more challenging.
 * Time-Consuming Updates — Requires individual updates across multiple test specs, increasing maintenance time and the risk of inconsistencies.

In summary, while cy.origin() in Cypress offers significant advantages for testing multi-domain applications, such as session persistence and context-specific execution, it also introduces complexities that can complicate the testing process and increase maintenance efforts. Careful consideration of these trade-offs is essential for effective multi-domain testing strategies.


Using Environment Variables to Manage Multiple Domains

After reviewing a few different approaches to multi-domain testing in Cypress, it becomes clear that managing different configurations is essential for ensuring accurate and efficient test execution. Cypress provides a straightforward way to handle this through environment variables. By using environment variables, you can control which domain or API your tests interact with, making it easier to manage various scenarios and requirements.

Setting Environment Variables

//cypress.env.json

const envConfig = {
  development: {
    DOMAIN_EU: "https://example.dev.eu",
    DOMAIN_US: "https://example.dev.us",
  },
  staging: {
    DOMAIN_EU: "https://example.staging.eu",
    DOMAIN_US: "https://example.staging.us",
  },
  production: {
    DOMAIN_EU: "https://example.eu",
    DOMAIN_US: "https://example.us",
  },
};

module.exports = { envConfig };

The above setup allows you to seamlessly connect specific domains with their respective environments, ensuring that your tests run against the correct URLs based on the active configuration. By managing both domains and environments together, you create a flexible and scalable testing framework that can easily adapt to changing requirements.

Once you have defined your environment variables, you can easily access them within your test cases. Here’s how to incorporate environment variables in your tests:

//test.cy.js

describe('Multi-Domain Testing with Environment Variables', () => {
  it('should navigate to the specified EU domain', () => {
    const domain = Cypress.env('DOMAIN_EU');
    cy.visit(domain);
    // your test code for the EU site
  });

  it('should navigate to the specified US domain', () => {
    const domain = Cypress.env('DOMAIN_US');
    cy.visit(domain);
    // your test code for the US site
  });
});

Pros:

 * Simplified Management — Environment variables allow a single location to manage URLs and API endpoints, simplifying updates and reducing hard-coded values in test scripts.
 * Easy Updates — Updating a value in the configuration file automatically reflects across all tests, saving time and making your tests more adaptable.
 * Reliable Testing — By reducing manual changes, you ensure more consistent and accurate test results across different environments.
 * Flexible Configurations — You can easily set up different environment variables for development, staging, and production, making it seamless to switch between environments.
 * CI/CD Friendly — CI/CD pipelines can easily integrate environment variables, ensuring consistent configurations across automated testing and deployment, which reduces the chances of environment-specific problems.
 * Version Control Friendly — Sensitive information (like API keys) can be stored in environment variables instead of being hard-coded, making it safer to use version control systems without exposing sensitive data.
 * Dynamic Configuration — Environment variables allow for runtime configuration changes, which can be useful for tests that require different setups based on varying conditions.

Cons:

 * Security Concerns — Sensitive data in environment variables can be at risk if not handled carefully, especially if it appears in logs or error messages.
 * Managing Complexity — As projects grow, managing a large number of environment variables can get tricky, requiring good organization and documentation.
 * Setup Dependencies — Tests may fail if the necessary environment variables are not set correctly, leading to potential issues in test execution.

Leveraging environment variables in Cypress provides a flexible and maintainable approach to managing multiple domains during testing. By centralizing your configurations and allowing for easy updates, you can enhance the efficiency of your testing process while minimizing errors associated with manual changes. This practice is especially valuable in multi-domain scenarios where different domains require unique settings.


What We Learned About Multi-Domain Testing with Cypress

In conclusion, effectively managing multiple domains in Cypress is crucial for ensuring a seamless user experience in modern web applications. A well-planned approach helps you overcome common challenges in multi-domain testing, such as handling session management, resolving CORS issues, and addressing the unique behaviors of different domains.

By applying the right strategies, you can achieve more reliable test execution across multiple domains, ultimately improving application quality and user satisfaction. Adopting these best practices will enable you to build robust applications that consistently meet user expectations and deliver dependable performance.

AuthorSunčica Kojić

Start a Project