Forem: Gleb Bahmutov

How To Learn Cypress.io Test Runner In 2024

Gleb Bahmutov — Mon, 01 Jan 2024 18:03:31 +0000

If your 2024 resolution is to acquire web automation testing skills, then learning how to write Cypress.io tests is the way to go. Here is my advice on how to learn it much faster and make the knowledge stick:

When stuck quickly consult the official documentation at docs.cypress.io. Do not "invent" your own way of coding things, and do not "fight" the Cypress approach: the Cypress docs are extensive and comprehensive. They probably show a good solution to the problem you are hitting.
Start learning by taking a course. Yes, I know, it is a time investment. But a few weeks of studying on your own can save you months and months of frustration down the line. There are Cypress courses available at LinkedIn and AutomationU, but if you want a practical, complete, and hands-on course, consider one of my Cypress courses.
During day-to-day test writing, find lots of tested Cypress examples and recipes showing how to use every cy command on my glebbahmutov.com/cypress-examples site. Tip: use the built-in search widget to quickly find the answers.
Use my Cypress Tips search page. I have scraped my Cypress examples, my blog posts, video descriptions, and courses to put all these search results on a single page.
Subscribe to my testing blog glebbahmutov.com/blog and my YouTube channel www.youtube.com/glebbahmutov. I write and record new Cypress content regularly. The short videos help me show Cypress in action.
Ask me any Cypress questions in my Discord channel or in Filip Hric's Discord. I promise to answer it. Of course, my answer could be just a link to a blog post, a video, or one of my course lessons 😉
You should skim learn.cypress.io but don't spend much time on it. The advice is generic and the code examples are pretty obsolete and not maintained.
Browse through my Cypress-themed presentations at slides.com/bahmutov. Many slide decks include links to the presentation recording, if available.
If you are working in an organization interested in hands-on Cypress and Playwright training, consider ordering an online or in-person testing workshop. I have several workshops that I taught multiple times, see them at cypress.tips/workshops. Each workshop can be adapted to your organization's needs, and I guarantee that everyone studying with me will learn something new no matter how little or how much you already know.

Bonus: Learn Cypress And Playwright

Why learn just one web testing tool if you could learn both to double your chances of finding a better job? I have created Cypress Vs Playwright online course that trains you to solve practical testing problems using hands-on coding lessons. Each lesson poses a problem and gives you the starting code. You must solve the assignment using each test runner to appreciate the difference in syntax and capabilities between Cypress and Playwright.

12 Recipes for testing React applications using cypress-react-unit-test

Gleb Bahmutov — Mon, 29 Jun 2020 13:19:06 +0000

Note: this blog post takes the twelve testing examples from 12 Recipes for testing React applications using Testing Library blog post by João Forja, where the same examples are tested using testing-library. This blog post uses cypress-react-unit-test + Cypress combination to test exactly the same scenarios.

Note 2: you can find these tests in the repo bahmutov/12-testing-recipes

Invokes given callback
Changes current route
Higher Order Component
Component cleans up on unmount
Depends on Context Provider
Uses functions that depend on time
Custom hooks
Portal
Focus is on correct element
Order of elements
Selected option
Dynamic page titles

Invokes given callback

We're testing that after some interaction the component calls a given callback.
We give a mock function to the component under test and interact with it so that it calls the callback. Then we assert we called the function with the expected parameters. If relevant, we also check the number of times the function was called.

/// <reference types="cypress" />
import React from 'react'
import { mount } from 'cypress-react-unit-test'

describe('Invoke callback', () => {
  function Button({ action }) {
    return <button onClick={() => action()}>Call</button>
  }

  it('callback is called on button click', () => {
    const callback = cy.stub()
    mount(<Button action={callback} />)

    cy.contains('button', /call/i)
      .click()
      .then(() => {
        expect(callback).to.have.been.calledOnce
        expect(callback).to.have.been.calledWithExactly()
      })
  })
})

The test runs and we can see the stub count of 1 in the Cypress' Command Log on the left.

The same test can be written differently avoiding .then by saving the reference to the stub using an alias.

it('callback is called on button click using an alias', () => {
  mount(<Button action={cy.stub().as('callback')} />)

  cy.contains('button', /call/i).click()
  cy.get('@callback')
    .should('have.been.calledOnce')
    .and('have.been.calledWithExactly')
})

Changes current route

We're testing that the component redirects the user to an expected router with the expected query parameters after an interaction.
We first create a routing environment similar to that in which we'll use the component. We set up that environment so we can capture the URL to which the component will redirect us. We interact with the component to cause the redirect. We then assert that we were redirected to the URL we expected.

/// <reference types="cypress" />
import React, { useState } from 'react'
import { MemoryRouter, Route, useHistory } from 'react-router-dom'
import { mount } from 'cypress-react-unit-test'

describe('Changes current route', () => {
  it('On search redirects to new route', () => {
    let location
    mount(
      <MemoryRouter initialEntries={['/']}>
        <Route path="/">
          <SearchBar />
        </Route>
        <Route
          path="/*"
          render={({ location: loc }) => {
            location = loc
            return null
          }}
        />
      </MemoryRouter>,
    )

    cy.get('input#query').type('react')
    cy.get('input[type=submit]')
      .click()
      .then(() => {
        expect(location.pathname).to.equal('/search-results')
        const searchParams = new URLSearchParams(location.search)
        expect(searchParams.has('query')).to.be.true
        expect(searchParams.get('query')).to.equal('react')
      })
  })
})

function SearchBar() {
  const history = useHistory()
  const [query, setQuery] = useState('')

  return (
    <form
      onSubmit={function redirectToResultsPage(e) {
        debugger
        e.preventDefault()
        history.push(`/search-results?query=${query}`)
      }}
    >
      <label htmlFor="query">search</label>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.currentTarget.value)}
        id="query"
      />
      <input type="submit" value="go" />
    </form>
  )
}

You can see where the test is typing and the button it is clicking

Higher Order Component

We're testing that a HOC gives the props we expect to the wrapped component.
We first create a mock component for the HOC to wrap. The mock component will store the received props in a variable. After rendering the component returned by the HOC we assert that it gave the mock component the props we expected.

import React from 'react'
import { mount } from 'cypress-react-unit-test'

function withSum(WrappedComponent, numbersToSum) {
  const sum = numbersToSum.reduce((a, b) => a + b, 0)
  return () => <WrappedComponent sum={sum} />
}

describe('Higher Order Component', () => {
  it('Adds number and gives result as a prop', () => {
    let result
    function WrappedComponent({ sum }) {
      result = sum
      return null
    }
    const ComponentWithSum = withSum(WrappedComponent, [4, 6])
    mount(<ComponentWithSum />)

    // mount is an asynchronous command
    cy.then(() => {
      expect(result).to.equal(10)
    })
  })
})

Seeing "Unknown" due to anonymous function in the mounting message weird, we can give it a label:

mount(<ComponentWithSum />, { alias: 'ComponentWithSum' })

Component cleans up on unmount

We want to assert that a component subscribes after mount and unsubscribes after unmount.
We start by mocking the subscription methods so we can assert they get called. We then render the component and assert that it subscribed. All that's left to do is make the component unmount and assert it unsubscribed.

/// <reference types="cypress" />
import React, { useEffect } from 'react'
import { mount, unmount } from 'cypress-react-unit-test'

function ComponentThatSubscribes({ subscriptionService }) {
  useEffect(() => {
    subscriptionService.subscribe()
    return () => subscriptionService.unsubscribe()
  }, [subscriptionService])
  return null
}

describe('Component cleans up on unmount', () => {
  it('Subscribes and unsubscribes when appropriate', () => {
    const subscriptionService = {
      subscribe: cy.stub().as('subscribe'),
      unsubscribe: cy.stub().as('unsubscribe'),
    }

    mount(<ComponentThatSubscribes subscriptionService={subscriptionService} />)

    cy.get('@subscribe')
      .should('have.been.calledOnce')
      .and('have.been.calledWithExactly')

    unmount()

    cy.get('@unsubscribe')
      .should('have.been.calledOnce')
      .and('have.been.calledWithExactly')
  })
})

Again, both cy.stub instances can be found in the Command Log.

Depends on Context Provider

We want to test a component that depends on a context Provider
To test the component, we'll recreate the environment in which we'll use the component. In other words, we'll wrap the component in the Context Provider.

/// <reference types="cypress" />
import React, { useContext } from 'react'
import { mount } from 'cypress-react-unit-test'

const UserContext = React.createContext()

function UserFullName() {
  const { user } = useContext(UserContext)
  return <p>{user.fullName}</p>
}

describe('Proivder', () => {
  it('displays name of current user', () => {
    mount(
      <UserContext.Provider value={{ user: { fullName: 'Giorno Giovanna' } }}>
        <UserFullName />
      </UserContext.Provider>,
    )
    cy.contains('Giorno Giovanna').should('be.visible')
  })
})

The test passes, and if we hover over the "contains" command, the found element is highlighted on the page.

Uses functions that depend on time

We want to test a component that depends on real-time. In this example, that dependency comes from using setTimeout().
When testing components that depend on real-time, we need to be aware that those tests shouldn't take too long. ~~One way to do that is to have the component receive the time interval as a prop to allow us to configure a shorter time interval for tests than we would have in production.~~ One way to do so that is to mock the clock during the test to speed things up.

/// <reference types="cypress" />
import React, { useState, useEffect } from 'react'
import { mount } from 'cypress-react-unit-test'

function TrafficLight() {
  const timeUntilChange = 500
  const [light, setLight] = useState('Red')
  useEffect(() => {
    setTimeout(() => setLight('Green'), timeUntilChange)
  }, [timeUntilChange])
  return <p>{light}</p>
}

describe('Functions that depend on time', () => {
  it('Changes from red to green to after timeout', () => {
    cy.clock()
    mount(<TrafficLight />)

    cy.contains(/red/i).should('be.visible')
    cy.tick(500)
    cy.contains(/green/i).should('be.visible')
  })
})

We are using cy.clock to freeze the application's clock. After checking if the light is red at the beginning, we fast-forward the timer by 500ms and check the light again. This time it shows "Green". We can confirm the DOM structure during each step by using the built-in Cypress time-traveling debugger.

Custom hooks

We want to test a custom hook.
Since we're testing a hook, we'll need to call it inside a component otherwise we'll get an error. Therefore, we'll create a mock component, use the hook inside it, and store what the hook returns in a variable. Now we can assert what we need to assert using that variable.

/// <reference types="cypress" />
import React, { useState, useCallback } from 'react'
import { mount } from 'cypress-react-unit-test'

function useCounter() {
  const [count, setCount] = useState(0)
  const increment = useCallback(() => setCount((x) => x + 1), [])
  return { count, increment }
}

describe('Hooks', () => {
  it('counter increments', () => {
    let counter
    function MockComponent() {
      counter = useCounter()
      return null
    }

    mount(<MockComponent />)
      .then(() => {
        expect(counter.count).to.equal(0)
        counter.increment()
      })
      .then(() => {
        expect(counter.count).to.equal(1)
      })
  })
})

You can also test the hook directly - cypress-react-unit-test will create a mock component for you.

import { useState, useCallback } from 'react'
import { mountHook } from 'cypress-react-unit-test'

function useCounter() {
  const [count, setCount] = useState(0)
  const increment = useCallback(() => setCount(x => x + 1), [])
  return { count, increment }
}

describe('useCounter hook', function() {
  it('increments the count', function() {
    mountHook(() => useCounter()).then(result => {
      expect(result.current.count).to.equal(0)
      result.current.increment()
      expect(result.current.count).to.equal(1)
      result.current.increment()
      expect(result.current.count).to.equal(2)
    })
  })
})

Portal

We want to test a component that's a portal.
A portal needs a DOM node to be rendered into. So to test it, we'll have to create that DOM node. After we make the assertions, we'll have to remove the DOM node as not to affect other tests.

/// <reference types="cypress" />
import React, { useRef, useEffect, useState } from 'react'
import ReactDOM from 'react-dom'
import { mount } from 'cypress-react-unit-test'

function PortalCounter() {
  const el = useRef(document.createElement('div'))
  const [count, setCount] = useState(0)

  useEffect(() => {
    const modalRoot = document.getElementById('modal-root')
    const currentEl = el.current
    modalRoot.appendChild(currentEl)
    return () => modalRoot.removeChild(currentEl)
  }, [])

  return ReactDOM.createPortal(
    <>
      <section aria-live="polite">
        count: <span data-testid="counter">{count}</span>
      </section>
      <button type="button" onClick={() => setCount((c) => c + 1)}>
        inc
      </button>
    </>,
    el.current,
  )
}

describe('Portal', () => {
  it('PortalCounter starts at 0 and increments', () => {
    const modalRoot = document.createElement('div')
    modalRoot.setAttribute('id', 'modal-root')
    document.body.appendChild(modalRoot)

    mount(<PortalCounter />)
    cy.contains('[data-testid=counter]', 0)
    cy.contains('button[type=button]', 'inc').click()
    cy.contains('[data-testid=counter]', 1)
  })
})

Focus is on correct element

We want to test that the focus on the element we expect.
We can verify if an element has focus or not by using .should('have.focus') assertion.

/// <reference types="cypress" />
import React from 'react'
import { mount } from 'cypress-react-unit-test'

function NameForm() {
  return (
    <form>
      <label htmlFor="name">Name</label>
      <input id="name" type="text" />
    </form>
  )
}

describe('Focus is on correct element', () => {
  it('clicking on label gives focus to name input', () => {
    mount(<NameForm />)

    cy.contains('label', 'Name').click()
    cy.get('input#name').should('have.focus')
  })
})

Order of elements

We want to test that a list of elements is rendered in the expected order.
We'll take advantage of cy.get queries returning elements in the order in which they appear on the HTML.
It's important to note that this approach doesn't take into account CSS that might change the order in which the elements are displayed.

/// <reference types="cypress" />
import React from 'react'
import { mount } from 'cypress-react-unit-test'

function NamesList({ names }) {
  return (
    <ul>
      {names.map((name) => (
        <li key={name}>{name}</li>
      ))}
    </ul>
  )
}

describe('Order of elements', () => {
  it('renders names in given order', () => {
    const names = ['Bucciarati', 'Abbacchio', 'Narancia']

    mount(<NamesList names={names} />)
    cy.get('li').should(($li) => {
      expect($li[0]).to.have.text(names[0])
      expect($li[1]).to.have.text(names[1])
      expect($li[2]).to.have.text(names[2])
    })
  })
})

In Cypress, you can see the component renders the elements in the expected order and then use visual testing to automatically validate it.

You can further simplify the above test using .each command

cy.get('li').each((li, k) => {
  expect(li).to.have.text(names[k])
})

Selected Option

We want to test that an input is checked.
We can use should('be.checked') to test if an element is checked.

/// <reference types="cypress" />
import React from 'react'
import { mount } from 'cypress-react-unit-test'

function SeasonsForm() {
  return (
    <form>
      <p>Best season:</p>
      <section>
        <input name="season" type="radio" id="winter" value="winter" />
        <label htmlFor="winter">Winter</label>
        <input name="season" type="radio" id="spring" value="spring" />
        <label htmlFor="spring">Spring</label>
        <input
          name="season"
          checked
          readOnly
          type="radio"
          id="summer"
          value="summer"
        />
        <label htmlFor="summer">Summer</label>
        <input name="season" type="radio" id="autumn" value="autumn" />
        <label htmlFor="autumn">Autumn</label>
      </section>
    </form>
  )
}

describe('Selected option', () => {
  it('Has Summer pre-selected', () => {
    mount(<SeasonsForm />)
    cy.get('input[type=radio]#summer').should('be.checked')
  })
})

Dynamic page titles

We want to test that the title of the current page is updated.
We access the current title by using cy.title. Even if the document title won't be immediately updated, Cypress will automatically waiting and retrying the assertion should('equal', '1').

/// <reference types="cypress" />
import React, { useState } from 'react'
import { Helmet } from 'react-helmet'
import { mount } from 'cypress-react-unit-test'

function DocTitleCounter() {
  const [counter, setCounter] = useState(0)

  return (
    <>
      <Helmet>
        <title>{String(counter)}</title>
      </Helmet>
      <button onClick={() => setCounter((c) => c + 1)}>inc</button>
    </>
  )
}

describe('Document title', () => {
  it('Increments document title', () => {
    mount(<DocTitleCounter />)
    cy.title().should('equal', '0')
    cy.contains('button', /inc/i).click()
    cy.title().should('equal', '1')
  })
})

Other resources

The original blog post 12 Recipes for testing React applications using Testing Library where the above 12 examples came from
More cypress-react-unit-test examples
My Vision for Component Tests in Cypress

Test React Component with cypress-react-unit-test Example

Gleb Bahmutov — Tue, 26 May 2020 23:55:37 +0000

I have read Testing React Components with react-test-renderer and the Act API by Valentino Gagliardi and thought it was a great post. I wanted to see how the same tests could be written using Cypress and cypress-react-unit-test. You can find my source code in repo bahmutov/testing-react-example

Let's get a React component working in the repository. The simplest case is to use react-scripts.

# We need react-scripts to build and run React components
npm i -S react react-dom react-scripts
# We need Cypress test runner and
# React framework adaptor
npm i -D cypress cypress-react-unit-test

Button component

Let's test the Button component in the src folder. Let's write the spec first, and we can code the Button component directly inside the spec file before factoring it out into its own file.

testing-react-example/
  cypress/
    fixtures/
    integration/
    plugins/
    support/
  src/
    Button.spec.js
  package.json
  cypress.json

The cypress.json file has all Cypress settings. In our case we want to enable the experimental component testing feature.

{
  "experimentalComponentTesting": true,
  "componentFolder": "src",
  "specFiles": "*spec.*"
}

The src/Button.spec.js looks like this:

/// <reference types="cypress" />
import React from 'react'
import { mount } from 'cypress-react-unit-test'

function Button(props) {
  return <button>Nothing to do for now</button>;
}

describe("Button component", () => {
  it("Matches the snapshot", () => {
    mount(<Button />);
  });
});

We run this test in interactive mode with command

npx cypress open

and clicking Button.spec.js filename.

The test passes - and at first it does not look like much.

Look closer - this is real browser (Electron, Chrome, Edge or Firefox) running the Button component as a mini web application. You can open DevTools and inspect the DOM just like you would with a real web application - because it is real.

Button with state

Now that we have the component and a corresponding component test, let's make the component a little more interesting.

import React from "react";
import { mount } from "cypress-react-unit-test";

class Button extends React.Component {
  constructor(props) {
    super(props);
    this.state = { text: "" };
    this.handleClick = this.handleClick.bind(this);
  }

  handleClick() {
    this.setState(() => {
      return { text: "PROCEED TO CHECKOUT" };
    });
  }

  render() {
    return (
      <button onClick={this.handleClick}>
        {this.state.text || this.props.text}
      </button>
    );
  }
}

describe("Button component", () => {
  it("it shows the expected text when clicked (testing the wrong way!)", () => {
    mount(<Button text="SUBSCRIBE TO BASIC" />);
    cy.get('@Button')
  });
});

Hmm, how do we check the state value of the component? We don't! The state is an internal implementation detail of the component. Instead we want to test the component using events from the user, like Click.

describe("Button component", () => {
  it("it shows the expected text when clicked", () => {
    mount(<Button text="SUBSCRIBE TO BASIC" />);
    cy.contains('SUBSCRIBE TO BASIC')
      .click()
      .should('have.text', 'PROCEED TO CHECKOUT')
  });
});

The test does change - we can see it in the browser, and we can see the DOM change by hovering over CLICK command.

The time-traveling debugger built-into Cypress makes going back and inspecting what the component does in response to the user events very simple.

Change implementation

Testing against the interface and not the implementation allows us to completely rewrite the component, and still use the same test. Let's change our Button component to use React Hooks. Notice the test remains the same:

import React, { useState } from "react";
import { mount } from "cypress-react-unit-test";

function Button(props) {
  const [text, setText] = useState("");
  function handleClick() {
    setText("PROCEED TO CHECKOUT");
  }
  return <button onClick={handleClick}>{text || props.text}</button>;
}

describe("Button component", () => {
  it("it shows the expected text when clicked", () => {
    mount(<Button text="SUBSCRIBE TO BASIC" />);
    cy.contains('SUBSCRIBE TO BASIC')
      .click()
      .should('have.text', 'PROCEED TO CHECKOUT')
  });
});

Mocking methods

Let's continue. Imagine the component is fetching a list of users. The component is running in the same environment as the spec, sharing the window object and thus it can stub its method fetch.

import React, { Component } from "react";
import {mount} from 'cypress-react-unit-test'

export default class Users extends Component {
  constructor(props) {
    super(props);
    this.state = { data: [] };
  }

  componentDidMount() {
    fetch("https://jsonplaceholder.typicode.com/users")
      .then(response => {
        // make sure to check for errors
        return response.json();
      })
      .then(json => {
        this.setState(() => {
          return { data: json };
        });
      });
  }
  render() {
    return (
      <ul>
        {this.state.data.map(user => (
          <li key={user.name}>{user.name}</li>
        ))}
      </ul>
    );
  }
}

describe("User component", () => {
  it("it shows a list of users", () => {
    const fakeResponse = [{ name: "John Doe" }, { name: "Kevin Mitnick" }];

    cy.stub(window, 'fetch').resolves({
      json: () => Promise.resolve(fakeResponse)
    })

    mount(<Users />)
    cy.get('li').should('have.length', 2)
    cy.contains('li', 'John Doe')
    cy.contains('li', 'Kevin Mitnick')
  });
});

The test passes and you can see the individual elements

Notice we did not have to tell the test to wait for the users to be fetched. Our test simply said "mount the component, there should be 2 list items"

mount(<Users />)
cy.get('li').should('have.length', 2)

In the Cypress test, every command is asynchronous, and almost every command will retry until attached assertions pass. Thus you don't need to worry about synchronous or asynchronous differences, fast or slow responses, etc.

Give cypress-react-unit-test a try. Besides this example bahmutov/testing-react-example, there are lots of examples and my vision for component testing is described in this blog post.

Unit testing Vuex data store using Cypress.io Test Runner

Gleb Bahmutov — Sun, 22 Dec 2019 18:13:18 +0000

Cypress Test Runner has become a very popular tool for writing end-to-end tests, but did you know it can also run unit tests in a real browser? This post shows how to unit test your typical front end code, like the Vuex data store. The post largely follows the example from official Vuex testing page, and you can find all source code in the bahmutov/test-vuex-with-cypress repo.

Setup

For our example, all we need are Vue and Vuex libraries and Cypress. Install them using NPM commands

npm install --save vue vuex
npm install --save-dev cypress

or Yarn commands

yarn add vue vuex
yarn add -D cypress

Cypress includes Mocha test runner, Electron browser, Chai assertions, and many other tools - we should be good to go without installing anything else.

Testing mutations

The first example I would like to test is a counter that starts at zero and increments the state via a mutation. Here is source file src/counter.js

import Vue from 'vue'
import Vuex from 'vuex'

Vue.use(Vuex)

const state = {
  count: 0,
}
export const mutations = {
  increment(state) {
    state.count++
  },
}

export default new Vuex.Store({
  state,
  mutations,
})

My spec (test) file will reside in cypress/integration/counter-spec.js and uses the familiar BDD syntax.

import { mutations } from '../../src/counter'

describe('mutations', () => {
  context('increment', () => {
    const { increment } = mutations
    it('INCREMENT', () => {
      const state = { count: 0 }
      increment(state)
      // see https://on.cypress.io/assertions
      // for "expect" examples
      expect(state.count).to.equal(1)
    })
  })
})

The source files are structured like this:

test-vuex-with-cypress/
  package.json
  src/
    counter.js
  cypress/
    integration/
      counter-spec.js
  cypress.json

Open Cypress with npx cypress open or yarn cypress open command and click on counter-spec.js.

The test should pass.

Cypress watches all loaded files - and it automatically reruns the tests when a file changes. In the screen recording below I have my text editor on the left and Cypress on the right. As I keep coding and saving, I am watching the tests pass and fail - a true test-driven development experience.

The iframe on the right stays empty - because our test does not visit a website. But we can take the full advantage of the Command Log column on the left side of the Test Runner. Currently, it is showing a single passing assertion. Let's change our assertions slightly - I will use cy.wrap command to wrap the state object and yield it to the increment function, and then check the value of the property count using should(...) BDD assertion.

import { mutations } from '../../src/counter'

describe('mutations', () => {
  context('increment', () => {
    const { increment } = mutations
    it('increments the state', () => {
      // wrapped state object will be passed
      // to the "increment" callback
      // which will return new object
      cy.wrap({ count: 0 })
        .then(increment)
        // and the next assertion will run against
        // the updated state
        .should('have.property', 'count', 1)
    })
  })
})

The test passes - and because Cypress "knows" about the wrapped value, it can show it in the Command Log.

Nice. The assertions expect(...).to.equal and wrap(...).should('equal') are equivalent, and everything depends on what you find more readable and useful in the GUI.

If our mutation expects a payload after the state argument like

export const mutations = {
  increment(state, n = 1) {
    state.count += n
  },
}

We can pass it explicitly

it('increments by 5', () => {
  cy.wrap({ count: 0 })
    .then(state => increment(state, 5))
    .should('deep.equal', { count: 5 })
})

Testing store

Let's try testing the entire store.

import store from '../../src/counter'
describe('store commits', () => {
  it('starts with zero', () => {
    // it is a good idea to add assertion message
    // as the second argument to "expect(value, ...)"
    expect(store.state.count, 'initial value').to.equal(0)
    store.commit('increment', 4)
    expect(store.state.count, 'changed value').to.equal(4)
  })
})

As we write more test we quickly discover one potential landmine - the imported store object is a singleton!

describe('store commits', () => {
  it('starts with zero', () => {
    // it is a good idea to add assertion message
    // as the second argument to "expect(value, ...)"
    expect(store.state.count, 'initial value').to.equal(0)
    store.commit('increment', 4)
    expect(store.state.count, 'changed value').to.equal(4)
  })

  it('starts with zero again', () => {
    expect(store.state.count, 'initial value').to.equal(0)
  })
})

At Cypress we strongly believe that every test should be independent of any other test; that each test should set its own initial data. To avoid singletons we can change our Counter code to return a factory function instead of the store object. Every call to the factory function should return a brand new store, with its own separate state object.

// src/counter.js
import Vue from 'vue'
import Vuex from 'vuex'

Vue.use(Vuex)

export const mutations = {
  increment(state, n = 1) {
    state.count += n
  },
}

const counterStoreFactory = () => {
  const state = {
    count: 0,
  }
  return new Vuex.Store({
    state,
    mutations,
  })
}
export default counterStoreFactory

Before each test, we create the store object in a local closure

import storeFactory from '../../src/counter'
describe('store commits', () => {
  let store

  beforeEach(() => {
    store = storeFactory()
  })

  it('starts with zero', () => {
    // it is a good idea to add assertion message
    // as the second argument to "expect(value, ...)"
    expect(store.state.count, 'initial value').to.equal(0)
    store.commit('increment', 4)
    expect(store.state.count, 'changed value').to.equal(4)
  })

  it('starts with zero again', () => {
    expect(store.state.count, 'initial value').to.equal(0)
  })
})

Now the tests pass, no matter in what order they run, if any tests are skipped with it.skip, or if an individual test is enabled exclusively using it.only modifier.

Time-traveling debugger

When Cypress runs the commands and assertions it links the objects it operates on to each command. For example, let's assert the entire state object in the next test.

it('compares entire state object', () => {
  expect(store.state).to.deep.equal({
    count: 0,
  })
  // equivalent assertion
  cy.wrap(store)
    .its('state')
    .should('deep.equal', {
      count: 0,
    })
})

When the test passes, we can click on the wrap or its commands shown in the Command Log on the left. Then if the DevTools console is open, the Test Runner prints the arguments as a real object that you can inspect further.

One has to be cautious when inspecting objects though - the reference points at the real object that can change later. For example, the next test checks the initial count value, then calls the increment commit mutation, and then the test checks the updated state.

it('saves objects like checkpoints', () => {
  cy.wrap(store)
    .its('state')
    .should('deep.equal', {
      count: 0,
    })
  cy.wrap(store).invoke('commit', 'increment', 10)
  cy.wrap(store)
    .its('state')
    .should('deep.equal', {
      count: 10,
    })
})

The test passes, but when we inspect the first state value, the object shows "count: 10".

We know the count was zero because the first assertion has passed, but when we inspect the value we see the current value. This is similar to the way console.log(object) shows the latest value in the DevTools console as the next gif demonstrates.

The trick I like to do to avoid any confusion is to make a clone of the state object before comparing it.

it('saves objects like checkpoints', () => {
  cy.wrap(store)
    .its('state')
    .then(Cypress._.cloneDeep)
    .should('deep.equal', {
      count: 0,
    })
  cy.wrap(store).invoke('commit', 'increment', 10)
  cy.wrap(store)
    .its('state')
    .then(Cypress._.cloneDeep)
    .should('deep.equal', {
      count: 10,
    })
})

Cypress includes Lodash library which lets us call _.cloneDeep function. This has the additional benefit of showing plain objects because we no longer deal with Vue's reactive getters and setters.

To see the full state object clone, click on the assertion message in the Command Log. The full value as it was during that instant of the test will be dumped to the DevTools console.

Asynchronous actions

Vuex store allows performing asynchronous updates via actions mechanism. Let's add an action to increment the count after one second delay.

// same mutations as before

const actions = {
  incrementAsync({ commit }, n = 1) {
    setTimeout(() => {
      commit('increment', n)
    }, 1000)
  },
}

const counterStoreFactory = () => {
  const state = {
    count: 0,
  }

  return new Vuex.Store({
    state,
    mutations,
    actions,
  })
}
export default counterStoreFactory

We cannot test the count update synchronously. The following test fails:

it('can be async (fails)', () => {
  store.dispatch('incrementAsync', 2)
  // the next assertion will fail immediately
  expect(store.state.count).to.equal(2)
})

Typically, to test something like this, the test runner would need to be aware of the framework's details to know when the state commit has happened. But Cypress has a better framework-independent way of dealing with asynchronous operations. It has a built-in retry-ability. In essence, an idempotent command will be retried until the assertions that immediately follow it pass or the command times out. Let's rewrite the test to retry.

it('can be async (passes)', () => {
  store.dispatch('incrementAsync', 2)
  cy.wrap(store.state)  // command
    .its('count')       // command
    .should('equal', 2) // assertion
})

The command its('count') is followed by assertion should('equal', 2). Initially, the count is zero, and the assertion fails. Cypress then runs its('count') again, passing the value to the assertion. It does this repeatedly until the action incrementAsync finishes and commits updated count. The command its('count') yields 2, the assertion should('equal', 2) passes and the test completes.

Tip: you can write pretty complex asynchronous tests by waiting for your own predicates using cypress-wait-until plugin.

Spying and stubbing

During testing we might want to assert that the store's methods were called (by spying on them) or even change their behavior (using stubs).

Cypress Test Runner comes with Sinon.js library bundled, let's use it. Because Vuex is implemented as a series of namespaced modules, we cannot spy on the method store.commit, instead, we need to spy on the store._modules.root.context object that has the actual commit method.

it('calls commit "increment" in the store', () => {
  cy.spy(store._modules.root.context, 'commit').as('commit')
  store.dispatch('incrementAsync', 2)
  cy.wrap(store.state)
    .its('count')
    .should('equal', 2)
  // we can also assert directly on the spies
  // thanks for Sinon-Chai bundled with Cypress
  // https://on.cypress.io/assertions#Sinon-Chai
  cy.get('@commit').should('have.been.calledOnce')
})

The test passes, and the "Spies / Stubs" table shows our spy under alias "commit" and when it was called during the test.

Sinon spies in Cypress play nicely with retry-ability. We don't have to rely on the state assertion to "wait" until the assertion passes.

it('spy retries assertion', () => {
  cy.spy(store._modules.root.context, 'commit').as('commit')
  store.dispatch('incrementAsync', 2)  
  store.dispatch('incrementAsync', 5)
  cy.get('@commit').should('have.been.calledTwice')
})

We can make the spy more precise, for example by only spying on calls made with specific arguments.

it('spies on specific call', () => {
  cy.spy(store._modules.root.context, 'commit')
    .withArgs('increment', 5)
    .as('commit5')
  store.dispatch('incrementAsync', 2)
  store.dispatch('incrementAsync', 5)
  cy.get('@commit5').should('have.been.calledOnce')
})

Every call to the spy is recorded, and you can click on its record to see more details in the DevTools console.

Spying is a nice way to confirm the store receives the expected calls. Let's add method stubbing where we can change the behavior of actions and mutations. In the test below we will allow all mutations to go through unchanged, but whenever there is mutation to increment count by 5, we will change the call and will increment by 100 instead.

it('stubs increment commit', () => {
  // allow all mutations to go through
  // but ("increment", 5) will call our fake function
  cy.stub(store._modules.root.context, 'commit')
    .callThrough()
    .withArgs('increment', 5)
    .callsFake((name, n) => {
      // confirm we are only stubbing increments by 5
      expect(n).to.equal(5)
      // call the original method, but pass a different value
      store._modules.root.context.commit.wrappedMethod(name, 100)
    })

  store.dispatch('incrementAsync', 2)
  store.dispatch('incrementAsync', 5)

  // our stub will turn increment by 5 to increment by 100 😃
  cy.wrap(store.state)
    .its('count')
    .should('equal', 102)
})

To explore spying further, read the Cypress Spies, Stubs And Clocks guide.

Tip: you can simplify accessing commit context and created spy using test context object and local variables.

beforeEach(function() {
  store = storeFactory()
  // save Vuex context in the test's own object
  this.context = store._modules.root.context
})
it('grabs context', function() {
  // save created spy in local variable
  const commit = cy.spy(this.context, 'commit')
  store.dispatch('incrementAsync', 2)
  // use Cypress retry-ability to wait for
  // the spy to be called once
  cy.wrap(commit).should('have.been.calledOnce')
})

Alternatively, give the spy an alias to access it - it will give more context to the Command Log.

it('uses alias', function() {
  // save created spy as an alias
  cy.spy(this.context, 'commit').as('commit')
  store.dispatch('incrementAsync', 2)
  // use Cypress retry-ability to wait for
  // the spy to be called once
  cy.get('@commit').should('have.been.calledOnce')
})

Tip: Cypress automatically removes all spies and stubs before each test, so you don't have to clean them up.

Code coverage

Let's make sure we are covering our code with unit tests. I will use Cypress code coverage plugin and istanbul to instrument unit tests as described in Cypress code coverage guide. Install the plugin and instrumentation peer dependencies:

npm install --save-dev @cypress/code-coverage \
  nyc istanbul-lib-coverage babel-plugin-istanbul
+ istanbul-lib-coverage@2.0.5
+ nyc@14.1.1
+ @cypress/code-coverage@1.10.4
+ babel-plugin-istanbul@5.2.0

Then add the following line to cypress/support/index.js file

import '@cypress/code-coverage/support'

and the following lines to cypress/plugins/index.js file

module.exports = (on, config) => {
  on('task', require('@cypress/code-coverage/task'))
  on(
    'file:preprocessor',
    require('@cypress/code-coverage/use-browserify-istanbul'),
  )
}

Run unit tests again - the code coverage will be automatically merged and saved in several formats in the folder coverage

coverage/
  clover.xml 
  coverage-final.json
  lcov-report/
    index.html
  lcof.info

3rd party coverage services accept lcov.info and clover.xml, while for me the static page report in lcov-report/index.html is the most useful - it is a guide showing which parts of the code were hit by the tests. The counter tests were very thorough - they have covered all statements in the code, except the default parameter value (marked in yellow).

open coverage/lcov-report/index.html

Add one more unit test - and get the complete code coverage!

it('increments async by default value', () => {
  store.dispatch('incrementAsync')
  cy.wrap(store.state)
    .its('count')
    .should('equal', 1)
})

Bonus: run tests using GitHub Action

Testing locally is important, but testing every commit pushed to the repository is even more valuable. Recently, GitHub Actions became generally available. I looked into GH Actions in the blog post Trying GitHub Actions and came very impressed. To make using Cypress from a GH Action simpler, we have published our official custom action called cypress-io/github-action. Here is how to set up testing on each code push:

First, create file .github/workflows/main.yml and paste the following example from cypress-io/github-action README.

name: tests
on: [push]
jobs:
  cypress-run:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v1
      # Install NPM dependencies, cache them correctly
      # and run all Cypress tests
      - name: Cypress run
        uses: cypress-io/github-action@v1

Second, push a commit to the repository.

Third - there is no third step! The tests will be running already, you can see them at bahmutov/test-vuex-with-cypress/actions. NPM installation, caching, running Cypress command - it is all done by the custom action cypress-io/github-action@v1 and the default values should handle our unit tests without any additional parameters.

I have also added a badge to the README to know the status of the master branch. Here is the Markdown syntax:

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg?branch=<BRANCH>

![test status](https://github.com/bahmutov/test-vuex-with-cypress/workflows/tests/badge.svg?branch=master)

Conclusions

I am part of the Cypress team, so I am partial (pun intended) to this Test Runner. I like the GUI, the file watching, the time-traveling debugger, the built-in assertions and function spies and stubs. I think running front-end unit tests inside a real browser is the preferred way, and the ability to use DevTools to inspect everything the tests do gives one superpower. Take Cypress for a spin - it is not just an end-to-end test runner!

Find the full source code for this blog post at bahmutov/test-vuex-with-cypress repo. If you want to see more unit testing with Cypress examples, check out our unit testing recipes.