Cypress Example

A reference app showcasing how to declare Cypress end-to-end tests and run them on IO's Test Architecture.

• Getting started
• Configuration
  • Basic
  • Advanced
• Authenticating to *.myvtex.com
• Notes on using TypeScript
• Test callbacks
• Running Cypress locally

Getting started

First of all, you should have a working Cypress test suite. If you do, skip to Basic Configuration.

Otherwise, to get the basic Cypress structure:

• Make sure you have cypress (and, optionally, typescript) as a dev dependency:
  • $ yarn add cypress@4.5.0 typescript -D
  • Note: 4.5.0 is the Cypress version IO runs your tests on, so we recommend you write and debug your tests using this version.
• Fire up Cypress once and it will scaffold some directories and sample integration tests for you:
  • $ npx cypress open

Configuration

Basic

Declare that your app wants to use the cypress@0.x builder in its manifest.json file and add vtex.tester-hub@0.x as one of its dependencies:

$ vtex add vtex.tester-hub@0.x

Then link or install your app. From now on you can use the test e2e command to run your tests:

$ vtex test e2e

Advanced

To make your test suite reusable across accounts and workspaces, you can take advantage of the <account> and <workspace> placeholders in your cypress.json "baseUrl":

// cypress.json
{
  "baseUrl": "https://<workspace>--<account>.myvtex.com",
  ...
}

Then make sure to use relative paths in your cy.visit() calls.

Note, however, that this isn't a valid URL and your tests won't work when you use cypress open or cypress run. Refer to the Running Cypress locally section for a work around.

Authenticating to *.myvtex.com

Since myvtex.com is an authenticated domain, tests against it need to set the VtexIdclientAutCookie cookie, otherwise they will land on the login page.

The test framework will make a token available - should one be provided - through the authToken environment variable. Test code can then access this token using Cypress.env('authToken').

To provide your local user token, pass the --token command line argument to the test command:

$ vtex test e2e --token

When running Cypress locally, you must provide the token yourself through the CYPRESS_authToken environment variable. Refer to the Running Cypress locally section for more information.

We provide a sample custom Cypress command to set the required cookie in this file. Tests must then call this command before attempting to visit a *.myvtex.com page.

Notes on using TypeScript

If you wish to write your integration tests in TypeScript, you will need a tsconfig.json file. This file must be inside the cypress folder. We provide a sample TypeScript configuration here.

Note that a .ts pluginsFile is not currently supported and, if you need a pluginsFile, you should use JavaScript. Additionally, don't forget to update your supportFile path in your cypress.json file if you choose to write it in TypeScript, e.g.:

// cypress.json
{
  ...
  "supportFile": "cypress/support/index.ts",
  ...
}

Test callbacks

Your app may choose to be notified whenever its tests are run. You can choose spec completion callbacks and/or test completion callbacks through the following properties in your cypress.json file:

// cypress.json
{
  ...
  "specCallback": true,
  "completeCallback": true,
  ...
}

tester-hub will then POST the JSON report payload on the following routes:

• /_v/e2e_spec_callback/*spec
  • where *spec is the full path to the spec, i.e. cypress/integration/basic.spec.ts
• /_v/e2e_complete_callback/:testId
  • where :testId is the test request id assigned by tester-hub

For more information on the payload format, refer to these files: node/middlewares/e2e.ts and node/typings/e2e.d.ts.

Additionally, you will need to declare that your app now uses the node@6.x builder in your manifest.json file and configure a service, allowing tester-hub to call your app. Refer to these files: node/service.json and node/index.ts.

Running Cypress locally

~~ Linux/MacOs only ~~

To make using dynamic baseUrl and *.myvtex.com authentication painless when running Cypress locally, we provide the cypress-local.sh script.

This script will resolve the baseUrl configured in your cypress.json file using the currently logged-in account and workspace, and also expose the user's local token through the CYPRESS_authToken environment variable.

• Download the file and make sure it's executable:

  $ sudo chmod +x cypress-local.sh

• Use it as a drop-in replacement for cypress:
  • ./cypress-local.sh open
  • ./cypress-local.sh run --headless --config pageLoadTimeout=100000,watchForFileChanges=false
• (Optional) set up package.json scripts:

  // package.json
  {
    ...
    "scripts": {
      "cypress:open": "./cypress-local.sh open",
      "cypress:run": "./cypress-local.sh run"
    },
    ...
  }