Cypress is an automatic take a look at runner for browser-based functions and pages. I’ve used it for years to jot down end-to-end exams for net initiatives, and was comfortable to see not too long ago that particular person element testing had come to Cypress. I work on a big enterprise Vue software, and we already use Cypress for end-to-end exams. Most of our unit and element exams are written with Jest and Vue Take a look at Utils.

As soon as element testing arrived in Cypress, my crew was all in favor of upgrading and making an attempt it out. You’ll be able to study lots about how element testing works straight from the Cypress docs, so I’m going skip over a few of the setup steps and deal with what it’s wish to work with element exams — what do they appear to be, how are we utilizing them, and a few Vue-specific gotchas and helpers we discovered.

Disclosure! On the time I wrote the primary draft of this text, I used to be the front-end crew lead at a big fleet administration firm the place we used Cypress for testing. Because the time of writing, I’ve began working at Cypress, the place I get to contribute to the open supply take a look at runner.

The Cypress component test runner is open, using Chrome to test a “Privacy Policy” component. Three columns are visible in the browser. The first contains a searchable list of component test spec files; the second shows the tests for the currently-spec; the last shows the component itself mounted in the browser. The middle column shows that two tests are passing.

All of the examples talked about listed here are legitimate on the time of writing utilizing Cypress 8. It’s a brand new function that’s nonetheless in alpha, and I wouldn’t be shocked if a few of these particulars change in future updates.

If you have already got a background in testing and element exams, you possibly can skip proper to our crew’s experiences.

What a element take a look at file seems like

For a simplified instance, I’ve created a undertaking that accommodates a “Privateness Coverage” element. It has a title, physique, and an acknowledgment button.

The Privacy Policy component has three areas. The title reads “Privacy Policy”; the body text reads “Information about privacy that you should read in detail,” and a blue button at the bottom reads “OK, I read it, sheesh.”

When the button is clicked, an occasion is emitted to let the guardian element know that this has been acknowledged. Right here it’s deployed on Netlify.

Now right here’s the final form of a element take a look at in Cypress that makes use of a few of the function’s we’re going to speak about:

import { mount } from '@cypress/vue'; // import the vue-test-utils mount perform
import PrivacyPolicyNotice from './PrivacyPolicyNotice.vue'; // import the element to check

describe('PrivacyPolicyNotice', () => {
 it('renders the title', () => {
    // mount the element by itself within the browser 🏗
    // assert some textual content is current within the right heading stage 🕵️ 
    cy.accommodates('h1', 'Privateness Coverage').ought to('be.seen'); 

  it('emits a "verify" occasion as soon as when verify button is clicked', () => {
    // mount the element by itself within the browser 🏗

    // this time let's chain some instructions collectively
    cy.accommodates('button', '/^OK/') // discover a button aspect beginning with textual content 'OK' 🕵️
    .click on() // click on the button 🤞
    .vue() // use a customized command to go get the vue-test-utils wrapper 🧐
    .then((wrapper) => {
      // confirm the element emitted a verify occasion after the clicking 🤯
      // `emitted` is a helper from vue-test-utils to simplify accessing
      // occasions which were emitted


This take a look at makes some assertions concerning the consumer interface, and a few concerning the developer interface (shoutout to Alex Reviere for expressing this division in the best way that clicked for me). For the UI, we’re focusing on particular parts with their anticipated textual content content material. For builders, we’re testing what occasions are emitted. We’re additionally implicitly testing that the element is a accurately shaped Vue element; in any other case it might not mount efficiently and all the opposite steps would fail. And by asserting particular sorts of parts for particular functions, we’re testing the accessibility of the element — if that accessible button ever turns into a non-focusable div, we’ll learn about it.

Right here’s how our take a look at seems after I swap out the button for a div. This helps us keep the anticipated keyboard habits and assistive know-how hints that come without spending a dime with a button aspect by letting us know if we by chance swap it out:

The Cypress component test runner shows that one test is passing and one is failing. The failure warning is titled 'Assertion Error' and reads 'Timed out retrying after 4000ms: Expected to find content: '/^OK/' within the selector: 'button' but never did.'

Just a little groundwork

Now that we’ve seen what a element take a look at seems like, let’s again up a bit of bit and speak about how this suits in to our general testing technique. There are lots of definitions for this stuff, so actual fast, for me, in our codebase:

  • Unit exams verify single features behave as anticipated when utilized by a developer.
  • Element exams mount single UI elements in isolation and make sure they behave as anticipated when utilized by an end-user and a developer.
  • Finish-to-end exams go to the applying and carry out actions and make sure the app as complete behaves accurately when utilized by an end-user solely.

Lastly, integration testing is a bit more of a squishy time period for me and might occur at any stage — a unit that imports different features, a element that imports different elements, or certainly, an “end-to-end” take a look at that mocks API responses and doesn’t attain the database, may all be thought-about integration exams. They take a look at a couple of a part of an software working collectively, however not your complete factor. I’m undecided about the true usefulness of that as a class, because it appears very broad, however completely different individuals and organizations use these phrases in different methods, so I needed to the touch on it.

For an extended overview of the completely different sorts of testing and the way they relate to front-end work, you possibly can try “Entrance-Finish Testing is For Everybody” by Evgeny Klimenchenko.

Element exams

Within the definitions above, the completely different testing layers are outlined by who will probably be utilizing a bit of code and what the contract is with that particular person. In order a developer, a perform that codecs the time ought to all the time return the proper end result after I present it a sound Date object, and may throw clear errors if I present it one thing completely different as effectively. These are issues we are able to take a look at by calling the perform by itself and verifying it responds accurately to varied situations, unbiased of any UI. The “developer interface” (or API) of a perform is all about code speaking to different code.

Now, let’s zoom in on element exams. The “contract” of a element is de facto two contracts:

  • To the developer utilizing a element, the element is behaving accurately if the anticipated occasions are emitted based mostly on consumer enter or different exercise. It’s additionally truthful to incorporate issues like prop sorts and validation guidelines in our thought of “right developer-facing habits,” although these issues can be examined at a unit stage. What I actually need from a element take a look at as a developer is to understand it mounts, and sends the indicators it’s speculated to based mostly on interactions.
  • To the consumer interacting with a element, it’s behaving accurately if the UI displays the state of the element always. This contains extra than simply the visible facet. The HTML generated by the element is the inspiration for its accessibility tree, and the accessibility tree supplies the API for instruments like display screen readers to announce the content material accurately, so for me the element isn’t “behaving accurately” if it doesn’t render the proper HTML for the contents.

At this level it’s clear that element testing requires two sorts of assertions — generally we test Vue-specific issues, like “what number of occasions acquired emitted of a sure kind?”, and generally we test user-facing issues, like “did a visual success message really find yourself on the display screen although?”

It additionally seems like element stage exams are a robust documentation device. The exams ought to assert all of the important options of a element — the outlined behaviors which might be trusted — and ignore particulars that aren’t important. This implies we are able to look to the exams to know (or keep in mind, six months or a yr from now!) what a element’s anticipated habits is. And, all going effectively, we are able to change any function that’s not explicitly asserted by the take a look at with out having to rewrite the take a look at. Design adjustments, animation adjustments, enhancing the DOM, all must be doable, and if a take a look at does fail, it is going to be for a purpose you care about, not as a result of a component acquired moved from one a part of the display screen to a different.

This final half takes some care when designing exams, and most particularly, when selecting selectors for parts to work together with, so we’ll return to this subject later.

How Vue element exams work with and with out Cypress

At a excessive stage, a mix of Jest and the Vue Take a look at Utils library has turns into kind of the usual method to operating element exams that I’ve seen on the market.

Vue Take a look at Utils offers us helpers to mount a element, give it its choices, and mock out numerous issues a element may rely upon to run correctly. It additionally supplies a wrapper object across the mounted element to make it a bit of simpler to make assertions about what’s occurring with the element.

Jest is a superb take a look at runner and can rise up the mounted element utilizing jsdom to simulate a browser setting.

Cypress’ element take a look at runner itself makes use of Vue Take a look at Utils to mount Vue elements, so the principle distinction between the 2 approaches is context. Cypress already runs end-to-end exams in a browser, and element exams work the identical method. This implies we are able to see our exams run, pause them mid-test, work together with the app or examine issues that occurred earlier within the run, and know that browser APIs that our software will depend on are real browser habits slightly than the jsdom mocked variations of those self same options.

As soon as the element is mounted, all the same old Cypress issues that we have now been doing in end-to-end exams apply, and some ache factors round deciding on parts go away. Primarily, Cypress goes to deal with simulating all of the consumer interactions, and making assertions concerning the software’s response to these interactions. This covers the user-facing a part of the element’s contract utterly, however what concerning the developer-facing stuff, like occasions, props, and all the things else? That is the place Vue Take a look at Utils comes again in. Inside Cypress, we are able to entry the wrapper that Vue Take a look at Utils creates across the mounted element, and make assertions about it.

What I like about that is that we find yourself with Cypress and Vue Take a look at Utils each getting used for what they’re actually good at. We will take a look at the element’s habits as a consumer with no framework-specific code in any respect, and solely dig into Vue Take a look at Utils for mounting the element and checking particular framework habits once we select to. We’ll by no means must await a Vue-specific $nextTick after performing some Vue-specific factor to replace the state of a element. That was all the time the trickiest factor to clarify to new builders on the crew with out Vue expertise — when and why they would wish to await issues when writing a take a look at for a Vue element.

Our expertise of element testing

Some great benefits of element testing sounded nice to us, however in fact, in a big undertaking only a few issues might be seamless out of the field, and as we acquired began with our exams, we bumped into some points. We run a big enterprise SPA constructed utilizing Vue 2 and the Vuetify element library. Most of our work closely makes use of Vuetify’s built-in elements and kinds. So, whereas the “take a look at elements by themselves” method sounds good, a giant lesson discovered was that we would have liked to arrange some context for our elements to be mounted in, and we would have liked to get Vuetify and a few world kinds taking place as effectively, or nothing was going to work.

Cypress has a Discord the place individuals can ask for assist, and after I acquired caught I requested questions there. Of us from the neighborhood —in addition to Cypress crew members — kindly directed me to instance repos, code snippets, and concepts for fixing our issues. Right here’s an inventory of the little issues we would have liked to know with a purpose to get our elements to mount accurately, errors we encountered, and no matter else stands out as fascinating or useful:

Importing Vuetify

By way of lurking within the Cypress Discord, I’d seen this instance element take a look at Vuetify repo by Bart Ledoux, in order that was my start line. That repo organizes the code into a reasonably widespread sample that features a plugins folder, the place a plugin exports an occasion of Veutify. That is imported by the applying itself, but it surely can be imported by our take a look at setup, and used when mounting the element being examined. Within the repo a command is added to Cypress that may exchange the default mount perform with one which mounts a element with Vuetify.

Right here is all of the code wanted to make that occur, assuming we did all the things in instructions.js and didn’t import something from the plugins folder. We’re doing this with a customized command which implies that as a substitute of calling the Vue Take a look at Utils mount perform straight in our exams, we’ll really name our personal cy.mount command:

// the Cypress mount perform, which wraps the vue-test-utils mount perform
import { mount } from "@cypress/vue"; 
import Vue from 'vue';
import Vuetify from 'vuetify/lib/framework';


// add a brand new command with the title "mount" to run the Vue Take a look at Utils 
// mount and add Vuetify
Cypress.Instructions.add("mount", (MountedComponent, choices) => {
  return mount(MountedComponent, {
    vuetify: new Vuetify({});, // the brand new Vuetify occasion
    ...choices, // To override/add Vue choices for particular exams

Now we’ll all the time have Vuetify together with our elements when mounted, and we are able to nonetheless move in all the opposite choices we have to for that element itself. However we don’t must manually add Veutify every time.

Including attributes required by Vuetify

The one downside with the brand new mount command above is that, to work accurately, Vuetify elements anticipate to be rendered in a sure DOM context. Apps utilizing Vuetify wrap all the things in a <v-app> element that represents the basis aspect of the applying. There are a few methods to deal with this however the easiest is so as to add some setup to our command itself earlier than it mounts a element.

Cypress.Instructions.add("mount", (MountedComponent, choices) => {
  // get the aspect that our mounted element will probably be injected into
  const root = doc.getElementById("__cy_root");

  // add the v-application class that enables Vuetify kinds to work
  if (!root.classList.accommodates("v-application")) {

  // add the data-attribute — Vuetify selector used for popup parts to connect to the DOM
  root.setAttribute('data-app', 'true');  

return mount(MountedComponent, {
    vuetify: new Vuetify({}), 

This takes benefit of the truth that Cypress itself has to create some root aspect to truly mount our element to. That root aspect is the guardian of our element, and it has the ID __cy_root. This offers us a spot to simply add the proper courses and attributes that Vuetify expects to search out. Now elements that use Vuetify elements will look and behave accurately.

One different factor we observed after some testing is that the required class of v-application has a show property of flex. This is smart in a full app context utilizing Vuetify’s container system, however had some undesirable visible uncomfortable side effects for us when mounting single elements — so we added yet another line to override that model earlier than mounting the element:

root.setAttribute('model', 'show: block');

This cleared up the occasional format points after which we have been really achieved tweaking the encircling context for mounting elements.

Getting spec information the place we wish them

A number of the examples on the market present a cypress.json config file like this one for element testing:

  "fixturesFolder": false,
  "componentFolder": "src/elements",
  "testFiles": "**/*.spec.js"

That’s really fairly near what we wish for the reason that testFiles property accepts a glob sample. This one says, Look in any folder for information ending in .spec.js. In our case, and doubtless many others, the undertaking’s node_modules folder contained some irrelevant spec.js information that we excluded by prefixing !(node_modules) like this:

"testFiles": "!(node_modules)**/*.spec.js"

Earlier than deciding on this resolution, when experimenting, we had set this to a selected folder the place element exams would reside, not a glob sample that might match them wherever. Our exams reside proper alongside our elements, so that might have been advantageous, however we even have two unbiased elements folders as we package deal up and publish a small a part of our app for use in different initiatives on the firm. Having made that change early, I admit I certain did overlook it had been a glob to start out with and was beginning to get off target earlier than popping into the Discord, the place I acquired a reminder and figured it out. Having a spot to rapidly test if one thing is the fitting method was useful many instances.

Command file battle

Following the sample outlined above to get Vuetify working with our element exams produced an issue. We had piled all these things collectively in the identical instructions.js file that we used for normal end-to-end exams. So whereas we acquired a few element exams operating, our end-to-end exams didn’t even begin. There was an early error from one of many imports that was solely wanted for element testing.

I used to be beneficial a few options however on the day, I selected to simply extract the mounting command and its dependencies into its personal file, and imported it solely the place wanted within the element exams themselves. Since this was the one supply of any downside operating each units of exams, it was a clear method to take that out of the the end-to-end context, and it really works simply advantageous as a standalone perform. If we have now different points, or subsequent time we’re doing cleanup, we’d most likely observe the principle suggestion given, to have two separate command information and share the widespread items between them.

Accessing the Vue Take a look at Utils wrapper

Within the context of a element take a look at, the Vue Take a look at Utils wrapper is obtainable underneath Cypress.vueWrapper. When accessing this to make assertions, it helps to make use of cy.wrap to make the end result chain-able like different instructions accessed by way of cy. Jessica Sachs provides a brief command in her instance repo to do that. So, as soon as once more inside instructions,js, I added the next:

Cypress.Instructions.add('vue', () => {
  return cy.wrap(Cypress.vueWrapper);

This can be utilized in a take a look at, like this:

  .accommodates('button', 'Do the factor as soon as')
  .click on()
  .ought to('be.disabled')
  .then((wrapper) => {
    // the Vue Take a look at Utils `wrapper` has an API particularly setup for testing: 

This begins to learn very naturally to me and clearly splits up once we are working with the UI in comparison with once we are inspecting particulars revealed by way of the Vue Take a look at Utils wrapper. It additionally emphasizes that, like numerous Cypress, to get essentially the most out of it, it’s essential to know the instruments it leverages, not simply Cypress itself. Cypress wraps Mocha, Chai, and numerous different libraries. On this case, it’s helpful to know that Vue Take a look at Utils is a third-party open supply resolution with its personal complete set of documentation, and that contained in the then callback above, we’re in Vue Take a look at Utils Land — not Cypress Land — in order that we go to the fitting place for assist and documentation.


Since this has been a latest exploration, we have now not added the Cypress element exams to our CI/CD pipelines but. Failures won’t block a pull request, and we haven’t checked out including the reporting for these exams. I don’t anticipate any surprises there, but it surely’s price mentioning that we haven’t accomplished integrating these into our complete workflow. I can’t converse to it particularly.

It’s additionally comparatively early days for the element take a look at runner and there are just a few hiccups. At first, it appeared like each second take a look at run would present a linter error and must be manually refreshed. I didn’t resolve that, after which it fastened itself (or was fastened by a more recent Cypress launch). I’d anticipate a brand new device to have potential points like this.

One different stumbling block about element testing typically is that, relying on how your element works, it may be troublesome to mount it with out plenty of work mocking different components of your system. If the element interacts with a number of Vuex modules or makes use of API calls to fetch its personal knowledge, it’s good to simulate all of that once you mount the element. The place end-to-end exams are virtually absurdly straightforward to rise up and operating on any undertaking that runs within the browser, element exams on present elements are much more delicate to your element design.

That is true of something that mounts elements in isolation, like Storybook and Jest, which we’ve additionally used. It’s usually once you try and mount elements in isolation that you just understand simply what number of dependencies your elements even have, and it could seem to be plenty of effort is required simply to offer the fitting context for mounting them. This nudges us in the direction of higher element design in the long term, with elements which might be simpler to check and whereas touching fewer components of the codebase.

Because of this, I’d counsel in the event you haven’t already acquired element exams, and so aren’t certain what it’s good to mock with a purpose to mount your element, select your first element exams fastidiously, to restrict the variety of components you need to get proper earlier than you possibly can see the element within the take a look at runner. Choose a small, presentational element that renders content material supplied by way of props or slots, to see it a element take a look at in motion earlier than entering into the weeds on dependencies.


The element take a look at runner has labored out effectively for our crew. We have already got intensive end-to-end exams in Cypress, so the crew is conversant in tips on how to spin up new exams and write consumer interactions. And we have now been utilizing Vue Take a look at Utils for particular person element testing as effectively. So there was not really an excessive amount of new to study right here. The preliminary setup points might have been irritating, however there are many pleasant individuals on the market who will help work by way of points, so I’m glad I used the “asking for assist” superpower.

I might say there are two foremost advantages that we’ve discovered. One is the constant method to the take a look at code itself between ranges of testing. This helps as a result of there’s not a psychological shift to consider refined variations between Jest and Cypress interactions, browser DOM vs jsdom and comparable points.

The opposite is having the ability to develop elements in isolation and getting visible suggestions as we go. By organising all of the variations of a element for improvement functions, we get the define of the UI take a look at prepared, and perhaps just a few assertions too. It seems like we get extra worth out of the testing course of up entrance, so it’s much less like a bolted-on process on the finish of a ticket.

This course of isn’t fairly test-driven improvement for us, although we are able to drift into that, but it surely’s usually “demo-driven” in that we need to showcase the states of a brand new piece of UI, and Cypress is a reasonably great way to try this, utilizing cy.pause() to freeze a operating take a look at after particular interactions and discuss concerning the state of the element. Creating with this in thoughts, understanding that we’ll use the exams to stroll by way of the elements options in a demo, helps set up the exams in a significant method and encourages us to cowl all of the eventualities we are able to consider at improvement time, slightly than after.


The psychological mannequin for what precisely Cypress as complete does was difficult for me to after I first discovered about it, as a result of it wraps so many different open supply instruments within the testing ecosystem. You’ll be able to rise up and operating rapidly with Cypress with out having a deep data of what different instruments are being leveraged underneath the hood.

This meant that when issues went incorrect, I keep in mind not being certain which layer I ought to take into consideration — was one thing not working due to a Mocha factor? A Chai challenge? A nasty jQuery selector in my take a look at code? Incorrect use of a Sinon spy? At a sure level, I wanted to step again and study these particular person puzzle items and what precise roles they have been taking part in in my exams.

That is nonetheless the case with element testing, and now there may be an additional layer: framework-specific libraries to mount and take a look at elements. In some methods, that is extra overhead and extra to study. Then again, Cypress integrates these instruments in a coherent method and manages their setup so we are able to keep away from an entire unrelated testing setup only for element exams. For us, we already needed to mount elements independently for testing with Jest, and to be used in Storybook, so we found out plenty of the mandatory mocking concepts forward of time, and tended to favor well-separated elements with easy props/occasions based mostly interfaces for that purpose.

On stability, we like working with the take a look at runner, and I really feel like I’m seeing extra exams (and extra readable take a look at code!) displaying up in pull requests that I evaluation, so to me that’s an indication that we’ve moved in a superb course.

#Testing #Vue #Parts #Cypress

Leave a Reply

Your email address will not be published. Required fields are marked *