Overview
This Cypress plugin can help you in the following cases.
1 Your test configuration depends on multiple factors.
For example, apiBaseUrl
differs per environment (dev, staging etc).
2 You need to be able to combine multiple configuration files together, allowing for overrides among configurations.
3 You need to store sensitive information (e.g., login credentials) in configuration files that should not be versioned (e.g., ignored by Git).
Setup
1 Install through Yarn:
yarn add --dev cypress-configuration-builder
or NPM:
npm install --dev cypress-configuration-builder
2 Open your Cypress plugins file (usually, /cypress/plugins/index.js
) and add:
const ccb = ; /** * @type */module ccb;
Example
yarn start --env configKeys=a.b
This will load the following files:
cypress.json
(loaded by default - see Cypress Configuration)cypress.a.json
cypress.a-secrets.json
cypress.b.json
cypress.b-secrets.json
Explanation
1 Except for cypress.json
, the rest of the file names follow these patterns:
- either:
cypress.<configKey>.json
- or:
cypress.<configKey>-secrets.json
2 The configuration files we want to combine are defined in the configKeys
environment variable.
2.1 The file keys are separated by a dot (U+002E) character.
2.2 The separator can change through the configKeysSeparator parameter.
2.3 2.1 and 2.2 imply that we cannot have the configKeysSeparator
string in a file name's configKey
part.
For example, if configKeysSeparator
is the dot character, we cannot have a configuration file named cypress.a.2.json
because passing it to configKeys
:
yarn run cypress run --env configKeys=a.2
would result in loading cypress.a.json
and cypress.2.json
, instead of cypress.a.2.json
.
3 The order the files are defined in the call (--configKeys
) matters.
Later files override earlier ones. For example, assuming we have the following two files:
// File: cypress.json "baseUrl": "http://default.com"
// File: cypress.a.json "baseUrl": "http://a.com"
baseUrl
will end up equal to: http://a.com.
3.1 The files are combined with deep merging.
For example, assuming the following files:
// File: cypress.json "a": "b": "c": 1 "d": 2
// File: cypress.a.json "a": "b": "c": 9
we will end up with this configuration:
4 Except for cypress.json
, if any of the other files does not exist, it is simply ignored.
Best practices
1 Use the cypress.json
file for parameters that should be shared by all tests.
2 Use environment (e.g., cypress.dev.json
) specific files for parameters specific to an environment.
3 Use the -secrets
files for configuration you want available only on your local machine. For example, login credentials.
Note Remember to ignore the
-secrets
files from Git in order to avoid leaking sensitive information.For example, add this entry to your
.gitignore
file:cypress.*-secrets.json
4 You are not restricted to per environment configuration files.
Feel free to mix and match in order to create a configuration that suits your needs.
For example, let's say we have the following file:
// File: cypress.a.json "a": 2 "b": 1
And we want to run a test that will have:
a
equal to 1 just for this test- keep the rest of the configuration in this file (in this case, just
b
)
We can simply create a new configuration file, let's call it cypress.a-2.json
, where we will define a
equal to 1:
// File: cypress.a-2.json "a": 1
Then, we can use it like this:
yarn start --env configKeys=a.a-2
This will give us the expected configuration:
5 Consider using the Cypress configuration file JSON schema in your configuration files for autocompletion.
Configuration
configKeys Indicates the configuration files to be loaded, in addition to the one Cypress loads by default (e.g., cypress.json
).
For example:
yarn run cypress run --env configKeys=a.b
will merge: cypress.json
, cypress.a.json
, cypress.a-secrets.json
, cypress.b.json
and cypress.b-secrets.json
.
configKeysSeparator Specifies the string that will be used as a separator for the values of configKeys
.
For example:
yarn run cypress run --env configKeys=a#b,configKeysSeparator=#
Notice, that we now use the number sign character (#) as a separator in configKeys
.
Invalid separators:
Tests
In order to execute the test suite run:
yarn test