A community-driven Cypress testing suite for Magento 2

This testing suite was announced in Peter Jaap his talk about Cypress testing in Magento 2 at Reacticon 4. Watch the talk for more information about Cypress testing.

A successful Cypress run which tests the store at https://hyva-demo.elgentos.io

• Prerequisites
• Limitations
• Progress
• Setup
• Running
• Contributing

• Magento 2.3.x / 2.4.x
• Hyvä or Luma-based theme
• npm
• An admin bearer token (see Setup)

• Magento 2 runs in Single Store Mode

• Default language is English

• Viewport is 1920x1280, with support for mobile viewports

• Multi Source Inventory is not used

This test suite is not plug & play for your store. A number of tests rely on Magento's default sample data. These tests will fail when you don't have the sample data. It is up to you to change the fixtures/selectors/tests to make them pass for your store.

We don't do Commerce builds over at elgentos so we haven't spent time creating tests for Commerce-only functionality.

We do not particularly strive for 100% test coverage. We have identified the most common and most revenue-dependent scenarios. For example, we do test viewing products, filtering categories, adding products to the cart, etcetera but we do (currently) not test the Email a Friend or Compare Products feature since these are rarely used in an average Magento store. We are perfectly willing to merge a PR with these tests of course.

You need to copy the whole suite into your project. We are open to suggestions on how to solve this, see Discussions.

We haven't made tests for the Hyvä React Checkout yet. PR's are definitely welcome now that we have a stable version.

We are at 72%; 56 out of the proposed 78 tests are done.

Wording & naming are subject to change.

First, install Cypress in the root of your Magento 2 project;

npm init
npm install cypress --save-dev
npm install cypress-file-upload cypress-localstorage-commands cypress-tags typescript --save-dev

The easiest way to install the tests is to clone this repository and move the cypress folder into your project. As of right now, we do not provide a fallback mechanism for customizations to the tests, see Limitations.

git clone [email protected]:elgentos/magento2-cypress-testing-suite.git 
mv magento2-cypress-testing-suite/cypress .
mv magento2-cypress-testing-suite/cypress.json .
rm -rf magento2-cypress-testing-suite

Also see Tags below about how to set up using tags.

Then edit the cypress.json file in the root of your project to update your baseUrl and possibly some other defaults we've set:

{
  "baseUrl": "https://example.com",
  "watchForFileChanges": false,
  "viewportWidth": 1920,
  "viewportHeight": 1080,
  "env": {
    "mobileViewportWidthBreakpoint": 768
  }
}

Also add these lines to your .gitignore to avoid cluttering your Git repo;

node_modules
cypress/screenshots
cypress/videos
cypress.env.json

Some tests are dependent on making changes in the database. This is done through the Magento 2 REST API. You will need to create an admin token for these tests. This is easily done using magerun2.

Get a list of all the admin users: magerun2 admin:user:list

If you don't have any admin users, create one; magerun2 admin:user:create --admin-user=john --admin-firstname=John --admin-lastname=Doe --admin-password=JohnDoe123 --admin-email="[email protected]"

Then create a token: magerun2 admin:token:create username_goes_here

You then can add the token to cypress.env.json as an environment variable:

{
  "MAGENTO2_ADMIN_TOKEN": "token_goes_here"
}

Or you can set it in your CI/CD variables by prefixing the environment variable name with CYPRESS_: CYPRESS_MAGENTO2_ADMIN_TOKEN: <token_goes_here>.

We use tags.to discern between hot tests and cold tests. You need to install the 3rd party tag support package. Following the setup for that package, you need to add it to the plugins/index.js and support/index.d.ts.

npm install cypress-tags typescript --save-dev

npm ci
npx cypress run
# npx cypress open # if you want to use the GUI

Individual specs can be run using the following command

npx cypress run --spec ./cypress/integration/path/to/some.spec.js

Set up your local URL in cypress/plugins/index.js. Then run Cypress with NODE_ENV=develop; npx cypress run.

We are very open to contributions! We would love to have mobile viewport support for Hyvä, tests for Commerce functionality, additional tests, code improvements, a fallback mechanism, etcetera etcetera. See the Issues tab for issues to pick up.

We will be updating this readme soon with extensive contribution guidelines, but here is a short summary:

• Avoid creating global cy functions (Custom Commands), instead put functions in utils/helpers and import them
• Avoid creating aliases that are only used once
• Use cy.get() as much as possible, only use cy.contains() in specific cases - try to avoid it
• Do not write assertions in page objects, move those to the spec files. Red flag; should() in a page object
• Every test (an it() function) has to be able to run stand-alone; it should not depend on any other test. You can test this by add .only (see Cypress docs).