Add end-to-end Cypress tests to your Amplify app

You can run end-to-end (E2E) tests in the test phase of your Amplify app to catch regressions before pushing code to production. The test phase can be configured in the build specification YAML. Currently, you can run only the Cypress testing framework during a build.

Tutorial: Set up end-to-end tests with Cypress

Cypress is a JavaScript-based testing framework that allows you to run E2E tests on a browser. For a tutorial that demonstrates how to set up E2E tests, see the blog post Running end-to-end Cypress tests for your fullstack CI/CD deployment with Amplify.

Add tests to your existing Amplify app

You can add Cypress tests to an existing app by updating the app's build settings in the Amplify console. The build specification YAML contains a collection of build commands and related settings that Amplify uses to run your build. Use the test step to run any test commands at build time. For E2E tests, Amplify Hosting offers a deeper integration with Cypress that allows you to generate a UI report for your tests.

The following list describes the test settings and how they are used.

preTest

Install the dependencies required to run Cypress tests. Amplify Hosting uses mochawesome to generate a report to view your test results and wait-on to set up the localhost server during the build.

test

Run cypress commands to perform tests using mochawesome.

postTest

The mochawesome report is generated from the output JSON. Note that if you are using Yarn, you must run this command in silent mode to generate the mochawesome report. For Yarn, you can use the following command.

yarn run --silent mochawesome-merge cypress/report/mochawesome-report/mochawesome*.json > cypress/report/mochawesome.json
                  

artifacts>baseDirectory

The directory from which tests are run.

artifacts>configFilePath

The generated test report data.

artifacts>files

The generated artifacts (screenshots and videos) available for download.

The following example excerpt from a build specification amplify.yml file shows how to add Cypress tests to your app.

test:
  phases:
    preTest:
      commands:
        - npm ci
        - npm install -g pm2
        - npm install -g wait-on
        - npm install mocha mochawesome mochawesome-merge mochawesome-report-generator
        - pm2 start npm -- start
        - wait-on http://localhost:3000
    test:
      commands:
        - 'npx cypress run --reporter mochawesome --reporter-options "reportDir=cypress/report/mochawesome-report,overwrite=false,html=false,json=true,timestamp=mmddyyyy_HHMMss"'
    postTest:
      commands:
        - npx mochawesome-merge cypress/report/mochawesome-report/mochawesome*.json > cypress/report/mochawesome.json
        - pm2 kill
  artifacts:
    baseDirectory: cypress
    configFilePath: '**/mochawesome.json'
    files:
      - '**/*.png'
      - '**/*.mp4'

Disabling tests

After the test configuration has been added to your amplify.yml build settings, the test step runs for every build, on every branch. If you want to globally disable tests from running, or only run tests for specific branches, you can use the USER_DISABLE_TESTS environment variable without modifying your build settings.

To globally disable tests for all branches, add the USER_DISABLE_TESTS environment variable with a value of true for all branches. The following screenshot, shows the Environment variables section in the Amplify console with tests disabled for all branches.

To disable tests for a specific branch, add the USER_DISABLE_TESTS environment variable with a value of false for all branches, and then add an override for each branch you want to disable with a value of true. In the following screenshot, tests are disabled on the main branch, and enabled for every other branch.

Disabling tests with this variable will cause the test step to be skipped altogether during a build. To re-enable tests, set this value to false, or delete the environment variable.