Execute code in Node via the task plugin event.

Anti-Pattern
We do not recommend starting a web server using cy.task(). Read about best practices here.

Syntax

cy.task(event)
cy.task(event, arg)
cy.task(event, arg, options)

Usage

Correct Usage

// in test
cy.task('log', 'This will be output to the terminal')

// in plugins file
on('task', {
  log (message) {
    console.log(message)

    return null
  }
})

Arguments

event (String)

An event name to be handled via the task event in the pluginsFile.

arg (Object)

An argument to send along with the event. This can be any value that can be serialized by JSON.stringify(). Unserializable types such as functions, regular expressions, or symbols will be omitted to null.

If you need to pass multiple arguments, use an object

// in test
cy.task('hello', { greeting: 'Hello', name: 'World' })

// in plugins/index.js
on('task', {
  // deconstruct the individual properties
  hello ({ greeting, name }) {
    console.log('%s, %s', greeting, name)

    return null
  }
})

options (Object)

Pass in an options object to change the default behavior of cy.task().

Option	Default	Description
`log`	`true`	Displays the command in the Command log
`timeout`	`taskTimeout`	Time to wait for `cy.task()` to resolve before timing out

Yields

cy.task() yields the value returned or resolved by the task event in the pluginsFile.

Examples

Command

cy.task() provides an escape hatch for running arbitrary Node code, so you can take actions necessary for your tests outside of the scope of Cypress. This is great for:

Seeding your test database.
Storing state in Node that you want persisted between spec files.
Performing parallel tasks, like making multiple http requests outside of Cypress.
Running an external process.

In the task plugin event, the command will fail if undefined is returned. This helps catch typos or cases where the task event is not handled.

If you do not need to return a value, explicitly return null to signal that the given event has been handled.

Read a file that might not exist

Command cy.readFile() assumes the file exists. If you need to read a file that might not exist, use cy.task.

// in test
cy.task('readFileMaybe', 'my-file.txt').then((textOrNull) => { ... })

// in plugins/index.js
const fs = require('fs')

on('task', {
  readFileMaybe (filename) {
    if (fs.existsSync(filename)) {
      return fs.readFileSync(filename, 'utf8')
    }

    return null
  }
})

Seed a database

// in test
describe('e2e', () => {
  beforeEach(() => {
    cy.task('defaults:db')
    cy.visit('/')
  })

  it('displays article values', () => {
    cy.get('.article-list')
      .should('have.length', 10)
  })
})

// in plugins/index.js
// we require some code in our app that
// is responsible for seeding our database
const db = require('../../server/src/db')

module.exports = (on, config) => {
  on('task', {
    'defaults:db': () => {
      return db.seed('defaults')
    }
  })
}

Return a Promise from an asynchronous task

// in test
cy.task('pause', 1000)

// in plugins/index.js
on('task', {
  pause (ms) {
    return new Promise((resolve) => {
      // tasks should not resolve with undefined
      setTimeout(() => resolve(null), ms)
    })
  }
})

Options

Change the timeout

You can increase the time allowed to execute the task, although we do not recommend executing tasks that take a long time to exit.

Cypress will not continue running any other commands until cy.task() has finished, so a long-running command will drastically slow down your test runs.

// will fail if seeding the database takes longer than 20 seconds to finish
cy.task('seedDatabase', null, { timeout: 20000 })

Notes

Tasks must end

Tasks that do not end are not supported

cy.task() does not support tasks that do not end, such as:

Starting a server.
A task that watches for file changes.
Any process that needs to be manually interrupted to stop.

A task must end within the taskTimeout or Cypress will fail the current test.

Tasks are merged automatically

Sometimes you might be using plugins that export their tasks for registration. Cypress automatically merges on('task') objects for you. For example if you are using cypress-skip-and-only-ui plugin and want to install your own task to read a file that might not exist:

// in plugins/index.js file
const skipAndOnlyTask = require('cypress-skip-and-only-ui/task')
const fs = require('fs')
const myTask = {
  readFileMaybe (filename) {
    if (fs.existsSync(filename)) {
      return fs.readFileSync(filename, 'utf8')
    }

    return null
  }
}

// register plugin's task
on('task', skipAndOnlyTask)
// and register my own task
on('task', myTask)

See #2284 for implementation.

Duplicate task keys
If multiple task objects use the same key, the later registration will overwrite that particular key, just like merging multiple objects with duplicate keys will overwrite the first one.

Rules

Requirements

cy.task() requires being chained off of cy.
cy.task() requires the task to eventually end.

Assertions

cy.task() will only run assertions you've chained once, and will not retry.

Timeouts

cy.task() can time out waiting for the task to end.

Command Log

List the contents of cypress.json

cy.task('readJson', 'cypress.json')

The command above will display in the Command Log as:

When clicking on the task command within the command log, the console outputs the following:

History

Version	Changes
3.0.0	`cy.task()` command added

W3cubDocs

task