1# Projects & Dependencies
2 
3## Table of Contents
4 
51. [Project Configuration](#project-configuration)
62. [Project Dependencies](#project-dependencies)
73. [Setup Projects](#setup-projects)
84. [Filtering & Running Projects](#filtering--running-projects)
95. [Sharing Configuration](#sharing-configuration)
106. [Advanced Patterns](#advanced-patterns)
11 
12## Project Configuration
13 
14### Basic Multi-Browser Setup
15 
16```typescript
17// playwright.config.ts
18import { defineConfig, devices } from "@playwright/test";
19 
20export default defineConfig({
21  projects: [
22    {
23      name: "chromium",
24      use: { ...devices["Desktop Chrome"] },
25    },
26    {
27      name: "firefox",
28      use: { ...devices["Desktop Firefox"] },
29    },
30    {
31      name: "webkit",
32      use: { ...devices["Desktop Safari"] },
33    },
34  ],
35});
36```
37 
38### Environment-Based Projects
39 
40```typescript
41export default defineConfig({
42  projects: [
43    {
44      name: "staging",
45      use: {
46        baseURL: "https://staging.example.com",
47      },
48    },
49    {
50      name: "production",
51      use: {
52        baseURL: "https://example.com",
53      },
54    },
55    {
56      name: "local",
57      use: {
58        baseURL: "http://localhost:3000",
59      },
60    },
61  ],
62});
63```
64 
65### Test Type Projects
66 
67```typescript
68export default defineConfig({
69  projects: [
70    {
71      name: "e2e",
72      testDir: "./tests/e2e",
73      use: { ...devices["Desktop Chrome"] },
74    },
75    {
76      name: "api",
77      testDir: "./tests/api",
78      use: { baseURL: "http://localhost:3000" },
79    },
80    {
81      name: "visual",
82      testDir: "./tests/visual",
83      use: {
84        ...devices["Desktop Chrome"],
85        viewport: { width: 1280, height: 720 },
86      },
87    },
88  ],
89});
90```
91 
92## Project Dependencies
93 
94### Setup Dependency
95 
96```typescript
97export default defineConfig({
98  projects: [
99    // Setup project runs first
100    {
101      name: "setup",
102      testMatch: /.*\.setup\.ts/,
103    },
104 
105    // Browser projects depend on setup
106    {
107      name: "chromium",
108      use: {
109        ...devices["Desktop Chrome"],
110        storageState: ".auth/user.json",
111      },
112      dependencies: ["setup"],
113    },
114    {
115      name: "firefox",
116      use: {
117        ...devices["Desktop Firefox"],
118        storageState: ".auth/user.json",
119      },
120      dependencies: ["setup"],
121    },
122  ],
123});
124```
125 
126### Multiple Auth States
127 
128```typescript
129export default defineConfig({
130  projects: [
131    // Auth setup projects
132    {
133      name: "setup-admin",
134      testMatch: /admin\.setup\.ts/,
135    },
136    {
137      name: "setup-user",
138      testMatch: /user\.setup\.ts/,
139    },
140 
141    // Admin tests
142    {
143      name: "admin-tests",
144      testDir: "./tests/admin",
145      use: { storageState: ".auth/admin.json" },
146      dependencies: ["setup-admin"],
147    },
148 
149    // User tests
150    {
151      name: "user-tests",
152      testDir: "./tests/user",
153      use: { storageState: ".auth/user.json" },
154      dependencies: ["setup-user"],
155    },
156 
157    // Tests that need both
158    {
159      name: "integration-tests",
160      testDir: "./tests/integration",
161      dependencies: ["setup-admin", "setup-user"],
162    },
163  ],
164});
165```
166 
167### Chained Dependencies
168 
169```typescript
170export default defineConfig({
171  projects: [
172    // Step 1: Database setup
173    {
174      name: "db-setup",
175      testMatch: /db\.setup\.ts/,
176    },
177 
178    // Step 2: Auth setup (needs DB)
179    {
180      name: "auth-setup",
181      testMatch: /auth\.setup\.ts/,
182      dependencies: ["db-setup"],
183    },
184 
185    // Step 3: Seed data (needs auth)
186    {
187      name: "seed-setup",
188      testMatch: /seed\.setup\.ts/,
189      dependencies: ["auth-setup"],
190    },
191 
192    // Tests (need everything)
193    {
194      name: "tests",
195      testDir: "./tests",
196      dependencies: ["seed-setup"],
197    },
198  ],
199});
200```
201 
202## Setup Projects
203 
204### Authentication Setup
205 
206Setup projects are the recommended way to handle authentication. They run before your main test projects and can use Playwright fixtures.
207 
208> **For complete authentication patterns** (storage state, multiple auth states, auth fixtures), see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns).
209 
210### Data Seeding Setup
211 
212```typescript
213// seed.setup.ts
214import { test as setup } from "@playwright/test";
215 
216setup("seed test data", async ({ request }) => {
217  // Create test data via API
218  await request.post("/api/test/seed", {
219    data: {
220      users: 10,
221      products: 50,
222      orders: 100,
223    },
224  });
225});
226```
227 
228### Cleanup Setup
229 
230```typescript
231// cleanup.setup.ts
232import { test as setup } from "@playwright/test";
233 
234setup("cleanup previous run", async ({ request }) => {
235  // Clean up data from previous test runs
236  await request.delete("/api/test/cleanup");
237});
238```
239 
240## Filtering & Running Projects
241 
242### Run Specific Project
243 
244```bash
245# Run single project
246npx playwright test --project=chromium
247 
248# Run multiple projects
249npx playwright test --project=chromium --project=firefox
250```
251 
252### Run by Grep
253 
254```bash
255# Run tests matching pattern
256npx playwright test --grep @smoke
257 
258# Run project with grep
259npx playwright test --project=chromium --grep @critical
260 
261# Exclude pattern
262npx playwright test --grep-invert @slow
263```
264 
265### Project-Specific Grep
266 
267```typescript
268export default defineConfig({
269  projects: [
270    {
271      name: "smoke",
272      grep: /@smoke/,
273      use: { ...devices["Desktop Chrome"] },
274    },
275    {
276      name: "regression",
277      grepInvert: /@smoke/,
278      use: { ...devices["Desktop Chrome"] },
279    },
280  ],
281});
282```
283 
284## Sharing Configuration
285 
286### Base Configuration
287 
288```typescript
289// playwright.config.ts
290const baseConfig = {
291  timeout: 30000,
292  expect: { timeout: 5000 },
293  use: {
294    trace: "on-first-retry",
295    screenshot: "only-on-failure",
296  },
297};
298 
299export default defineConfig({
300  ...baseConfig,
301  projects: [
302    {
303      name: "chromium",
304      use: {
305        ...baseConfig.use,
306        ...devices["Desktop Chrome"],
307      },
308    },
309    {
310      name: "firefox",
311      use: {
312        ...baseConfig.use,
313        ...devices["Desktop Firefox"],
314      },
315    },
316  ],
317});
318```
319 
320### Shared Project Settings
321 
322```typescript
323const sharedBrowserConfig = {
324  timeout: 60000,
325  retries: 2,
326  use: {
327    video: "on-first-retry",
328    trace: "on-first-retry",
329  },
330};
331 
332export default defineConfig({
333  projects: [
334    {
335      name: "chromium",
336      ...sharedBrowserConfig,
337      use: {
338        ...sharedBrowserConfig.use,
339        ...devices["Desktop Chrome"],
340      },
341    },
342    {
343      name: "firefox",
344      ...sharedBrowserConfig,
345      use: {
346        ...sharedBrowserConfig.use,
347        ...devices["Desktop Firefox"],
348      },
349    },
350  ],
351});
352```
353 
354## Advanced Patterns
355 
356### Conditional Projects
357 
358```typescript
359const projects = [
360  {
361    name: "chromium",
362    use: { ...devices["Desktop Chrome"] },
363  },
364];
365 
366// Add Firefox only in CI
367if (process.env.CI) {
368  projects.push({
369    name: "firefox",
370    use: { ...devices["Desktop Firefox"] },
371  });
372}
373 
374// Add mobile only for specific test dirs
375if (process.env.TEST_MOBILE) {
376  projects.push({
377    name: "mobile",
378    use: { ...devices["iPhone 14"] },
379  });
380}
381 
382export default defineConfig({ projects });
383```
384 
385### Project Metadata
386 
387```typescript
388export default defineConfig({
389  projects: [
390    {
391      name: "chromium",
392      use: { ...devices["Desktop Chrome"] },
393      metadata: {
394        platform: "desktop",
395        browser: "chromium",
396        priority: "high",
397      },
398    },
399  ],
400});
401 
402// Access in test
403test("example", async ({ page }, testInfo) => {
404  const { platform, priority } = testInfo.project.metadata;
405  console.log(`Running on ${platform} with ${priority} priority`);
406});
407```
408 
409### Teardown Projects
410 
411```typescript
412export default defineConfig({
413  projects: [
414    {
415      name: "setup",
416      testMatch: /.*\.setup\.ts/,
417      teardown: "teardown", // Run teardown after this completes
418    },
419    {
420      name: "teardown",
421      testMatch: /.*\.teardown\.ts/,
422    },
423    {
424      name: "tests",
425      dependencies: ["setup"],
426    },
427  ],
428});
429```
430 
431```typescript
432// cleanup.teardown.ts
433import { test as teardown } from "@playwright/test";
434 
435teardown("cleanup", async ({ request }) => {
436  await request.delete("/api/test/data");
437});
438```
439 
440## Anti-Patterns to Avoid
441 
442| Anti-Pattern               | Problem                | Solution                            |
443| -------------------------- | ---------------------- | ----------------------------------- |
444| Too many browser projects  | Slow CI, expensive     | Focus on critical browsers          |
445| Missing setup dependencies | Tests fail randomly    | Declare all dependencies explicitly |
446| Duplicated configuration   | Hard to maintain       | Extract shared config               |
447| Not using setup projects   | Repeated auth in tests | Use setup project + storageState    |
448 
449## Related References
450 
451- **Global Setup**: See [global-setup.md](global-setup.md) for globalSetup vs setup projects
452- **Fixtures**: See [fixtures-hooks.md](fixtures-hooks.md) for authentication patterns
453- **CI/CD**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for running projects in CI
454