AgentSkillsCN

playwright-python-test-generation

运用基于角色的定位器、以Web为先的断言，以及Pytest的组织方式，生成稳健的Playwright Python测试。在使用Playwright与Python编写、审查或调试UI测试或端到端测试时使用。涵盖定位策略、断言最佳实践、文件组织、Fixture设置，以及测试执行策略。

SKILL.md
--- frontmatter
name: playwright-python-test-generation
description: Generate resilient Playwright Python tests using role-based locators, web-first assertions, and Pytest organisation. Use when writing, reviewing, or debugging UI or end-to-end tests with Playwright and Python. Covers locator strategy, assertion best practices, file organisation, fixture setup, and test execution strategy.
argument-hint: "[feature or page to test, e.g. 'login page' or 'file upload flow']"

Playwright Python Test Generation Instructions

Write resilient Playwright tests using role-based locators, web-first assertions, and clear pytest organisation.

Code Quality Standards

Locators

  • •Prioritise user-facing, role-based locators for resilience and accessibility:
    • •get_by_role(), get_by_label(), get_by_text(), get_by_placeholder()
  • •Avoid fragile CSS selectors or XPath unless no role-based alternative exists

Assertions

  • •Use auto-retrying web-first assertions via the expect API:
    • •expect(page).to_have_title(...) ✅
    • •expect(locator).to_have_text(...) ✅
    • •expect(locator).to_be_visible() — use only when testing visibility change specifically
  • •Prefer expect over plain assert for UI tests

Timeouts

  • •Rely on Playwright's built-in auto-waiting mechanisms
  • •Never add time.sleep() or hardcoded waits
  • •Never increase default timeouts unless absolutely required and documented

Clarity

  • •Use descriptive test titles: def test_navigation_link_navigates_to_doc_page():
  • •Add comments only to explain complex logic — not to describe simple actions like "click a button"

Test Structure

Imports

Every test file must begin with:

python
from playwright.sync_api import Page, expect

Fixtures

  • •Use page: Page fixture as argument in test functions
  • •Place shared setup in standard Pytest fixtures
  • •Navigation (page.goto()) goes at the beginning of each test function

File Organisation

  • •Location: tests/ directory (or follow existing project structure)
  • •Naming: test_<feature-or-page>.py — required for Pytest discovery
  • •Scope: One test file per major application feature or page

Assertion Reference

ScenarioAssertion
Element countexpect(locator).to_have_count(n)
Exact textexpect(locator).to_have_text("exact")
Partial textexpect(locator).to_contain_text("partial")
URL checkexpect(page).to_have_url("https://...")
Title checkexpect(page).to_have_title(re.compile("..."))
Visibilityexpect(locator).to_be_visible()

Example Test File

python
import re
import pytest
from playwright.sync_api import Page, expect

@pytest.fixture(scope="function", autouse=True)
def before_each_after_each(page: Page):
    page.goto("https://example.com/")

def test_has_title(page: Page):
    expect(page).to_have_title(re.compile("Example"))

def test_get_started_link(page: Page):
    page.get_by_role("link", name="Get started").click()
    expect(page.get_by_role("heading", name="Installation")).to_be_visible()

def test_navigation_link_works(page: Page):
    page.get_by_role("navigation").get_by_role("link", name="Docs").click()
    expect(page).to_have_url(re.compile(r"/docs"))

Test Execution Strategy

  1. •Execution: Run from terminal using pytest or pytest tests/
  2. •Debug Failures: Analyse test failures, identify root causes
  3. •Trace Viewer: Use --tracing=on flag for visual failure debugging
  4. •Screenshots: Capture on failure with page.screenshot(path="failure.png")