feat: add parameter through --env CLI flag (#358)

CONTRIBUTING.md

@@ -58,6 +58,8 @@ If you want to run a single test file
 
 ```shell
 npx ava-ts manual-tests/<filename>.ts
+# or with debug output
+DEBUG=test npx ava-ts manual-tests/<filename>.ts
 ```
 
 #### Snapshots

docs/examples.md

@@ -32,6 +32,7 @@
  - [install-extra-tool](#install-extra-tool) - run commands after installing NPM modules but before caching
  - [config](#config) - pass additional config parameter via --config argument
  - [config-file](#config-file) - custom configuration file
+ - [env](#env) - Passing values via --env CLI argument
  - [tags](#tags) - tag recorded run
  - [attach-workspace](#attach-workspace) - attaches the workspace assuming previous job has installed it
  - [run-tasks-post-checkout](#run-tasks-post-checkout) - perform steps after code checkout but before installing dependencies
@@ -42,7 +43,7 @@
 ## simple
 
 
-Runs all Cypress tests without recording results on the Dashboard. Installs dependencies with `npm ci`, caches NPM modules and the Cypress binary. 
+Runs all Cypress tests without recording results on the Dashboard. Installs dependencies with "npm ci", caches NPM modules and Cypress binary. 
 
 ```yaml
 version: 2.1
@@ -95,7 +96,7 @@ workflows:
 ## yarn
 
 
-Installs NPM dependencies using `yarn install --frozen-lockfile` command, then runs Cypress tests. Caches NPM modules and Cypress binary. 
+Installs NPM dependencies using "yarn install --frozen-lockfile" command, then runs Cypress tests. Caches NPM modules and Cypress binary. 
 
 ```yaml
 version: 2.1
@@ -111,7 +112,7 @@ workflows:
 ## custom-install
 
 
-Install dependencies using your own custom command. Related parameter: [custom-verify](#custom-verify). 
+Install dependencies using your own custom command. Related parameter: [custom-verify](#custom-verify) 
 
 ```yaml
 version: 2.1
@@ -127,7 +128,7 @@ workflows:
 ## custom-verify
 
 
-Verify Cypress was installed using custom command. Default command is `npx cypress verify` Related parameter: [custom-install](#custom-install).
+Verify Cypress was installed using custom command. Default command is "npx cypress verify" Related parameter: [custom-install](#custom-install) 
 
 ```yaml
 version: 2.1
@@ -143,7 +144,7 @@ workflows:
 ## custom-cache-key
 
 
-Apply custom key for `npm install` (or `yarn install`) cache. Useful to tweak caching settings to your liking. Related options [yarn](#yarn). 
+Apply custom key for npm install (or yarn install) cache. Useful to tweak caching settings to your liking. Related options [yarn](#yarn). 
 
 ```yaml
 version: 2.1
@@ -160,7 +161,7 @@ workflows:
 ## using-node14
 
 
-Runs all Cypress tests on Node 14 image by specifying `executor` name. There are [several executors included](https://circleci.com/developer/orbs/orb/cypress-io/cypress#executors) with this orb or you can use your own executor, such as a Docker image from [cypress-docker-images](https://github.com/cypress-io/cypress-docker-images). See [custom-executor](#custom-executor) example.
+Runs all Cypress tests on Node 14 image by specifying `executor` name. There are [several executors included](https://circleci.com/developer/orbs/orb/cypress-io/cypress#executors) with this orb or you can use your own executor, such as a Docker image from [cypress-docker-images](https://github.com/cypress-io/cypress-docker-images). See [custom-executor](#custom-executor) example. 
 
 ```yaml
 version: 2.1
@@ -175,7 +176,8 @@ workflows:
 
 ## chrome
 
-Runs tests on Chrome in a [custom-executor](#custom-executor) - a Docker image that includes the Chrome browser, such as a Docker image from [cypress-docker-images](https://github.com/cypress-io/cypress-docker-images). See [`--browser`](https://on.cypress.io/launching-browsers) documentation for available browser arguments.
+
+Runs tests on Chrome in a [custom-executor](#custom-executor) - a Docker image that includes the Chrome browser, such as a Docker image from [cypress-docker-images](https://github.com/cypress-io/cypress-docker-images). See [`--browser`](https://on.cypress.io/launching-browsers) documentation for available browser arguments. 
 
 ```yaml
 version: 2.1
@@ -196,7 +198,7 @@ workflows:
 ## start-server
 
 
-Often we need to start a local webserver before running end-to-end tests. This option runs the given command to starts the server in the background and then runs all Cypress tests. Related option [wait-on](#wait-for-server-to-respond).
+Often we need to start a local webserver before running end-to-end tests. This option runs the given command to starts the server in the background and then runs all Cypress tests. Related option [wait-on](#wait-for-server-to-respond). 
 
 ```yaml
 version: 2.1
@@ -212,7 +214,7 @@ workflows:
 ## wait-for-server-to-respond
 
 
-Starts server, waits for it to respond and then runs all Cypress tests. Uses `npx wait-on ...` command under the hood, see [wait-on](https://github.com/jeffbski/wait-on#readme). Note, if you are using Webpack server, it might not respond to the default HTTP OPTIONS request. In that case use `wait-on` to send `HTTP GET` request by using url `wait-on: 'http-get://localhost:....'`. You can also pass `wait-on` config, see [issue #90](https://github.com/cypress-io/circleci-orb/issues/90). Related option [start](#start).
+Starts server, waits for it to respond and then runs all Cypress tests. Uses `npx wait-on ...` command under the hood, see [wait-on](https://github.com/jeffbski/wait-on#readme). Note, if you are using Webpack server, it might not respond to the default HTTP OPTIONS request. In that case use `wait-on` to send `HTTP GET` request by using url `wait-on: 'http-get://localhost:....'`. You can also pass `wait-on` config, see [issue #90](https://github.com/cypress-io/circleci-orb/issues/90). Related option [start](#start). 
 
 ```yaml
 version: 2.1
@@ -286,7 +288,7 @@ workflows:
 ## release
 
 
-If you want to run an entire job after running Cypress tests, you can reuse the workspace from the `cypress/run` job. For example, to run a semantic release script you could follow this example. Note - for simpler steps you can use "post-steps" parameter, see [store-test-reports](#store-test-reports) example.
+If you want to run an entire job after running Cypress tests, you can reuse the workspace from the `cypress/run` job. For example, to run a semantic release script you could follow this example. Note - for simpler steps you can use "post-steps" parameter, see [store-test-reports](#store-test-reports) example. 
 
 ```yaml
 version: 2.1
@@ -314,7 +316,7 @@ workflows:
 ## linux-and-mac
 
 
-Runs tests on Linux and on Mac via two jobs. Note how the user defines and uses own [custom executor](#custom-executor) "mac".
+Runs tests on Linux and on Mac via two jobs. Note how the user defines and uses own [custom executor](#custom-executor) "mac". 
 
 ```yaml
 version: 2.1
@@ -336,7 +338,8 @@ workflows:
 
 ## custom-executor
 
-Use any executor to run the job defined by the orb, such as a custom Docker image name, or a Docker image from [cypress-docker-images](https://github.com/cypress-io/cypress-docker-images). Assumes the executor has all OS dependencies necessary to run Cypress.
+
+Use any executor to run the job defined by the orb, such as a custom Docker image name, or a Docker image from [cypress-docker-images](https://github.com/cypress-io/cypress-docker-images). Assumes the executor has all OS dependencies necessary to run Cypress. 
 
 ```yaml
 version: 2.1
@@ -345,7 +348,7 @@ orbs:
 executors:
   with-chrome:
     docker:
-      - image: 'cypress/browsers:chrome69'
+      - image: 'cypress/browsers:node14.16.0-chrome90-ff88'
 workflows:
   build:
     jobs:
@@ -364,7 +367,7 @@ version: 2.1
 orbs:
   cypress: cypress-io/cypress@1
 executors:
-  base10:
+  base10-foo-bar:
     docker:
       - image: 'cypress/base:10'
     environment:
@@ -374,13 +377,13 @@ workflows:
   build:
     jobs:
       - cypress/run:
-          executor: base10
+          executor: base10-foo-bar
 ```
 
 ## install-private-npm-modules
 
 
-In this example, we write the NPM auth token before running `npm install` command. This allows us to install private NPM modules for example. 
+In this example, we write the NPM auth token before running "npm install" command. This allows us to install private NPM modules for example. 
 
 ```yaml
 version: 2.1
@@ -400,7 +403,7 @@ workflows:
 ## store-test-reports
 
 
-Stores test results using post-steps parameter, see https://on.cypress.io/reporters, assumes that reports are saved in folder "cypress/results". Also see [artifacts](#artifacts) parameter.
+Stores test results using post-steps parameter, see https://on.cypress.io/reporters, assumes that reports are saved in folder "cypress/results". Also see [artifacts](#artifacts) parameter. 
 
 ```yaml
 version: 2.1
@@ -418,7 +421,7 @@ workflows:
 ## artifacts
 
 
-Stores test screenshots and videos as CircleCI artifacts using "store_artifacts" job option. Note, this setting assumes the default Cypress folders for screenshots and videos. If you store screenshots and videos in custom folders, see [any-artifacts](#any-artifacts) example how to store arbitrary folders.
+Stores test screenshots and videos as CircleCI artifacts using "store_artifacts" job option. Note, this setting assumes the default Cypress folders for screenshots and videos. If you store screenshots and videos in custom folders, see [any-artifacts](#any-artifacts) example how to store arbitrary folders. 
 
 ```yaml
 version: 2.1
@@ -434,7 +437,7 @@ workflows:
 ## any-artifacts
 
 
-Stores additional folders like "mochawesome-report" or code coverage folder as a CircleCI artifact. Related option [artifacts](#artifacts).
+Stores additional folders like "mochawesome-report" or code coverage folder as a CircleCI artifact. Related option [artifacts](#artifacts). 
 
 ```yaml
 version: 2.1
@@ -468,7 +471,7 @@ workflows:
 ## custom-command-prefix
 
 
-Use your own arbitrary command to prefix default `cypress run` test command.
+Use your own arbitrary command to prefix default cypress run test command.
 
 ```yaml
 version: 2.1
@@ -563,7 +566,7 @@ workflows:
 ## print-info
 
 
-It is useful to print information about the OS and found browsers using the `cypress info` command.
+It is useful to print information about the OS and found browsers using the "cypress info" command 
 
 ```yaml
 version: 2.1
@@ -580,7 +583,7 @@ workflows:
 ## install-extra-tool
 
 
-Sometimes you want to install another tool after installing regular dependencies but before running `cypress verify` and caching NPM modules and Cypress binary. In this example, it installs one more tool, `print-env`, and runs it.
+Sometimes you want to install another tool after installing regular dependencies but before running "cypress verify" and caching NPM modules and Cypress binary. In this example, it installs one more tool "print-env" and runs it. 
 
 ```yaml
 version: 2.1
@@ -598,7 +601,7 @@ workflows:
 ## config
 
 
-Passing additional Cypress config parameters via `--config` CLI argument
+Passing additional Cypress config parameters via --config CLI argument
 
 ```yaml
 version: 2.1
@@ -614,7 +617,7 @@ workflows:
 ## config-file
 
 
-Uses non-default configuration file like one would pass with `--config-file` argument.
+Uses non-default configuration file
 
 ```yaml
 version: 2.1
@@ -627,10 +630,26 @@ workflows:
           config-file: staging.json
 ```
 
+## env
+
+
+Passing values via --env CLI argument
+
+```yaml
+version: 2.1
+orbs:
+  cypress: cypress-io/cypress@1
+workflows:
+  build:
+    jobs:
+      - cypress/run:
+          env: 'userName=Joe,apiKey=1234567890'
+```
+
 ## tags
 
 
-Pass tags to the dashboard like one would pass with the `--tags` argument.
+Pass tags to the dashboard
 
 ```yaml
 version: 2.1
@@ -710,7 +729,7 @@ workflows:
 ## debug
 
 
-To debug Cypress, use `DEBUG=...` environment variable which works via the [debug](https://github.com/visionmedia/debug) NPM module. For example, to debug Cypress CLI use `cypress:cli`, and to debug everything use `cypress*` (which could be very verbose). 
+To debug Cypress, use DEBUG=... environment variable which works via https://github.com/visionmedia/debug NPM module. For example, to debug Cypress CLI use "cypress:cli", and to debug everything use "cypress*", which could be very verbose. 
 
 ```yaml
 version: 2.1
@@ -727,7 +746,7 @@ workflows:
 ## custom-build-id
 
 
-Runs two jobs splitting the specs in parallel using Cypress Dashboard [parallelization](https://on.cypress.io/parallelization). Uses custom build ID to link the jobs together into a logical run. Notice the environment variable syntax to be expanded at the build time. See example in [circleci-orb-parallel-example](https://github.com/cypress-io/circleci-orb-parallel-example). 
+Runs two jobs splitting the specs in parallel using Cypress Dashboard [parallelization](https://on.cypress.io/parallelization). Uses custom build ID to link the jobs together into a logical run. Notice the environment variable syntax to be expanded at the build time. See example in https://github.com/cypress-io/circleci-orb-parallel-example. 
 
 ```yaml
 version: 2.1
@@ -745,3 +764,4 @@ workflows:
           parallelism: 2
           ci-build-id: 'testing-commit-${CIRCLE_SHA1}'
 ```
+

docs/jobs.md

@@ -33,6 +33,7 @@ Public jobs defined in this orb that your config workflow can use. See [examples
      - timeout
      - config-file
      - config
+     - env
 
  - [install](#install)
      - executor
@@ -98,7 +99,7 @@ default: `cache-{{ arch }}-{{ .Branch }}-{{ checksum "package.json" }}`
 
 > A common unique ID that ties multiple test jobs into a single logical run.
 > See Cypress [parallelization docs](https://on.cypress.io/parallelization).
-> See usage example in https://github.com/cypress-io/circleci-orb-parallel-example
+> See usage example in [circleci-orb-parallel-example](https://github.com/cypress-io/circleci-orb-parallel-example).
 
 
 type: string
@@ -144,6 +145,14 @@ type: string
 type: string
 
 
+**`env`**
+
+> Values to pass using --env argument
+
+
+type: string
+
+
 **`executor`**
 
 > Cypress executor to use, see [executors.md](executors.md).

manual-tests/env.test.ts

@@ -0,0 +1,29 @@
+import test from 'ava'
+import { stripIndent } from 'common-tags'
+import debugApi from 'debug'
+import { effectiveConfig, extractCypressRun } from '../scripts/utils'
+
+const debug = debugApi('test')
+
+test('env parameter', async (t) => {
+  const workflows = stripIndent`
+    workflows:
+      build:
+        jobs:
+          - cypress/run:
+              env: foo=bar,baz=qux
+  `
+
+  const result = await effectiveConfig(workflows)
+  if (debug.enabled) {
+    debug('effective config')
+    console.error(result)
+  }
+  const runTestsStep = extractCypressRun(result)
+  debug('run test step: %o', runTestsStep)
+  const runCommand = runTestsStep.command
+  t.is(typeof runCommand, 'string')
+
+  debug('run command: %s', runCommand)
+  t.snapshot(runCommand, 'passing env values')
+})

manual-tests/env.test.ts.md

@@ -0,0 +1,11 @@
+# Snapshot report for `manual-tests/env.test.ts`
+
+The actual snapshot is saved in `env.test.ts.snap`.
+
+Generated by [AVA](https://ava.li).
+
+## env parameter
+
+> passing env values
+
+    'npx cypress run --env foo=bar,baz=qux'

scripts/examples.ts

@@ -47,6 +47,7 @@ const exampleTitles = {
     'run commands after installing NPM modules but before caching',
   config: 'pass additional config parameter via --config argument',
   'config-file': 'custom configuration file',
+  env: 'Passing values via --env CLI argument',
   tags: 'tag recorded run',
   'attach-workspace':
     'attaches the workspace assuming previous job has installed it',