Testing

Testing helps you write and maintain working Astro code. Astro supports many popular tools for unit tests, component tests, and end-to-end tests including Jest, Mocha, Jasmine, Cypress and Playwright. You can even install framework-specific testing libraries such as React Testing Library to test your UI framework components.

Testing frameworks allow you to state assertions or expectations about how your code should behave in specific situations, then compare these to the actual behavior of your current code.

A Vite-native unit test framework with ESM, TypeScript and JSX support powered by esbuild.

See the Astro + Vitest starter template on GitHub.

Cypress is a front-end testing tool built for the modern web. Cypress enables you to write end-to-end tests for your Astro site.

You can install Cypress using the package manager of your choice.

npmpnpmYarn

Terminal window

This will install Cypress locally as a dev dependency for your project.

In the root of your project, create a cypress.config.js file with the following content:

1. Choose a page to test. This example will test the example page index.astro below.

   src/pages/index.astro

2. Create an index.cy.js file in the cypress/e2e folder. Use the following test in the file to verify that the page title and header are correct.

   cypress/e2e/index.cy.js

Cypress can be run from the command line or from the Cypress App. The App provides a visual interface for running and debugging your tests.

First, start the dev server so Cypress can access your live site.

To run our test from the previous example using the command line, execute the following command:

Alternatively, to run the test using the Cypress App, execute the following command:

Once the Cypress App is launched, choose E2E Testing, then select the browser to be used to run tests.

Once the test run is finished, you should see green check marks in the output confirming that your test passed:

More information about Cypress can be found in the links below:

• Introduction to Cypress
• Testing Your App

Playwright is an end-to-end testing framework for modern web apps. Use the Playwright API in JavaScript or TypeScript to test your Astro code on all modern rendering engines including Chromium, WebKit, and Firefox.

You can get started and run your tests using the VS Code Extension.

Alternatively, you can install Playwright within your Astro project using the package manager of your choice. Follow the CLI steps to choose JavaScript/TypeScript, name your test folder, and add an optional GitHub Actions workflow.

npmpnpmYarn

Terminal window

1. Choose a page to test. This example will test the example page index.astro below.

   src/pages/index.astro

2. Create a new folder and add the following test file in src/test. Copy and paste the following test into the file to verify that the page meta information is correct. Update the value of the page <title> to match the page you are testing.

   src/test/index.spec.ts

You can run a single test or several tests at once, testing one or multiple browsers. By default, your test results will be shown in the terminal. Optionally, you can open the HTML Test Reporter to show a full report and filter test results.

1. To run our test from the previous example using the command line, use the test command. Optionally, include the file name to run just the single test:

   Terminal window

2. To see the full HTML Test Report, open it using the following command:

   Terminal window

You can also have Playwright start your server when you run your testing script by using the webServer option in the Playwright configuration file.

Here is an example of the configuration and commands required when using npm:

1. Add a test script to your package.json file in the project root, such as "test:e2e": "playwright test".

2. In playwright.config.ts, add the webServer object and update the command value to npm run preview.

   playwright.config.ts

3. Run npm run build, then run npm run test:e2e to run the Playwright tests.

More information about Playwright can be found in the links below:

• Getting started with Playwright
• Use a development server