Custom Cypress integration

This is an experimental feature.

The enableCypressExtension experimental feature flag allows you to leverage Cypress extensions within your FastStore project, enabling you to seamlessly run custom Cypress tests.

Cypress extensions enhance the testing capabilities of your FastStore project by enabling the incorporation of custom Cypress tests alongside the native integration tests provided by FastStore.

With enableCypressExtension, you can implement custom integration tests into a dedicated Cypress folder within your storefront project. This integration ensures the smooth execution of both the native tests and the custom ones you create as part of the continuous integration (CI) pipeline. Learn how to add custom integration tests in the following steps.

Before you begin

Please be aware that this feature is experimental and may not be suitable for all use cases.
Refer to Cypress documentation for more information on this testing tool.
Make sure you're using @faststore/cli version 2.2.9 or above. If you have versions older than the requirement, update them following the instructions in Updating the '@faststore/cli' package version.

Step 1: Enabling `enableCypressExtension`

Open the discovery.config.js file.
Add the experimental object and set the enableCypressExtension value to true:

discovery.config.js


_10  experimental: {
_10      enableCypressExtension: true,
_10  }

Step 2: Integrating custom Cypress tests into your FastStore project

Like any other project using Cypress, you'll follow standard practices, including setting up standard Cypress folders and configuration files. This allows you to seamlessly add and execute your custom integration tests within your project. For further details on Cypress configuration, refer to the official Cypress configuration guide.

In the root directory of your storefront project, create a new folder named cypress.
Add your custom integration tests within the cypress/integration folder.
With the local server running, run yarn test to open the Cypress app and check your test execution.
Open a pull request with the changes you have made.
Within the pull request, navigate to Checks > Integration Tests and check the Details section.

${"base64":" ","img":{"width":2854,"height":1362,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":284060,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/custom-test-checks___583ac9b78e43ebdafde93a735a47d61b.png"}}$

Review the results to check the execution status of your custom integration tests.

Running only custom Cypress tests in FastStore projects

As storefront projects evolve, changes to component and page code may lead to errors in the default end-to-end tests conducted for all FastStore projects.

In such cases, you can override FastStore's default tests using custom tests with the same name as the original test files. For example:

plp.test.js


_10import { cypress } from '../../discovery.config'
_10
_10const { pages } = cypress
_10
_10describe('Custom PLP tests', () => {
_10  it('visit collection page', () => {
_10    cy.visit(pages.collection)
_10    cy.get('[data-testid="product-gallery"]').should('exist').and('be.visible')
_10  })
_10})

Although exclusive execution of custom tests is possible for projects using Cypress version 12.x, we do not recommend this approach. If possible, keep the default Cypress tests.

Some projects may prefer exclusive execution of their custom Cypress tests. Although it's not our recommendation, for projects using Cypress 12.x or higher, you can run the Integration Tests only for your custom tests.

Follow the steps below to configure your project to only run custom Cypress tests:

Instructions

Step 1 - Setting Cypress version

First, ensure that you use Cypress version 12 by setting the cypressVersion experimental feature flag:

Open the discovery.config.js file.
Inside the experimental object, add the cypressVersion property.
Set the cypressVersion value to 12.

discovery.config.js


_10  experimental: {
_10      enableCypressExtension: true,
_10      cypressVersion: 12,
_10  }

Step 2 - Updating the Cypress configuration file

Ensure that your Cypress configuration file (cypress.json) matches the latest Cypress configuration file format. To do so, refer to the official Cypress configuration file guide.

Step 3 - Changing the custom Cypress tests directory

Now, change your custom Cypress tests directory from cypress/integration to cypress/e2e:

In your storefront project, rename the folder from cypress/integration to cypress/e2e.
Update your new Cypress configuration file cypress.config.ts to match the new custom tests folder cypress/e2e by specifying the specPattern:

cypress.config.ts


_10import { defineConfig } from 'cypress'
_10
_10export default defineConfig({
_10  ...,
_10  e2e: {
_10    ...,
_10    specPattern: 'cypress/e2e/**/*.test.{js,jsx,ts,tsx}',
_10  },
_10})

Run yarn dev in the terminal to sync the changes you have made.