Recipes

This repo contains various recipes for testing common scenarios using Cypress: Fundamentals, Testing the DOM, Logging in, Preprocessors, Blogs, Stubbing and spying, Unit Testing, Server Communication

Fundamentals

Recipe	Description
Node Modules	Import your own node modules
Environment variables	Passing environment variables to tests
Dynamic tests	Create tests dynamically from data
Fixtures	Loading single or multiple fixtures
Adding Chai Assertions	Add new or custom chai assertions
Cypress module API	Run Cypress via its module API

Testing the DOM

Recipe	Description
Tab Handling and Links	Links that open in a new tab
Hover and Hidden Elements	Test hidden elements requiring hover
Form Interactions	Test form elements like input type range
Drag and Drop	Use .trigger() to test drag and drop

Logging in recipes

Recipe	Description
Single Sign On	Log in across multiple servers or providers
HTML Web Forms	Log in with a basic HTML form
XHR Web Forms	Log in using an XHR
CSRF Tokens	Log in with a required CSRF token

Also see Authentication plugins and watch video "Organizing Tests, Logging In, Controlling State"

Preprocessors

Recipe	Description
grep	Filter tests by name using Mocha-like grep syntax
Typescript with Browserify	Add typescript support with browserify
Typescript with Webpack	Add typescript support with webpack

Blogs

Demo recipes from the blog posts at www.cypress.io/blog

Recipe	Description
Application Actions	Application actions are a replacement for Page Objects
Direct Control of AngularJS	Bypass the DOM and control AngularJS
E2E API Testing	Run your API Tests with a GUI
E2E Snapshots	End-to-End Snapshot Testing
Element Coverage	Track elements covered by tests
Codepen.io Testing	Test a HyperApp Codepen demo
Testing Redux Store	Test an application that uses Redux data store
Vue + Vuex + REST Testing	Test an application that uses central data store
A11y Testing	Accessability testing with cypress-axe

Stubbing and spying

Recipe	Description
Stubbing Functions	Use cy.stub() to test function calls
Stubbing window.fetch	Use cy.stub() to control fetch requests
Stubbing methods called on window	Use cy.stub() for methods called on window
Stubbing Google Analytics	Use cy.stub() to test Google Analytics calls

Unit Testing

Recipe	Description
Application Code	Import and test your own application code
React	Test your React components in isolation
File Upload in React	Test file upload in React app

Server Communication

Recipe	Description
Bootstrapping your App	Seed your application with test data
Seeding your Database in Node	Seed your database with test data

Overview

• This repo is structured similar to how other "Monorepos" work.
• Each example project has it's own Cypress configuration, tests, backend and frontend assets.
• Each of these example projects share a single "root" Cypress that is installed in the root node_modules folder.
• This structure looks different from normal projects, but its the easiest way to manage multiple projects without installing Cypress independently for each one.

Installation

## install all dependencies
npm install

Opening Cypress GUI

cd ./examples/testing-dom__drag-drop
# start local server
npm start &
# and open Cypress GUI
npm run cypress:open

Running from the CLI

Same as running Cypress GUI but with cypress run command (and any CLI arguments)

cd ./examples/testing-dom__drag-drop
# start local server
npm start &
# run Cypress tests headlessly
npm run cypress:run

### runs all example projects in specific browser
### similar to cypress run --browser <name>
npm run cypress:run -- --browser chrome

### sends test results, videos, screenshots
### to Cypress dashboard
npm run cypress:run -- --record

Recipes

Node Modules

• Import ES2015 modules.
• Require CommonJS modules.
• Organize reusable utility functions.
• Import 3rd party node_modules.

Single Sign On

• Login when authentication is done on a 3rd party server.
• Parse tokens using cy.request().
• Manually set tokens on local storage.
• Map external hosts and point to local servers.

HTML Web Forms

• Test a standard username/password HTML form.
• Test errors submitting invalid data.
• Test unauthenticated redirects.
• Authenticate users with cookies.
• Create a custom cy.login() test command.
• Bypass needing to use your actual UI.
• Increase speed of testing with cy.request().

XHR Web Forms

• Test an AJAX backed username/password form.
• Test errors submitting invalid data.
• Stub JSON based XHR requests.
• Stub application functions.
• Create a custom cy.login() test command.
• Bypass needing to use your actual UI.
• Increase speed of testing with cy.request().

CSRF Tokens

• Use cy.request() to get around CSRF protections.
• Parse CSRF tokens out of HTML.
• Parse CSRF tokens out of response headers.
• Expose CSRF via a route.
• Disable CSRF when not in production.

Tab Handling and Links

• Test anchor links opening in new tabs: <a target="_blank">.
• Test anchor links that link to external domains: <a href="...">.
• Prevent content from opening in a new tab.
• Request external content that would open in a new tab using cy.request().
• Speed up tests by reducing loading times.

Hover and Hidden Elements

• Interact with elements that are hidden by CSS.
• Use .invoke() and .trigger() to simulate hovering.
• Trigger mouseover, mouseout, mouseenter, mouseleave events. Get around the lack of a .hover() command.

Form Interactions

• Use .invoke() and .trigger() to test a range input (slider).

Drag and Drop

• Use .trigger() to test drag-n-drop that uses mouse events.
• Use .trigger() to test drag-n-drop that uses drag events.
• Use cypress-file-upload for file upload testing with drag-n-drop.

grep

• Use Mocha-like syntax to select tests to run
• Implemented as a preprocessor cypress-select-tests

Typescript with Browserify

• Use @cypress/browserify-preprocessor to write Cypress tests in Typescript

Typescript with Webpack

• Use @cypress/webpack-preprocessor to write Cypress tests in Typescript
• Lint TypeScript spec code against Cypress type definitions

A11y Testing

This demo shows the cypress-axe plugin which can run the Axe-core library against the webpage to check if the page follows accessibility practices.

Application Actions

• Invoke methods on the application's model object
• Avoid code duplication and need to create page object hierarchy
• Run e2e very quickly by skipping UI unless testing that specific UI feature

Direct Control of AngularJS

• Blog article written here
• Programmatically control AngularJS
• Bypass the DOM, update scopes directly
• Create custom command for controlling services

E2E API Testing

• Blog article written here
• Use cy.request() to perform API Testing
• Use the Cypress GUI to help debug requests

E2E Snapshots

• Blog post End-to-End Snapshot Testing
• Adding .snapshot() command by requiring 3rd party module
• Capturing and saving snapshots of primitive values
• Testing central data Vuex store using snapshots
• Making assertions against a DOM element with cy.get('...').snapshot()

Codepen Testing

• Blog post
• Load Codepen and get around iframe security restrictions.
• Use cy.request() to load a document into test iframe.
• Test HyperApp.js application through the DOM and through actions.

Element Coverage

• Blog post Element coverage
• Overwrite several built-in Cypress commands like cy.type and cy.click
• Draw elements after the tests finish

Testing Redux Store

• control application via DOM and check that Redux store has been properly updated
• drive application by dispatching Redux actions
• use Redux actions directly from tests
• load initial Redux state from a fixture file

Vue + Vuex + REST Testing

• Blog post
• Test a Vue.js web application that uses central data store
• Mock REST calls to the server
• Dispatch actions to the Vuex store
• Test text file upload

Stubbing Functions

• Use cy.stub() to stub dependencies in a unit test.
• Handle promises returned by stubbed functions.
• Handle callbacks in stubbed functions.

Stubbing window.fetch

• Use cy.spy() to verify the behavior of a function.
• Use cy.stub() to verify and control the behavior of a function.
• Use cy.clock() and cy.tick() to control time.
• Stub window.fetch to control server responses.
• Replace window.fetch with a polyfill that uses XHR and is loaded only for tests.
• Delete window.fetch during specific visit or every window load.

Stubbing methods called on window

• Use cy.spy() to test window.open behavior.

Stubbing Google Analytics

• Use blacklistHosts to block Google Analytics from receiving requests.
• Use cy.stub() to verify that window.ga(...) was called with the correct arguments

Application Code

• Unit test your own application code libraries.
• Import modules using ES2015.
• Test simple math functions.
• Test the canonical fizzbuzz test.
• Automatically retry assertion until a given property inside an object:
  • is added or deleted
  • has expected value

React

• Unit test a React JSX Component using Enzyme, react-testing-library and cypress-react-unit-test libraries.

File Upload in React

• Passing synthetic test file to upload via an .trigger('change') event
• Stub remote server using cy.route()
• Alternatively stub axios.post method using cy.stub()
• Alternatively use cypress-file-upload for file upload testing.

Adding Chai Assertions

• Extend chai with the chai-date-string assertion plugin.
• Extend chai with the chai-colors assertion plugin.
• Globally extend chai for all specs.
• Set up Intelligent Code completion for custom assertions.

Cypress module API

• Run Cypress tests using its Node module API

require('cypress').run({
  // options
}).then(testResults => {
  // rerun failing specs
  // or email test report
  // or post it on Slack
  // ...
})

Bootstrapping your App

• Use cy.visit() onBeforeLoad callback.
• Start your application with test data.
• Stub an XHR to seed with test data.
• Wait on an XHR to finish.

Seeding your Database in Node

• Use cy.task() to communicate with node via the pluginsFile.
• Seed your database with test data.
• Wrap your pluginsFile so you can require files that use ES modules (import/export).

Environment Variables

• Pass values via env object in cypress.json.
• Pass any variable that starts with CYPRESS_.
• Extract any other variable from process.env using cypress/plugins/index.js callback.

Dynamic tests

• Run the same test against different viewport resolutions
• Run the same test against multiple subdomains
• Generate tests based on the fetched data

Fixtures

• loading a single fixture file or multiple fixtures in multiple ways

Development

See Development.md