{"__v":0,"_id":"56954a97fe18811700c9c025","category":{"__v":16,"_id":"56954a95fe18811700c9bfdf","pages":["56954a97fe18811700c9c01d","56954a97fe18811700c9c01e","56954a97fe18811700c9c01f","56954a97fe18811700c9c020","56954a97fe18811700c9c021","56954a97fe18811700c9c022","56954a97fe18811700c9c023","56954a97fe18811700c9c024","56954a97fe18811700c9c025","56954a97fe18811700c9c026","56954a97fe18811700c9c027","56954a97fe18811700c9c028","56954a97fe18811700c9c029","5696cda524490c3700170a05","5697efe61c4dc8230054268e","5697efe72cf4060d004eaa75","56993ff47465970d00650b8f","56a7a155dfdabc0d000ae910","56a7a155b5d0920d0051cd81","56a7a1a6cf6d771700baeee3","56a7a1a63d33bc2100793d5d","56a7a23097e8b00d0096d209","56a7a230ea3e3417000df4b1","56a7a25acf6d771700baeee6","56a7a25a03f28c0d00a545bf","56a7a2b83d33bc2100793d60","56a7a2b8b5d0920d0051cd82","56b27fe42db51f0d0044e566"],"project":"568fde81b700ce0d002f4b43","version":"56954a94fe18811700c9bfda","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-09T16:40:53.584Z","from_sync":false,"order":4,"slug":"guides","title":"Guides"},"parentDoc":null,"project":"568fde81b700ce0d002f4b43","user":"568fffce769f210d0013258f","version":{"__v":6,"_id":"56954a94fe18811700c9bfda","project":"568fde81b700ce0d002f4b43","createdAt":"2016-01-12T18:48:52.007Z","releaseDate":"2016-01-12T18:48:52.007Z","categories":["56954a95fe18811700c9bfdb","56954a95fe18811700c9bfdc","56954a95fe18811700c9bfdd","56954a95fe18811700c9bfde","56954a95fe18811700c9bfdf","56954a95fe18811700c9bfe0","56954a95fe18811700c9bfe1","56954a95fe18811700c9bfe2","56954a95fe18811700c9bfe3","56954a95fe18811700c9bfe4","5695649fdcaf0d1700cb8721","5696c1168560a60d00e2c1d6","56a7a32e79395317007c1ad6","5898fc3eec49fb0f004c2663","589cc675ea37da23004e05e1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"foo","version_clean":"0.0.0","version":"0.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-09T16:43:06.271Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"# Contents\n\n- :fa-angle-right: [Use Case](#section-use-case)\n- :fa-angle-right: [Setting Environment Variables](#section-setting-environment-variables)\n  - [Option #1: Set in `cypress.json`](#section-option-1-set-in-cypress-json-)\n  - [Option #2: Create a `cypress.env.json`](#section-option-2-create-a-cypress-env-json-)\n  - [Option #3: Export as `CYPRESS_*`](#section-option-3-export-as-cypress_-)\n  - [Option #4: Pass in from the CLI as `--env`](#section-option-4-pass-in-from-the-cli-as-env-)\n- :fa-angle-right: [Overriding Configuration](#section-overriding-configuration)\n\n***\n\n# Use Case\n\nEnvironment variables should be used:\n- Whenever values are different across developer machines\n- Whenever values change frequently and are highly dynamic\n\nThe most common use case is to access custom values you've written in your `hosts` file.\n\nFor instance instead of hard coding this in your tests:\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  // this would break on other dev machines\\n  .visit(\\\"http://server.dev.local\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nWe can move this into an environment variable.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy\\n  // now this is pointing to a dynamic\\n  // environment variable\\n  .visit(Cypress.env(\\\"host\\\"))\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n# Setting Environment Variables\n\nThere are 4 different ways to set environment variables. Each has a slightly different use case.\n\n**To summarize you can:**\n\n- set in `cypress.json`\n- create a `cypress.env.json`\n- export as `CYPRESS_*`\n- pass in the CLI as `--env`\n\nDon't feel obligated to pick just one method. It is common to use one strategy for local development but another when running in CI.\n\nWhen your tests are running, you can use the [`Cypress.env()`](https://on.cypress.io/api/env) function to access the values of your environment variables.\n\n***\n\n## Option #1: Set in `cypress.json`\n\nAny key/value you set in your [`cypress.json`](https://on.cypress.io/guides/configuration) under the `env` key will become an environment variable.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// cypress.json\\n{\\n  \\\"projectId\\\": \\\"128076ed-9868-4e98-9cef-98dd8b705d75\\\",\\n  \\\"env\\\": {\\n    \\\"foo\\\": \\\"bar\\\",\\n    \\\"some\\\": \\\"value\\\"\\n  }\\n}\\n\",\n            \"language\": \"json\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// in your test files\\n\\nCypress.env()       // => {foo: \\\"bar\\\", some: \\\"value\\\"}\\nCypress.env(\\\"foo\\\")  // => \\\"bar\\\"\\nCypress.env(\\\"some\\\") // => \\\"value\\\"\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"- Great for values that need to be checked into source control and remain the same on all machines\",\n  \"title\": \"Benefits\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"- Only works for values which should be the same on across all machines\",\n  \"title\": \"Downsides\"\n}\n[/block]\n\n***\n\n## Option #2: Create a `cypress.env.json`\n\nYou can create your own `cypress.env.json`, which Cypress will automatically check. Values in here will overwrite conflicting values in `cypress.json`.\n\nThis strategy is useful because if you add `cypress.env.json` to your `.gitignore` file, the values in here can be different for each developer machine.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// cypress.env.json\\n\\n{\\n  \\\"host\\\": \\\"veronica.dev.local\\\",\\n  \\\"api_server\\\": \\\"http://localhost:8888/api/v1/\\\"\\n}\\n\",\n            \"language\": \"json\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// in your test files\\n\\nCypress.env()             // => {host: \\\"veronica.dev.local\\\", api_server: \\\"http://localhost:8888/api/v1\\\"}\\nCypress.env(\\\"host\\\")       // => \\\"veronica.dev.local\\\"\\nCypress.env(\\\"api_server\\\") // => \\\"http://localhost:8888/api/v1/\\\"\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"- Dedicated file just for environment variables\\n- Enables you to generate this file from other build processes\\n- Values can be different on each machine if not checked into source control\",\n  \"title\": \"Benefits\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"- Another file you have to deal with\\n- Overkill for 1 or 2 environment variables\",\n  \"title\": \"Downsides\"\n}\n[/block]\n\n***\n\n## Option #3: Export as `CYPRESS_*`\n\nAny environment variable on your machine that starts with either `CYPRESS_` or `cypress_` will automatically be added and made available to you.\n\nConflicting values from this method will override `cypress.json` and `cypress.env.json` files.\n\nCypress will automatically **strip off** the `CYPRESS_` when adding your environment variables.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"# export cypress env variables from the command line\\nexport CYPRESS_HOST=laura.dev.local\\nexport cypress_api_server=http://localhost:8888/api/v1/\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// in your test files\\n\\nCypress.env()             // => {HOST: \\\"laura.dev.local\\\", api_server: \\\"http://localhost:8888/api/v1\\\"}\\nCypress.env(\\\"HOST\\\")       // => \\\"laura.dev.local\\\"\\nCypress.env(\\\"api_server\\\") // => \\\"http://localhost:8888/api/v1/\\\"\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"- Quickly export some values\\n- Can be stored in your `bash_profile`\\n- Allows for dynamic values between different machines\\n- Especially useful for CI environments\",\n  \"title\": \"Benefits\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"- Not as obvious where values come from vs the other methods\",\n  \"title\": \"Downsides\"\n}\n[/block]\n\n***\n\n## Option #4: Pass in from the CLI as `--env`\n\nLastly you can also pass in environment variables as options when [using the CLI tool](https://github.com/cypress-io/cypress-cli).\n\nValues here will overwrite all other conflicting environment variables.\n\nYou can use the `--env` option on `cypress run`.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Multiple values must be separated by a comma. NOT A SPACE.\"\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cypress run --env host=kevin.dev.local,api_server=http://localhost:8888/api/v1\\n\",\n            \"language\": \"yaml\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// in your test files\\n\\nCypress.env()             // => {host: \\\"kevin.dev.local\\\", api_server: \\\"http://localhost:8888/api/v1\\\"}\\nCypress.env(\\\"host\\\")       // => \\\"kevin.dev.local\\\"\\nCypress.env(\\\"api_server\\\") // => \\\"http://localhost:8888/api/v1/\\\"\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"- Does not require any changes to files / config\\n- Obvious where environment variables come from\\n- Allows for dynamic values between different machines\\n- Overwrites all other forms of setting env variables\",\n  \"title\": \"Benefits\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"- Pain to write the `--env` options everywhere you use Cypress\",\n  \"title\": \"Downsides\"\n}\n[/block]\n\n***\n\n# Overriding Configuration\n\nIf your environment variables match a standard configuration key then instead of setting an `environment variable` they will instead override the configuration value.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## this changes the baseUrl configuration value\\n## and will not set an environment variable in Cypress.env()\\nexport CYPRESS_BASE_URL=http://localhost:8080\\n\\n## the key 'foo' does not match a configuration key so\\n## this just sets a regular environment variable in Cypress.env()\\nexport CYPRESS_FOO=bar\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\nYou can [read more about how environment variables can change configuration here](https://on.cypress.io/configuration).","excerpt":"Set up environment variables","slug":"environment-variables","type":"basic","title":"Environment Variables"}

Environment Variables

Set up environment variables

# Contents - :fa-angle-right: [Use Case](#section-use-case) - :fa-angle-right: [Setting Environment Variables](#section-setting-environment-variables) - [Option #1: Set in `cypress.json`](#section-option-1-set-in-cypress-json-) - [Option #2: Create a `cypress.env.json`](#section-option-2-create-a-cypress-env-json-) - [Option #3: Export as `CYPRESS_*`](#section-option-3-export-as-cypress_-) - [Option #4: Pass in from the CLI as `--env`](#section-option-4-pass-in-from-the-cli-as-env-) - :fa-angle-right: [Overriding Configuration](#section-overriding-configuration) *** # Use Case Environment variables should be used: - Whenever values are different across developer machines - Whenever values change frequently and are highly dynamic The most common use case is to access custom values you've written in your `hosts` file. For instance instead of hard coding this in your tests: [block:code] { "codes": [ { "code": "cy\n // this would break on other dev machines\n .visit(\"http://server.dev.local\")\n", "language": "javascript" } ] } [/block] We can move this into an environment variable. [block:code] { "codes": [ { "code": "cy\n // now this is pointing to a dynamic\n // environment variable\n .visit(Cypress.env(\"host\"))\n", "language": "javascript" } ] } [/block] *** # Setting Environment Variables There are 4 different ways to set environment variables. Each has a slightly different use case. **To summarize you can:** - set in `cypress.json` - create a `cypress.env.json` - export as `CYPRESS_*` - pass in the CLI as `--env` Don't feel obligated to pick just one method. It is common to use one strategy for local development but another when running in CI. When your tests are running, you can use the [`Cypress.env()`](https://on.cypress.io/api/env) function to access the values of your environment variables. *** ## Option #1: Set in `cypress.json` Any key/value you set in your [`cypress.json`](https://on.cypress.io/guides/configuration) under the `env` key will become an environment variable. [block:code] { "codes": [ { "code": "// cypress.json\n{\n \"projectId\": \"128076ed-9868-4e98-9cef-98dd8b705d75\",\n \"env\": {\n \"foo\": \"bar\",\n \"some\": \"value\"\n }\n}\n", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "// in your test files\n\nCypress.env() // => {foo: \"bar\", some: \"value\"}\nCypress.env(\"foo\") // => \"bar\"\nCypress.env(\"some\") // => \"value\"\n", "language": "javascript" } ] } [/block] [block:callout] { "type": "success", "body": "- Great for values that need to be checked into source control and remain the same on all machines", "title": "Benefits" } [/block] [block:callout] { "type": "danger", "body": "- Only works for values which should be the same on across all machines", "title": "Downsides" } [/block] *** ## Option #2: Create a `cypress.env.json` You can create your own `cypress.env.json`, which Cypress will automatically check. Values in here will overwrite conflicting values in `cypress.json`. This strategy is useful because if you add `cypress.env.json` to your `.gitignore` file, the values in here can be different for each developer machine. [block:code] { "codes": [ { "code": "// cypress.env.json\n\n{\n \"host\": \"veronica.dev.local\",\n \"api_server\": \"http://localhost:8888/api/v1/\"\n}\n", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "// in your test files\n\nCypress.env() // => {host: \"veronica.dev.local\", api_server: \"http://localhost:8888/api/v1\"}\nCypress.env(\"host\") // => \"veronica.dev.local\"\nCypress.env(\"api_server\") // => \"http://localhost:8888/api/v1/\"\n", "language": "javascript" } ] } [/block] [block:callout] { "type": "success", "body": "- Dedicated file just for environment variables\n- Enables you to generate this file from other build processes\n- Values can be different on each machine if not checked into source control", "title": "Benefits" } [/block] [block:callout] { "type": "danger", "body": "- Another file you have to deal with\n- Overkill for 1 or 2 environment variables", "title": "Downsides" } [/block] *** ## Option #3: Export as `CYPRESS_*` Any environment variable on your machine that starts with either `CYPRESS_` or `cypress_` will automatically be added and made available to you. Conflicting values from this method will override `cypress.json` and `cypress.env.json` files. Cypress will automatically **strip off** the `CYPRESS_` when adding your environment variables. [block:code] { "codes": [ { "code": "# export cypress env variables from the command line\nexport CYPRESS_HOST=laura.dev.local\nexport cypress_api_server=http://localhost:8888/api/v1/\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "// in your test files\n\nCypress.env() // => {HOST: \"laura.dev.local\", api_server: \"http://localhost:8888/api/v1\"}\nCypress.env(\"HOST\") // => \"laura.dev.local\"\nCypress.env(\"api_server\") // => \"http://localhost:8888/api/v1/\"\n", "language": "javascript" } ] } [/block] [block:callout] { "type": "success", "body": "- Quickly export some values\n- Can be stored in your `bash_profile`\n- Allows for dynamic values between different machines\n- Especially useful for CI environments", "title": "Benefits" } [/block] [block:callout] { "type": "danger", "body": "- Not as obvious where values come from vs the other methods", "title": "Downsides" } [/block] *** ## Option #4: Pass in from the CLI as `--env` Lastly you can also pass in environment variables as options when [using the CLI tool](https://github.com/cypress-io/cypress-cli). Values here will overwrite all other conflicting environment variables. You can use the `--env` option on `cypress run`. [block:callout] { "type": "info", "body": "Multiple values must be separated by a comma. NOT A SPACE." } [/block] [block:code] { "codes": [ { "code": "cypress run --env host=kevin.dev.local,api_server=http://localhost:8888/api/v1\n", "language": "yaml" } ] } [/block] [block:code] { "codes": [ { "code": "// in your test files\n\nCypress.env() // => {host: \"kevin.dev.local\", api_server: \"http://localhost:8888/api/v1\"}\nCypress.env(\"host\") // => \"kevin.dev.local\"\nCypress.env(\"api_server\") // => \"http://localhost:8888/api/v1/\"\n", "language": "javascript" } ] } [/block] [block:callout] { "type": "success", "body": "- Does not require any changes to files / config\n- Obvious where environment variables come from\n- Allows for dynamic values between different machines\n- Overwrites all other forms of setting env variables", "title": "Benefits" } [/block] [block:callout] { "type": "danger", "body": "- Pain to write the `--env` options everywhere you use Cypress", "title": "Downsides" } [/block] *** # Overriding Configuration If your environment variables match a standard configuration key then instead of setting an `environment variable` they will instead override the configuration value. [block:code] { "codes": [ { "code": "## this changes the baseUrl configuration value\n## and will not set an environment variable in Cypress.env()\nexport CYPRESS_BASE_URL=http://localhost:8080\n\n## the key 'foo' does not match a configuration key so\n## this just sets a regular environment variable in Cypress.env()\nexport CYPRESS_FOO=bar\n", "language": "shell" } ] } [/block] You can [read more about how environment variables can change configuration here](https://on.cypress.io/configuration).