init

---
name: init
description: Use when the user wants to set up a Playwright testing environment for a project — detects the framework and generates config, folder structure, an example test, and a CI workflow.
category: Engineering
version: 1.0.0
tools: []
---

# Initialize Playwright Project

Guide setup of a production-ready Playwright testing environment: detect the framework, generate config, folder structure, an example test, and a CI workflow — and return them in the chat for the user to add to their project.

## Steps

### 1. Analyze the Project

Ask about or infer from context:

- Framework in use (React, Next.js, Vue, Angular, Svelte) from `package.json`
- Whether TypeScript is used (`tsconfig.json` present) or plain JavaScript
- Whether Playwright is already installed (`@playwright/test` in dependencies)
- Existing test directories (`tests/`, `e2e/`, `__tests__/`)
- Existing CI config (`.github/workflows/`, `.gitlab-ci.yml`)

### 2. Note Installation Requirements

If not already installed, the user needs `@playwright/test` as a dev dependency and the browser binaries installed (the framework's official quickstart covers this).

### 3. Generate `playwright.config.ts`

Adapt to the detected framework:

**Next.js:**
```typescript
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['html', { open: 'never' }],
    ['list'],
  ],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: "chromium", use: { ...devices['Desktop Chrome'] } },
    { name: "firefox", use: { ...devices['Desktop Firefox'] } },
    { name: "webkit", use: { ...devices['Desktop Safari'] } },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});
```

**React (Vite):** change `baseURL` to `http://localhost:5173`, `webServer.command` to `npm run dev`.

**Vue/Nuxt:** change `baseURL` to `http://localhost:3000`, `webServer.command` to `npm run dev`.

**Angular:** change `baseURL` to `http://localhost:4200`, `webServer.command` to `npm run start`.

**No framework detected:** omit the `webServer` block; set `baseURL` from user input or leave as a placeholder.

### 4. Create Folder Structure

```
e2e/
├── fixtures/
│   └── index.ts          # Custom fixtures
├── pages/
│   └── .gitkeep          # Page object models
├── test-data/
│   └── .gitkeep          # Test data files
└── example.spec.ts       # First example test
```

### 5. Generate Example Test

```typescript
import { test, expect } from '@playwright/test';

test.describe('Homepage', () => {
  test('should load successfully', async ({ page }) => {
    await page.goto('/');
    await expect(page).toHaveTitle(/.+/);
  });

  test('should have visible navigation', async ({ page }) => {
    await page.goto('/');
    await expect(page.getByRole('navigation')).toBeVisible();
  });
});
```

### 6. Generate CI Workflow

If `.github/workflows/` exists, provide a `playwright.yml`:

```yaml
name: "playwright-tests"

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main, dev]

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: "install-dependencies"
        run: npm ci
      - name: "install-playwright-browsers"
        run: npx playwright install --with-deps
      - name: "run-playwright-tests"
        run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: "playwright-report"
          path: playwright-report/
          retention-days: 30
```

If `.gitlab-ci.yml` exists, add a Playwright stage instead.

### 7. Update `.gitignore`

Recommend appending, if not already present:

```
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
```

### 8. Suggest npm Scripts

Recommend adding to `package.json` scripts:

```json
{
  "test:e2e": "playwright test",
  "test:e2e:ui": "playwright test --ui",
  "test:e2e:debug": "playwright test --debug"
}
```

## Output

Summarize what was produced: config file contents and key settings, test directory layout and example test, CI workflow (if applicable), and suggested npm scripts.