A reference app showcasing how to declare Cypress end-to-end tests and run them on IO's Test Architecture.
- Getting started
- Configuration
- Authenticating to *.myvtex.com
- Notes on using TypeScript
- Test callbacks
- Running Cypress locally
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 [email protected] 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
Declare that your app wants to use the [email protected]
builder in its manifest.json file and add [email protected]
as one of its dependencies:
$ vtex add [email protected]
Then link or install your app. From now on you can use the test e2e
command to run your tests:
$ vtex test e2e
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.
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.
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",
...
}
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
- where
/_v/e2e_complete_callback/:testId
- where
:testId
is the test request id assigned bytester-hub
- where
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 [email protected]
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.
~~ 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" }, ... }