quasar-testing

Cypress

You’re looking at Cypress AE v5 (Cypress 12 & 13) docs. If you’re searching for Cypress AE v4 (Cypress 9) docs, head here

$ yarn quasar ext add @quasar/testing-e2e-cypress

Add into your .eslintrc.js the following code:

{
  // ...
  overrides: [
    {
      files: ['test/cypress/**/*.{js,jsx,ts,tsx}', '**/*.cy.{js,jsx,ts,tsx}'],
      extends: [
        // Add Cypress-specific lint rules, globals and Cypress plugin
        // See https://github.com/cypress-io/eslint-plugin-cypress#rules
        'plugin:cypress/recommended',
      ],
    },
  ],
}

This App Extension (AE) manages Quasar and Cypress integration for you, both for JavaScript and TypeScript.

Some custom commands are included out-of-the-box:

Name Usage Description
dataCy cy.dataCy('my-data-id') Implement the selection best practice which avoids brittle tests, is equivalent to cy.get('[data-cy=my-data-id]')
selectDate cy.get('.q-date').selectDate('2023/02/23') Select a given date into a QDate component, it accept either a Date object or a string which new Date(myDate) can parse correctly
testRoute cy.testRoute('home')
cy.testRoute('books/*/pages/*')		 Test if the current URL matches the provided string using minimatch. Leading #, if using router hash mode, and / are automatically prepended.
within[Portal\|Menu\|SelectMenu\|Dialog] cy.withinSelectMenu(() => cy.get('.q-item').first().click())
cy.withinDialog({ dataCy: 'add-action-dialog', fn() { /* business haha */ } });		 Auto-scope commands into the callback within the Portal-based component and perform assertions common to all of them.
should('have.[color\|backgroundColor]') cy.get('foo').should('have.color', 'white')
cy.get('foo').should('have.backgroundColor', '#000')
cy.get('foo').should('have.color', 'var(--q-primary)')		 Provide a couple color-related custom matchers, which accept any valid CSS color format.

Check out how to use these commands, and other recipes about testing Quasar UI components, into our automated tests suite.

You must have a running dev server in order to run integration tests. The scripts added by this AE automatically take care of this: yarn test:e2e and yarn test:e2e:ci will launch quasar dev when starting up the tests and kill it when cypress process ends.

This AE is a wrapper around Cypress, you won’t be able to use this or understand most of the documentation if you haven’t read the official documentation.

Cypress Component Testing is supported and the AE scaffolds the code to run both “e2e” and “component” tests with Cypress. As for “e2e” tests, you’ll need to first take a look to their official documentation, or you won’t understand many of the concepts described into this documentation. Consequentially, we may rename this package from @quasar/quasar-app-extension-testing-e2e-cypress to @quasar/quasar-app-extension-testing-cypress in a future release.

Code coverage

We support scaffolding code coverage configuration for Cypress tests, when using Vite-based Quasar CLI.

To generate reports, run test:e2e:ci and/or test:component:ci scripts. Running them both sequentially within the same command (eg. yarn test:e2e:ci && yarn test:component:ci) will result in combined coverage report. You’ll find the generated report into coverage/lcov-report folder.

We provide a preset configuration for the coverage report which:

Check out nyc official documentation if you want to customize report generation. You can either add options into .nycrc file or generate reports on the fly running nyc report <options>.

If you want to override the options that are defined by our preset configuration(or any preset), you should be aware of this nyc issue. You can either apply this workaround or embed our preset configuration into your .nycrc file directly, instead of extends.

Note that we do not setup Istanbul TS configuration and its dependencies as Cypress claims it’s able to manage TS code coverage out-of-the-box. Some TS files may be excluded by the report in scenarios, eg. if they aren’t actually imported (dead code), if they’re tree-shaked away by a bundler or if they only contain types/interfaces, and as such have no actual JS representation. Please open an issue if you notice some files are missing from generated reports in this scenario.

Upgrade from Cypress AE v5.1 to v5.2 onwards

If you’re coming from v4, follow the migration guide in the next section first.

Here’s all the steps you need to take while upgrading from v5.1 to v5.2:

Upgrade from Cypress AE v4

if you’re coming from v3, follow the migration guide for v4 and v4.1 first

All changes are related to Cypress v10-v11-v12 breaking changes, Quasar first-party helpers haven’t been changed unless Cypress required it.

Alternatively to the following guide, a faster but more error-prone way for advanced developers would be to run yarn quasar ext add @quasar/testing-e2e-cypress and yarn add -D cypress, then let the package scaffold new files overriding the existing ones and manually merge your changes into the generated files. Even in this case, we suggest to take a look to the following migration guide and use it as a checklist, as some files must be renamed/removed.

Here’s all the steps you need to take while upgrading from v4 to v5:

yarn upgrade @quasar/quasar-app-extension-testing-e2e-cypress
yarn add -D cypress

yarn add -D typescript

import { injectQuasarDevServerConfig } from '@quasar/quasar-app-extension-testing-e2e-cypress/cct-dev-server';

export default defineConfig({
  // ...
  component: {
    devServer: injectQuasarDevServerConfig(),
  },
});

// Since Cypress v10 we cannot import `config` directly from VTU as Cypress bundles its own version of it
// See https://github.com/cypress-io/cypress/issues/22611
import { VueTestUtils } from 'cypress/vue';
const { config } = VueTestUtils;

Caveats

Automatic override of Cypress commands

Many Cypress commands rely on the presence of a native DOM inputs, but many Quasar input components won’t usually render them for better performance, or will use them under the hood, but hide them to the user.

This resulted in a bad DX for some Cypress commands/assertions when used on some Quasar input components, so we patched those Cypress commands/assertions on our side. Here’s the list of patched methods and some limitations due to the override:

Feel free to open a PR if you want to help removing these limitations.

QSelect and data-cy

QSelect automatically apply unknown props to an inner element of the component, including data-cy. This means that you need to use cy.dataCy('select').closest('.q-select') to get the actual root element of the component. While this isn’t important when clicking the select to open its options menu, it is if you’re checking any of its attributes (eg. aria-disabled to see if it’s enabled or not)

You can define an helper to access a QSelect element, here’s an example:

function dataCySelect(dataCyId: string) {
  return cy.dataCy(dataCyId).closest('.q-select');
}

Additionally, when using use-input prop, the data-cy is mirrored on the inner native select too. This can generate confusion as cy.dataCy('select') in those cases will return a collection and you’ll need to use .first() or .last() to get respectively the component wrapper or the native input.

Component Testing Caveats

This AE aims to be as lightweight as possible to reduce maintenance burden. That’s why we currently don’t provide our own helpers to manage VueRouter, Vuex and Pinia.

The good news is that we don’t actually need to, since official documentation for those libraries is already available:

Using boot files

When testing components, your Quasar boot files aren’t loaded. If you need some features defined in your boot files, you can manually add them in your support file.

For instance, to make an axios API client globally available, simply set it in the VueTestUtils config.global.mocks object (like you would do on app.config.globalProperties in your boot file):

import { VueTestUtils } from 'cypress/vue';
import axios from 'axios';

const api = axios.create({ baseURL: 'https://api.example.com' });

VueTestUtils.config.global.mocks.$api = api;

Using vModel into your tests

Vue Test Utils doesn’t provide an helper to test your components vModel, so we created our own, which even allow you use refs into your tests, based on this discussion.

const model = ref(null);
mount(QSelect, {
  props: {
    ...vModelAdapter(model),
    // or, if you're using a custom name for your vModel, use
    // ...vModelAdapter(model, 'myModelName'),
    options,
  },
});

Check out more examples here.

Testing the AE

cd test-project-webpack # or "cd test-project-vite" or "cd test-project-app"
yarn sync:cypress # or "yarn sync:all", if it's the first time you run this command
yarn test:e2e:ci # check if e2e tests still work with the local version of the AE
yarn test:component:ci # check if component tests still work with the local version of the AE
This site is open source. Improve this page.