Skip to content

Commit 615e2e8

Browse files
playwrightmachineplaywrightmachine
authored
cherry-pick(#23470): docs: improve by adding teardown and examples (#23621)
1 parent a2798c3 commit 615e2e8

File tree

2 files changed

+189
-7
lines changed

2 files changed

+189
-7
lines changed

‎docs/src/test-global-setup-teardown-js.md

+181-6
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,26 @@ There are two ways to configure global setup and teardown: using a global setup
99

1010
[Project dependencies](./api/class-testproject#test-project-dependencies) are a list of projects that need to run before the tests in another project run. They can be useful for configuring the global setup actions so that one project depends on this running first. Using dependencies allows global setup to produce traces and other artifacts.
1111

12-
In this example the chromium, firefox and webkit projects depend on the setup project.
12+
### Setup
13+
14+
First we add a new project with the name 'setup'. We then give it a [`property: TestProject.testMatch`] property in order to match the file called `global.setup.ts`:
15+
16+
```js title="playwright.config.ts"
17+
import { defineConfig } from '@playwright/test';
18+
19+
export default defineConfig({
20+
projects: [
21+
{
22+
name: 'setup',
23+
testMatch: /global.setup\.ts/,
24+
},
25+
// {
26+
// other project
27+
// }
28+
]
29+
});
30+
```
31+
Then we add the [`property: TestProject.dependencies`] property to our projects that depend on the setup project and pass into the array the name of of our dependency project, which we defined in the previous step:
1332

1433
```js title="playwright.config.ts"
1534
import { defineConfig } from '@playwright/test';
@@ -25,26 +44,182 @@ export default defineConfig({
2544
use: { ...devices['Desktop Chrome'] },
2645
dependencies: ['setup'],
2746
},
47+
]
48+
});
49+
```
50+
### Setup Example
51+
52+
This example will show you how to use project dependencies to create a global setup that logins into an application and saves the state in storage state. This is useful if you want to run multiple tests that require a sign sign-in state and you want to avoid login for each test.
53+
54+
The setup project will write the storage state into an 'playwright/.auth/user.json' file next to your playwright.config. By exporting a const of `STORAGE_STATE` we can then easily share the location of the storage file between projects with the [`StorageState`](./test-use-options#basic-options) method. This applies the storage state on the browser context with its cookies and a local storage snapshot.
55+
56+
In this example the 'logged in chromium' project depends on the setup project whereas the 'logged out chromium' project does not depend on the setup project, and does not use the `storageState` option.
57+
58+
```js title="playwright.config.ts"
59+
import { defineConfig } from '@playwright/test';
60+
61+
export const STORAGE_STATE = path.join(__dirname, 'playwright/.auth/user.json');
62+
63+
export default defineConfig({
64+
use: {
65+
baseURL: 'http://localhost:3000/',
66+
},
67+
projects: [
2868
{
29-
name: 'firefox',
30-
use: { ...devices['Desktop Firefox'] },
31-
dependencies: ['setup'],
69+
name: 'setup',
70+
testMatch: /global.setup\.ts/,
3271
},
3372
{
34-
name: 'webkit',
35-
use: { ...devices['Desktop Safari'] },
73+
name: 'logged in chromium',
74+
use: { ...devices['Desktop Chrome'] },
75+
testMatch: '**/*.loggedin.spec.ts',
3676
dependencies: ['setup'],
77+
use: {
78+
storageState: STORAGE_STATE,
79+
},
80+
},
81+
{
82+
name: 'logged out chromium',
83+
use: { ...devices['Desktop Chrome'] },
84+
testIgnore: ['**/*loggedin.spec.ts']
3785
},
3886
],
3987
});
88+
```
89+
90+
We then create a setup test, stored at root level of your project, that logs in to an application and populates the context with the storage state after the login actions have been performed. By doing this you only have to log in once and the credentials will be stored in the `STORAGE_STATE` file, meaning you don't need to log in again for every test. Start by importing the `STORAGE_STATE` from the Playwright config file and then use this as the path to save your storage state to the page's context.
91+
92+
```js title="global.setup.ts"
93+
import { test as setup, expect } from '@playwright/test';
94+
import { STORAGE_STATE } from '../playwright.config';
95+
96+
setup('do login', async ({ page }) => {
97+
await page.goto('/');
98+
await page.getByLabel('User Name').fill('user');
99+
await page.getByLabel('Password').fill('password');
100+
await page.getByText('Sign in').click();
101+
102+
// Wait until the page actually signs in.
103+
await expect(page.getByText('Hello, user!')).toBeVisible();
104+
105+
await page.context().storageState({ path: STORAGE_STATE });
106+
});
107+
```
40108

109+
```js title="tests/menu.loggedin.spec.ts"
110+
import { test, expect } from '@playwright/test';
111+
112+
test.beforeEach(async ({ page }) => {
113+
await page.goto('/');
114+
});
115+
116+
test('menu', async ({ page }) => {
117+
// You are signed in!
118+
})
41119
```
120+
121+
For a more detailed example check out our blog post: [A better global setup in Playwright reusing login with project dependencies](https://dev.to/playwright/a-better-global-setup-in-playwright-reusing-login-with-project-dependencies-14) or check the [v1.31 release video](https://youtu.be/PI50YAPTAs4) to see the demo.
122+
123+
### Teardown
124+
125+
You can teardown your setup by adding a [`property: TestProject.teardown`] property to your setup project. This will run after all dependent projects have run.
126+
127+
First we add a new project into the projects array and give it a name such as 'cleanup db'. We then give it a [`property: TestProject.testMatch`] property in order to match the file called `global.teardown.ts`:
128+
129+
```js title="playwright.config.ts"
130+
import { defineConfig } from '@playwright/test';
131+
132+
export default defineConfig({
133+
projects: [
134+
// {
135+
// setup project
136+
// },
137+
{
138+
name: 'cleanup db',
139+
testMatch: /global.teardown\.ts/,
140+
},
141+
// {
142+
// other project
143+
// }
144+
]
145+
});
146+
```
147+
Then we add the [`property: TestProject.teardown`] property to our setup project with the name 'cleanup db' which is the name we gave to our teardown project in the previous step:
148+
149+
```js title="playwright.config.ts"
150+
import { defineConfig } from '@playwright/test';
151+
152+
export default defineConfig({
153+
projects: [
154+
{
155+
name: 'setup db',
156+
testMatch: /global\.setup\.ts/,
157+
teardown: 'cleanup db',
158+
},
159+
{
160+
name: 'cleanup db',
161+
testMatch: /global\.teardown\.ts/,
162+
},
163+
// {
164+
// other project
165+
// }
166+
]
167+
});
168+
```
169+
170+
### Teardown Example
171+
172+
Start by creating a `global.setup.ts` file at the root level of your project. This will be used to seed the database with some data before all tests have run.
173+
174+
```js title="global.setup.ts"
175+
// seed the database with some data
176+
```
177+
Then create a `global.teardown.ts` file at the root level of your project. This will be used to delete the data from the database after all tests have run.
178+
179+
```js title="global.teardown.ts"
180+
// delete the data from the database
181+
```
182+
In the Playwright config file:
183+
- Add a project into the projects array and give it a name such as 'setup db'. Give it a [`property: TestProject.testMatch`] property in order to match the file called `global.setup.ts`.
184+
185+
- Create another project and give it a name such as 'cleanup db'. Give it a [`property: TestProject.testMatch`] property in order to match the file called `global.teardown.ts`.
186+
187+
- Add the [`property: TestProject.teardown`] property to our setup project with the name 'cleanup db' which is the name given to our teardown project in the previous step. Finally add the 'chromium' project with the [`property: TestProject.dependencies`] on the 'setup db' project.
188+
189+
190+
```js title="playwright.config.ts"
191+
import { defineConfig } from '@playwright/test';
192+
193+
export default defineConfig({
194+
projects: [
195+
{
196+
name: 'setup db',
197+
testMatch: /global\.setup\.ts/,
198+
teardown: 'cleanup db',
199+
},
200+
{
201+
name: 'cleanup db',
202+
testMatch: /global\.teardown\.ts/,
203+
},
204+
{
205+
name: 'chromium',
206+
use: { ...devices['Desktop Chrome'] },
207+
dependencies: ['setup db'],
208+
},
209+
]
210+
});
211+
```
212+
42213
## Configure globalSetup and globalTeardown
43214

44215
You can use the `globalSetup` option in the [configuration file](#configuration-object) to set something up once before running all tests. The global setup file must export a single function that takes a config object. This function will be run once before all the tests.
45216

46217
Similarly, use `globalTeardown` to run something once after all the tests. Alternatively, let `globalSetup` return a function that will be used as a global teardown. You can pass data such as port number, authentication tokens, etc. from your global setup to your tests using environment variables.
47218

219+
:::note
220+
Using `globalSetup` and `globalTeardown` will not produce traces or artifacts. If you want to produce traces and artifacts, use [project dependencies](#project-dependencies).
221+
:::
222+
48223
```js title="playwright.config.ts"
49224
import { defineConfig } from '@playwright/test';
50225

‎docs/src/test-projects-js.md

+8-1
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,6 @@ export default defineConfig({
183183
],
184184
});
185185
```
186-
187186
### Running Sequence
188187

189188
When working with tests that have a dependency, the dependency will always run first and once all tests from this project have passed, then the other projects will run in parallel.
@@ -206,6 +205,14 @@ Running order:
206205

207206
<img width="70%" style={{display: 'flex', margin: 'auto'}} alt="Browser login project is blue, database is red and e2e tests relies on both" loading="lazy" src="https://user-images.githubusercontent.com/13063165/225938262-33c1b78f-f092-4762-a478-7f8cbc1e3b21.jpg" />
208207

208+
### Teardown
209+
210+
You can also [`property: TestProject.teardown`] your setup by adding a teardown property to your setup project. This will run after all dependent projects have run. See the [teardown guide](./test-global-setup-teardown.md#teardown) for more information.
211+
212+
213+
<img style={{display: 'flex', margin: 'auto'}} alt="global setup and teardown" loading="lazy" src="https://github.com/microsoft/playwright/assets/13063165/dfcf10a9-f601-4d0c-bd8d-9490e6efbf7a" />
214+
215+
209216
## Custom project parameters
210217

211218
Projects can be also used to parametrize tests with your custom configuration - take a look at [this separate guide](./test-parameterize.md#parameterized-projects).

0 commit comments

Comments
 (0)