Playwright Project Structure

A messy kitchen slows down even a skilled chef, since ingredients and tools sit in random places. A messy test project causes the same frustration for a testing team. Playwright sets up a clean, predictable folder structure from the very first installation, and understanding this structure saves hours of confusion later.

The Default Folder Layout

my-project/
  |-- tests/
  |     |-- example.spec.js
  |-- tests-examples/
  |-- playwright.config.js
  |-- package.json
  |-- package-lock.json
  |-- node_modules/

The tests Folder

Every test file belongs here. A team building an online store might create files named cart.spec.js, login.spec.js, and checkout.spec.js, each covering one part of the website. Playwright scans this folder automatically and runs every file inside it.

The playwright.config.js File

This file acts like a control panel for the entire project. It decides which browsers to test, how long to wait before giving up on an action, where to save screenshots, and how many tests run at the same time.

module.exports = {
  testDir: './tests',
  timeout: 30000,
  use: {
    baseURL: 'https://example.com',
    headless: true,
  },
};

The baseURL setting lets every test use short relative links instead of typing the full website address repeatedly.

The package.json File

This file lists every tool the project depends on, including Playwright itself. It also stores shortcut commands, so a team can type npm test instead of a longer command every time.

The node_modules Folder

This folder holds the actual code for every installed package. Nobody edits files inside it directly, and most teams exclude it from version control since it can regenerate automatically from package.json.

A Practical Example: Growing a Project

A small project starts with three test files. Six months later, the same project has fifty test files covering login, search, cart, checkout, and account settings. Because every file still lives inside the tests folder, Playwright continues finding and running them without any extra configuration.

Organizing Tests Into Subfolders

Large projects often group related tests into subfolders for clarity.

tests/
  |-- auth/
  |     |-- login.spec.js
  |     |-- signup.spec.js
  |-- cart/
  |     |-- add-item.spec.js
  |     |-- remove-item.spec.js

Playwright still finds every test file regardless of how deep it sits inside subfolders.

Quick Practice Task

Open your project's playwright.config.js file and locate the baseURL setting. Change it to point to a website of your choice, then confirm the sample test still runs correctly.

Key Takeaways

• The tests folder holds every test file Playwright runs.
• playwright.config.js controls browsers, timeouts, and other project-wide settings.
• package.json tracks dependencies and useful shortcut commands.
• Subfolders keep large projects with many tests organized clearly.