Streamlit E2E 测试指南:基于 Playwright 与 pytest 的全栈黑盒测试实践

原创2026-09-18 17:38:062,206 阅读
文章标签:Web框架数据可视化数据分析后端前端低代码

Streamlit E2E 测试指南:基于 Playwright 与 pytest 的全栈黑盒测试实践

Streamlit 的端到端(E2E)测试体系位于仓库的 e2e_playwright 目录,采用 Playwright + pytest 组合,以用户视角(黑盒)验证由前端、后端、通信、状态与视觉表现组成的完整 Streamlit 系统。本文以 e2e_playwright/AGENTS.md(由 e2e_playwright/CLAUDE.md 通过 @./AGENTS.md 指令引入)为骨架,结合 e2e_playwright/conftest.py 等源码实现,系统讲解 E2E 测试的目录结构、核心 Fixture 与工具、外部应用测试模式、URL 处理规范、编写与运行测试的最佳实践,以及截图快照的更新流程。读完后,你将能够为新的 Streamlit 元素编写可复用的 E2E 测试,并在本地、CI 及外部托管应用三种环境下正确运行与维护它们。

E2E 测试在 Streamlit 开发中的定位

E2E 测试与 Python/JS 单元测试互为补充。单元测试更快,聚焦内部逻辑、输入输出校验与特定消息序列;而 E2E 测试验证的是完整的 Streamlit 系统——从前端渲染、后端执行到 WebSocket 通信、状态管理乃至视觉外观。因此,当需要测试依赖全栈行为或需要视觉验证的功能时,应使用 E2E 测试,尤其是新增元素或对既有元素做重大改动时。

前端 (frontend/) ── WebSocket ──> 后端 (lib/streamlit/) ──> 应用脚本 (*.py)
       │                                   │
       └───────── 视觉快照断言(pixelmatch 像素比对)

这一取舍逻辑决定了测试编写方式:E2E 测试成本高昂,应"一次浏览器运行换取最大置信度",而非像单元测试那样追求细粒度覆盖。详细的运行与实现文档可参考 wiki/running-e2e-tests.md。

测试结构与组织约定

E2E 测试全部位于 e2e_playwright/ 目录,每个测试由两个文件成对组成:

文件 作用
*.py 被测的 Streamlit 应用脚本(如 st_dataframe.py)
*_test.py Playwright pytest 测试文件,负责启动并测试上述应用(如 st_dataframe_test.py)

运行测试时,pytest 文件会自动执行对应的 Streamlit 脚本——这一映射由 conftest.py 中的 resolve_test_to_script 完成:它把测试模块文件名中的 _test.py 替换为 .py,从而定位被测脚本。若测试针对某个具体的 Streamlit 元素,文件名应以 st_<element_name> 为前缀(例如 st_button.py 与 st_button_test.py),便于按元素检索和组织。

测试产物遵循固定目录约定:

  • 所有截图快照存放在 e2e_playwright/__snapshots__/<os>/,其中 <os> 为运行平台(如 darwin、linux),因为不同操作系统会产生略有差异的渲染结果;
  • 其他 E2E 测试结果存放在 e2e_playwright/test-results/ 下:
    • e2e_playwright/test-results/<test_name>/:失败测试相关的视频与 trace;
    • e2e_playwright/test-results/snapshot-tests-failures/<os>/<test_script>/<test_name>/:失败快照测试的期望图、实际图与差异图;
    • e2e_playwright/test-results/snapshot-updates/<os>/<test_script>/<test_name>/:本次运行中更新过的全部截图。

核心 Fixtures 与工具方法

测试所需的大部分基础设施由 conftest.py 提供,直接从 conftest.py 导入即可使用:

Fixture / 工具 类型 说明
app: Page fixture 以亮色主题加载被测应用
themed_app: Page fixture 以亮色与暗色两种主题加载应用(由 app_theme 参数化驱动,见 conftest.py)
app_target: AppTarget fixture 应用交互包装器,抽象了应用 DOM 位于顶层 Page 还是宿主页 FrameLocator 的差异,支持 iframe 托管的扩展应用
app_base_url: str fixture 应用导航的基础 URL(外部地址或 localhost,见 conftest.py)
build_app_url(...) 函数 URL 构造器,基于 app_base_url 组合 path/query/fragment
assert_snapshot fixture 截图测试(对 locator 元素截图并做像素比对),调用元素前需确保其渲染稳定
wait_for_app_run(app) 函数 等待一次应用运行结束
wait_for_app_loaded(app) 函数 等待应用首次加载完成
rerun_app(app) 函数 触发一次应用重跑并等待完成
wait_until(app, fn) 函数 循环执行测试函数直至返回 True 或超时
app_with_query_params fixture 以一组预配置的查询参数加载应用

等待语义的源码实现

等待逻辑是 E2E 测试稳定性的基石。wait_for_app_run 的实现揭示了它依赖的前端状态信号:

  1. 先等待 initial_wait(默认 210ms),兼容具有防抖超时的组件(如 pydeck 图表有 200ms 防抖);
  2. 等待 [data-testid='stApp'][data-test-connection-state='CONNECTED'] 出现,确保 WebSocket 连接建立;
  3. 等待 [data-testid='stApp'][data-test-script-state='notRunning'],即脚本运行状态从 initial → running → notRunning 走完;
  4. 断言 stSkeleton 元素数量为 0,确保所有元素已完成渲染;
  5. 最后再等待 wait_delay(默认 100ms)让页面完全绘制。

wait_until 则是 expect 无法覆盖的场景下的通用轮询工具:以 interval(默认 100ms)为周期重复调用回调,直到返回 True/None 或超过 timeout(默认 5000ms);回调抛出的 AssertionError 会被吞掉并继续轮询,直至超时后以 TimeoutError 失败。

外部测试模式(External Test Mode)

默认情况下,E2E 测试会在本地为对应测试脚本启动一个 Streamlit 服务器。但在某些环境中,你可能希望针对已运行的应用执行测试(例如应用托管在 SSO 之后,或嵌入在宿主页面中,如 Snowsight)。

启用方式与参数

外部模式通过 CLI 选项或环境变量配置,两者取其一(CLI 优先)。这些选项在 pytest_addoption 中注册:

CLI 选项 环境变量 说明
--external-app-url STREAMLIT_E2E_EXTERNAL_APP_URL 外部托管应用的绝对 HTTP(S) URL(不启动本地服务器)
--external-host-url STREAMLIT_E2E_EXTERNAL_HOST_URL 将应用嵌入 iframe 的宿主页面绝对 HTTP(S) URL(不启动本地服务器),需与 --external-app-url 同时配置
--external-iframe-selector STREAMLIT_E2E_EXTERNAL_IFRAME_SELECTOR 宿主页面中 iframe 元素的 CSS 选择器,默认 iframe
--browser-state-path STREAMLIT_E2E_BROWSER_STATE_PATH Playwright storage state JSON 文件路径,可用于预置已认证的浏览器会话

当外部应用模式启用时,只有标记了 @pytest.mark.external_test 的测试会被执行,其余测试全部跳过——这一逻辑由 autouse 的 skip_non_external_tests_in_external_mode fixture 实现。此外,pytest_collection_modifyitems 会在收集阶段做校验:若开启了外部模式但没有任何测试被标记,直接抛出 UsageError 提示用户,避免"静默全跳过"的困惑。

external_test 标记的参数

@pytest.mark.external_test 仅支持少量关键字参数,完整的规范列表见 conftest.py(也可通过 pytest --markers 查看):

  • upload_test_assets(布尔值,默认 False):当外部托管应用需要访问 e2e_playwright/static/ 目录时设为 True。

标记不接收位置参数,未知关键字参数会触发 UsageError(如 @pytest.mark.external_test(upload_test_assets=True) 是合法用法)。需要说明的是,是否将测试标记为 external_test 目前需要手动判断:仅当测试明确设计为针对外部托管应用/宿主页面运行时才添加该标记。

AppTarget 抽象

编写 external_test 测试时,应优先使用 app_target fixture 而非裸的 Page/FrameLocator。AppTarget 是一个冻结数据类,集中封装并隐藏了"应用 DOM 在哪里"的细节:

  • page:顶层 Playwright Page,用于路由、事件、重载、超时、trace 等;
  • dom:应用选择器的执行上下文(本地模式为 Page,外部宿主模式为 FrameLocator);
  • base_url:应用自身的规范基础 URL(不是宿主页面);
  • mode:"local" | "external_direct" | "external_host" 三种运行模式。

它提供了 locator()、get_by_test_id()、get_by_role()、get_by_text() 等与 Playwright 一致的接口,以及 wait_for_run()、wait_for_loaded() 方法,使测试代码无需按本地/iframe 分支编写。从源码结构看,这一抽象正是为了把 iframe 与顶层页面的差异收敛为测试基础设施的内部实现细节。

外部测试的适用性判断

从文档与实现可归纳出,一个适合标记为 external_test 的测试通常具备以下特征:

  • 可以在不启动本地应用服务器的情况下运行(不依赖测试模块的 *.py 脚本由测试框架拉起);
  • 使用稳定的选择器以及 app_target/app_base_url 抽象(保证顶层与 iframe 托管两种场景都能工作);
  • 避免依赖本地专有基础设施,如请求路由/拦截(iframed_app)或与文件系统耦合的假设。

URL 处理规范:不硬编码 localhost

在测试模块(conftest.py 之外)中,严禁硬编码或拼接 http://localhost:{app_port}。正确做法是统一使用 app_base_url 与 build_app_url:

# 导航:优先 page.goto(build_app_url(...)),而不是字符串拼接
page.goto(build_app_url(app_base_url, path="/page", query={"key": "value"}, fragment="section"))

# 网络拦截与直接 HTTP 调用同样基于 app_base_url 构造
page.route(build_app_url(app_base_url, path="/media/**"), handler)
page.request.get(build_app_url(app_base_url, path="/_stcore/health"))

build_app_url 的实现保证了:

  • 保留基础路径(base path),即使传入以 / 开头的 path 也会拼接到基础路径之后(如 base_url="https://host/prefix" 时 path="/_stcore/health" 得到 /prefix/_stcore/health);
  • query 支持 dict 或 "a=1&b=2" 字符串两种传入方式,且会与 base URL 中原有的 query 合并;
  • fragment 接受 "foo" 或 "#foo" 两种写法。

同时要避免通过解析当前 URL 来"恢复" localhost 端口(如 urlparse(app.url).port);需要稳定基址时一律使用 app_base_url(或 app_target.base_url)。这套规范的目的是让同一份测试代码既能在本地运行,也能无缝切换到外部应用模式。

测试资源管理:禁用外部 URL

测试中应避免引用外部 URL(第三方依赖),因为它们可能引发网络波动或直接导致测试中断。仓库为此提供了统一的本地资源约定:

  • Python API 资源(如 st.audio、st.video、st.image):通过文件路径从 e2e_playwright/static/ 加载;
  • URL 引用:将文件放入 e2e_playwright/static/,以 ./app/static/<filename> 作为相对 URL 使用。

可参考 st_video.py 和 st_image.py 中的既有写法。static/ 目录中还预置了 sample.pdf、cat.jpg、sintel-short.mp4 等各类媒体素材,覆盖音频、视频、图片、PDF 等多种测试场景。

编写测试的最佳实践

E2E 测试的运行成本远高于单元测试,因此优化的核心目标是"每次浏览器运行的置信度最大化":

成本控制与组织策略

  • 每个方面只测试一次,优先使用聚合场景测试而非大量微测试;
  • 新测试若与既有测试文件范围匹配,优先加入现有文件,避免为小改动新建测试脚本;
  • 将相关测试分组到单一、逻辑完整的测试文件中(如按 widget 或功能分组),因为 CI 中每个独立测试文件都需要启动一个新的 Streamlit 应用服务器;
  • 多个测试共享相同 setup 与页面状态时,优先采用单个聚合场景:只加载一次应用、按顺序覆盖多个断言,减少浏览器加载次数;
  • 谨慎使用 @pytest.mark.parametrize:避免对昂贵流程做参数化,当 setup 主导运行时间时,优先在单个场景测试内迭代变体。

断言与等待

  • 使用 expect 而非 assert:expect 具备自动等待能力,可显著降低 flakiness;assert 没有自动重试,容易因时序问题产生偶发失败;
  • 若 expect 不够用,使用 wait_until 工具;wait_for_timeout 应尽量避免,仅在确有特定用途时使用;
  • 断言应模拟用户与 UI 交互的真实方式。

元素定位器优先级

优先使用基于 label 或 key 的定位器,而非基于索引的访问(如 get_by_test_id().nth(0))。推荐优先级如下:

  1. 按 label 获取元素(见 app_utils.py 中的 get_text_input、get_button、get_slider 等方法);
  2. 不支持 label 但支持 key 的元素:通过唯一 key 获取(get_element_by_key);
  3. 若元素既不支持 label 也不支持 key,可用 st.container(key="my_key") 包裹,再通过 get_element_by_key("my_key").get_by_test_id("stComponent") 定位。

同时遵循以下选择器规范:

  • 优先使用稳定定位器 get_by_test_id、get_by_text、get_by_role,而不是通过 .locator 使用 CSS/XPath;
  • 当目标文本是页面其他文本的前缀或子串时,必须配合 exact=True 使用 get_by_text() 与 filter(has_text=...)。例如 get_by_text("Count:", exact=True) 可避免误匹配 "Count: 5"——不加 exact=True 时 Playwright 按子串匹配,多个元素命中会触发 strict mode 违规;
  • 尽量利用共享的 app_utils 工具方法(从 e2e_playwright.shared.app_utils 导入)。

负面断言与交互多样性

  • 每个场景尽可能添加至少一条"必须不发生"(must NOT happen)的检查:在验证正向 UI 结果的同时,断言某个可能的回归不会出现,例如不出现重复元素、tooltip 在 hover 前不显示、disabled=True 时 widget 保持不可交互、不发生意外的 rerun/状态变化等;
  • 负面检查要"高信号":E2E 成本昂贵,每个场景优先做一个有针对性的负面断言,而不是堆砌大量负面矩阵;
  • 让测试混合不同的交互方式(如输入框交替使用 fill 和 type),以获得更高的覆盖度。

截图细节

  • 最小化截图面积:优先截取特定元素而非整页,除非确有必要;
  • 主容器内的元素截图高度应控制在 640px 以下(700px 屏幕高度减去 60px 头部),避免被顶部 header 裁切;
  • 命令相关快照的命名约定为 st_command-test_description;
  • 为测试起描述性名称。

编写测试时应覆盖的常见场景

为某个元素新增或修改测试时,文档明确要求覆盖以下维度:

  • 视觉(Visuals):为 normal 与 disabled 两种状态各做快照测试;
  • 交互(Interactivity):测试用户交互并验证应用状态或输出(如通过 st.write 写入的文本,可借助 app_utils.py 中的 expect_markdown 等辅助函数);
  • 常见上下文(Common Contexts):验证元素在 @st.fragment 内和 st.form 内的行为;
  • 核心行为(Core Behavior):
    • 状态持久化:元素被临时卸载再重新挂载后,widget 值应保留;
    • disabled=True 时元素不可交互;
    • 若元素使用 help 参数,验证 hover 时 tooltip 正确出现;
    • 若元素使用 key 参数,验证对应的 CSS class 或属性已设置;
    • 若元素是 widget,验证提供 key 后其身份保持稳定;
  • 自定义配置(Custom Config):需要特定 Streamlit 配置选项的测试,使用 @pytest.mark.early 标记的模块级 fixture;
  • 既有测试兼容性:向既有应用脚本新增元素时,检查现有测试是否断言了元素数量(如 to_have_count(18)),并同步更新为新总数。

其中,@pytest.mark.early 的作用在 conftest.py 中有明确实现:pytest 收集时会通过 reorder_early_fixtures 将这些 fixture 提前到执行顺序最前,从而允许在应用初始化之前修改配置。

本地运行、调试与快照更新

运行测试

运行命令由 Makefile 提供,所有 _test.py 文件也会在 CI 的每个 Pull Request 上自动执行:

# 运行单个测试文件
make run-e2e-test e2e_playwright/name_of_the_test.py

# 运行单个测试用例
make run-e2e-test e2e_playwright/name_of_the_test.py::test_name

# 传入任意 pytest 参数(通过 PYTEST_ADDOPTS 环境变量)
PYTEST_ADDOPTS='-k test_name -vvv' make run-e2e-test e2e_playwright/name_of_the_test.py

注意两点:

  1. 若修改了前端逻辑,需先运行 make frontend-fast 更新前端产物,否则 E2E 测试可能使用旧的前端资源(conftest.py 中 404 提示也印证了这一点:应用返回 404 时会提示尝试构建前端);
  2. 快照缺失或不匹配的错误可以暂时忽略,这些快照需要手动更新。

本地运行依赖 make 目标内部通过 uv run pytest 执行,并默认使用 pytest-playwright 提供的浏览器实例。测试服务器由 app_server fixture 通过 start_app_server 启动,它会以 streamlit run 拉起被测脚本,并传入 --server.headless true、--global.e2eTest true、--server.fileWatcherType none 等一系列测试专用配置,启动失败时自动重试最多 3 次。

调试测试

Makefile 提供交互式调试模式(基于 Playwright 的 debug 模式,包含 headed 浏览器与 Inspector):

make debug-e2e-test e2e_playwright/name_of_the_test.py

其他常用调试手段:

# 慢速模式 + 视频录制(在 e2e_playwright 目录下直接执行)
cd e2e_playwright
uv run pytest name_of_the_test.py -s --video on --slowmo 500

# headed 模式:打开真实浏览器窗口观察测试执行
# 可与 --slowmo 组合,便于在 DevTools 中检查元素

快照更新

截图测试默认只针对本地操作系统(如 e2e_playwright/__snapshots__/darwin/)生效,因为 CI 运行在 Ubuntu 上可能产生略有差异的快照。本地更新截图的方式:

  1. 删除 e2e_playwright/__snapshots__/<os>/ 下的过期快照;
  2. 运行 make update-snapshots 一次(首次运行可能因缺少截图而失败,这是预期行为)。

此外,仓库提供自动化的快照更新脚本 make update-snapshots(对应 scripts/update_e2e_snapshots.py),其流程为:匹配本地分支对应的 PR → 等待该 PR 最新的 Playwright E2E 工作流运行完成 → 将 CI 生成的更新快照同步到本地仓库。如需只更新改动过的文件可用 make update-snapshots-changed。同步后应只提交预期更新的快照,警惕 flaky 测试导致的无关联快照变化。

assert_snapshot 的参数与阈值

assert_snapshot 提供像素级比对能力,核心参数如下:

参数 默认值 说明
element 必填 待截图的 ElementHandle、Locator 或 Page
name 测试函数名 快照文件名(不含扩展名),可附加参数化后缀
image_threshold 0.002 允许差异像素占总像素的比例(微小图会取 max(1, ...) 保证非零阈值)
pixel_threshold 0.05 传给 pixelmatch 的逐像素比较阈值(0.0–1.0),不允许超过 0.10,否则比对过于宽松
fail_fast False 遇到第一个像素差异即停止比对
file_type "png" 快照格式,支持 "png"/"jpg"(jpg 使用 quality=90)
show_app_header None 是否显示应用 header;对非 Page 元素默认隐藏 header(通过透明化 .stAppHeader 背景实现)

其实现逻辑值得注意:快照缺失时不会立即失败,而是记录错误并继续,以便一次运行生成全部缺失快照;快照不匹配时会生成 diff_*、actual_*、expected_* 三张图写入 snapshot-tests-failures 目录,并且只有最后一次 rerun 才更新快照并失败,避免与 rerunfailures 插件冲突导致 flaky 追踪失真。

三条规则与减少 flakiness 的策略

Three Rules of Playwright

仓库将 Playwright 使用经验浓缩为三条规则:

  1. 尽可能使用 expect 断言:assert 缺乏自动等待,是 Playwright 测试 flakiness 的主要来源之一;
  2. 尽可能使用 get_by_test_id 定位元素:仅当目标无法通过 test-id 访问时才使用 .locator;
  3. 不要用 assert! 若 expect 无法覆盖你的场景,改用 wait_until 工具方法。

减少 flakiness 的通用手段

在交互元素上执行操作之前,额外添加 expect(element).to_X 检查通常能显著降低 flakiness。增加或调整超时有时也能缓解,但更多时候这是一种掩盖问题的反模式。当无法找到直接修复方案、且 flakiness 并不指向可复现的 bug 时:

  • pytest.mark.skip_browser:当 flakiness 仅出现在特定浏览器时跳过该浏览器;
  • pytest.mark.flaky(reruns=3):显著降低测试导致 CI 失败的概率。

其他实用技巧

  • 测试与特定浏览器不兼容时,使用 @pytest.mark.skip_browser("firefox") 装饰器跳过;
  • assert_snapshot 是非等待断言,若元素尚未完全加载会引入 flakiness,调用前应根据情况先做等待检查;
  • 不要在测试中使用 wait_for_timeout(Playwright 官方文档明确"生产环境禁止使用",等待时间类的测试天然 flaky),应改用自动等待的定位器操作与断言;
  • 需要特定 Streamlit 配置选项时,可在测试文件中添加 @pytest.mark.early 标记的模块级 fixture 来注入环境变量:
import os
import pytest

@pytest.fixture(scope="module")
@pytest.mark.early
def configure_options():
    """Configure Streamlit config options."""
    os.environ["STREAMLIT_SERVER_MAX_MESSAGE_SIZE"] = "3"
    yield
    del os.environ["STREAMLIT_SERVER_MAX_MESSAGE_SIZE"]

def test_something(app: Page, configure_options):
    # Test code

测试结果归档与 CI 集成

CI 中的 Playwright E2E Tests workflow 运行完成后,测试结果会上传为 workflow artifacts,可从工作流运行摘要的 Artifacts 部分访问。playwright_test_results 文件夹仅在测试失败时上传,包含视频、差异截图以及 snapshot-updates 文件夹(内含本次运行更新的全部截图)——后者是 CI 环境下更新快照的主要途径:删除本地过期快照 → 推送改动 → CI 完成后从 artifacts 取回更新截图 → 确认无误后推回分支。

本地失败测试的结果则位于 e2e_playwright/test-results/,包括视频、trace、差异截图与更新截图,按测试名与平台分目录存放。此外,conftest 中通过 playwright_profiling fixture 对受支持浏览器自动进行性能测量(可用 @pytest.mark.no_perf 标记跳过),并注册了 e2e_playwright.shared.stats_reporter 作为 pytest 插件。

小结

Streamlit 的 E2E 测试体系是一套成熟的"应用脚本 + 测试文件"双文件范式:通过 conftest.py 集中提供服务器管理、URL 构造、等待语义与快照比对等基础设施,通过 AppTarget 抽象屏蔽本地与 iframe 托管的差异,并以外部的 external_test 标记将测试扩展到 SSO 等真实托管环境。对开发者而言,最需要牢记的三件事是:用 expect 代替 assert、用 build_app_url 代替 localhost 硬编码、用聚合场景代替微测试。遵循 e2e_playwright/AGENTS.md 与 wiki/running-e2e-tests.md 中的约定,即可为 Streamlit 的每个新元素写出稳定、高效且可持续维护的全栈回归测试。

登录后查看全文
streamlit