Selenium to Playwright Migration Part 7: Quick Reference Card and Migration Checklist
This is part of the Selenium to Playwright Migration Series. Follow the complete 7-part tutorial to migrate your test suite from Selenium Java to Playwright TypeScript.
The one-page reference card for your Selenium to Playwright migration. Pin this to your desk, bookmark it, share it with your team.
Contents
The 10 Rules of Migration
- Delete all waits first — Playwright auto-waits for everything
- Replace XPath with semantic locators — getByRole, getByLabel, getByText
- Remove base classes — use Playwright fixtures instead
- Delete PageFactory — Playwright locators are lazy by default
- Convert Assert to expect() — auto-retry assertions are more reliable
- One config file replaces 5 — playwright.config.ts replaces testng.xml, listeners, properties
- Go bottom-up — Config, Utils, Pages, Modules, Tests, CI
- Run parallel from day one — fullyParallel: true in config
- Use .env for everything — no more Java properties files
- AI converts 80%, you validate 100% — never trust AI output without review
Migration Checklist
- Project initialized with
npm init playwright@latest - playwright.config.ts configured (parallel, retries, reporters)
- .env file created with all environment variables
- src/config/index.ts exports typed configuration
- All Page Objects converted (no inheritance, semantic locators)
- Module layer created for business flows
- All tests converted to test() blocks with async/await
- Zero WebDriverWait or Thread.sleep remaining
- Zero XPath locators (replaced with getByRole/getByLabel)
- GitHub Actions CI pipeline configured with sharding
- All tests pass in headless mode
- Trace and video configured for failure debugging
- Old Selenium suite running in parallel (during transition)
- Team trained on Playwright debugging (Trace Viewer, UI Mode)
Common Gotchas
| Gotcha | Solution |
|---|---|
Forgetting await | TypeScript strict mode catches this. Enable "strict": true in tsconfig.json |
| Using CSS selectors for everything | Prefer getByRole/getByLabel. CSS selectors break when classes change |
| Creating wait helper classes | Delete them. Use expect() with custom timeouts when needed |
| Extending a base class | Use fixtures for shared setup. Composition over inheritance |
| Running tests sequentially | Set fullyParallel: true. Each test gets its own BrowserContext |
| Committing .env files | Add .env to .gitignore. Use CI secrets for pipeline values |
Estimated Timelines
| Suite Size | Team Size | Timeline | Est. Cost |
|---|---|---|---|
| 50 tests | 1 engineer | 3-4 weeks | Internal |
| 200 tests | 2 engineers | 2-3 months | $20-30K |
| 500 tests | 3 engineers | 3-6 months | $50-80K |
| 1000+ tests | 4+ engineers | 6-12 months | $100K+ |
This completes the Selenium to Playwright Migration Series. Go back to Part 1 to start from the beginning, or bookmark any part for reference.
