企业官网建设流程全解析

1. 项目概述：为什么断言是自动化测试的灵魂

在构建Django+Vue自动化测试平台的过程中，我们一路从环境搭建、前后端分离架构设计，走到了Web UI自动化的核心环节。当脚本能够自动打开浏览器、点击按钮、输入文本时，很多新手会认为自动化已经大功告成。然而，真正的考验才刚刚开始——如何判断脚本执行的结果是正确的？这就是断言（Assertion）登场的时候。

断言，简单来说，就是自动化测试中的“检查点”。它像一个严格的质检员，在每个关键步骤后验证实际结果是否符合预期。没有断言的自动化脚本，就像一辆没有方向盘的汽车，虽然能跑起来，但你永远不知道它会开到哪里去，也无法判断任务是否成功完成。在Playwright中，断言不仅仅是简单的assert语句，它提供了一套丰富、智能且对异步操作友好的断言机制，这是其相较于传统Selenium WebDriver的一大优势。

我见过不少团队在初期为了快速上线，只写操作不写断言，或者断言写得非常简陋。结果就是，测试脚本运行时一片“绿色”（通过），上线后却bug频出。问题就在于，那些“通过”的测试可能根本没有验证到核心的业务逻辑。因此，深入理解并熟练运用Playwright的断言，是将自动化脚本从“玩具”升级为“武器”的关键一步。本篇，我们就来彻底拆解Playwright的断言体系，让你写的每一个检查点都精准有力。

2. Playwright断言机制深度解析

2.1 两种风格的断言：expectAPI 与 传统assert

Playwright主要提供了两种断言方式，它们适用于不同的场景和编程习惯。

第一种是Playwright推荐的expectAPI。这是Playwright专门为测试场景设计的一套断言库，语法更贴近自然语言，并且内置了自动等待机制，这是它最大的亮点。你不需要手动写time.sleep或者复杂的显式等待逻辑，expect在执行断言前会自动等待条件成立，直到超时。

from playwright.sync_api import expect # expect API 示例：它会自动等待元素可见、可操作 expect(page.locator("button#submit")).to_be_visible() expect(page.locator(".success-message")).to_have_text("操作成功！")

第二种是Python内置的assert语句。这种方式更直接，但它不具备自动等待功能。它会在执行的瞬间立刻检查条件，如果当时条件不满足，测试就会立刻失败。因此，在使用assert时，你通常需要结合Playwright的同步等待方法（如wait_for_selector）来确保元素状态稳定。

# 传统 assert 示例：需要手动确保元素状态 page.locator("button#submit").wait_for(state="visible") assert page.locator("button#submit").is_visible() is True page.locator(".success-message").wait_for() assert page.locator(".success-message").text_content() == "操作成功！"

如何选择？我的经验是：在绝大多数UI自动化场景下，优先使用expectAPI。它的自动等待能极大地简化代码，提高脚本的稳定性和可读性，避免因页面加载或渲染延迟导致的“假失败”。只有在验证一些非UI的、瞬时性的状态（比如某个变量的值、某个同步函数的返回值）时，才使用传统的assert。

2.2expectAPI 的自动等待与超时控制

expectAPI的自动等待机制是其核心价值。它的工作原理是：当你调用一个断言匹配器（如to_be_visible()）时，Playwright会在一个设定的时间窗口内（默认5秒）反复检查条件是否满足。只要在超时前条件成立，断言就立即通过；如果直到超时条件仍未满足，则断言失败并抛出错误。

这个超时时间是可以全局或局部配置的。在自动化测试平台中，我们通常需要根据网络环境和应用响应速度来调整这个值。

from playwright.sync_api import Page, expect def test_slow_loading_page(page: Page): # 方法1：在具体的expect断言中设置超时 # 等待这个元素出现，最多等10秒 expect(page.locator("#slow-element")).to_be_visible(timeout=10000) # 方法2：设置全局的expect超时（在Playwright配置或fixture中） # 通常在pytest的fixture或conftest.py中设置 # page.set_default_timeout(30000) # 设置页面操作的默认超时 # expect.set_options(timeout=10000) # 设置expect的默认超时

实操心得：不要盲目地将超时设置得特别长。过长的超时会掩盖性能问题，让失败的测试用例执行时间变得难以忍受。我通常的实践是：在测试平台的配置文件中，根据测试环境（如测试内网、预发布环境、生产镜像）设置不同的默认超时。内网可以短一些（如10秒），外网或性能较差的环境可以长一些（如30秒）。对于某些已知加载很慢的特定页面或组件，再在用例中单独覆盖超时设置。

2.3 断言的可读性与链式调用

expectAPI采用了类似自然语言的链式调用，这让测试代码读起来就像在描述测试预期。

# 链式调用，清晰表达“期望提交按钮是可见的、可点击的，并且文本是‘提交’” expect(page.locator("button#submit")).to_be_visible().to_be_enabled().to_have_text("提交") # 这比下面这种分离的assert要直观得多 assert page.locator("button#submit").is_visible() assert page.locator("button#submit").is_enabled() assert page.locator("button#submit").text_content() == "提交"

注意事项：虽然链式调用很优雅，但要注意，链式中的每个匹配器（matcher）都是独立的断言，并且都会触发其自身的自动等待周期。这意味着上面链式调用的总等待时间可能是三个匹配器超时时间的总和。如果对执行速度有极致要求，且你确信元素在满足第一个条件时后续条件也必然满足，可以考虑合并断言或使用自定义匹配器。

3. 核心断言匹配器（Matchers）实战详解

Playwright提供了丰富的匹配器来验证各种状态。下面我们分类讲解最常用、最核心的匹配器。

3.1 页面与导航断言

这类断言用于验证页面级的属性，如标题、URL等，常用于测试路由跳转是否正确。

def test_page_navigation(page: Page): page.goto("https://example.com/login") # 1. 断言页面标题 expect(page).to_have_title("Example Domain") # 或者包含某个关键词 expect(page).to_have_title(re.compile(r"Example")) # 2. 断言当前URL expect(page).to_have_url("https://example.com/login") # 使用正则表达式匹配URL的一部分，非常灵活 expect(page).to_have_url(re.compile(r".*/login$")) # 3. 结合操作进行断言 page.locator("text=Go to Dashboard").click() # 点击后，断言页面URL发生了变化，跳转到了dashboard expect(page).to_have_url(re.compile(r".*/dashboard"))

避坑技巧：to_have_url在进行全等匹配时非常严格，包括协议（http/https）、端口、哈希（#）和查询参数（?）。在测试中，我们更常用正则表达式（re.compile）进行部分匹配，这样更健壮，不易受环境或随机参数影响。

3.2 元素状态断言

这是UI自动化中断言最密集的部分，用于验证元素在界面上的表现。

def test_element_states(page: Page): page.goto("https://example.com/form") submit_button = page.locator("button[type='submit']") email_input = page.locator("#email") hidden_element = page.locator(".tooltip") checkbox = page.locator("#agree-terms") # 1. 可见性 expect(submit_button).to_be_visible() expect(hidden_element).to_be_hidden() # 或者 .not_to_be_visible() # 2. 可用性（是否可交互） expect(submit_button).to_be_enabled() # 模拟一个禁用场景 page.locator("#disable-btn").click() expect(submit_button).to_be_disabled() # 3. 元素是否存在於DOM中（无论是否可见） # 这在验证动态加载或移除元素时非常有用 expect(page.locator("#dynamic-element")).to_be_attached() # 4. 焦点状态 email_input.click() expect(email_input).to_be_focused() # 5. 复选框/单选框状态 expect(checkbox).not_to_be_checked() checkbox.check() expect(checkbox).to_be_checked() # 6. 编辑状态（如input是否可编辑） readonly_input = page.locator("#readonly-field") expect(readonly_input).to_be_readonly() expect(email_input).to_be_editable()

常见问题：to_be_visible()断言的是元素在视口中且没有被CSS隐藏（如display: none,visibility: hidden,opacity: 0, 宽度/高度为0）。如果一个元素在DOM中但被滚出屏幕外，它依然是“visible”的。如果需要断言元素在可视区域内，可能需要结合JavaScript或滚动操作。

3.3 元素内容断言

验证元素包含的文本、HTML、属性值或输入框的值。

def test_element_content(page: Page): page.goto("https://example.com/profile") user_name = page.locator(".user-name") bio_textarea = page.locator("#bio") avatar_img = page.locator(".avatar") # 1. 文本内容（精确匹配） expect(user_name).to_have_text("张三") # 文本内容（包含匹配） expect(user_name).to_contain_text("张") # 使用正则表达式匹配文本 expect(user_name).to_have_text(re.compile(r"^张\S+$")) # 2. 输入框/文本域的值 expect(bio_textarea).to_have_value("这是我的个人简介。") # 清空后断言为空 bio_textarea.fill("") expect(bio_textarea).to_be_empty() # 3. HTML内容（谨慎使用，因为HTML结构易变） # expect(page.locator("div.container")).to_have_html("<span>Hello</span>") # 4. 元素属性 expect(avatar_img).to_have_attribute("src", re.compile(r"avatar_\d+\.jpg")) expect(avatar_img).to_have_attribute("alt", "用户头像") # 断言属性存在 expect(avatar_img).to_have_attribute("data-loaded") # 断言属性不存在 expect(avatar_img).not_to_have_attribute("data-error")

重要经验：断言文本时，优先使用to_contain_text()而不是to_have_text()。因为to_have_text()要求完全匹配，包括空白字符，前端一个不经意的空格或换行符就可能导致测试失败。to_contain_text()只检查是否包含子字符串，鲁棒性更强。对于必须精确匹配的场景（如验证错误提示码），再用to_have_text()。

3.4 元素集合断言

当定位器返回多个元素时（如page.locator(“.list-item”)），我们需要对元素集合进行断言。

def test_element_collections(page: Page): page.goto("https://example.com/todo-list") todo_items = page.locator(".todo-item") selected_items = page.locator(".todo-item:checked") # 1. 断言元素数量 expect(todo_items).to_have_count(5) # 数量大于、小于等于 expect(todo_items).to_have_count(gte=3) # 大于等于3 expect(selected_items).to_have_count(lte=2) # 小于等于2 # 2. 断言集合中至少有一个元素满足某个条件 # 例如，检查任务列表中是否至少包含一个“紧急”任务 expect(todo_items.filter(has_text="紧急")).to_have_count(gte=1) # 或者使用更简洁的 locator.first 或 .nth(index) expect(todo_items.first).to_contain_text("晨会") # 3. 遍历集合并对每个元素进行断言（高级用法） all_texts = todo_items.all_text_contents() for text in all_texts: assert text.strip() != "" # 确保每个任务项都有文字

性能提示：对元素集合进行断言（尤其是to_have_count）时，Playwright需要先查询到所有匹配的元素。如果页面列表很长（成百上千条），这个操作可能会有性能开销。在非必要时，尽量避免对超大列表进行全量计数断言，可以改为断言第一页或前N项的数量。

3.5 非UI状态断言：网络请求与浏览器环境

Playwright的强大之处在于，它不仅能断言UI，还能断言浏览器环境和非可视化的状态。

def test_non_ui_assertions(page: Page): # 监听并断言网络请求 with page.expect_response("**/api/user/profile") as response_info: page.locator("#refresh-profile").click() response = response_info.value # 断言API响应状态码为200 expect(response).to_be_ok() # 等价于 assert response.status == 200 # 更细粒度的响应断言 expect(response).to_have_status(200) # 断言响应头 expect(response).to_have_header("content-type", "application/json") # 断言响应体（JSON） response_json = response.json() assert response_json["status"] == "success" # 断言页面弹窗（alert, confirm, prompt） page.on("dialog", lambda dialog: dialog.accept()) # 触发一个确认对话框 page.evaluate("window.confirm('确定要删除吗？')") # 在真实场景中，这里可以断言对话框文本 # 需要通过 page.on(“dialog”, handler) 在handler里断言 # 断言浏览器下载事件（需要配合下载监听） # 这是一个高级特性，用于验证点击后是否触发了文件下载

应用场景：在网络请求断言中，结合page.route或page.on(‘request’/‘response’)，可以实现对前端API调用的完整监控和断言。这对于测试前端与后端的交互逻辑、验证请求参数是否正确、响应数据是否符合预期至关重要，是UI自动化测试走向“端到端”验证的关键。

4. 在Django+Vue测试平台中集成与封装断言

4.1 设计平台专用的断言工具类

在自动化测试平台中，我们不希望每个测试用例都写一堆原始的expect调用。为了提高代码复用性和可维护性，封装一个断言工具类是很好的实践。

# utils/assertions.py import re from typing import Any, Optional, Pattern from playwright.sync_api import Page, Locator, expect, Response class PlatformAssertions: """自动化测试平台专用断言工具类""" def __init__(self, page: Page): self.page = page def assert_toast_message(self, expected_text: str, timeout: float = 5000): """断言Toast轻提示消息。 假设平台的Toast组件有一个固定的选择器 `.ant-message-success` 或 `.el-message` """ toast_locator = self.page.locator(".ant-message-success:visible, .el-message:visible").last expect(toast_locator).to_contain_text(expected_text, timeout=timeout) # 等待Toast自动消失，避免影响后续操作 expect(toast_locator).to_be_hidden(timeout=timeout) def assert_form_field_error(self, field_locator: Locator, expected_error: str): """断言表单字段的错误提示。 假设错误提示在字段下方的 `.ant-form-item-explain` 元素内。 """ error_container = field_locator.locator("xpath=./following-sibling::*[contains(@class, 'form-item-explain')]") expect(error_container).to_be_visible() expect(error_container).to_contain_text(expected_error) def assert_table_has_record(self, table_locator: Locator, **kwargs): """断言表格中包含符合特定条件的记录。 kwargs 是字段名和期望值的键值对。 例如: assert_table_has_record(table, username="张三", status="启用") """ # 构建一个XPath表达式来匹配所有行，并检查是否存在满足所有条件的行 xpath_conditions = [] for field, value in kwargs.items(): # 这里需要根据平台前端表格的实际DOM结构来调整 # 假设每个字段有一个 `data-column="${field}"` 的属性 xpath_conditions.append(f".//td[@data-column='{field}' and normalize-space(.)='{value}']") if xpath_conditions: combined_condition = " and ".join([f"../{cond}" for cond in xpath_conditions]) # 查找满足所有条件的行 row_locator = table_locator.locator(f"xpath=.//tr[{combined_condition}]") expect(row_locator).to_be_attached() expect(row_locator).to_have_count(gte=1) def assert_api_response(self, url_pattern: str, expected_status: int = 200, expected_data_part: Optional[dict] = None): """监听并断言一个API调用的响应。 这是一个简化示例，实际中可能需要更复杂的请求/响应匹配。 """ # 注意：这个方法会阻塞，直到匹配到响应或超时。 # 它适用于知道某个操作一定会触发特定API请求的场景。 with self.page.expect_response(lambda resp: re.match(url_pattern, resp.url) and resp.status == expected_status) as resp_info: # 通常在这里执行触发请求的操作，比如点击按钮 # 这个操作需要由调用者执行 pass response = resp_info.value if expected_data_part: response_json = response.json() for key, value in expected_data_part.items(): assert response_json.get(key) == value, f"API响应字段 {key} 不匹配。期望: {value}, 实际: {response_json.get(key)}" return response # 返回响应对象，供进一步断言 # 在conftest.py或测试用例中这样使用 # @pytest.fixture # def assertions(page): # return PlatformAssertions(page)

4.2 与Pytest测试框架深度结合

我们的测试平台底层使用Pytest来组织用例。Playwright的expect可以与Pytest的断言失败信息完美结合，但我们可以做得更好。

# conftest.py import pytest from playwright.sync_api import Page from utils.assertions import PlatformAssertions @pytest.fixture def assertions(page: Page) -> PlatformAssertions: """提供一个封装好的断言工具fixture""" return PlatformAssertions(page) # 自定义一个Pytest钩子，让Playwright的断言失败信息更友好 def pytest_assertrepr_compare(config, op, left, right): """当expect断言失败时，美化错误输出。 这是一个高级技巧，需要了解pytest的内部机制。 注意：原生的expect失败信息已经很好，这里只是示例如何自定义。 """ # 这里可以尝试解析来自expect的异常，并返回一个更清晰的错误信息列表 # 由于expect抛出的是AssertionError，我们可以检查其错误信息是否包含特定模式 pass # 测试用例示例 def test_user_login_success(page: Page, assertions: PlatformAssertions): """测试用户登录成功场景""" page.goto("/login") # 假设平台已配置基础URL page.fill("#username", "testuser") page.fill("#password", "correct_password") page.click("button[type='submit']") # 使用封装的断言方法 assertions.assert_toast_message("登录成功") # 断言页面跳转到了仪表盘 expect(page).to_have_url(re.compile(r".*/dashboard")) # 断言用户菜单显示了正确的用户名 expect(page.locator(".user-menu")).to_contain_text("testuser")

4.3 处理异步加载与动态内容的断言策略

现代Vue.js应用大量使用异步加载和动态渲染，这对断言时机提出了挑战。

def test_async_data_table(page: Page, assertions: PlatformAssertions): """测试一个通过API异步加载数据的表格""" page.goto("/user-management") # 1. 首先断言加载状态 loading_skeleton = page.locator(".ant-table-placeholder .ant-skeleton") expect(loading_skeleton).to_be_visible() # 等待加载完成，骨架图消失 expect(loading_skeleton).not_to_be_attached(timeout=10000) # 2. 断言表格数据已加载（行数大于0） table_rows = page.locator(".ant-table-tbody tr") expect(table_rows).to_have_count(gte=1) # 3. 使用更稳健的方法：等待特定内容出现 # 假设第一行总会显示一个已知的管理员用户 expect(table_rows.first).to_contain_text("admin") # 4. 模拟搜索过滤，断言结果 page.fill(".search-input", "张三") page.click(".search-button") # 搜索后，再次等待加载完成 expect(loading_skeleton).not_to_be_attached(timeout=5000) # 断言结果行都包含“张三” filtered_rows = page.locator(".ant-table-tbody tr") for i in range(filtered_rows.count()): # 注意：这里用 all_text_contents 一次性获取所有文本，避免在循环内频繁查询DOM row_text = filtered_rows.nth(i).text_content() assert "张三" in row_text # 或者使用Playwright的 `:has-text` 伪类选择器 expect(page.locator(".ant-table-tbody tr:has-text(\"张三\")")).to_be_attached()

核心技巧：对于动态内容，断言的黄金法则是“等待状态稳定，再断言结果”。优先使用Playwright内置的自动等待（expect或locator.wait_for），而不是硬编码的sleep。同时，断言“数据已加载”的一个可靠信号是某个加载中状态（如骨架屏、loading图标）的消失，或者某个必然存在的数据元素的出现。

5. 高级断言技巧与复杂场景处理

5.1 软断言（Soft Assertions）与断言收集

在UI测试中，有时我们希望一个用例执行所有检查点，即使中间有失败，也继续执行并最终报告所有失败，而不是遇到第一个失败就停止。这被称为“软断言”。

Playwright本身没有内置的软断言，但我们可以利用Python的上下文管理器或Pytest的钩子来模拟。

import contextlib from typing import List from playwright.sync_api import Page, expect class SoftAssertContext: """一个简单的软断言上下文管理器""" def __init__(self): self.errors: List[AssertionError] = [] def expect(self, condition, message=""): """模仿expect的软断言版本""" try: # 这里需要根据实际condition来调用真正的expect # 这是一个简化示例，实际实现更复杂 pass except AssertionError as e: self.errors.append(AssertionError(f"{message}: {e}")) def __enter__(self): return self def __exit__(self, exc_type, exc_val, exc_tb): if self.errors: # 将所有收集到的错误信息合并抛出 error_messages = "\n".join(str(e) for e in self.errors) raise AssertionError(f"软断言失败，共有 {len(self.errors)} 个错误:\n{error_messages}") # 使用示例（概念性） def test_user_profile_comprehensive(page: Page): page.goto("/profile") with SoftAssertContext() as checker: # 这些断言中如果有失败的，不会立即终止测试 checker.expect(page.locator(".user-name").is_visible(), "用户名应可见") checker.expect(page.locator(".user-email").text_content() == "user@example.com", "邮箱应正确") checker.expect(page.locator(".user-role").to_have_text("管理员"), "角色应正确") # ... 更多断言 # 退出上下文管理器时，如果收集到任何错误，会一次性抛出

更实用的方案：对于大多数项目，使用Pytest的pytest-assume插件是更简单可靠的选择。它提供了pytest.assume函数来实现软断言。

pip install pytest-assume

import pytest def test_with_soft_assertions(page: Page): page.goto("/profile") # 使用 pytest.assume，即使失败也会继续执行 pytest.assume(page.locator(".user-name").is_visible() is True) pytest.assume(page.locator(".user-email").text_content() == "user@example.com") pytest.assume(page.locator(".user-role").text_content() == "管理员") # 测试结束时，所有失败的 assume 会被汇总报告

5.2 视觉回归测试与截图断言

除了逻辑断言，有时我们还需要验证UI的外观没有意外变化，这就是视觉回归测试。Playwright可以轻松进行截图比较。

import hashlib from pathlib import Path def test_homepage_screenshot(page: Page): """主页截图对比测试""" page.goto("/") page.wait_for_load_state("networkidle") # 等待网络空闲，页面稳定 # 1. 获取当前截图 screenshot_bytes = page.screenshot(full_page=True) current_hash = hashlib.md5(screenshot_bytes).hexdigest() # 2. 定义基准图路径（通常存储在项目 test_screenshots/baseline/ 目录下） baseline_dir = Path(__file__).parent / "test_screenshots" / "baseline" baseline_dir.mkdir(parents=True, exist_ok=True) baseline_file = baseline_dir / "homepage.png" # 3. 如果基准图不存在，则保存当前截图作为基准（首次运行或更新基准） if not baseline_file.exists(): baseline_file.write_bytes(screenshot_bytes) print(f"基准图已创建: {baseline_file}") return # 4. 读取基准图并计算哈希 baseline_bytes = baseline_file.read_bytes() baseline_hash = hashlib.md5(baseline_bytes).hexdigest() # 5. 简单哈希对比（快速但不够精确，像素级变化就会失败） if current_hash != baseline_hash: # 哈希不同，可能发生了视觉变化 # 保存差异图或当前失败图，用于人工审查 failed_dir = Path(__file__).parent / "test_screenshots" / "failed" failed_dir.mkdir(parents=True, exist_ok=True) failed_file = failed_dir / "homepage_failed.png" failed_file.write_bytes(screenshot_bytes) # 这里可以集成更专业的图像对比库，如 pixelmatch, OpenCV # 计算差异度，如果差异在可接受范围内（如<1%），则通过 # 否则抛出断言错误 raise AssertionError(f"主页视觉发生变化。基准图哈希: {baseline_hash}, 当前哈希: {current_hash}. 失败截图已保存至: {failed_file}") print("视觉测试通过。")

注意事项：简单的哈希对比非常严格，任何像素变化都会导致失败，包括时间戳、随机数等动态内容。在生产中，需要结合以下策略：

1. 忽略区域：在截图前，用白色矩形覆盖动态区域（如时间、用户名）。
2. 使用专业的视觉对比库：如pixelmatch，可以设置容差阈值，并生成差异图。
3. 只在关键页面进行：视觉回归测试耗时且维护成本高，通常只用于核心、UI稳定的页面（如登录页、首页框架）。

5.3 自定义匹配器（Custom Matchers）扩展

当平台有特殊的UI组件或业务逻辑时，可以创建自定义匹配器，让断言代码更简洁、语义更清晰。

# utils/custom_matchers.py from playwright.sync_api import Locator, expect import re def to_be_in_active_tab(locator: Locator): """自定义匹配器：断言一个元素在当前激活的标签页内。 假设平台标签页组件，激活的标签页有 `.is-active` 类。 """ # 这个匹配器需要检查目标元素的祖先中，是否有一个包含 `.is-active` 类的标签页容器 # 实现逻辑略复杂，这里展示概念 pass # 更实际的例子：断言一个Vue组件的特定状态 # 假设我们的平台使用Element UI，有一个 `el-switch` 开关组件 def to_be_switched_on(locator: Locator): """断言一个Element UI开关组件处于打开状态""" # 检查内部是否有表示“开”的类，如 `.is-checked` class_attribute = locator.get_attribute("class") if class_attribute and "is-checked" in class_attribute: return True # 或者检查 aria-checked 属性 aria_checked = locator.get_attribute("aria-checked") if aria_checked == "true": return True raise AssertionError(f"开关组件预期为打开状态，但实际未打开。") # 注册自定义匹配器（需要一些猴子补丁技巧，谨慎使用） # 一种更安全的方式是封装成工具函数 def assert_switch_on(switch_locator: Locator): """断言开关已打开的工具函数""" expect(switch_locator).to_have_class(re.compile(r".*is-checked.*")) # 在测试中使用 def test_feature_toggle(page: Page): page.goto("/settings") dark_mode_switch = page.locator(".el-switch__input") # 使用自定义的工具函数 assert_switch_on(dark_mode_switch)

6. 断言最佳实践与常见陷阱排查

6.1 断言设计的最佳实践

1. 一断言一验证：每个断言只验证一件事。不要在一个断言里同时检查文本、颜色和位置。这样失败时才能快速定位问题。
2. 断言业务价值，而非实现细节：断言“登录成功后显示用户仪表盘”，而不是断言“某个<div>的CSS类变成了active”。后者在前端重构时极易失效。
3. 使用有意义的失败信息：expect默认的错误信息已经不错，但在自定义assert时，务必提供清晰的错误信息。

   # 差 assert item_count == 5 # 好 assert item_count == 5, f"期望列表有5项，实际找到 {item_count} 项。"

4. 优先使用Playwright的自动等待断言：99%的情况应该用expect，而不是assert+sleep/wait_for。
5. 为不稳定的元素设置合理的超时：对于已知加载慢的元素，适当增加timeout参数，但要在测试报告里记录，以便后续性能优化。

6.2 常见断言失败原因与排查表

6.3 调试技巧：当断言失败时

1. 启用慢动作和录制：在测试运行时，添加slow_mo参数，并录制视频，可以清晰看到失败前发生了什么。

   browser = p.chromium.launch(headless=False, slow_mo=1000) # 每个操作延迟1秒 context = browser.new_context(record_video_dir=”videos/“)

2. 失败时截图：利用Pytest的钩子或Playwright的on(“page”)事件监听器，在断言失败时自动截取屏幕、控制台日志和网络请求。

   # 在 conftest.py 中 @pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: # 获取测试用例中的 page fixture page = item.funcargs.get("page") if page: screenshot_path = f"failure_{item.name}.png" page.screenshot(path=screenshot_path, full_page=True) print(f"测试失败截图已保存: {screenshot_path}")

3. 使用Playwright Inspector：在调试模式下运行测试 (PWDEBUG=1)，Playwright会打开一个图形化界面，允许你逐步执行、查看选择器、检查页面状态。

断言是自动化测试的“大脑”，它决定了测试的智能程度和可靠性。在Django+Vue测试平台中构建一套健壮、可维护的断言体系，是保障平台产出价值的关键。从简单的元素存在性检查，到复杂的异步逻辑与视觉回归，Playwright提供了强大的工具集。结合平台业务进行合理封装，并遵循最佳实践，你的自动化测试将不再是脆弱的“脚本”，而成为值得信赖的“质量守门员”。