feat: add skipOn and onlyOn with headed or headless mode (#39)

* add skipOn headed or headless

* add onlyOn and tests

Author: bahmutov

README.md

@@ -167,6 +167,30 @@ it('loads users', () => {
 })
 ```
 
+### Headed
+
+You can skip or run tests in headed / headless environments
+
+```js
+import { skipOn, onlyOn } from '@cypress/skip-test'
+
+skipOn('headed', () => {
+  it('skips the current test in headed mode', () => {
+    cy.wrap(true).should('equal', true)
+  })
+})
+
+onlyOn('headless', () => {
+  it('runs only in headless mode', () => { ... })
+})
+```
+
+**Note:** when skipping tests in this case, it will insert an empty placeholder test to provide information why the tests were skipped.
+
+```text
+- Skipping test(s), not on headed
+```
+
 ### `ENVIRONMENT`
 
 This module also reads special environment variable `ENVIRONMENT` inside its checks. For example, to only stub network calls on `staging` environment, execute the tests like this:

cypress/integration/headed-only-spec.js

@@ -0,0 +1,8 @@
+/// <reference types="cypress" />
+import { onlyOn } from '../..'
+
+onlyOn('headed', () => {
+  it('runs the current test only in headed mode', () => {
+    cy.wrap(true).should('equal', true)
+  })
+})

cypress/integration/headed-spec.js

@@ -0,0 +1,8 @@
+/// <reference types="cypress" />
+import { skipOn } from '../..'
+
+skipOn('headed', () => {
+  it('skips the current test in headed mode', () => {
+    cy.wrap(true).should('equal', true)
+  })
+})

index.js

@@ -57,6 +57,10 @@ const isOn = name => {
     return checkBrowserName(normalizedName)
   }
 
+  if (isHeadedName(normalizedName)) {
+    return headedMatches(normalizedName)
+  }
+
   if (isEnvironment(name)) {
     return true
   }
@@ -73,6 +77,18 @@ const skip = () => {
 
 const isPlatform = name => ['win32', 'darwin', 'linux'].includes(name)
 const isBrowser = name => ['electron', 'chrome', 'firefox'].includes(name)
+const isHeadedName = name => ['headed', 'headless'].includes(name)
+
+const headedMatches = name => {
+  if (name === 'headed') {
+    return Cypress.browser.isHeaded
+  }
+  if (name === 'headless') {
+    return Cypress.browser.isHeadless
+  }
+  throw new Error(`Do not know how to treat headed flag "${name}"`)
+}
+
 /**
  * You can pass custom environment name when running Cypress
  * @example
@@ -140,6 +156,13 @@ const skipOn = (name, cb) => {
       return it(`Skipping test(s) on ${normalizedName}`)
     }
 
+    if (isHeadedName(normalizedName)) {
+      if (!headedMatches(normalizedName)) {
+        return cb()
+      }
+      return it(`Skipping test(s) in ${normalizedName} mode`)
+    }
+
     if (!matchesUrlPart(normalizedName)) {
       return cb()
     }
@@ -205,6 +228,8 @@ const onlyOn = (name, cb) => {
   if (cb) {
     if (isOn(name)) {
       return cb()
+    } else {
+      return it(`Skipping test(s), not on ${name}`)
     }
   } else {
     const normalizedName = normalizeName(name)

package.json

@@ -8,7 +8,9 @@
     "test": "cypress run",
     "semantic-release": "semantic-release",
     "format": "prettier --write '*.js' 'cypress/**/*.js'",
-    "e2e": "mocha --timeout 30000 test"
+    "e2e": "mocha --timeout 30000 test",
+    "cy:open": "cypress open",
+    "cy:run": "cypress run"
   },
   "keywords": [
     "cypress",

test/headed-spec.js

@@ -0,0 +1,98 @@
+const spok = require('spok').default
+const cypress = require('cypress')
+const assert = require('assert')
+const debug = require('debug')('test')
+
+const assertResults = results => {
+  // let's confirm the number of tests
+  // and maybe some additional information
+  debug('results %o', results)
+
+  spok(assert, results, {
+    totalSuites: 0,
+    totalTests: 1,
+    runs: spok.array
+  })
+  assert(results.runs.length === 1, 'single run')
+}
+
+const shouldHaveTest = (title, state, results) => {
+  assert(results.runs.length === 1, 'there should be just a single run')
+  const test = results.runs[0].tests.find(t => t.title[0] === title)
+  debug('found test %o', test)
+  assert(test, 'could not find test')
+
+  spok(assert, test, {
+    title,
+    state,
+    // there should not be any errors
+    error: null
+  })
+}
+
+/* eslint-env mocha */
+describe('skipping test in headed mode', () => {
+  it('runs the test in headless mode', () => {
+    return cypress
+      .run({
+        spec: 'cypress/integration/headed-spec.js',
+        headed: false,
+        video: false
+      })
+      .then(results => {
+        assertResults(results)
+        shouldHaveTest(
+          'skips the current test in headed mode',
+          'passed',
+          results
+        )
+      })
+  })
+
+  it('skips test in headed mode', () => {
+    return cypress
+      .run({
+        spec: 'cypress/integration/headed-spec.js',
+        headed: true,
+        video: false
+      })
+      .then(results => {
+        assertResults(results)
+        // the plugin automatically replaces any tests in skipped block
+        // with a single dummy test with this name
+        shouldHaveTest('Skipping test(s) in headed mode', 'pending', results)
+      })
+  })
+})
+
+describe('only running test in headed mode', () => {
+  it('runs the test in headed mode', () => {
+    return cypress
+      .run({
+        spec: 'cypress/integration/headed-only-spec.js',
+        headed: true,
+        video: false
+      })
+      .then(results => {
+        assertResults(results)
+        shouldHaveTest(
+          'runs the current test only in headed mode',
+          'passed',
+          results
+        )
+      })
+  })
+
+  it('skips test in headless mode', () => {
+    return cypress
+      .run({
+        spec: 'cypress/integration/headed-only-spec.js',
+        headed: false,
+        video: false
+      })
+      .then(results => {
+        assertResults(results)
+        shouldHaveTest('Skipping test(s), not on headed', 'pending', results)
+      })
+  })
+})