Selenium与Playwright混合测试框架：渐进式演进与风险可控的架构设计

1. 项目概述：为什么我们需要一个混合框架？

如果你在自动化测试领域摸爬滚打超过三年，大概率会遇到一个经典的“历史包袱”问题：公司有一套运行多年、稳定但技术栈陈旧的自动化测试框架，它基于 Selenium，脚本成千上万，覆盖了核心业务流。与此同时，市场上出现了像 Playwright 这样的新秀，它宣称更快、更稳定、功能更强大。你是选择冒着巨大风险，投入海量人力物力去全盘重构，还是守着旧框架，眼睁睁看着新技术的红利无法享受？

我最近就主导了这样一个项目，目标不是二选一，而是“我全都要”。我们设计并落地了一套Selenium + Playwright 混合框架。这不是简单的代码堆砌，而是一套有清晰边界、能平滑过渡的架构方案。它允许团队在维护现有 Selenium 脚本（保障业务稳定）的同时，逐步、按需地在新的模块或特性中使用 Playwright，享受其现代化 API 和卓越性能。最终，我们既没有中断持续交付，又成功将新项目的自动化效率提升了近40%。

这个方案的核心价值在于“渐进式”和“风险可控”。它不是一个推翻重来的革命，而是一场精心策划的演进。接下来，我会详细拆解这个混合框架的设计思路、核心实现、以及我们在实操中踩过的坑和总结的经验，希望能给面临类似困境的团队提供一个可直接参考的蓝图。

2. 混合框架的整体设计与架构拆解

2.1 核心诉求与设计原则

在动手写第一行代码之前，我们必须明确要解决什么问题，以及设计时需要遵循哪些原则，否则很容易做出一个四不像的、难以维护的“缝合怪”。

我们的核心诉求很明确：

1. 兼容性第一：现有所有基于 Selenium 的测试用例必须能无修改、或极小修改地继续运行。这是底线，不能影响现有业务的测试覆盖和发布流程。
2. 能力可扩展：新框架必须能轻松集成 Playwright，并且为未来可能出现的其他自动化工具（如 Cypress, Puppeteer）留出接口。
3. 脚本隔离与低耦合：Selenium 脚本和 Playwright 脚本在运行时应该互不干扰，但又能共享一些基础服务（如配置管理、测试数据、报告生成）。
4. 平滑过渡路径：为开发人员提供清晰的指引，知道在什么场景下该用 Selenium，什么场景下该用 Playwright，以及如何将旧的 Selenium 脚本逐步迁移到 Playwright。

基于这些诉求，我们确立了几个关键的设计原则：

• 抽象与封装：将对浏览器驱动的操作（如元素查找、点击、输入）抽象成统一的“浏览器操作层”。上层测试用例不关心底层是 Selenium 还是 Playwright。
• 工厂模式与依赖注入：通过一个“驱动工厂”来根据配置或上下文，动态创建 Selenium 或 Playwright 的驱动实例。测试用例只需声明“我需要一个浏览器驱动”，而不需要知道具体类型。
• 配置驱动：所有行为，包括选择哪种浏览器、使用哪种自动化工具、超时时间、是否无头模式等，都通过配置文件（如 YAML, JSON）或环境变量来控制。这提供了极大的灵活性。
• 公共能力下沉：将报告生成、日志记录、截图、异常处理、数据驱动等所有测试用例共用的能力，设计成独立的服务模块，供两种驱动调用。

2.2 技术栈选型与考量

确定了原则，接下来是具体的技术选型。这里每一个选择背后都有其权衡。

• 语言平台：Python

  • 为什么？现有 Selenium 框架基于 Python（普遍情况），团队熟悉。Python 的语法简洁，生态丰富（Pytest, Allure, 各种数据处理库），能快速落地。虽然 Playwright 对 Node.js 支持更原生，但其 Python 版本同样强大且稳定，完全满足需求。
  • 备选方案：如果旧框架是 Java 或 C#，那么延续原有语言是更稳妥的选择，可以减少学习成本和环境冲突。

• 测试运行器：Pytest

  • 为什么？Pytest 比 Unittest 更灵活、功能更强大。其 Fixture 机制是实现驱动工厂和依赖注入的绝佳载体。我们可以轻松地编写一个browser_driver的 Fixture，根据参数动态返回不同的驱动实例。它的插件体系（如 Allure-Pytest）也便于集成报告。

• 报告系统：Allure

  • 为什么？Allure 报告美观、信息维度丰富（步骤、截图、日志、分类），并且对 Pytest 支持良好。无论是 Selenium 还是 Playwright 执行的步骤，都可以通过 Allure 的装饰器统一记录，生成一份整合的报告，便于结果分析。

• 元素定位与管理：Page Object Model (POM) 的增强版

  • 为什么？POM 是 UI 自动化的最佳实践，能有效分离页面元素定位和测试逻辑。在混合框架中，我们对其进行了增强，使其支持“多后端”。即一个 Page 类里，可以同时定义 Selenium 的定位器 (By.ID) 和 Playwright 的定位器 (page.locator)，或者通过一个统一的定位器字符串，由底层驱动去解释执行。

• 驱动管理：WebDriver Manager (Selenium) + Playwright CLI (Playwright)

  • Selenium 侧：使用webdriver-manager库自动管理 ChromeDriver、Geckodriver 等二进制文件的下载和匹配，避免手动维护驱动版本的麻烦。
  • Playwright 侧：使用playwright install命令安装所需的浏览器（Chromium, Firefox, WebKit）。这里有个重要技巧：在 Linux CI/CD 环境中，如果从默认源下载慢或失败，可以配置镜像源加速，例如PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ playwright install chromium。这个细节能极大提升环境搭建效率。

这个技术栈组合，在保证强大功能的同时，也兼顾了与旧系统的兼容性和新特性的引入效率。

3. 核心模块解析与实现细节

3.1 驱动工厂：核心的抽象层

这是整个框架的“大脑”。它的职责是根据配置，创建并返回一个标准化、可用的浏览器驱动对象。这个对象对外提供统一的接口（如find_element,click,type_text），内部则封装了 Selenium 或 Playwright 的具体实现。

# core/driver_factory.py import os from selenium import webdriver from selenium.webdriver.chrome.service import Service as ChromeService from webdriver_manager.chrome import ChromeDriverManager from playwright.sync_api import sync_playwright from core.config import Config # 假设有一个配置管理类 class DriverFactory: @staticmethod def create_driver(browser_type="chrome", automation_tool="selenium"): """ 创建浏览器驱动实例。 :param browser_type: 浏览器类型，如 'chrome', 'firefox', 'edge' :param automation_tool: 自动化工具，'selenium' 或 'playwright' :return: 驱动实例 """ config = Config() if automation_tool.lower() == "selenium": return DriverFactory._create_selenium_driver(browser_type, config) elif automation_tool.lower() == "playwright": return DriverFactory._create_playwright_driver(browser_type, config) else: raise ValueError(f"不支持的自动化工具: {automation_tool}") @staticmethod def _create_selenium_driver(browser_type, config): if browser_type == "chrome": options = webdriver.ChromeOptions() if config.headless: options.add_argument("--headless=new") options.add_argument("--no-sandbox") options.add_argument("--disable-dev-shm-usage") # 自动管理驱动版本 service = ChromeService(ChromeDriverManager().install()) driver = webdriver.Chrome(service=service, options=options) driver.implicitly_wait(config.implicit_wait) driver.set_page_load_timeout(config.page_load_timeout) return driver # ... 其他浏览器处理逻辑 @staticmethod def _create_playwright_driver(browser_type, config): playwright = sync_playwright().start() launch_options = {"headless": config.headless} if browser_type == "chrome": browser = playwright.chromium.launch(**launch_options) elif browser_type == "firefox": browser = playwright.firefox.launch(**launch_options) else: raise ValueError(f"Playwright 暂不支持 {browser_type}") context = browser.new_context(viewport={'width': 1920, 'height': 1080}) page = context.new_page() page.set_default_timeout(config.page_load_timeout * 1000) # Playwright 使用毫秒 # 这里返回一个封装了 Playwright page 和 context 的自定义对象，便于统一接口 return PlaywrightDriverWrapper(page, context, playwright)

关键点解析：

1. 统一入口：create_driver方法是对外唯一入口，测试用例只需调用它。
2. 配置化：所有参数（浏览器类型、是否无头、超时时间）都来自统一的Config类，易于管理和切换。
3. 隔离实现：Selenium 和 Playwright 的创建逻辑被隔离在私有方法_create_*_driver中，互不干扰。
4. 返回包装对象：对于 Playwright，我们返回一个自定义的PlaywrightDriverWrapper。这个包装器实现了与 Selenium WebDriver 类似的接口（如find_element，click），这样上层的 Page Object 和测试用例就可以用几乎相同的方式操作两种驱动。这是实现“脚本兼容”的关键。

3.2 统一的页面对象模型

有了统一的驱动，下一步是让页面对象也能适配两种后端。我们采用“组合优于继承”的原则。

# pages/base_page.py from abc import ABC, abstractmethod class BasePage(ABC): def __init__(self, driver): """ :param driver: 可以是 Selenium WebDriver 或我们的 PlaywrightDriverWrapper """ self.driver = driver def find_element(self, locator): """统一查找元素方法""" # 这里 driver 需要实现 find_element 方法 # Selenium WebDriver 原生支持，PlaywrightDriverWrapper 需要封装 page.locator return self.driver.find_element(locator) def click(self, locator): element = self.find_element(locator) element.click() def type_text(self, locator, text): element = self.find_element(locator) element.clear() element.send_keys(text) # 可以定义一些共用的方法，如等待、截图等 def take_screenshot(self, name): self.driver.save_screenshot(f"screenshots/{name}.png") # pages/login_page.py class LoginPage(BasePage): # 定位器可以定义为字符串，由底层驱动解析 # 或者定义成字典，包含不同后端的定位策略 USERNAME_INPUT = "id=username" # 通用格式，驱动层解析 PASSWORD_INPUT = {"selenium": ("id", "password"), "playwright": "#password"} # 分别定义 LOGIN_BUTTON = "css=button[type='submit']" def login(self, username, password): self.type_text(self.USERNAME_INPUT, username) self.type_text(self.PASSWORD_INPUT, password) self.click(self.LOGIN_BUTTON)

设计考量：

• 定位器策略：示例展示了两种方式。第一种“通用字符串”需要驱动层实现一个解析器，将"id=username"解析成对应的定位方式。第二种“字典定义”更直观，但会让 Page 类稍微复杂。我们团队最终选择了第一种，并在BasePage的find_element方法中增加了简单的解析逻辑，保持了 Page 类的简洁。
• 操作封装：所有对浏览器的操作都通过BasePage提供的方法进行。如果未来 Playwright 有某个特别高效的操作（如page.fill），我们可以在PlaywrightDriverWrapper中覆盖父类方法，实现优化，而上层 Page 类无需感知。

3.3 Pytest Fixture：优雅的依赖注入

如何将驱动工厂优雅地集成到测试用例中？Pytest Fixture 是最佳选择。

# conftest.py import pytest from core.driver_factory import DriverFactory @pytest.fixture(scope="function") # 每个测试函数一个独立的浏览器实例 def browser(request): """ 主要的浏览器驱动 Fixture。 可以通过命令行参数或标记来指定使用哪种工具。 """ # 从命令行参数获取工具类型，默认 selenium tool = request.config.getoption("--tool", default="selenium") # 或者通过 pytest.mark 标记 marker = request.node.get_closest_marker("tool") if marker: tool = marker.args[0] if marker.args else "selenium" browser_type = request.config.getoption("--browser", default="chrome") driver = DriverFactory.create_driver(browser_type=browser_type, automation_tool=tool) yield driver # 将驱动实例提供给测试用例 # 测试结束后清理 driver.quit() if tool == "playwright": # PlaywrightDriverWrapper 需要关闭 playwright 对象 driver.close_playwright() @pytest.fixture def login_page(browser): """依赖 browser fixture，生成登录页实例""" from pages.login_page import LoginPage return LoginPage(browser) # 定义命令行参数 def pytest_addoption(parser): parser.addoption("--tool", action="store", default="selenium", help="选择自动化工具: selenium 或 playwright") parser.addoption("--browser", action="store", default="chrome", help="选择浏览器类型")

使用方式：

# test_login.py import pytest # 方式1：使用默认工具（Selenium） def test_login_with_selenium(login_page): login_page.login("admin", "password123") assert login_page.driver.title == "Dashboard" # 方式2：使用标记指定工具 @pytest.mark.tool("playwright") def test_login_with_playwright(login_page): login_page.login("admin", "password123") # Playwright 特有的断言方式，更强大 # 例如：expect(login_page.driver.locator(".welcome-msg")).to_have_text("Welcome, admin!") # 这里需要我们的 PlaywrightDriverWrapper 暴露一些原生对象或方法 assert login_page.driver.get_inner_page().inner_text(".welcome-msg") == "Welcome, admin!" # 方式3：通过命令行运行 # pytest test_login.py --tool=playwright --browser=firefox

通过 Fixture 和标记，我们可以非常灵活地控制单个用例、单个模块甚至整个测试集使用哪种自动化工具来运行，实现了完美的共存与隔离。

4. 混合框架的实操部署与执行流程

4.1 环境搭建与依赖安装

一个稳定的环境是自动化测试的基石。混合框架对环境的要求略高，需要同时管理 Selenium 和 Playwright 的依赖。

1. 创建虚拟环境（强烈推荐）

python -m venv .venv source .venv/bin/activate # Linux/Mac # .venv\Scripts\activate # Windows

2. 安装核心依赖创建一个requirements.txt文件：

# 核心测试框架 pytest>=7.0.0 pytest-html>=3.0.0 # 可选，基础报告 allure-pytest>=2.9.0 # 推荐，美观报告 # Selenium 生态 selenium>=4.0.0 webdriver-manager>=3.8.0 # 自动管理浏览器驱动 # Playwright 生态 playwright>=1.32.0 pytest-playwright>=0.3.0 # 官方插件，提供了一些有用的 Fixture，但我们主要用自己封装的

安装：

pip install -r requirements.txt

3. 安装 Playwright 浏览器Playwright 需要单独安装浏览器二进制文件。

# 安装所有支持的浏览器（Chromium, Firefox, WebKit） playwright install # 或者只安装 Chromium playwright install chromium

重要提示：在 CI/CD 环境或网络受限的服务器上，playwright install可能会因为网络问题失败。此时必须使用镜像源。这是很多团队初次部署 Playwright 时最大的坑。

# 设置镜像环境变量后安装 export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ playwright install chromium # 或者一行命令 PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ playwright install chromium

这个镜像源（npmmirror.com，即淘宝 NPM 镜像）在国内访问速度极快，能保证环境搭建的成功率。

4.2 测试执行策略与配置管理

框架搭好了，怎么用？我们制定了清晰的执行策略。

配置文件 (config.yaml或config.json)：

# config.yaml default: tool: "selenium" # 默认工具 browser: "chrome" headless: false # 本地调试通常为非无头 base_url: "https://your-test-env.com" implicit_wait: 10 page_load_timeout: 30 ci: tool: "selenium" # CI 上仍以稳定为主，可逐步切部分用例到 playwright browser: "chrome" headless: true # CI 环境无头模式节省资源 base_url: "${CI_ENVIRONMENT_URL}" implicit_wait: 5 page_load_timeout: 15 playwright_suite: tool: "playwright" browser: "chromium" # Playwright 的浏览器命名略有不同 headless: true base_url: "https://your-test-env.com" # Playwright 默认超时设置不同，可在代码中单独配置

执行命令示例：

# 1. 运行所有用例（使用默认配置，即Selenium） pytest # 2. 运行所有用例，但强制使用Playwright pytest --tool=playwright # 3. 运行标记为‘smoke’的冒烟用例，使用Playwright和Firefox pytest -m smoke --tool=playwright --browser=firefox # 4. 运行某个目录下的用例，使用CI配置（通过环境变量加载不同配置） export CONFIG_PROFILE=ci pytest tests/regression/ # 5. 并行运行测试（利用pytest-xdist） pytest -n auto --tool=playwright # Playwright 对并行支持更好

策略总结：

• 日常开发/调试：本地运行，headless: false，便于观察和调试。
• CI/CD 流水线：
  • 核心回归测试集：初期仍使用 Selenium，保证绝对稳定。
  • 新功能测试集/专项测试：使用 Playwright，享受其速度和稳定性，并积累经验。
  • 性能对比：可以同一套用例，分别用 Selenium 和 Playwright 跑，收集执行时间数据，量化收益。
• 渐进式迁移：为旧的 Selenium 用例打上标签，如@pytest.mark.migration_candidate。定期挑选一部分，在 Playwright 环境下运行，验证通过后，可以将其底层驱动切换到 Playwright，或者用 Playwright 重写其 Page Object。

4.3 报告生成与结果整合

无论用哪种工具执行，我们都希望有一份统一的测试报告。Allure 完美胜任。

1. 在测试中记录步骤和截图

import allure from pages.login_page import LoginPage def test_login(login_page): with allure.step("导航到登录页面"): login_page.driver.get("https://example.com/login") allure.attach(login_page.driver.get_screenshot_as_png(), name="login_page", attachment_type=allure.attachment_type.PNG) with allure.step("输入用户名和密码"): login_page.login("user", "pass") with allure.step("验证登录成功"): assert "Dashboard" in login_page.driver.title # Playwright 可以附加更丰富的追踪信息 if hasattr(login_page.driver, 'get_inner_page'): # 如果是Playwright包装器 allure.attach( login_page.driver.get_inner_page().screenshot(), name="post_login", attachment_type=allure.attachment_type.PNG )

2. 生成报告

# 运行测试并生成 Allure 原始数据 pytest --alluredir=./allure-results # 生成并打开 HTML 报告 allure serve ./allure-results # 在 CI 中生成静态报告 allure generate ./allure-results -o ./allure-report --clean

最终的报告会清晰展示每个测试用例的步骤、截图，并且你无法从报告上直接区分这个步骤是由 Selenium 还是 Playwright 执行的，它们被完美地整合在了一起。

5. 常见问题、踩坑实录与进阶技巧

5.1 混合框架特有的挑战与解决方案

问题1：元素定位器兼容性

• 现象：Selenium 的By.XPATH写得好好的，切换到 Playwright 的page.locator时报错或找不到元素。
• 根因：两者对 XPath 或 CSS Selector 的解析引擎有细微差异，或者页面动态加载导致时机不同。
• 解决方案：
  1. 使用更稳健的定位器：优先使用 ID、唯一的 CSS Selector。避免使用过于复杂或依赖页面结构的 XPath。
  2. 统一封装等待：在BasePage的find_element方法中，强制加入显式等待。Playwright 的locator本身有自动等待机制，但为了统一，我们可以封装一个wait_for_element方法，确保元素在交互前已处于可操作状态。
  3. 开发定位器验证脚本：写一个小工具，用两种驱动分别执行同一套定位器，快速找出不兼容的项。

问题2：异步操作处理

• 现象：Playwright 很多操作是异步的（虽然同步 API 是包装好的），在处理页面弹窗、导航等场景时，逻辑与 Selenium 不同。
• 解决方案：
  • 封装异步操作：在PlaywrightDriverWrapper中，将 Playwright 的异步 API（如page.wait_for_event）封装成同步方法，对外提供与 Selenium 一致的wait_for_alert,wait_for_navigation等方法。
  • 利用 Playwright 优势：对于新写的 Playwright 脚本，可以大胆使用其强大的异步事件处理，例如page.on(“dialog”)来处理弹窗，这比 Selenium 的Alert处理更优雅。

问题3：执行速度与资源占用

• 现象：同时开启多个 Selenium 和 Playwright 浏览器实例时，内存消耗较大。
• 解决方案：
  • 合理控制 Fixture 作用域：对于只读操作的测试，可以使用scope="session"或scope="module"的 Fixture，共享浏览器实例。
  • 使用 Playwright 的上下文：Playwright 的BrowserContext比启动多个浏览器实例轻量得多。可以在一个浏览器实例下创建多个隔离的上下文来并行运行测试，大幅节省资源。
  • CI 环境优化：在 CI 中务必使用headless: true模式。对于 Selenium，使用--disable-gpu,--disable-dev-shm-usage等 Chrome 参数也有助于提升稳定性。

5.2 从 Selenium 平滑迁移到 Playwright 的实战技巧

迁移不是一蹴而就的，我们总结了一套“小步快跑”的策略。

技巧1：并行验证，建立信心不要直接修改旧脚本。而是为旧的测试用例创建一个“Playwright 镜像”套件。用相同的测试数据和逻辑，但 Page Object 调用新的、基于 Playwright 封装的驱动来运行。在 CI 上让这两个套件并行运行一段时间，对比通过率和执行时间。这能直观证明 Playwright 的可靠性和优势，也能提前发现兼容性问题。

技巧2：优先迁移“痛点”模块哪些用例最适合先用 Playwright 重写？

• 稳定性差的用例：那些在 Selenium 下经常因元素加载、弹窗、iframe 等问题失败的“脆皮”用例。Playwright 的自动等待和更强大的选择器往往能根治这些问题。
• 新开发的功能模块：为新页面或新功能直接编写 Playwright 版本的测试，避免历史包袱。
• 性能敏感型用例：如需要大量数据验证或遍历的测试，Playwright 的速度优势明显。

技巧3：构建共享工具库将一些通用操作抽象成工具函数，同时提供 Selenium 和 Playwright 的实现。例如，一个file_upload函数，内部判断当前驱动类型，分别调用send_keys或 Playwright 的set_input_files。这样，迁移用例时，很多业务逻辑代码可以复用。

技巧4：团队培训与知识沉淀组织内部 Workshop，分享 Playwright 的核心概念（如 Auto-waiting, Locators vs Selectors, Tracing）、优秀实践以及和 Selenium 的对比。建立团队内部的 Playwright 知识 Wiki，记录常见的定位器转换对照表、最佳实践和踩坑记录。这能极大降低团队成员的心理门槛和学习成本。

5.3 进阶优化：让框架更强大

当混合框架稳定运行后，可以考虑以下优化点：

1. 智能驱动选择：不再完全通过配置或标记指定工具。可以基于一些启发式规则自动选择。例如，如果测试用例标记了@flaky（不稳定的），框架自动用 Playwright 执行它，利用其更好的稳定性来提升通过率。
2. 性能监控与对比：在框架中集成简单的性能收集模块，记录每个用例（或每个步骤）在 Selenium 和 Playwright 下的执行时间，并持久化到数据库或日志中。定期分析报告，用数据驱动决策，明确展示迁移的价值。
3. 与 Cursor/IDE 深度集成：利用 Playwright 强大的 Codegen 功能，录制用户操作生成脚本。可以将这个功能集成到框架中，作为一个快速创建新测试原型的工具。虽然生成的代码需要重构和融入 POM，但极大地提升了创建用例的初始速度。
4. 容器化部署：将整个测试框架（包括 Python 环境、浏览器、依赖）打包成 Docker 镜像。这确保了测试环境的高度一致性，无论是在本地、测试服务器还是任何 CI/CD 平台（如 GitLab CI, Jenkins, GitHub Actions）上，都能以完全相同的方式运行。这也是实现稳定、可重复的自动化测试的关键一步。

回顾整个混合框架的构建过程，其精髓不在于技术有多新颖，而在于对“演进式架构”的实践。它承认历史遗产的价值，同时为拥抱未来打开了一扇门。这套方案让我们团队在没有停摆、没有大规模重写的情况下，稳步提升了自动化测试的技术栈和效能。如果你也在为类似的技术债烦恼，不妨从这个混合框架的思路开始，找到属于你们团队的平滑过渡之路。