14. 链式定位与过滤

为什么要链式

真实页面里到处是成组的相似元素：商品列表、表格行、卡片。一个定位器往往同时命中好几个，直接操作就会撞上严格模式（Strict Mode）报错。

解法不是硬写一长串 CSS，而是把定位器一层层缩窄。getByRole、getByText 这些创建定位器的方法，在 Locator（定位器）上也都有一份，所以能接在后面继续往下找。

用 .locator() 往下缩窄

在已有定位器里继续找子元素：

const product = page.getByRole('listitem').filter({ hasText: 'Product 2' });

await product.getByRole('button', { name: 'Add to cart' }).click();
await expect(product).toHaveCount(1);

也可以把两个定位器「套娃」：

const dialog = page.getByTestId('settings-dialog');
const saveButton = page.getByRole('button', { name: 'Save' });
await dialog.locator(saveButton).click(); // 在 dialog 里找那个 Save

用 .filter() 按文字过滤

filter({ hasText }) 在元素内部（含后代节点）搜文字。默认是子串匹配、大小写不敏感，也接受正则。

// 点第二个商品卡片里的「加入购物车」
await page
  .getByRole('listitem')
  .filter({ hasText: 'Product 2' })
  .getByRole('button', { name: 'Add to cart' })
  .click();

反向过滤也有：按「不含文字」筛。

// 统计不含「缺货」的商品，期望有 5 个
await expect(
  page.getByRole('listitem').filter({ hasNotText: 'Out of stock' })
).toHaveCount(5);

用 .filter() 按子元素过滤

filter({ has }) 只保留「内部含某个匹配子元素」的那些。注意：里面的定位器是相对于外层去找的，不是从文档根找。

await page
  .getByRole('listitem')
  .filter({ has: page.getByRole('heading', { name: 'Product 2' }) })
  .getByRole('button', { name: 'Add to cart' })
  .click();

还能按「不含某子元素」过滤：filter({ hasNot: ... })。

用 .filter() 只留可见元素

有一类页面很烦人：DOM 里塞了一堆隐藏的模板节点，或者列表用 display: none 做筛选。这些节点你定位得到，用户却看不见，数量一断言就对不上。

filter({ visible: true }) 专治这个：

// 忽略隐藏的待办项，只数看得见的
const todoItems = page.getByTestId('todo-item').filter({ visible: true });
await expect(todoItems).toHaveCount(3);

叠加多个过滤条件

多个 filter 可以串起来，越收越精：

await page
  .getByRole('listitem')
  .filter({ hasText: 'Mary' })
  .filter({ has: page.getByRole('button', { name: 'Say goodbye' }) })
  .screenshot({ path: 'screenshot.png' });

取第几个：nth / first / last

当只能靠顺序区分时，用这几个。序号从 0 开始。

const banana = page.getByRole('listitem').nth(1); // 第 2 个
const first = page.getByRole('listitem').first();  // 第 1 个
const last = page.getByRole('listitem').last();    // 最后 1 个

交集与并集：and / or

.and() 取同时满足两个定位器的元素：

const button = page.getByRole('button').and(page.getByTitle('Subscribe'));

.or() 取满足任意一个的元素，常用来等「要么这个、要么那个」：

const newEmail = page.getByRole('button', { name: 'New' });
const dialog = page.getByText('Confirm security settings');

await expect(newEmail.or(dialog).first()).toBeVisible();
if (await dialog.isVisible())
  await page.getByRole('button', { name: 'Dismiss' }).click();
await newEmail.click();

小结

链式定位用 .locator() 往下缩，.filter() 按文字、子元素或可见性收，.nth() / .first() / .last() 按顺序取（慎用），.and() / .or() 做交集并集。

最容易记错的一点：filter 里的定位器是相对外层节点去找的，不是从文档根找。