Once Playwright is installed, structuring your test project well makes it easier to scale. A clear layout for tests, helpers, and configuration reduces friction when multiple people work on the same suite.
Typical Playwright Project Structure
The default scaffold arranges tests in a tests directory and uses playwright.config to control settings. You can customise folders later, but starting from the standard layout helps everyone navigate quickly.
playwright-demo/
├─ package.json
├─ playwright.config.ts
├─ tests/
│ ├─ example.spec.ts
│ ├─ auth.spec.ts
│ └─ cart.spec.ts
└─ helpers/
├─ test-data.ts
└─ api-clients.ts.spec.ts (or .test.ts) files under the configured test directory, so you rarely need manual file lists.auth.spec.ts, checkout.spec.ts) rather than by HTTP method or individual page, which makes reports easier to interpret.The test runner provides CLI flags to filter tests, run in headed or headless mode, and control reporters. Learning a few key commands early makes local debugging smoother.
# Run all tests in headed mode for debugging
npx playwright test --headed
# Run only tests in a specific file
npx playwright test tests/auth.spec.ts
# Run tests by title pattern
npx playwright test --grep "checkout"
# Use trace viewer after a failed run
npx playwright show-trace trace.zipCommon Mistakes
Mistake 1 — Keeping tests and helpers in many random folders
This slows navigation.
❌ Wrong: Spreading test files across unrelated directories with no clear structure.
✅ Correct: Use a predictable tests directory and a small number of helper folders.
Mistake 2 — Not using the CLI effectively
Debugging becomes painful.
❌ Wrong: Always running the entire suite in headless mode when debugging a single scenario.
✅ Correct: Use filters, headed mode, and trace viewer to focus on specific problems.