feat: add attach-workspace option (#235)

* fix home url

* try validating orb on CircleCI

* feat: add attach-workspace parameter

docs/examples.md

@@ -28,6 +28,7 @@
  - [install-extra-tool](#install-extra-tool) - run commands after installing NPM modules but before caching
  - [config-file](#config-file) - custom configuration file
  - [tags](#tags) - tag recorded run
+ - [attach-workspace](#attach-workspace) - attaches the workspace assuming previous job has installed it
 
 ## simple
 
@@ -577,3 +578,23 @@ workflows:
 
 ```
 
+## attach-workspace
+
+
+You may run multiple job after installing dependencies once. In that case every job should attach workspace and require cypress/install. Related parameter "no-workspace" 
+
+```yaml
+version: 2.1
+orbs:
+  cypress: cypress-io/cypress@1
+workflows:
+  build:
+    jobs:
+      - cypress/install
+      - cypress/run:
+          requires:
+            - cypress/install
+          attach-workspace: true
+
+```
+

docs/jobs.md

@@ -21,6 +21,7 @@ Public jobs defined in this orb that your config workflow can use. See [examples
      - store_artifacts
      - yarn
      - cache-key
+     - attach-workspace
      - no-workspace
      - working_directory
      - timeout
@@ -41,6 +42,18 @@ Public jobs defined in this orb that your config workflow can use. See [examples
 A single complete job to run Cypress end-to-end tests in your project. If recording on the Dashboard, set `CYPRESS_RECORD_KEY` environment variable
 
 
+**`attach-workspace`**
+
+> Assuming there was an install job before, first attach
+> the workspace to avoid re-installing dependencies
+
+
+type: boolean
+
+
+default: `false`
+
+
 **`browser`**
 
 > Browser to use to run end-to-end tests. Typically "electron" (default) or "chrome".
@@ -109,8 +122,9 @@ type: string
 
 **`no-workspace`**
 
-> Do not write workspace (for example if there are no jobs to follow), which
-> saves time on each build.
+> Do not write workspace after this job is done.
+> This is useful if there are no jobs to follow,
+> which saves time on each build.
 
 
 type: boolean

package.json

@@ -17,7 +17,7 @@
     "unit": "ava-ts 'test/*.test.ts'",
     "doc": "npm run doc:examples && npm run doc:jobs && npm run doc:executors",
     "docs": "npm run doc",
-    "doc:examples": "ts-node ./scripts/examples > docs/examples.md",
+    "doc:examples": "FORCE_COLOR=2 ts-node ./scripts/examples > docs/examples.md",
     "doc:jobs": "ts-node ./scripts/jobs > docs/jobs.md",
     "doc:executors": "ts-node ./scripts/executors > docs/executors.md",
     "effective:config": "circleci config process src/orb.yml | sed /^#/d"
@@ -38,6 +38,7 @@
     "@types/node": "10.17.14",
     "ava": "2.4.0",
     "ava-ts": "0.25.2",
+    "chalk": "3.0.0",
     "common-tags": "1.8.0",
     "execa": "4.0.0",
     "husky": "3.0.3",

scripts/examples.ts

@@ -5,6 +5,7 @@ import { safeDump } from 'js-yaml'
 import json2md from 'json2md'
 import { example, getOrb, normalizeString } from '../scripts/utils'
 import { symmetricDifference } from 'ramda'
+import chalk from 'chalk'
 
 const orb = getOrb()
 const examples = orb.examples
@@ -36,7 +37,8 @@ const exampleTitles = {
   'custom-cache-and-directory': 'use custom cache key in a monorepo situation',
   'install-extra-tool': 'run commands after installing NPM modules but before caching',
   'config-file': 'custom configuration file',
-  tags: 'tag recorded run'
+  tags: 'tag recorded run',
+  'attach-workspace': 'attaches the workspace assuming previous job has installed it'
 }
 
 // we want to make sure all orb examples are represented in the object above
@@ -47,7 +49,7 @@ const checkExamples = () => {
   const unknownNames = symmetricDifference(knownNames, examplesNames)
   if (unknownNames.length) {
     console.error('Hmm, I see example names that are different')
-    console.error(unknownNames.join(', '))
+    console.error(unknownNames.map(name => chalk.red(name)).join('\n'))
     console.error('Check orb.yml examples and scripts/examples.ts to resolve the lists')
     throw new Error('example names do not match')
   }