Playwright 稳定操作 SPA 表单的三个关键点：等待、定位与事件

引子

用 Playwright 操作单页应用（SPA）的表单，经常遇到三类问题：元素明明在，却点不到；内容填进去了，提交却是空的；提交一次变成两次。这些问题大多不是框架的锅，而是等待策略、元素定位、事件触发三处细节没处理对。这篇文章结合真实项目经验，把三处关键点讲清楚。

一、等待：不要等"加载完成"，要等"可交互"

最常见的写法是：

page.goto(url, wait_until="networkidle")

但在 SPA 里，networkidle 并不等于"表单可操作"。组件可能还在做二次渲染，按钮处于禁用态，输入框尚未绑定事件。更稳的做法是针对目标元素等待：

page.locator("textarea[placeholder*='摘要']").wait_for(state="visible")
page.locator("button:has-text('发布')").wait_for(state="enabled")

如果有防抖、动画或异步校验，再加一个"状态断言"而不是固定 sleep：

page.wait_for_function(
    "() => document.querySelector('.tagator_tag')?.innerText.trim().length > 0"
)

原则：等待可观察的状态，而不是等待时间。固定 sleep 在本地能跑通，在 CI 上就会随机失败。

二、定位：优先语义，其次结构，最后坐标

定位策略的优先级建议是：

1. 语义定位：get_by_role、get_by_label、get_by_placeholder，可读性最好；
2. 稳定属性：data-testid、固定 class 前缀；
3. 结构定位：locator("form >> nth=0")；
4. 坐标点击：最后手段，最脆弱。

SPA 常见的坑是同文案多元素。比如页面上有两个"提交"按钮，一个在弹窗里、一个在底部。此时不要用 get_by_text("提交") 直接点，而应限定作用域：

dialog = page.locator(".developer-modal.show")
dialog.get_by_role("button", name="提交").click()

另一个坑是隐藏副本。响应式布局常保留两份 DOM，其中一份尺寸为 0。判断标准不是 offsetParent 是否为真，而是：

const r = el.getBoundingClientRect();
const visible = r.width > 0 && r.height > 0;

三、事件：fill 不等于"用户输入"

富文本编辑器、标签输入框、受控组件往往监听的是 input / keydown 事件，而不是 value 赋值。直接改 value 会出现"界面上有字，提交却为空"。

稳妥的写法是先聚焦，再逐字输入：

box = page.locator("textarea").first
box.click()
page.keyboard.type(text, delay=5)

对于标签类组件，需要模拟回车确认：

inp.dispatch_event("keydown", {"key": "Enter", "keyCode": 13})
inp.dispatch_event("keyup",   {"key": "Enter", "keyCode": 13})

如果是通过 JS 设值，务必用原生 setter 并派发事件，否则 React/Vue 的受控值不会更新：

const setter = Object.getOwnPropertyDescriptor(
    HTMLInputElement.prototype, "value").set;
setter.call(input, value);
input.dispatchEvent(new Event("input", { bubbles: true }));

还有一类"应用内函数"入口，比如页面暴露了 submitForm()。调用它比模拟点击更稳，但要注意它可能不做前端校验，参数必须自己保证正确。

四、防重复提交

点击后如果没等到结果就再次点击，会产生重复数据。建议：

• 点击后立即禁用按钮或记录状态标记；
• 等待明确的成功信号（URL 变化、成功提示、接口返回）；
• 失败时先判断是否已成功（幂等检查），再决定是否重试。

with page.expect_response(lambda r: "/api/submit" in r.url) as ri:
    page.get_by_role("button", name="发布").click()
assert ri.value.status == 200

五、小结

三个关键点可以浓缩成三句话：

• 等待可交互状态，别等网络空闲；
• 在作用域内做语义定位，并用尺寸判断可见性；
• 用真实输入事件驱动受控组件，提交后用明确信号确认。

把这三条固化进项目的页面对象（Page Object）里，SPA 表单自动化的稳定性会有质的提升。