Playwright Spec Files

Spec files are where your tests live. Naming conventions, folder layout, and file organization determine whether a Playwright suite stays maintainable as it grows from ten tests to ten thousand.

Spec File Conventions

By default Playwright looks for *.spec.ts (or .spec.js) under tests/. You can change testDir and testMatch in config to fit monorepos or feature-based folders.

Name files after features or user journeys: login.spec.ts, checkout.spec.ts. Avoid generic names like test1.spec.ts that do not signal intent in CI logs.

tests/
  auth/
    login.spec.ts
    logout.spec.ts
  shop/
    cart.spec.ts
    checkout.spec.ts

Mirror your app's domain structure so developers find tests quickly.

Configuring Test Discovery

export default defineConfig({
  testDir: './tests',
  testMatch: '**/*.spec.ts',
  testIgnore: '**/*.setup.ts',
});

testDir sets the root folder for discovery.
testMatch glob patterns include or exclude files.
Setup files often use .setup.ts and run via dependencies in projects.
Co-locate helper modules as *.helper.ts outside testMatch if needed.

Spec File Conventions

Naming and layout patterns used in production suites.

Pattern	Example	When to Use
Feature spec	`checkout.spec.ts`	Single feature area
Nested folder	`tests/admin/users.spec.ts`	Large apps by module
Setup project	`auth.setup.ts`	Generate storageState once
Tag in title	`test('checkout @smoke', ...)`	Filter with --grep
Serial group	`describe.configure({ mode: 'serial' })`	Ordered dependent tests
Skip file	`test.describe.skip`	Temporarily disable a group

Tags and Selective Runs

test('critical path @smoke @checkout', async ({ page }) => {
  // ...
});

// CI smoke job:
// npx playwright test --grep @smoke

Setup Projects for Auth

Use a setup project that runs auth.setup.ts once, saves storageState, and declare dependencies: ['setup'] on test projects so login runs once per worker, not per test.

Common Mistakes

One mega spec file with dozens of unrelated tests.
Not excluding setup/helper files from testMatch.
Duplicating login flows in every spec instead of setup projects.
File names that do not appear in --list output meaningfully.

Key Takeaways

Use *.spec.ts under a clear folder hierarchy.
Configure testDir, testMatch, and testIgnore for your repo layout.
Tags in titles enable smoke vs full regression CI jobs.
Setup projects reduce repeated authentication boilerplate.

Pro Tip

Run npx playwright test --list before a big refactor to see exactly which files and tests the runner will pick up.