Testing

An intro to testing in Astro

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.

Unit and integration tests

Vitest

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

Use Astro’s getViteConfig() helper in your vitest.config.ts configuration file to set up Vitest with your Astro project’s settings:

/// <reference types="vitest/config" />
import { getViteConfig } from 'astro/config';

export default getViteConfig({
  test: {
    // Vitest configuration options
  },
});

By default, getViteConfig() will try to load an Astro config file in your project and apply it to the test environment. As of Astro 4.8, if you need to customize the Astro configuration applied in your tests, pass a second argument to getViteConfig():

export default getViteConfig(
  { test: { /* Vitest configuration options */ } },
  {
    site: 'https://example.com/',
    trailingSlash: 'always',
  },
);

See the Astro + Vitest starter template on GitHub.

Vitest and Container API

You can natively test Astro components using the container API. First, setup vitest as explained above, then create a .test.js file to test your component:

import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import { expect, test } from 'vitest';
import Card from '../src/components/Card.astro';

test('Card with slots', async () => {
  const container = await AstroContainer.create();
  const result = await container.renderToString(Card, {
    slots: {
      default: 'Card content',
    },
  });

  expect(result).toContain('This is a card');
  expect(result).toContain('Card content');
});

End-to-end tests

Playwright

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.

Installation

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.

Create your first Playwright test

Running your Playwright tests

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.

Advanced: Launching a development web server during the tests

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:

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

Cypress

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.

Installation

You can install Cypress using the package manager of your choice. This will install Cypress locally as a dev dependency for your project.

Configuration

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

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    supportFile: false
  }
})

Create your first Cypress test

Running your Cypress tests

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:

npx cypress run

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

npx cypress open

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:

Running:  index.cy.js                                                                     (1 of 1)

✓ titles are correct (107ms)

1 passing (1s)

To check that your test really does work, you can change the following line in the index.astro file:

 <body>
   <h1>Hello world from Astro</h1>
   <h1>Hello from Astro</h1>
 </body>

Then run the test again. You should see a red “x” in the output confirming that your test failed.

Next steps

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

NightwatchJS

Nightwatch.js is a test automation framework with a powerful set of tools to write, run, and debug your tests across the web with built-in support for all major browsers and their mobile equivalents, as well as native mobile applications.

Installation

You can install NightwatchJS within your Astro project using the package manager of your choice. Follow the CLI steps to choose JavaScript/TypeScript, name your test folder, and select whether or not to include component testing and testing on mobile browsers.

Create your first Nightwatch test

Running your NightwatchJS tests

You can run the tests with the NightwatchJS VSCode Extension or using the CLI steps below:

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