Test runner v3.7.0 recipes (#368)

* add custom Brave browser example

* add config-file

* update test names

* add --browser brave

* ughh it is cypress run, not cypress open on CI

* test new 3.7.0 linux build

```json
{
  "platform": "linux",
  "arch": "x64",
  "env": {
    "CYPRESS_INSTALL_BINARY": "cdn.cypress.io/beta/binary/3.7.0/linux-x64/circle-develop-b03b25c258990966cbc99e50796c039abbf2f893-194641/cypress.zip"
  },
  "packages": "cdn.cypress.io/beta/npm/3.7.0/circle-develop-b03b25c258990966cbc99e50796c039abbf2f893-194639/cypress.tgz",
  "branch": "3.7.0",
  "commit": "b03b25c258990966cbc99e50796c039abbf2f893",
  "status": {
    "owner": "cypress-io",
    "repo": "cypress",
    "sha": "b03b25c258990966cbc99e50796c039abbf2f893",
    "platform": "linux",
    "arch": "x64",
    "context": "[linux-x64] cypress-test-example-repos"
  }
}
```

* test new 3.7.0 linux build

```json
{
  "platform": "linux",
  "arch": "x64",
  "env": {
    "CYPRESS_INSTALL_BINARY": "cdn.cypress.io/beta/binary/3.7.0/linux-x64/circle-develop-b03b25c258990966cbc99e50796c039abbf2f893-194641/cypress.zip"
  },
  "packages": "cdn.cypress.io/beta/npm/3.7.0/circle-develop-b03b25c258990966cbc99e50796c039abbf2f893-194639/cypress.tgz",
  "branch": "3.7.0",
  "commit": "b03b25c258990966cbc99e50796c039abbf2f893",
  "status": {
    "owner": "cypress-io",
    "repo": "cypress",
    "sha": "b03b25c258990966cbc99e50796c039abbf2f893",
    "platform": "linux",
    "arch": "x64",
    "context": "[linux-x64] cypress-test-example-repos"
  }
}
```

* test with https

```json
{
  "platform": "linux",
  "arch": "x64",
  "env": {
    "CYPRESS_INSTALL_BINARY": "https://cdn.cypress.io/beta/binary/3.7.0/linux-x64/circle-develop-b03b25c258990966cbc99e50796c039abbf2f893-194641/cypress.zip"
  },
  "packages": "https://cdn.cypress.io/beta/npm/3.7.0/circle-develop-b03b25c258990966cbc99e50796c039abbf2f893-194639/cypress.tgz",
  "branch": "3.7.0",
  "commit": "b03b25c258990966cbc99e50796c039abbf2f893",
  "status": {
    "owner": "cypress-io",
    "repo": "cypress",
    "sha": "b03b25c258990966cbc99e50796c039abbf2f893",
    "platform": "linux",
    "arch": "x64",
    "context": "[linux-x64] cypress-test-example-repos"
  }
}
```

Author: bahmutov

README.md

@@ -13,6 +13,7 @@ Recipe | Description
 [Adding Custom Commands](./examples/fundamentals__add-custom-command) | Write your own custom commands with correct types
 [Adding Chai Assertions](./examples/extending-cypress__chai-assertions) | Add new or custom chai assertions with correct types
 [Cypress module API](./examples/fundamentals__module-api) | Run Cypress via its module API
+[Custom browsers](./examples/fundamentals_custom-browsers) | Control which browsers the project can use, or even add a custom browser into the list
 
 ## Testing the DOM
 

circle.yml

@@ -89,6 +89,7 @@ jobs:
       # is in variable CIRCLE_NODE_TOTAL and the current container index in CIRCLE_NODE_INDEX
       # which starts at 0 and goes to $CIRCLE_NODE_TOTAL - 1
       - run: npm run test:ci -- --chunk $CIRCLE_NODE_INDEX --total-chunks $CIRCLE_NODE_TOTAL
+
   # a single utility script to run multiple examples against Chrome
   test-examples-chrome:
     parallelism: 10
@@ -100,6 +101,18 @@ jobs:
           at: ~/
       - run: npm run test:ci:chrome -- --chunk $CIRCLE_NODE_INDEX --total-chunks $CIRCLE_NODE_TOTAL
 
+  # a single utility script to run multiple examples against Brave browser
+  test-examples-brave:
+    # only one recipe shows how to run Cypress using Brave browser
+    parallelism: 1
+    working_directory: ~/app
+    docker:
+      - image: cypress/browsers:node12.13.0-chrome78-ff70-brave78
+    steps:
+      - attach_workspace:
+          at: ~/
+      - run: npm run test:ci:brave -- --chunk $CIRCLE_NODE_INDEX --total-chunks $CIRCLE_NODE_TOTAL
+
   # define a new job with defaults for each "examples/*" subfolder
   blogs__a11y:
     <<: *defaults
@@ -211,6 +224,15 @@ all_jobs: &all_jobs
           only:
             - master
 
+  - test-examples-brave:
+      requires:
+        - build
+      filters:
+        branches:
+          only:
+            - master
+            - 3.7.0
+
   # when adding new example subfolder with a recipe
   # add its name here to "create" CircleCI job
 

examples/fundamentals__custom-browsers/README.md

@@ -0,0 +1,36 @@
+# Custom browsers
+
+Cypress v3.7.0+ allows the project to customize the list of browsers. In this example, [cypress/plugins/index.js](cypress/plugins/index.js) filters the list of all browsers detected on the user's machine and only returns the bundled Electron browser. Or you could do the opposite and only allow the project to use Chrome browsers
+
+```js
+// cypress/plugins/index.js
+module.exports = (on, config) => {
+  return {
+    browsers: config.browsers.filter((browser) => browser.family === 'chrome'),
+  }
+}
+```
+
+![Only Chrome browsers displayed](images/only-chrome.png)
+
+## Custom browser
+
+Plugins file can also adjust or overwrite the list of browsers. For example [cypress/plugins/brave.js](cypress/plugins/brave.js) file finds the Brave Browser and returns only that browser.
+
+```shell
+npx cypress open --config pluginsFile=cypress/plugins/brave.js
+```
+
+![Brave browser running tests](images/brave.png)
+
+If you want to use Brave browser during non-interactive run, pass its name
+
+```shell
+npx cypress run --config pluginsFile=cypress/plugins/brave.js --browser brave
+```
+
+**Tip:** if you are passing lots of `--config` options, set them in a new configuration file, like `cypress-brave.json` and use
+
+```shell
+npx cypress run --config-file cypress-brave.json
+```

examples/fundamentals__custom-browsers/cypress.json

@@ -0,0 +1,4 @@
+{
+  "supportFile": false,
+  "fixturesFolder": false
+}

examples/fundamentals__custom-browsers/cypress/integration/spec.js

@@ -0,0 +1,9 @@
+/// <reference types="cypress" />
+it('works', () => {
+  cy.log(
+    `Running in browser **${Cypress.browser.displayName} v${
+      Cypress.browser.majorVersion
+    }**`
+  )
+  cy.task('echo', { browser: Cypress.browser })
+})

examples/fundamentals__custom-browsers/cypress/plugins/brave.js

@@ -0,0 +1,64 @@
+/* eslint-disable no-console */
+const os = require('os')
+const execa = require('execa')
+const tasks = require('./tasks')
+
+/**
+ * Parses STDOUT from "brave-browser --version" command.
+ * @param {string} stdout from Brave, something like "Brave Browser 77.0.69.135"
+ */
+const parseBraveVersion = (stdout) => {
+  const [, version] = /Brave Browser (\d+\.\d+\.\d+\.\d+)/.exec(stdout)
+
+  console.log('Brave browser version is', version)
+  const majorVersion = parseFloat(version.split('.')[0])
+
+  return { version, majorVersion }
+}
+
+const findBraveBrowserInfo = (browserPath) => {
+  return execa(browserPath, ['--version'])
+  .then((result) => result.stdout)
+  .then(parseBraveVersion)
+  .then(({ version, majorVersion }) => {
+    return {
+      name: 'brave',
+      family: 'chrome',
+      displayName: 'Brave',
+      version,
+      path: browserPath,
+      majorVersion,
+    }
+  })
+}
+
+const findBraveBrowser = () => {
+  // the path is hard-coded for simplicity
+  switch (os.platform()) {
+    case 'darwin':
+      return findBraveBrowserInfo(
+        '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'
+      )
+    case 'linux':
+      return findBraveBrowserInfo('brave-browser')
+    default:
+      throw new Error(`Cannot find Brave browser on platform ${os.platform()}`)
+  }
+}
+
+module.exports = (on, config) => {
+  on('task', tasks)
+
+  // only filter browsers if we are passed a list - this way
+  // this example works on Cypress v3.7.0+ and below
+  if (!config.browsers) {
+    return
+  }
+
+  // Cypress v3.7.0+
+  return findBraveBrowser().then((browser) => {
+    return {
+      browsers: [browser],
+    }
+  })
+}

examples/fundamentals__custom-browsers/cypress/plugins/index.js

@@ -0,0 +1,16 @@
+const tasks = require('./tasks')
+
+module.exports = (on, config) => {
+  on('task', tasks)
+
+  // only filter browsers if we are passed a list - this way
+  // this example works on Cypress v3.7.0+ and below
+  if (!config.browsers) {
+    return
+  }
+
+  // Cypress v3.7.0+
+  return {
+    browsers: config.browsers.filter((browser) => browser.family === 'electron'),
+  }
+}

examples/fundamentals__custom-browsers/cypress/plugins/tasks.js

@@ -0,0 +1,8 @@
+/* eslint-disable no-console */
+module.exports = {
+  echo (what) {
+    console.log(what)
+
+    return null
+  },
+}

examples/fundamentals__custom-browsers/images/brave.png

@@ -0,0 +1,12 @@
+{
+  "name": "cypress-custom-browsers",
+  "version": "1.0.0",
+  "description": "Customizes list of browsers",
+  "scripts": {
+    "start": "echo nothing to start",
+    "cypress:run": "../../node_modules/.bin/cypress run",
+    "cypress:open": "../../node_modules/.bin/cypress open",
+    "test:ci": "../../node_modules/.bin/cypress run",
+    "test:ci:brave": "../../node_modules/.bin/cypress run --config pluginsFile=cypress/plugins/brave.js --browser brave"
+  }
+}

examples/fundamentals__custom-browsers/images/only-chrome.png

@@ -14,7 +14,8 @@
     "warn-only": "stop-only --warn --folder examples --skip node_modules",
     "test:ci": "node ./test-examples",
     "test:ci:windows": "node ./test-examples --windows",
-    "test:ci:chrome": "node ./test-examples --chrome"
+    "test:ci:chrome": "node ./test-examples --chrome",
+    "test:ci:brave": "node ./test-examples --brave"
   },
   "repository": {
     "type": "git",

examples/fundamentals__custom-browsers/package.json

@@ -18,6 +18,7 @@ const is = require('check-more-types')
 // run this script with "--chrome" CLI flag
 const args = arg({
   '--chrome': Boolean,
+  '--brave': Boolean,
   '--windows': Boolean,
   '--chunk': Number,
   '--total-chunks': Number,
@@ -35,6 +36,10 @@ if (args['--chrome']) {
   scriptName = 'test:ci:chrome'
 }
 
+if (args['--brave']) {
+  scriptName = 'test:ci:brave'
+}
+
 if (args['--windows']) {
   scriptName = 'test:ci:windows'
 }