31. Code Review & Best Practices
Playwright with Python · 244 pages source format
Naming conventions, DRY principles # Avoid: def test1(page): ... # Prefer: descriptive, scenario-revealing names def test_login_fails_with_incorrect_password(page): ...
What you'll learn
- Naming conventions, DRY principles
- Common anti-patterns in automation
- Documentation standards for shared frameworks
Naming conventions, DRY principles
...
...
Pointers: A test name should describe the scenario and expected outcome well enough that a failure notification alone (just the test name, no need to open the code) tells a reader roughly what broke. DRY (Don't Repeat Yourself) in this context mainly means:
object method (Chapter 14) or a utility function (Chapter 29), not copy-pasted.
# Prefer: descriptive, scenario-revealing namesInteractive study board
Common anti-patterns in automation
explicit state-based waits (Chapter 8).
every minor markup refactor.
(e.g., relying on data another test created). This breaks under parallel execution
(Chapter 22) and makes debugging a failure much harder, since the "real" cause
might be in an unrelated test file.
correct behavior.
logical grouping, instead of organized-by-feature files (Chapter 29's folder architecture).
- Hardcoded waits (time.sleep()) instead of relying on auto-waiting or
- Brittle CSS selectors instead of role-based locators (Chapter 5), breaking on
- Order-dependent tests — a test that only passes if a different test ran first
- Overly broad assertions — asserting page.url != "" instead of asserting the actual expected URL, giving false confidence that doesn't actually verify
- God test files — one enormous test file covering an entire module with no
Interactive study board
Documentation standards for shared frameworks
A framework other engineers will onboard onto needs:
only this file.
shopping cart as a side effect").
patterns, and folder structure decisions — so contributors don't reinvent or
diverge from established patterns.
Pointers: This chapter plays directly to your existing QA documentation strength — a framework with excellent test coverage but no documentation is nearly as hard to maintain as one with poor coverage, since new contributors can't safely extend what they don't understand.
- A root README.md explaining setup steps (environment, install, first test run) — someone should be able to go from a fresh clone to a passing test run following
- Docstrings on non-obvious utility functions and page object methods, especially ones with side effects worth knowing about (e.g., "this method also clears the
- A short "conventions" doc covering marker vocabulary (Chapter 13), naming