当前位置：首页 > news >正文

从零搭建最简pytest+Playwright UI自动化测试框架

news 2026/6/30 3:29:05

1. 项目概述：为什么需要一个“最简”的自动化测试项目？

做UI自动化测试的同行，估计都经历过这样的阶段：一开始雄心勃勃，想搭建一个“大而全”的测试框架，把页面对象模型（PO）、数据驱动、测试报告、持续集成一股脑全塞进去。结果往往是，框架还没搭完，项目需求已经变了；或者框架过于复杂，新同事上手要花一周时间看文档，最后大家宁愿回归手动测试。我自己带团队踩过这个坑，所以后来我们定了个规矩：任何新项目的自动化，都必须从一个“最简可行产品”（MVP）开始。这个“最简 pytest 自动化测试项目”就是基于这个理念设计的。

它的核心目标不是展示多么高深的技术，而是解决一个最实际的问题：如何用最小的启动成本，让UI自动化测试立刻跑起来，并具备可持续扩展的骨架。我们选择pytest作为测试框架，而不是unittest，原因很简单：pytest的夹具（fixture）机制、丰富的插件生态（比如pytest-html生成报告、pytest-xdist并行测试）以及更简洁的断言写法，能让测试代码更干净、更易维护。对于UI测试，我们通常会搭配Selenium或Playwright，这里为了极致简单和现代性，我会以Playwright为例，因为它开箱即用，无需额外管理浏览器驱动。

这个项目适合谁呢？如果你是测试新手，想快速了解UI自动化测试的完整流程；如果你是开发人员，需要为自己负责的模块补充一些冒烟测试；或者你是测试负责人，正在为团队寻找一个轻量级、不折腾的标准化起点——那么这个最简项目都能给你一个清晰的、可立即执行的蓝图。它剥离了所有“高级”但可能过早优化的部分，只保留核心路径：打开浏览器、执行操作、断言结果、生成报告。

2. 项目骨架设计与核心思路拆解

2.1 为什么是“pytest + Playwright”这个组合？

在开始写代码之前，我们先聊聊选型。UI自动化测试框架有很多，老牌的Selenium依然强大，新兴的Cypress专注于Web，Appium负责移动端。这里选择Playwright，是经过实战权衡的。

首先，安装和配置的简易性是“最简项目”的首要考量。Selenium需要你额外下载对应浏览器版本的WebDriver并配置路径，这对新手是个门槛，也容易在团队协作时因环境不一致而出错。Playwright通过playwright install命令一键安装浏览器（Chromium, Firefox, WebKit），所有依赖都封装在库内，保证了环境的一致性。

其次，自动等待机制。Selenium的隐式/显式等待需要手动编写，写不好就是满屏的time.sleep(10)，测试既慢又不稳定。Playwright的大多数操作（如click,fill）内置了智能等待，它会等待元素可操作（可见、可点击、稳定）后再执行，极大地减少了因页面加载或动画导致的“元素找不到”的失败。

再者，多浏览器、多上下文支持。Playwright原生支持无头模式、模拟移动设备、拦截网络请求等，这些能力在后续测试场景扩展时非常有用。而pytest的夹具系统，能完美地管理Playwright的浏览器、上下文和页面实例的生命周期，让测试代码既独立又高效。

这个组合的思路是：用pytest组织测试用例和提供支撑设施（夹具、参数化），用Playwright作为稳定可靠的浏览器操作引擎。我们先搭建一个能跑通的“hello world”，再逐步往里添加必要的“肌肉”。

2.2 最简项目目录结构解析

一个清晰、标准的目录结构是项目可维护性的基础。它不需要复杂，但必须逻辑分明。下面是我们这个最简项目的骨架：

ui_auto_project/ ├── conftest.py # pytest 共享夹具定义，核心配置文件 ├── requirements.txt # 项目依赖清单 ├── pages/ # （可选预留）页面对象模型目录 │ └── __init__.py ├── test_cases/ # 测试用例存放目录 │ ├── __init__.py │ └── test_login.py # 示例测试模块 ├── fixtures/ # （可选预留）自定义夹具目录 │ └── __init__.py ├── reports/ # 测试报告输出目录（自动生成） └── utils/ # （可选预留）工具函数目录 └── __init__.py

现在看起来有点空，但别急，我们一步步填充。关键文件只有三个：conftest.py,requirements.txt, 和test_cases/test_login.py。其他目录（pages,fixtures,utils）是为你后续扩展预留的位置，在“最简”版本里，我们可以先不创建它们，或者创建空目录和__init__.py文件占位。reports目录会在首次执行测试并生成报告时自动创建。

注意：conftest.py这个文件名是pytest的约定，它会被自动发现并加载，其中定义的夹具可以被整个项目（包括子目录）的测试用例使用。这是实现“最简”的关键，我们将浏览器和页面的管理逻辑都封装在这里。

3. 环境搭建与核心依赖安装

3.1 一步到位的依赖管理

让我们从创建虚拟环境开始，这是Python项目的最佳实践，可以避免包版本冲突。打开你的终端（命令行），执行以下步骤：

# 1. 创建项目目录并进入 mkdir ui_auto_project && cd ui_auto_project # 2. 创建虚拟环境（以venv为例，也可用conda） python -m venv venv # 3. 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 4. 创建 requirements.txt 文件并写入核心依赖

requirements.txt文件的内容如下：

pytest>=7.0.0 playwright>=1.40.0 pytest-html>=4.0.0 pytest-xdist>=3.0.0

pytest: 测试框架本体。
playwright: 浏览器自动化库。
pytest-html: 用于生成美观的HTML测试报告。
pytest-xdist: 用于后续实现测试用例并行执行，提升效率。虽然“最简项目”初期可能用不上，但提前安装好，为扩展留出接口。

接着，安装这些依赖，并让Playwright安装它所需的浏览器：

# 5. 安装Python依赖包 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 6. 安装Playwright的浏览器（Chromium, Firefox, WebKit） playwright install chromium # 我们主要用Chromium，足够轻量

实操心得：playwright install可能会因为网络问题下载缓慢或失败。可以尝试设置环境变量来加速，例如在终端执行set PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright(Windows) 或export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright(Linux/Mac) 后再执行安装命令。这一步是很多新手卡住的地方，务必确保浏览器安装成功。

3.2 核心灵魂：conftest.py 的编写

conftest.py是这个项目的“大脑”，它定义了测试的运行时环境。我们将在这里创建两个核心夹具：一个用于管理浏览器实例，一个用于为每个测试用例提供全新的页面（Page）对象。

# conftest.py import pytest from playwright.sync_api import Page, Browser, BrowserContext, sync_playwright @pytest.fixture(scope="session") def browser() -> Browser: """ 会话级别的夹具，整个测试会话只启动一次浏览器。 使用 yield 实现 teardown，测试全部结束后关闭浏览器。 """ playwright = sync_playwright().start() # 启动Chromium浏览器，headless=False表示有界面，便于调试。正式运行可设为True。 browser = playwright.chromium.launch(headless=False, slow_mo=500) # slow_mo 让操作变慢，方便观察 yield browser # 将浏览器实例提供给测试用例 browser.close() playwright.stop() @pytest.fixture def page(browser: Browser) -> Page: """ 函数级别的夹具，每个测试函数都会获得一个全新的页面上下文和Page对象。 这确保了测试之间的隔离性，一个测试的cookie、localStorage不会影响另一个。 """ context = browser.new_context() # 创建新的浏览器上下文 page = context.new_page() # 在新上下文中创建新页面 yield page # 测试结束后，自动关闭上下文，清理环境 context.close()

为什么这样设计？

browser夹具（session作用域）：启动和关闭浏览器是非常耗时的操作。如果每个测试用例都开一次浏览器，测试总时间会变得不可接受。将其设为session级别，所有用例共享一个浏览器进程，极大提升了执行速度。
page夹具（function作用域）：UI测试最怕用例间状态污染。A用例登录了，B用例可能因为已登录状态而跳过登录步骤，导致测试逻辑错误。为每个用例创建全新的context和page，就像每次都用隐身模式打开一个新窗口，保证了测试的独立性和可重复性。
slow_mo参数：在调试阶段，将headless设为False并加上slow_mo=500（单位毫秒），可以让每个Playwright操作延迟半秒执行，你能清晰地看到自动化脚本每一步在做什么，对于定位问题非常有帮助。线上运行时再改为headless=True。

4. 编写第一个可运行的测试用例

4.1 测试用例设计：以登录场景为例

理论说再多，不如跑一个。我们以一个最常见的Web登录场景作为第一个测试用例。假设我们有一个测试用的登录页面（这里使用https://www.saucedemo.com/，一个公开的测试网站）。

在test_cases目录下创建test_login.py：

# test_cases/test_login.py def test_successful_login(page): """ 测试成功登录流程。 步骤：1. 访问登录页 2. 输入用户名密码 3. 点击登录 4. 断言跳转后的页面包含特定元素 """ # 1. 导航到登录页面 page.goto("https://www.saucedemo.com/") # 2. 定位元素并操作 # Playwright 使用 CSS Selector, XPath, text 等多种定位方式，这里用最直观的 placeholder 文本 page.locator("[data-test='username']").fill("standard_user") page.locator("[data-test='password']").fill("secret_sauce") page.locator("[data-test='login-button']").click() # 3. 断言 - 登录成功后，页面应跳转到库存页，并且能看到购物车图标 # 使用 pytest 自带的 assert，也可以使用 Playwright 的 expect assert page.is_visible("[data-test='shopping-cart-link']") # 更精确的断言：检查URL是否包含/inventory.html assert "/inventory.html" in page.url def test_failed_login_with_wrong_password(page): """ 测试使用错误密码登录的失败场景。 预期：页面显示错误信息，且停留在登录页。 """ page.goto("https://www.saucedemo.com/") page.locator("[data-test='username']").fill("standard_user") page.locator("[data-test='password']").fill("wrong_password") page.locator("[data-test='login-button']").click() # 断言错误信息出现 error_message = page.locator("[data-test='error']") assert error_message.is_visible() # 断言错误信息文本内容符合预期 assert "Username and password do not match" in error_message.inner_text() # 断言URL没有变化，仍在登录页 assert page.url == "https://www.saucedemo.com/"

这个文件定义了两个测试函数。pytest会自动发现以test_开头的函数或方法并执行。每个函数都接收一个page参数，这个参数就是我们之前在conftest.py中定义的page夹具，pytest会自动注入。

4.2 运行测试并查看结果

现在，激动人心的时刻到了。在项目根目录（ui_auto_project）下打开终端，确保虚拟环境已激活，然后运行：

pytest

你会看到类似以下的输出：

============================= test session starts ============================== platform win32 -- Python 3.9.13, pytest-7.4.0, pluggy-1.0.0 rootdir: C:\path\to\ui_auto_project plugins: html-4.0.0, xdist-3.0.0 collected 2 items test_cases\test_login.py .. [100%] ============================== 2 passed in 8.12s ===============================

两个绿色的点（..）表示两个测试用例都通过了！一个最简的、可工作的UI自动化测试项目已经搭建完成。你会看到一个Chromium浏览器窗口弹出，自动完成登录操作，然后关闭。

注意事项：第一次运行可能会稍慢，因为Playwright需要初始化。如果测试失败，请检查：
网络是否能正常访问https://www.saucedemo.com/。
浏览器是否成功安装（playwright install chromium是否执行成功）。
网站页面结构是否发生变化（虽然这个测试站比较稳定，但也不是绝对的）。这时就需要更新你的元素定位器了。

5. 增强项目：生成HTML报告与常用配置

5.1 生成直观的HTML测试报告

控制台输出对于调试是好的，但对于给领导或团队分享结果就不够直观了。pytest-html插件可以生成漂亮的HTML报告。我们修改一下运行命令：

pytest --html=reports/report.html --self-contained-html

--html=reports/report.html: 指定HTML报告的输出路径和文件名。
--self-contained-html: 将CSS样式等内嵌到HTML文件中，生成单个文件，方便分享。

运行后，打开reports/report.html文件，你会看到一个包含测试通过率、耗时、每个用例状态（通过/失败/跳过）的详细报告。如果用例失败，报告还会包含失败瞬间的截图（需要额外配置）和错误堆栈，这对于排查问题至关重要。

5.2 创建 pytest.ini 统一运行配置

每次都输入一长串命令行参数很麻烦。我们可以在项目根目录创建一个pytest.ini文件，将常用配置固化下来。

# pytest.ini [pytest] # 自动发现测试文件的路径 testpaths = test_cases # 定义命令行默认参数 addopts = -v # 显示详细结果 --html=reports/report.html --self-contained-html --capture=no # 实时打印print信息，调试时有用 # 配置日志 log_cli = true log_cli_level = INFO

创建了这个文件后，以后在项目根目录下只需要简单地输入pytest，它就会自动应用addopts中的所有选项，直接生成HTML报告。

5.3 实现失败自动截图

UI测试失败时，光有错误日志是不够的，我们需要知道当时的页面长什么样。我们可以通过扩展conftest.py中的夹具，在测试失败时自动截图。

# 在 conftest.py 中新增或修改 page 夹具 import pytest from playwright.sync_api import Page, Browser, sync_playwright import datetime @pytest.fixture def page(browser: Browser, request) -> Page: # 注意，这里增加了 request 参数 context = browser.new_context() page = context.new_page() yield page # 在 teardown 阶段检查测试是否失败 if request.node.rep_call.failed if hasattr(request.node, 'rep_call') else False: # 生成带有时间戳的截图文件名 timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S") test_name = request.node.name screenshot_path = f"reports/screenshots/failure_{test_name}_{timestamp}.png" # 确保截图目录存在 import os os.makedirs(os.path.dirname(screenshot_path), exist_ok=True) page.screenshot(path=screenshot_path, full_page=True) print(f"\n*** 测试失败，截图已保存至: {screenshot_path} ***") context.close() # 这个钩子函数用于在测试调用后存储结果 @pytest.hookimpl(tryfirst=True, hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield rep = outcome.get_result() # 将结果存储到节点中，供 page 夹具访问 setattr(item, "rep_" + rep.when, rep)

这段代码做了几件事：

为page夹具增加了request参数，它可以访问当前测试用例的信息。
定义了一个pytest_runtest_makereport钩子，它在每个测试阶段（setup, call, teardown）后运行，并将结果报告对象附加到测试用例节点（item）上。
在page夹具的teardown（yield之后）部分，检查测试的call阶段是否失败（rep_call.failed）。
如果失败，则使用page.screenshot()截取整个页面的图片，并以测试名和时间戳命名，保存到reports/screenshots/目录下。

现在，当任何测试失败时，你都能在控制台看到截图保存的路径，并在reports/screenshots/目录下找到它，直观地看到失败时的页面状态。

6. 从“最简”到“可用”：关键模式与最佳实践

6.1 元素定位策略与等待机制

元素定位是UI自动化的基石，不稳定的定位是测试脚本最大的天敌。Playwright提供了多种定位器（Locator），比Selenium的find_element更强大。

1. 优先使用语义化属性：避免使用脆弱的XPath或易变的CSS类名。优先使用开发专门为测试添加的属性，如># 好：使用自定义测试属性，最稳定 page.locator("[data-testid='login-button']").click() # 中：使用角色（role）和名称（name），适用于ARIA元素 page.locator("button", has_text="登录").click() # 结合文本 page.get_by_role("button", name="登录").click() # Playwright推荐的新API # 差：依赖可能变化的类名或复杂XPath page.locator(".btn.btn-primary.mt-20").click() page.locator("//*[@id='root']/div/div[2]/form/button").click()

2. 拥抱内置等待，告别time.sleep：Playwright的定位器和操作（click,fill,check等）默认会等待元素可操作（最多30秒）。你几乎不需要手动写等待。

# 这是正确的做法，click内部会等待按钮可点击 page.locator("[data-test='submit']").click() # 除非必要，否则不要这样做！ import time time.sleep(5) # 死等，效率低下且不可靠 page.locator("[data-test='submit']").click()

如果确实需要等待特定条件（如元素出现、消失、包含特定文本），使用page.wait_for_selector或locator.wait_for。

6.2 测试数据的管理与参数化

硬编码的测试数据（如用户名密码）不利于维护和扩展。pytest的@pytest.mark.parametrize装饰器是进行数据驱动测试的利器。

# test_cases/test_login_parametrize.py import pytest # 将测试数据从测试逻辑中分离 login_test_data = [ ("standard_user", "secret_sauce", True, "登录成功"), ("locked_out_user", "secret_sauce", False, "用户被锁定"), ("problem_user", "secret_sauce", True, "登录成功但用户有bug"), ("standard_user", "wrong", False, "密码错误"), ] @pytest.mark.parametrize("username, password, expected_success, description", login_test_data) def test_login_with_multiple_users(page, username, password, expected_success, description): """ 使用参数化一次性运行多组登录数据测试。 """ page.goto("https://www.saucedemo.com/") page.locator("[data-test='username']").fill(username) page.locator("[data-test='password']").fill(password) page.locator("[data-test='login-button']").click() if expected_success: assert page.is_visible("[data-test='shopping-cart-link']"), f"{description} 断言失败" else: # 失败时，应该能看到错误信息框 assert page.is_visible("[data-test='error']"), f"{description} 断言失败"

运行这个测试文件，pytest会根据login_test_data列表的长度自动生成并运行4个独立的测试用例。在报告中，每个用例都会有对应的参数显示，一目了然。这是提升测试覆盖率和脚本复用性的核心手段。

6.3 面向未来的架构预留：Page Object Model (PO) 思想

虽然我们的“最简项目”没有强制使用完整的页面对象模型（PO），但了解其思想并预留接口至关重要。PO的核心是将页面元素定位和页面操作行为封装成类，测试脚本只调用这些类的方法，不与具体的page.locator直接交互。

这样做的好处是：当页面UI发生变化时，你只需要修改对应的PO类中的元素定位器，所有测试用例都无需改动，维护成本大大降低。

我们可以在pages目录下预留一个登录页的PO类示例：

# pages/login_page.py class LoginPage: def __init__(self, page): self.page = page self.username_input = page.locator("[data-test='username']") self.password_input = page.locator("[data-test='password']") self.login_button = page.locator("[data-test='login-button']") self.error_message = page.locator("[data-test='error']") def navigate(self): self.page.goto("https://www.saucedemo.com/") def login(self, username: str, password: str): self.username_input.fill(username) self.password_input.fill(password) self.login_button.click() def get_error_text(self) -> str: if self.error_message.is_visible(): return self.error_message.inner_text() return ""

然后在测试用例中这样使用：

# test_cases/test_login_with_po.py from pages.login_page import LoginPage def test_login_with_po(page): login_page = LoginPage(page) login_page.navigate() login_page.login("standard_user", "secret_sauce") assert page.is_visible("[data-test='shopping-cart-link']")

可以看到，测试用例变得非常简洁，只关心业务逻辑（“登录”），不关心具体如何输入、点击。当登录按钮的定位器从[data-test='login-button']变成[data-testid='submit']时，你只需要修改LoginPage类中的一行代码。这就是PO模式的价值。在项目初期，你可以先不实现完整的PO，但要有意识地将复杂的页面操作封装成函数，为将来重构为PO做好准备。

7. 常见问题排查与实战技巧实录

7.1 “元素找不到”或“操作超时”问题深度排查

这是UI自动化中最常见的问题，没有之一。当你的测试报告TimeoutError时，请按以下清单排查：

检查元素定位器是否唯一且正确：
- 动作：在浏览器的开发者工具（F12）中，使用Ctrl+F在Elements面板搜索你的定位器（如[data-test='username']）。
- 预期：应该高亮显示唯一的一个目标元素。如果匹配到多个或零个，就需要调整定位器。
- 技巧：Playwright提供了一个无敌的调试工具——playwright codegen。在终端运行playwright codegen https://www.saucedemo.com，它会打开一个浏览器和一个录制器。你在浏览器里的操作会被自动转换成代码，并给出它推荐的定位器，这是学习定位器写法的最佳方式。

检查页面是否加载完成：

问题：脚本执行太快，页面或框架（如React, Vue）还没渲染完元素。
解决：page.goto()默认会等待load事件。但对于单页应用（SPA），可能需要等待更具体的条件。

# 等待某个特定元素出现，作为页面加载完成的标志 page.goto("https://example.com") page.wait_for_selector("#main-content", state="visible") # 等待主内容区可见 # 或者等待网络基本空闲 page.goto("https://example.com", wait_until="networkidle")

检查是否有iframe、Shadow DOM或新窗口：

iframe：需要先切换到iframe上下文才能操作其中的元素。

# 通过iframe的name或选择器定位 frame = page.frame(name="login-frame") # 或者 frame = page.frame_locator("iframe[title='Login']").content_frame # 然后在frame上操作 frame.locator("input").fill("text")

新窗口/标签页：操作会打开新窗口，需要切换上下文。

# 点击一个打开新窗口的链接 with page.expect_popup() as popup_info: page.locator("a[target='_blank']").click() new_page = popup_info.value # 现在可以在 new_page 上操作了 new_page.locator("h1").inner_text()

检查是否有动态内容或复杂交互：

有些元素是在用户执行某些操作（如鼠标悬停）后才出现的。你需要模拟这个操作。

# 鼠标悬停触发下拉菜单 menu = page.locator(".nav-menu") menu.hover() # 先悬停 # 等待下拉菜单出现后再点击其中的项 page.locator(".dropdown-item").click()

7.2 测试稳定性提升技巧

为操作增加重试机制：对于某些偶发性的失败（如网络波动），可以简单重试。

import tenacity from tenacity import retry, stop_after_attempt, wait_fixed @retry(stop=stop_after_attempt(3), wait=wait_fixed(1)) def click_submit_with_retry(page): page.locator("[data-test='submit']").click() # 在测试中调用 click_submit_with_retry(page)

但注意，重试应谨慎使用，它可能掩盖真正的bug。更好的方法是优化定位器和等待条件。

使用更稳定的定位器组合：不要依赖单一的定位策略。

# 组合使用多种定位方式，提高鲁棒性 # 优先用 testid，没有则用 role+name，再没有则用文本+CSS选择器兜底 submit_btn = (page.get_by_test_id("submit-button") or page.get_by_role("button", name="提交") or page.locator("button.primary", has_text="提交")) submit_btn.click()

在CI/CD中稳定运行：在无头模式（headless=True）下运行时，可以配置一些浏览器启动参数来增加稳定性。

# 在 conftest.py 的 browser 夹具中 browser = playwright.chromium.launch( headless=True, args=[ '--disable-dev-shm-usage', # 克服Docker等环境下的资源限制问题 '--no-sandbox', '--disable-gpu', '--window-size=1920,1080' # 设置固定窗口大小 ] )

7.3 测试报告与结果分析优化

为报告添加更多上下文：使用pytest的@pytest.mark装饰器为测试用例打标签，如@pytest.mark.smoke（冒烟测试）、@pytest.mark.regression（回归测试）。运行时可使用pytest -m smoke只运行冒烟用例。
集成Allure报告：如果团队对报告有更高要求，可以集成Allure，它能生成更美观、交互性更强的报告，支持附件（截图、日志）、步骤（Step）描述、用例分层等。
```
pip install allure-pytest pytest --alluredir=./allure-results allure serve ./allure-results # 生成并打开本地报告
```
失败重跑机制：有些失败是环境偶发问题导致的，可以使用pytest-rerunfailures插件自动重跑失败的用例。
```
pip install pytest-rerunfailures pytest --reruns 2 --reruns-delay 1 # 失败后重试2次，每次间隔1秒
```

这个“最简项目”就像一颗种子，它包含了UI自动化测试最核心的DNA：环境隔离、用例组织、报告生成和基本的稳定性处理。围绕它，你可以根据实际项目需求，生长出数据驱动、页面对象、API混合测试、视觉回归测试、性能监控等丰富的分支。记住，最好的框架不是一开始就设计得尽善尽美，而是在解决真实问题的过程中，逐步演化出来的。

查看全文

http://www.jsqmd.com/news/1093464/