最近在搞自动化测试，用Java配合Playwright操作页面上的单选和多选按钮，踩了一堆坑，也总结了不少经验。这篇笔记是《刚刚问世》系列的开篇，专门讲讲如何用Playwright可靠地点击和验证这类控件。如果你是刚入门Java自动化、或者从Selenium切换过来的测试工程师，这篇教程应该能帮你少走弯路。说得直白点，单选按钮和多选按钮看着简单，但真正跑自动化的时候，定位、点击、断言，每一步都有讲究，搞不好就是“假成功”——测试明明通过了，实际上元素根本没选上。
1. 项目背景与整体思路
1.1 为什么在Java里选Playwright而不是Selenium
先说结论：Playwright在同步等待、元素交互、浏览器上下文管理上比Selenium顺手太多。早年用Selenium写Java用例，最头疼的就是Thread.sleep()满天飞，页面加载快了慢了都会导致脚本时好时坏。Playwright核心卖点是自动等待，比如点击一个元素前，它会自动等元素可交互，基本不用手动sleep。这一点对单选多选按钮特别友好，因为这类控件经常由JavaScript动态渲染，稍不留神就会点到还没生成好的元素。
再一个就是API设计。Java版的Playwright API与官方保持一致，locator对象非常强大，支持CSS、XPath、文本、属性等定位方式。尤其是locator.check()和locator.uncheck()这两个方法，天生就是为单选框和复选框准备的，不用我们再费劲去模拟点击或写JavaScript脚本绕路。相比之下Selenium里需要用click()，配上一大堆等元素可见可点的封装，代码量直接翻倍。
1.2 单选和多选按钮在自动化里的真正难点
很多自动化测试刚上手时，会以为单选框/复选框就是“找到元素，点一下”的事，实际跑起来才知道有多坑。先说单选按钮，同一组Radio按钮在HTML里通常共享一个name属性，但Value不同。如果你不小心用XPath选到了多个元素，Playwright会直接报错，提醒你locator不唯一，这其实是保护机制，但对新手就是一头雾水。
多选按钮的坑更多。复选框有三种状态：选中、未选中、半选中（indeterminate）。半选中状态常见于“全选”和“子项”的联动场景，普通点击只能切换未选中到选中，根本点不出半选状态，断言时也会一脸懵。另外，很多页面会隐藏原生复选框，改用自定义样式的span或div，直接用check()可能点了没反应，必须用force或先定位到父级元素。
所以整个教程的核心思路就是：先搞清楚控件的DOM结构，再选对定位策略，最后用Playwright专门的方法做交互和断言，每一步都加上充分等待，尽量杜绝“偶发性失败”。
2. 环境准备与基础配置
2.1 搭建最小可用的Java+Playwright项目
我假设你已经装了JDK 11以上和Maven，没装的话先去搞定这些基础工具。项目结构用最普通的Maven工程就行，不用IDE的额外魔法。
在pom.xml里加入Playwright依赖，版本号建议选当前最新的稳定版。我的环境用的版本是1.40左右，后续升级主版本时注意API可能有细微变化。
<dependency> <groupId>com.microsoft.playwright</groupId> <artifactId>playwright</artifactId> <version>1.40.0</version> </dependency> <dependency> <groupId>org.testng</groupId> <artifactId>testng</artifactId> <version>7.8.0</version> </dependency>注意，光是加依赖还不够。Playwright需要下载浏览器驱动，运行一条命令行命令就能搞定：
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install chromium"如果这步下载慢，把Chromium换成带系统依赖的版本，或者优先使用现有的Chrome通道，后面我会在常见问题里细讲。
2.2 初始化浏览器和页面上下文
写代码之前，先建立一套基础封装。Playwright的设计是“浏览器实例（Browser）+ 上下文（BrowserContext）+ 页面（Page）”三层。上下文相当于一个独立的会话，隔离cookie和缓存，特别适合并行执行测试用例。
先看一个最简单的初始化：
import com.microsoft.playwright.*; public class RadioCheckboxDemo { private Playwright playwright; private Browser browser; private BrowserContext context; private Page page; public void setup() { playwright = Playwright.create(); browser = playwright.chromium().launch(new BrowserType.LaunchOptions() .setHeadless(false) // 调试时先不隐藏浏览器，跑稳定了再改true .setSlowMo(300)); // 慢动作300ms，方便肉眼观察 context = browser.newContext(); page = context.newPage(); } public void teardown() { browser.close(); playwright.close(); } }setHeadless(false)在早期调试特别关键，因为单选和多选按钮的视觉反馈很直观，你一眼就能看出到底有没有被点上。setSlowMo也是调试利器，相当于给每一步操作加了慢放镜头。等脚本完全稳定之后，再把headless改回true，放到CI里跑。
3. 单选按钮操作详解
3.1 精确定位Radio按钮的几个姿势
说一组数据，自己写用例时感受最深：CSS选择器定位单选按钮，成功率几乎百分百，XPath偶尔会踩到动态属性变换。我习惯优先用CSS结合属性选择器。
比如页面上有一组性别单选按钮，DOM长这样：
<label> <input type="radio" name="gender" value="male"> 男 </label> <label> <input type="radio" name="gender" value="female"> 女 </label>在Playwright里，可以这样定位并勾选“男”：
Locator maleRadio = page.locator("input[name='gender'][value='male']"); maleRadio.check();check()方法模拟鼠标勾选操作，会自动等元素可点击。还有一点值得说，check()和click()不同，check()会严格校验元素类型和可见性，如果元素不存在或者被禁用，会给出清晰异常，这对后期排查问题很有帮助。
如果页面是自定义样式的Radio，比如原生input被css隐藏，外面包了一层div，那就要先找到这个能点击的可视元素。最稳的办法是先用isVisible()确认原生input不可见时，就改用locator("div.custom-radio").click()，然后用原生input的选中状态做断言。这里要注意，裸用check()可能报“element is not visible”的错。
3.2 验证单选按钮是否真的被选中
勾选完了，测试不能瞎点“通过”。Playwright提供了非常好用的断言方法，但我更推荐用expect静态方法，它自带一个可配置的轮询等待，比直接读属性更抗抖动。
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat; assertThat(maleRadio).isChecked();如果你想在业务代码里判断状态，那就用isChecked()方法：
if (maleRadio.isChecked()) { System.out.println("男生已选中"); } else { System.out.println("仍未选中"); }关于单选按钮，还有一个特别容易踩的坑：同一组里的单选按钮是互斥的。自动化勾选“女”时，Playwright会自动处理互斥吗？答案是不会。它只是老老实实地给当前元素发点击事件，不会帮你取消同组其他按钮的选中。所以脚本里如果要切换选择，必须自己先勾选新的那个，再断言旧的那个已取消，顺序反了就会造成“同时选中”的假象。
Locator femaleRadio = page.locator("input[name='gender'][value='female']"); femaleRadio.check(); assertThat(femaleRadio).isChecked(); assertThat(maleRadio).not().isChecked(); // 关键：确认原来的被取消这段逻辑非常推荐写进用例里，既验证了当前选择，又验证了组内互斥，一举两得。
4. 多选按钮操作详解
4.1 批量勾选多个复选框的优雅做法
多选按钮的外观和单选框长得不一样，通常是方框，HTML里的type为checkbox。场景最常见的是兴趣爱好看板，比如下面这几个：
<label><input type="checkbox" name="hobby" value="reading"> 阅读</label> <label><input type="checkbox" name="hobby" value="travel"> 旅行</label> <label><input type="checkbox" name="hobby" value="music"> 音乐</label>如果要把“阅读”和“旅行”都选上，代码可以写成：
page.locator("input[name='hobby'][value='reading']").check(); page.locator("input[name='hobby'][value='travel']").check();这里有个细节：check()方法对复选框是“确保选中”，但如果复选框本来就是选中的，它不会重复点击，也就不会出现“把选中的又取消”这种反直觉行为。这一点非常重要，因为直接用click()就可能出这种问题，自动化脚本在失败重跑时，容易因为初装状态和数据残留而翻车。
要是想批量遍历操作，可以这样：
Locator hobbyBoxes = page.locator("input[name='hobby']"); for (int i = 0; i < hobbyBoxes.count(); i++) { hobbyBoxes.nth(i).check(); }批量勾选全部爱好在测试里挺常见，遍历count()再nth(i).check()是一套很稳的写法。但是要注意，这里的count()获取的是当前时刻节点的数量。如果页面是懒加载的，可能需要先等待所有节点出现，否则遍历过程中会漏选。
4.2 断言多选按钮的三种状态
多选按钮最大的坑是半选状态。比如一个“全选”复选框下挂了一堆子项，如果只选了部分子项，父级复选框的DOM会显示indeterminate属性，但Playwright原生断言里没有isIndeterminate()这个方法，需要我们自己用JavaScript去评估。
我实操中最常用的写法：
Locator parentCheckbox = page.locator("input#selectAll"); boolean isIndeterminate = (boolean) parentCheckbox.evaluate( "el => el.indeterminate" );还有一种方式，是直接评估DOM属性，确认选中状态：
boolean isChecked = (boolean) parentCheckbox.evaluate( "el => el.checked" );对于普通子复选框，常规断言用assertThat(childCheckbox).isChecked()就够了。我一般把三种状态的断言写成一个工具类：
| 状态 | 判断方法 | 备注 |
|---|---|---|
| 选中 | isChecked() | 原生支持 |
| 未选中 | not().isChecked() | 原生支持 |
| 半选 | 通过evaluate读indeterminate | 需要自己封装 |
这样写测试的意义在于，半选状态恰恰是业务逻辑中容易出错的环节。你点了5个子项中的2个，父级一定要显示半选，如果产品需求如此，自动化就必须把这个状态锁定。
5. 实操案例：一个完整的测试流程
5.1 设计一个包含单选和多选的表单页面
纸上谈兵没什么意思，我真正搭建了一个简单的订餐页来跑这套逻辑。页面里有三个字段：选择餐品类型（单选：午餐、晚餐）、选择配菜（多选：薯条、沙拉、饮料）、是否加辣（单选开关）。整个页面由静态HTML和一点点原生JavaScript组成，没有任何框架，方便调试。
关键DOM样式如下：
<form id="orderForm"> <div class="field-group"> <span>餐品类型</span> <label><input type="radio" name="meal" value="lunch"> 午餐</label> <label><input type="radio" name="meal" value="dinner"> 晚餐</label> </div> <div class="field-group"> <span>配菜选择</span> <label><input type="checkbox" name="side" value="fries"> 薯条</label> <label><input type="checkbox" name="side" value="salad"> 沙拉</label> <label><input type="checkbox" name="side" value="drink"> 饮料</label> </div> <button type="submit">提交</button> </form>测试目标很明确：先选“午餐”，再选“薯条”和“沙拉”，提交后验证页面返回的摘要。这个案例虽然简单，但能把单选、多选、提交、断言全部串起来。
5.2 编写并跑通自动化脚本
打开页面之后，第一步是page.setContent()加载本地HTML，也可以用本地文件协议。我这里用静态HTML塞进去最简单：
page.navigate("file:///path/to/order.html");然后依次操作：
page.locator("input[name='meal'][value='lunch']").check(); page.locator("input[name='side'][value='fries']").check(); page.locator("input[name='side'][value='salad']").check(); assertThat(page.locator("input[name='meal'][value='lunch']")).isChecked(); assertThat(page.locator("input[name='side'][value='fries']")).isChecked(); assertThat(page.locator("input[name='side'][value='salad']")).isChecked();接着就是点击提交按钮，并验证页面上出现的摘要信息。我用了一个比较校验的方式，先读取提交后用locator.textContent()拿到文本，再判断是否包含预期值。
page.click("button[type='submit']"); String summary = page.locator("#summary").textContent(); assert summary.contains("午餐") : "提交结果中没有午餐"; assert summary.contains("薯条") && summary.contains("沙拉") : "配菜选择不正确";跑完之后，控制台看到绿色通过，我的第一感受是：这种代码比当年的Selenium干净太多了。尤其是不用再写线程睡眠等待，也不需要到处封装ExpectedConditions，核心业务逻辑一眼能看懂。
6. 常见问题与排查技巧实录
6.1 “元素定位不到”和“定位到多个元素”的区分
这个错误几乎每个新手都会碰到。Playwright抛异常时，如果提示“strict mode violation”，意思就是你的定位符匹配到了多个元素，需要进一步缩小范围。这时候别急着改代码，先到Chrome DevTools里复制一下元素的完整CSS路径，或者查看是否有ifame包裹。单选多选按钮经常被包在iframe里，定位之前必须切换：
FrameLocator frame = page.frameLocator("iframe#mainFrame"); frame.locator("input[name='meal'][value='lunch']").check();如果完全找不到，可能是元素压根没加载，这时就得检查是不是登录态或者权限问题。建议先在普通浏览器里手动操作一遍，再回到自动化环境。
6.2 点击了没反应，勾选状态没改变
这是多选按钮的重灾区，尤其那些使用自定义UI的复选框。原生input被隐藏后，check()可能会报“not visible”或直接静默失败。解决办法通常是临时改用JS强制点击，但我不建议一上来就上JavaScript，因为那会绕过Playwright的事件模拟和等待机制，反而容易掩盖真实问题。
更稳妥的顺序是：
- 检查原生input是否可见，不可见则点击其对应的
label或父级视觉元素； - 实在不行，才考虑使用
click(new ClickOptions().setForce(true))强制点击； - 最后靠
isChecked()断言来确认结果。
我踩得最久的一个坑是：用了check()之后，由于页面控件有动画，状态还没刷新，立刻断言就挂了。Playwright的expect断言自带等待，所以只要用assertThat(...).isChecked()就不会有这个问题。如果你非要立刻用isChecked()读原始值，那就要自己在前面加个page.waitForTimeout(300)，但这种做法最好别进生产代码。
6.3 半选状态断言不可靠的坑
文档里说isChecked()只反映checked属性，半选状态的indeterminate属性它不关心。所以前面我提到要用evaluate，但还有一点容易被忽略：indeterminate并不是HTML属性，而是DOM属性，用getAttribute("indeterminate")是拿不到东西的，必须用el.indeterminate。这个细节坑了我整整一下午，分享出来希望大家绕开。
6.4 浏览器驱动安装失败的补救措施
有次执行npx playwright install时因为网络问题一直失败，直连下载几分钟就超时。后来我改用系统中已有的Chrome浏览器来跑，只要在启动时指定channel：
browser = playwright.chromium().launch(new BrowserType.LaunchOptions() .setChannel("chrome") .setHeadless(false));不过用系统Chrome有一个要注意的点：它可能不支持Playwright所有的浏览器特性，比如某些视频或权限API。但就操作单选多选按钮这个场景，一点问题都没有。
最后再分享一个小技巧。如果单选和多选按钮是页面渲染后才动态出现的，最好在操作前用locator.waitFor()等待它变得可见，而不是直接check()。我一开始偷懒不想写等待，结果脚本在CI上偶发失败，改了之后稳定性立马提高。另外，建议所有交互代码都通过页面对象模型（POM）封装起来，单选多选按钮本身虽然简单，但业务层的变化会经常导致脚本调整，封装好了之后，每次改起来只需要动一个地方，维护成本会低很多。这篇上篇先写到这，下篇我准备聊一聊如何把单选多选的校验逻辑融合到数据驱动测试中去，到时候见。
