Add mocha like grep (#250)

* added Mocha-like grep example

* update readme

* add new recipe to circle

* add new recipe to the root readme

* add env variables for fgrep and grep

* rename tests to have admin

* update example readme

* tweak readme

Author: bahmutov

Diff for: README.md

@@ -16,6 +16,7 @@ Recipe | Category | Description
 [Hover and Hidden Elements](#hover-and-hidden-elements) | Testing the DOM | Test hidden elements requiring hover
 [Form Interactions](#form-interactions) | Testing the DOM | Test form elements like input type `range`
 [Drag and Drop](#drag-and-drop) | Testing the DOM | Use `.trigger()` to test drag and drop
+[grep](#grep) | Preprocessors | Filter tests by name using Mocha-like `grep` syntax
 [Typescript with Browserify](#typescript-with-browserify) | Preprocessors | Add typescript support with browserify
 [Typescript with Webpack](#typescript-with-webpack) | Preprocessors | Add typescript support with webpack
 [Application Actions](#application-actions) | Blogs | Application actions are a replacement for Page Objects
@@ -149,6 +150,11 @@ Get around the lack of a `.hover()` command.
 - Use [`.trigger()`](https://on.cypress.io/trigger) to test drag-n-drop that uses mouse events.
 - Use [`.trigger()`](https://on.cypress.io/trigger) to test drag-n-drop that uses drag events.
 
+### [grep](./examples/preprocessors__grep)
+
+- Use Mocha-like syntax to select tests to run
+- Implemented as a preprocessor [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests)
+
 ### [Typescript with Browserify](./examples/preprocessors__typescript-browserify)
 
 - Use [`@cypress/browserify-preprocessor`](https://github.com/cypress-io/cypress-browserify-preprocessor) to write Cypress tests in Typescript

Diff for: circle.yml

@@ -111,6 +111,12 @@ jobs:
     <<: *defaults
   logging-in__xhr-web-forms:
     <<: *defaults
+  preprocessors__grep:
+    <<: *defaults
+    # in this particular example we want to grep tests
+    # and run only tests with name having "@admin"
+    environment:
+      CYPRESS_grep: '@admin'
   preprocessors__typescript-browserify:
     <<: *defaults
   preprocessors__typescript-webpack:
@@ -208,6 +214,9 @@ workflows:
       - logging-in__xhr-web-forms:
           requires:
             - build
+      - preprocessors__grep:
+          requires:
+            - build
       - preprocessors__typescript-browserify:
           requires:
             - build
@@ -277,6 +286,7 @@ workflows:
             - logging-in__html-web-forms
             - logging-in__single-sign-on
             - logging-in__xhr-web-forms
+            - preprocessors__grep
             - preprocessors__typescript-browserify
             - preprocessors__typescript-webpack
             - server-communication__bootstrapping-your-app

Diff for: examples/preprocessors__grep/README.md

@@ -0,0 +1,99 @@
+# Selecting tests using Mocha-like "grep"
+
+This example uses [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests) preprocessor plugin to filter tests, similar to how [Mocha](https://mochajs.org/) has the `--grep` CLI argument. This project provides an imitation using a string (no regular expressions).
+
+Because Cypress ignores unknown CLI parameters, you need to pass `grep` argument as an environment variables, for example by using `--env` CLI argument.
+
+## Examples
+
+### interactive
+
+Open Cypress GUI but only allow running tests with `@admin` in the name
+
+```bash
+$ npm run cypress:open -- --env grep=@admin
+```
+
+shows only "@admin" tests were executed, while the rest were skipped
+
+![Running all tests with admin](images/grep-admin.png)
+
+### headless
+
+Run tests with `edge case` in the name in headless mode
+
+```bash
+$ npm run cypress:run -- --env grep='edge case'
+```
+
+produces
+
+```text
+Running: feature-a.js...     (1 of 2)
+picking tests to run in file cypress/integration/feature-a.js
+
+
+  feature A
+    - works
+    - reports for @admin
+
+
+  0 passing (30ms)
+  2 pending
+
+  Running: feature-b.js...   (2 of 2)
+picking tests to run in file cypress/integration/feature-b.js
+
+
+  feature B
+    - works
+    ✓ an edge case (54ms)
+    - works for @admin
+
+
+  1 passing (87ms)
+  2 pending
+```
+
+## Notes
+
+### test title
+
+The full test title used for string matching is a concatenation of suite names plus the test's own name.
+
+```js
+describe('app', () => {
+  context('feature A', () => {
+    it('works', () => {
+      // full test name is 'app feature A works'
+    })
+  })
+})
+```
+
+Thus you can run all tests form the given suite
+
+```bash
+$ npm run cypress:run -- --env grep='feature A'
+```
+
+## NPM arguments
+
+Note how you need to use `--` to separate NPM open or run script command from arguments to Cypress itself.
+
+```bash
+# runs only tests with "works" in their name
+$ npm run cypress:run -- --env grep=works
+```
+
+## Quote strings with spaces
+
+If you want to pass string with spaces, please quote it like
+
+```bash
+$ npm run cypress:run -- --env grep='feature A'
+```
+
+## Details
+
+See [cypress/plugins/index.js](cypress/plugins/index.js) file how to configure test selection preprocessor, built on top of [Cypress Browserify preprocessor](https://github.com/cypress-io/cypress-browserify-preprocessor).

Diff for: examples/preprocessors__grep/cypress.json

@@ -0,0 +1 @@
+{}

Diff for: examples/preprocessors__grep/cypress/integration/feature-a.js

@@ -0,0 +1,5 @@
+describe('feature A', () => {
+  it('works', () => {})
+
+  it('reports for @admin', () => {})
+})

Diff for: examples/preprocessors__grep/cypress/integration/feature-b.js

@@ -0,0 +1,7 @@
+describe('feature B', () => {
+  it('works', () => {})
+
+  it('an edge case', () => {})
+
+  it('works for @admin', () => {})
+})

Diff for: examples/preprocessors__grep/cypress/plugins/index.js

@@ -0,0 +1,4 @@
+const selectTestsWithGrep = require('cypress-select-tests/grep')
+module.exports = (on, config) => {
+  on('file:preprocessor', selectTestsWithGrep(config))
+}

Diff for: examples/preprocessors__grep/cypress/support/index.js

@@ -0,0 +1 @@
+// no additional commands

Diff for: examples/preprocessors__grep/images/grep-admin.png

@@ -0,0 +1,10 @@
+{
+  "name": "cypress-example-grep",
+  "version": "1.0.0",
+  "description": "Selecting specs and tests to run using grep",
+  "scripts": {
+    "start": "echo",
+    "cypress:run": "../../node_modules/.bin/cypress run",
+    "cypress:open": "../../node_modules/.bin/cypress open"
+  }
+}