@commercetools-frontend/cypress-environments

@commercetools-frontend/cypress-environments

This package allows to load environment variables into a Cypress environment from dotenv files.

Installation

$ npm install --save @commercetools-frontend/cypress-environments

Usage

Inside of your cypress.config.js import the package as follows:

const {
  getConfigurationForEnvironment,
} = require('@commercetools-frontend/cypress-environments');

Then inside your e2e.setupNodeEvents in Cypress v10.x load the configuration by calling await getConfigurationForEnvironment(environment).

This will return an object with the merged configuration based on the requested environment.

Adding a configuration file

This module uses cosmiconfig to load a configuration file named cypress-environments. As a result it supports many formats such as cypress-environments.config.cjs or cypress-environments.rc.json depending on your preference.

Within the configuration file an array environments property should be defined containing a set of environments with name, secrets and config globs.

The contents of the configuration file could look like:

const projectKeys = {
  gcpEu: 'ctp-gcp-production-eu',
};

module.exports = {
  environments: [
    {
      name: projectKeys.gcpEu,
      secrets: `cypress/config/${projectKeys.gcpEu}/.env.secrets*`,
      config: `cypress/config/${projectKeys.gcpEu}/.env.config*`,
    },
  ],
};

From here the documentation assumes the above format and naming for further examples.

Adding environment configurations

The package expects configurations for environments to be stored in cypress/config/<environment_name>. For example this structure:

cypress/config
├── ctp-gcp-production-eu
|──── .env.config
|──── .env.secrets.ci (Decrypred from `*.enc`)
|──── .env.config.local.template
|──── .env.secrets.local.template
├── ctp-aws-production-fra
└── ctp-vw-production-eu

Would load the values from .env.config anytime the environment is ctp-gcp-production-eu. Additionally on CI (when CI=true) it would load the .env.secrets.ci file, otherwise it would attempt to load values from .env.config.local and .env.secrets.local (assuming they have been properly configured - see *.template files for reference).

Given multiple files can be loaded some values can be overwritten by a subsequently loaded file. First the .env.config file will be loaded. After the secrets from .env.secrets and then .env.secrets.ci or .env.secrets.local respectively. Any file loaded later can overwrite values of a file loaded before.

Provided configuration values

The module provides default values for ctp-aws-production-fra, ctp-gcp-production-eu, ctp-gcp-production-us and ctp-gcp-production-au. These values will be loaded first before any custom configuration. These default configurations contain the API_URL, MC_API_URL, MC_URL and AUTH_URL for the given environment.

Troubleshooting

Configuration does not load as expected

Inspect the logs of the module to inspect which files match the globs. This output could be:

ℹ️  'CI' environment variables are defined. Assuming operating from a CI system.
ℹ️  Found 1 secret file(s) and 1 config file(s) matching the defined globs.
✅ Found and loading environment variables from: 'cypress/config/ctp-gcp-production-eu/.env.config'
ℹ️  No environment variables at: 'cypress/config/ctp-gcp-production-eu/.env.config.ci'. If needed create it or duplicate the template file.
✅ Found and loading environment variables from: 'cypress/config/ctp-gcp-production-eu/.env.secrets.ci'
✅ Found and loading environment variables from: '/Users/<username>/merchant-center-frontend/packages-cypress/environments/src/config/.env.ctp-gcp-production-eu.config'

Verify that the files are loaded as expected and make sure they exist.

Secrets are not loaded

Make sure the secrets are decrypted on CI from the *.enc or locally a *.template file for the secrets has been duplicated and filled.

Local configuration and secrets are loaded on CI

Ensure that the CI environment variable is set. Most CI providers set it by default but you can also pass it to the command when running Cypress.