|
| 1 | +--- |
| 2 | +description: 'Playwright Python AI test generation instructions based on official documentation.' |
| 3 | +applyTo: '**' |
| 4 | +--- |
| 5 | + |
| 6 | +# Playwright Python Test Generation Instructions |
| 7 | + |
| 8 | +## Test Writing Guidelines |
| 9 | + |
| 10 | +### Code Quality Standards |
| 11 | +- **Locators**: Prioritize user-facing, role-based locators (get_by_role, get_by_label, get_by_text) for resilience and accessibility. |
| 12 | +- **Assertions**: Use auto-retrying web-first assertions via the expect API (e.g., expect(page).to_have_title(...)). Avoid expect(locator).to_be_visible() unless specifically testing for a change in an element's visibility, as more specific assertions are generally more reliable. |
| 13 | +- **Timeouts**: Rely on Playwright's built-in auto-waiting mechanisms. Avoid hard-coded waits or increased default timeouts. |
| 14 | +- **Clarity**: Use descriptive test titles (e.g., def test_navigation_link_works():) that clearly state their intent. Add comments only to explain complex logic, not to describe simple actions like "click a button." |
| 15 | + |
| 16 | +### Test Structure |
| 17 | +- **Imports**: Every test file should begin with from playwright.sync_api import Page, expect. |
| 18 | +- **Fixtures**: Use the page: Page fixture as an argument in your test functions to interact with the browser page. |
| 19 | +- **Setup**: Place navigation steps like page.goto() at the beginning of each test function. For setup actions shared across multiple tests, use standard Pytest fixtures. |
| 20 | + |
| 21 | +### File Organization |
| 22 | +- **Location**: Store test files in a dedicated tests/ directory or follow the existing project structure. |
| 23 | +- **Naming**: Test files must follow the test_<feature-or-page>.py naming convention to be discovered by Pytest. |
| 24 | +- **Scope**: Aim for one test file per major application feature or page. |
| 25 | + |
| 26 | +## Assertion Best Practices |
| 27 | +- **Element Counts**: Use expect(locator).to_have_count() to assert the number of elements found by a locator. |
| 28 | +- **Text Content**: Use expect(locator).to_have_text() for exact text matches and expect(locator).to_contain_text() for partial matches. |
| 29 | +- **Navigation**: Use expect(page).to_have_url() to verify the page URL. |
| 30 | +- **Assertion Style**: Prefer `expect` over `assert` for more reliable UI tests. |
| 31 | + |
| 32 | + |
| 33 | +## Example |
| 34 | + |
| 35 | +```python |
| 36 | +import re |
| 37 | +import pytest |
| 38 | +from playwright.sync_api import Page, expect |
| 39 | + |
| 40 | +@pytest.fixture(scope="function", autouse=True) |
| 41 | +def before_each_after_each(page: Page): |
| 42 | + # Go to the starting url before each test. |
| 43 | + page.goto("https://playwright.dev/") |
| 44 | + |
| 45 | +def test_main_navigation(page: Page): |
| 46 | + expect(page).to_have_url("https://playwright.dev/") |
| 47 | + |
| 48 | +def test_has_title(page: Page): |
| 49 | + # Expect a title "to contain" a substring. |
| 50 | + expect(page).to_have_title(re.compile("Playwright")) |
| 51 | + |
| 52 | +def test_get_started_link(page: Page): |
| 53 | + page.get_by_role("link", name="Get started").click() |
| 54 | + |
| 55 | + # Expects page to have a heading with the name of Installation. |
| 56 | + expect(page.get_by_role("heading", name="Installation")).to_be_visible() |
| 57 | +``` |
| 58 | + |
| 59 | +## Test Execution Strategy |
| 60 | + |
| 61 | +1. **Execution**: Tests are run from the terminal using the pytest command. |
| 62 | +2. **Debug Failures**: Analyze test failures and identify root causes |
0 commit comments