feat: add Cypress.grep method

Author: bahmutov

README.md

@@ -173,18 +173,17 @@ it('works', { tags: '@smoke @fast' }, () => ...)
 
 ## DevTools console
 
-Watch [this video](https://youtu.be/Sp1NfcLPpwg) to see how to run only one or some tagged tests without editing the spec source files!
+You can set the grep string from the DevTools Console. This plugin adds method `Cypress.grep` to set the grep string and restart the tests
 
-- from the browser, open the DevTools console
-- if you want to run tests with specific tag or tag expression, enter the command to set the grep value like `Cypress.env('grep', '@tag1')` for example and then click the reload button or press "r" key. The tests should re-run and the grep value should be applied.
-
-![Run-time grep from DevTools console](./images/grep-tag.gif)
-
-- if you want to run just a test with a title, copy the test title and use an array with just the test title `Cypress.env('grep', ['test title here'])` and re-run the test
-
-![Run a single test by title from the DevTools console](./images/test-title-grep.gif)
+```js
+// use grep "@tag1"
+Cypress.grep('@tag1')
+// run the test with substring "hello world"
+// without parsing separate words as tags
+Cypress.grep(['hello world'])
+```
 
-- to remove the grep string, enter `Cypress.env('grep', null)`
+- to remove the grep string, enter `Cypress.grep()`
 
 ## Debugging
 

images/debug.png

@@ -92,4 +92,15 @@ function cypressGrep() {
   describe.skip = _describe.skip
 }
 
+if (!Cypress.grep) {
+  // expose a utility method to set the grep and run the tests
+  Cypress.grep = function grep(s) {
+    Cypress.env('grep', s)
+    debug('set new grep to "%s", restarting', s)
+    setTimeout(() => {
+      window.top.document.querySelector('.reporter .restart').click()
+    }, 0)
+  }
+}
+
 module.exports = cypressGrep