Getting Started with Cypress Component Testing (Vue 2/3)

Getting Start with Cypress Component Testing (Vue 2/3)

As of Cypress 7.0, our new Cypress Component Test Runner is bundled with the Cypress Test Runner! It builds on the learnings from the original component testing implementation, which was hidden behind the experimentalComponentTesting flag.

In this blog post we will see how to set up Cypress component testing with a Vue CLI project. It supports both Vue 2 and Vue 3, with TypeScript support out of the box.

You can get the source code for the example used in the blog post here.

Creating a new Vue CLI Project

Create a new Vue CLI project to get started. For this example I chose Vue 2 and TypeScript.

Configuring The Cypress Component Test Runner

Once you've got a Vue project, you'll also need to install Cypress and the Webpack Dev Server and Vue adapters. Vue CLI projects are Webpack based; that's why we are installing the relevant Webpack adapter:

# Vue 2
yarn add cypress @cypress/vue @cypress/webpack-dev-server --dev

# Vue 3
npm install cypress @cypress/vue@next @cypress/webpack-dev-server --dev

Component testing is configured as a Cypress plugin. This means you need to create a plugins file. By default this goes in cypress/plugins/index.js.

Next, we need to register the dev-server:start event and tell Cypress to use the same Webpack configuration as the Vue CLI project uses.

const { startDevServer } = require('@cypress/webpack-dev-server')
const webpackConfig = require('@vue/cli-service/webpack.config.js')

module.exports = (on, config) => {
  on('dev-server:start', options =>
    startDevServer({
      options,
      webpackConfig
    })
  )

  return config
}

Finally, we need to tell Cypress where and how to find our tests. Cypress is heavily configurable via cypress.json. My cypress.json looks as follows:

{
  "component": {
    "componentFolder": "src",
    "testFiles": "**/*.spec.ts"
  }
}

All my comoponent are in src, and the spec files are always named *.spec.ts.

Writing Some Tests

It is finally time to write some tests. I created src/components/HelloWorld.spec.ts to try things out with the following minimal test:

import { mount } from '@cypress/vue'
import HelloWorld from './HelloWorld.vue'

describe('HelloWorld', () => {
  it('renders a message', () => {
    const msg = 'Hello Cypress Component Testing!'
    mount(HelloWorld, {
      propsData: {
        msg
      }
    })

    cy.get('h1').should('have.text', msg)
  })
})

The mount function is very similar to the one from Vue Test Utils. It's actually built on top of Vue Test Utils, so you can use the mounting options you might already be familiar with.

Learn more about how to write assertions with Cypress in the official docs. Get an overview of the cy object and how to use it here.

Finally, open the Component Test Runner:

yarn cypress open-ct # or npx cypress open-ct

Select the spec and watch the test pass!

Try updating the test and making it fail. Cypress will re-run your test (almost) instantly. This makes for a great red-green-refactor loop.

Vue 3 Usage

Everything works the same with Vue 3. Just make sure you have a Vue 3 project and the correct adapter:

yarn add @cypress/vue@next --dev
# or
npm install @cypress/vue@next --dev

The mount function exported by @cypress/vue has the same API for both Vue 2 and Vue 3. The mounting options are the same as Vue Test Utils, so if you've used Vue Test Utils before, you'll feel right at home.

Discussion

The Cypress Component Test Runner is an alternative to a jsdom based testing environment, such as Jest and Vue Test Utils. Cypress component testing offers many benefits:

• Runs in a real browser. This means your tests are closer to what your users will be experiencing.
• Visual. You can see exactly what is rendered. No more console.log(wrapper.html()).
• Powered by Cypress - the most popular and reliable E2E testing tool out there.

It also doubles as a design environment. You can see the component as you develop it, and hot reload gives you a near instant feedback loop.

The Cypress Component Test Runner is still in alpha but is quickly evolving and promises to change the landscape of component testing.

Conclusion

The Cypress Component Test Runner brings everything that is great about Cypress to component testing. Since the underlying adapters are built on libraries like Webpack and Vue Test Utils, you don't need to throw away your entire test suite - incremental migration is more than possible.

Our visual approach unites testing and design in a single tool. The days of grepping a messy console output to figure out what the user will see are over - now you can see exactly what the component will look like as your tests run.

You can get the source code for the example used in the blog post here.