Headless模式下Playwright截图失真问题求解决方案

1. 统一有头/无头模式的浏览器参数 #

无头模式默认的视口、渲染配置和有头模式存在差异，需强制对齐参数：

• 在conftest.py中统一设置浏览器启动参数，固定视口大小并禁用硬件加速：

import pytest
from playwright.sync_api import BrowserType

@pytest.fixture(scope="session")
def browser_type_launch_args(browser_type_launch_args):
    return {
        **browser_type_launch_args,
        "viewport": {"width": 1280, "height": 720},
        "args": ["--disable-gpu", "--no-sandbox"],
    }

• 测试时无论用有头还是无头模式，都使用上述相同参数，确保渲染环境一致。

2. 等待页面完全稳定后再截图 #

无头模式下资源加载、渲染时机可能和有头模式不同，需添加等待逻辑：

• 等待目标元素可见且短时间内无变化：

page.goto("https://playwright.dev/", wait_until="networkidle")
banner = page.get_by_role("banner")
expect(banner).to_be_visible()
page.wait_for_timeout(500)  # 等待动态内容加载完成
assert_snapshot(banner.screenshot())

networkidle会等待500ms内无网络请求，确保静态资源加载完毕。

3. 排除动态变化的元素 #

若目标区域包含随机文案、动画等动态内容，截图时遮盖或避开这些元素：

• 使用mask参数遮盖动态元素：

dynamic_notice = page.get_by_text("实时通知")
assert_snapshot(banner.screenshot(mask=[dynamic_notice]))

• 或用clip参数只截取固定的核心区域：

assert_snapshot(banner.screenshot(clip={"x": 0, "y": 0, "width": 1280, "height": 100}))

4. 统一浏览器版本与运行环境 #

确保有头、无头模式使用相同浏览器版本，避免渲染引擎差异：

• 用Playwright命令同步浏览器版本：

playwright install

• CI测试环境需和本地使用完全一致的浏览器版本，消除环境差异。

5. 调整截图对比的容错阈值 #

针对细微像素差异（如抗锯齿、渲染精度），设置合理的容错参数：

assert_snapshot(
    banner.screenshot(),
    threshold=0.1,  # 允许10%的像素差异
    max_diff_pixels=100  # 最多允许100个像素不同
)

注意：阈值不宜过高，避免遗漏真实的UI变更。

6. 禁用页面动画与过渡效果 #

无头模式下动画可能未完全停止，导致截图状态不一致：

• 页面加载前注入CSS禁用所有动画：

page.add_style_tag(content="""
    * {
        animation: none !important;
        transition: none !important;
    }
""")
page.goto("https://playwright.dev/")

内容的提问来源于stack exchange，提问作者r_spb