“Debugging is like being the detective in a crime movie where you are also the murderer.” – Filipe Fortes
Playwright is a powerful tool for end-to-end testing, but debugging test failures can be tricky.
Based on my experience, I’ve put together a practical guide that covers structure, data parsing, configuration, timeouts, and debugging techniques.
Structuring Your Tests
A well-structured test suite makes it easier to locate and fix failing tests.
- Keep your tests modular. Use
describeblocks to group related tests. - Write reusable helpers for login, navigation, or data entry.
- Organize test files by feature (e.g.,
login.spec.ts,dashboard.spec.ts).
Data Parsing Techniques
Data handling often causes hidden issues. Some tips:
- Use
JSON.parse()for structured test data and load it from external files. - For CSV data, use libraries like papaparse or csv-parse.
- Ensure consistent data types — always cast numbers explicitly when reading from strings.
- Use environment variables for sensitive values like credentials.
By standardizing how you parse and use data, you reduce unexpected mismatches during tests.
Configuration Techniques
Playwright offers a central playwright.config.ts file that controls how tests run. Key settings include:
-
Browsers: Run against multiple browsers by setting
projects. -
Retries: Add retries for flaky tests with
retries: 2. -
Reporters: Use
htmlorjsonreporters for better visibility. -
Base URL: Define
use: { baseURL: "http://localhost:3000" }to simplify navigation.
Keep configurations consistent across environments using .env files and environment variables.
Handling Timeouts
Timeouts are one of the most common debugging headaches.
-
Global Timeout: Set in
playwright.config.tswithtimeout: 30000. -
Action Timeout: Control time for specific actions using
page.setDefaultTimeout(5000). -
Navigation Timeout: Use
page.setDefaultNavigationTimeout(10000)to catch slow page loads.
✅ Always prefer await page.waitForSelector() over hard waits like page.waitForTimeout(5000).
Proper timeout management prevents both flaky tests and long waits during failures.
Debugging Techniques
When a test fails, use these approaches to identify the root cause quickly:
- Run with
npx playwright test --debugto open the inspector. - Use
page.pause()inside a test to stop execution and explore manually. - Enable tracing with
npx playwright test --trace onto capture screenshots, console logs, and network calls. - Add
console.log()statements for critical variables to check runtime values. - Capture video or screenshots on failure by enabling it in the config file.
These methods help you narrow down issues without guesswork.
Final Thoughts
Debugging doesn’t have to be painful.
By combining structured tests, clean configuration, and the right tools, you can save hours during development and focus on building great tests instead of chasing errors.
Hope this helps you debug faster!
Written by Pranav Bharti
Top comments (1)
While debugging flaky Playwright tests, I mostly lean on trace mode and the trace viewer - they’re clutch for spotting selector or timing hiccups. Running tests in headed mode with --debug and stepping through the Playwright Inspector saves me a ton of time. For setup, I stick with a base config, throw in environment-specific tweaks, and keep global timeouts steady. I vibe with JSON data files because they’re super clear, and I make sure each test checks just one behavior, using reusable fixtures for stuff like login and navigation. One thing I wish I’d learned earlier: always keep tracing on - it makes debugging so much smoother.