Skip to content

[testing.mdx] restructure page with test types as headings #8367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sarah11918 merged 1 commit into from
May 22, 2024
Merged

[testing.mdx] restructure page with test types as headings #8367

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 134 additions & 130 deletions src/content/docs/en/guides/testing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@ Testing helps you write and maintain working Astro code. Astro supports many pop

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.

## Vitest
## Unit and integration tests

### Vitest

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

Expand Down Expand Up @@ -43,11 +45,132 @@ export default getViteConfig(

See the [Astro + Vitest starter template](https://github.com/withastro/astro/tree/latest/examples/with-vitest) on GitHub.

## Cypress
## 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](https://playwright.dev/docs/getting-started-vscode).

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.

<PackageManagerTabs>
<Fragment slot="npm">
```shell
npm init playwright@latest
```
</Fragment>
<Fragment slot="pnpm">
```shell
pnpm dlx create-playwright
```
</Fragment>
<Fragment slot="yarn">
```shell
yarn create playwright
```
</Fragment>
</PackageManagerTabs>

#### Create your first Playwright test

<Steps>
1. Choose a page to test. This example will test the example page `index.astro` below.

```html title="src/pages/index.astro"
---
---
<html lang="en">
<head>
<title>Astro is awesome!</title>
<meta name="description" content="Pull content from anywhere and serve it fast with Astro's next-gen island architecture." />
</head>
<body></body>
</html>
```

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.

```jsx title="src/test/index.spec.ts" "Astro is awesome!"
import { test, expect } from '@playwright/test';

test('meta is correct', async ({ page }) => {
await page.goto("http://localhost:4321/");

await expect(page).toHaveTitle('Astro is awesome!');
});
```

:::tip[Set a `baseUrl`]
You can set [`"baseURL": "http://localhost:4321"`](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) in the `playwright.config.ts` configuration file to use `page.goto("/")` instead of `page.goto("http://localhost:4321/")` for a more convenient URL.
:::
</Steps>

#### 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.

<Steps>
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:

```sh
npx playwright test index.spec.ts
```

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

```sh
npx playwright show-report
```
</Steps>

:::tip
Run your tests against your production code to more closely resemble your live, deployed site.
:::

##### 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`](https://playwright.dev/docs/test-advanced#launching-a-development-web-server-during-the-tests) option in the Playwright configuration file.

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

<Steps>
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`.

```js title="playwright.config.ts" ins={4-9} "npm run preview"
import { defineConfig } from '@playwright/test';

export default defineConfig({
webServer: {
command: 'npm run preview',
url: 'http://localhost:4321/',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: 'http://localhost:4321/',
},
});
```

3. Run `npm run build`, then run `npm run test:e2e` to run the Playwright tests.
</Steps>

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

- [Getting started with Playwright](https://playwright.dev/docs/intro)
- [Use a development server](https://playwright.dev/docs/test-webserver#configuring-a-web-server)

### 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
#### Installation

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

Expand All @@ -71,7 +194,7 @@ You can install Cypress using the package manager of your choice.
</Fragment>
</PackageManagerTabs>

### Configuration
#### Configuration

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

Expand All @@ -85,7 +208,7 @@ export default defineConfig({
})
```

### Create your first Cypress test
#### Create your first Cypress test

<Steps>
1. Choose a page to test. This example will test the example page `index.astro` below.
Expand Down Expand Up @@ -120,7 +243,7 @@ export default defineConfig({
:::
</Steps>

### Running your Cypress tests
#### 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.

Expand Down Expand Up @@ -163,18 +286,18 @@ To check that your test really does work, you can change the following line in t
Then run the test again. You should see a red "x" in the output confirming that your test failed.
:::

### Next steps
#### Next steps

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

- [Introduction to Cypress](https://docs.cypress.io/guides/basics/introduction-to-cypress)
- [Testing Your App](https://docs.cypress.io/guides/end-to-end-testing/testing-your-app)

## NightwatchJS
### 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
#### 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.

Expand All @@ -196,7 +319,7 @@ You can install NightwatchJS within your Astro project using the package manager
</Fragment>
</PackageManagerTabs>

### Create your first Nightwatch test
#### Create your first Nightwatch test

<Steps>
1. Choose a page to test. This example will test the example page `index.astro` below.
Expand Down Expand Up @@ -232,7 +355,7 @@ You can install NightwatchJS within your Astro project using the package manager
:::
</Steps>

### Running your NightwatchJS tests
#### Running your NightwatchJS 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.

Expand Down Expand Up @@ -264,122 +387,3 @@ More information about NightwatchJS can be found in the links below:

- [Intro to Nightwatch](https://nightwatchjs.org/guide/overview/what-is-nightwatch.html)
- [Testing with Nightwatch](https://nightwatchjs.org/guide/writing-tests/introduction.html)

## 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](https://playwright.dev/docs/getting-started-vscode).

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.

<PackageManagerTabs>
<Fragment slot="npm">
```shell
npm init playwright@latest
```
</Fragment>
<Fragment slot="pnpm">
```shell
pnpm dlx create-playwright
```
</Fragment>
<Fragment slot="yarn">
```shell
yarn create playwright
```
</Fragment>
</PackageManagerTabs>

### Create your first Playwright test

<Steps>
1. Choose a page to test. This example will test the example page `index.astro` below.

```html title="src/pages/index.astro"
---
---
<html lang="en">
<head>
<title>Astro is awesome!</title>
<meta name="description" content="Pull content from anywhere and serve it fast with Astro's next-gen island architecture." />
</head>
<body></body>
</html>
```

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.

```jsx title="src/test/index.spec.ts" "Astro is awesome!"
import { test, expect } from '@playwright/test';

test('meta is correct', async ({ page }) => {
await page.goto("http://localhost:4321/");

await expect(page).toHaveTitle('Astro is awesome!');
});
```

:::tip[Set a `baseUrl`]
You can set [`"baseURL": "http://localhost:4321"`](https://playwright.dev/docs/api/class-testoptions#test-options-base-url) in the `playwright.config.ts` configuration file to use `page.goto("/")` instead of `page.goto("http://localhost:4321/")` for a more convenient URL.
:::
</Steps>

### 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.

<Steps>
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:

```sh
npx playwright test index.spec.ts
```

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

```sh
npx playwright show-report
```
</Steps>

:::tip
Run your tests against your production code to more closely resemble your live, deployed site.
:::

#### 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`](https://playwright.dev/docs/test-advanced#launching-a-development-web-server-during-the-tests) option in the Playwright configuration file.

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

<Steps>
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`.

```js title="playwright.config.ts" ins={4-9} "npm run preview"
import { defineConfig } from '@playwright/test';

export default defineConfig({
webServer: {
command: 'npm run preview',
url: 'http://localhost:4321/',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: 'http://localhost:4321/',
},
});
```

3. Run `npm run build`, then run `npm run test:e2e` to run the Playwright tests.
</Steps>

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

- [Getting started with Playwright](https://playwright.dev/docs/intro)
- [Use a development server](https://playwright.dev/docs/test-webserver#configuring-a-web-server)