Initial commit

skills/test-maintainer/resources/best-practices.md

@@ -0,0 +1,81 @@
+# Playwright Testing Best Practices Checklist
+
+## Test Structure
+
+- [ ] Tests follow AAA pattern (Arrange-Act-Assert)
+- [ ] One assertion per test (or closely related assertions)
+- [ ] Tests are independent and can run in any order
+- [ ] Clear, descriptive test names using "should" format
+- [ ] Proper use of test.describe for grouping related tests
+
+## Locators
+
+- [ ] **ONLY** data-testid locators used (no CSS/XPath)
+- [ ] data-testid values are semantic and descriptive
+- [ ] No brittle selectors (class names, IDs, XPath)
+- [ ] Locators are unique on the page
+- [ ] Use .first() or .nth() for intentional multiple elements
+
+## Waiting & Timing
+
+- [ ] Explicit waits before interactions
+- [ ] NO hardcoded waits (page.waitForTimeout())
+- [ ] Use waitForLoadState() after navigation
+- [ ] Wait for network requests when needed
+- [ ] Proper timeouts for slow operations
+
+## Code Organization
+
+- [ ] No code duplication - extract to utilities/Page Objects
+- [ ] Use Page Object Model for complex pages
+- [ ] Common setup in fixtures
+- [ ] Utilities for repeated actions
+- [ ] Clear file and folder structure
+
+## TypeScript
+
+- [ ] All functions have proper types
+- [ ] No `any` types (use specific types)
+- [ ] Interfaces for complex data structures
+- [ ] Async/await used correctly
+- [ ] Proper error handling
+
+## Test Isolation
+
+- [ ] Tests don't depend on each other
+- [ ] Clean state before each test
+- [ ] Proper cleanup in afterEach/afterAll
+- [ ] No shared mutable state
+- [ ] Each test creates its own data
+
+## Assertions
+
+- [ ] Use appropriate matchers (toBeVisible, toContainText, etc.)
+- [ ] Assertions have proper error messages
+- [ ] Wait for conditions before asserting
+- [ ] Check both positive and negative cases
+- [ ] Use expect() consistently
+
+## Configuration
+
+- [ ] Proper timeout settings
+- [ ] Retries enabled for flaky tests
+- [ ] Screenshot on failure
+- [ ] Trace on first retry
+- [ ] Parallel execution configured
+
+## Documentation
+
+- [ ] Complex test logic has comments
+- [ ] Page Objects are documented
+- [ ] Utilities have JSDoc comments
+- [ ] README explains test structure
+- [ ] Known issues documented
+
+## Maintenance
+
+- [ ] Regular review of flaky tests
+- [ ] Remove obsolete tests
+- [ ] Update tests when UI changes
+- [ ] Refactor duplicate code
+- [ ] Keep dependencies updated