Playwright高级技巧：自定义选择器与定位器

在日常的Web自动化测试中，我们都遇到过这样的场景：页面上那些没有规范属性、动态生成的元素，让编写稳定的选择器变成了一场噩梦。上周我就花了整整一个下午，只为了定位一个不断变换class名的下拉菜单——这种情况在如今的单页应用中太常见了。

如果你也厌倦了脆弱的CSS选择器，那么自定义选择器与定位器将是你的解放工具。Playwright在这方面提供的灵活性，能让你的测试代码从“勉强能用”变成“坚如磐石”。

为什么我们需要自定义选择器？

先看看这个典型的痛点场景：你正在测试一个React应用，发现页面上的按钮是这么写的：

<button class="bg-blue-500 hover:bg-blue-700 px-4 py-2 rounded-lg">
  提交
</button>

用常规的CSS选择器，你可能会写：

await page.click('button.bg-blue-500');

但问题来了：如果UI设计师调整了样式，把bg-blue-500改成bg-blue-600，你的测试就挂了。更糟糕的是，在大型项目中，这种样式类名变动几乎无法避免。

自定义选择器：定义自己的定位策略

Playwright允许你注册自定义选择器引擎，这有点像定义自己的定位“方言”。让我通过一个实际例子来演示。

假设我们有一个自定义数据属性data-testid，这是目前比较流行的做法：

// 注册一个自定义选择器引擎
await page.locator.register('testId', {
// 这个引擎会在浏览器端执行
  create(root, selector) {
    return root.querySelector(`[data-testid="${selector}"]`);
  },

// 支持查询多个元素
  queryAll(root, selector) {
    return root.querySelectorAll(`[data-testid="${selector}"]`);
  }
});

// 使用方式简洁明了
const submitButton = page.locator('testId=submit-button');
await submitButton.click();

现在，即使按钮的class、结构甚至标签类型改变，只要data-testid="submit-button"保持不变，你的测试就能正常运行。

更复杂的自定义定位器

有时候，简单的属性选择器还不够。考虑一个常见的场景：在一个表格行中，需要找到包含特定文本的单元格所在的行。

// 创建一个定位特定表格行的定位器
function rowWithCellText(text) {
  return page.locator('tr').filter({
    has: page.locator('td', { hasText: text })
  });
}

// 使用示例：找到包含“张三”的行，然后点击该行的编辑按钮
const targetRow = rowWithCellText('张三');
await targetRow.locator('.edit-btn').click();

这种方法的美妙之处在于它的可读性——代码几乎就是在描述“找到包含‘张三’的行”。

组合定位器：构建复杂查询链

Playwright定位器的真正强大之处在于它们的组合能力。想象一下这个需求：在一个购物车页面，找到第一个数量大于2的商品，然后将其删除。

// 定义可重用的定位器组件
const cartItems = page.locator('.cart-item');
const quantityGreaterThan = (min) => 
  page.locator('.quantity').filter({ 
    hasText: (text) => parseInt(text) > min 
  });

// 组合使用
const targetItem = cartItems
  .filter({ has: quantityGreaterThan(2) })
  .first();

await targetItem.locator('.remove-btn').click();

这种声明式的写法不仅清晰，而且维护起来也容易得多。

处理动态内容和影子DOM

现代Web组件经常使用影子DOM，这给自动化测试带来了额外的挑战。别担心，Playwright也能处理：

// 自定义选择器，穿透影子DOM查找元素
await page.locator.register('shadowId', {
  create(root, selector) {
    // 递归查找影子DOM
    function findInShadow(node, targetId) {
      if (node.shadowRoot) {
        const found = node.shadowRoot.querySelector(`[data-id="${targetId}"]`);
        if (found) return found;
        
        // 继续在影子DOM内部查找
        for (const child of node.shadowRoot.children) {
          const result = findInShadow(child, targetId);
          if (result) return result;
        }
      }
      returnnull;
    }
    
    return findInShadow(root, selector);
  },

  queryAll(root, selector) {
    const results = [];
    
    function findAllInShadow(node, targetId) {
      if (node.shadowRoot) {
        const found = node.shadowRoot.querySelectorAll(`[data-id="${targetId}"]`);
        results.push(...found);
        
        for (const child of node.shadowRoot.children) {
          findAllInShadow(child, targetId);
        }
      }
    }
    
    findAllInShadow(root, selector);
    return results;
  }
});

实际项目中的最佳实践

经过多个项目的实践，我总结出了一些经验：

1. 统一的选择器策略

// selector-utils.js
exportconst Selectors = {
byTestId: (id) =>`[data-test="${id}"]`,
byAriaLabel: (label) =>`[aria-label="${label}"]`,
byPartialText: (text) =>`text=${text}`,

// 组合定位器
rowByCellText: (tableSelector, text) =>
    page.locator(`${tableSelector} tr`).filter({
      has: page.locator('td', { hasText: text })
    })
};

1. 等待策略封装

async function waitForLocator(locator, options = {}) {
const { timeout = 10000, state = 'visible' } = options;

try {
    await locator.waitFor({ state, timeout });
    return locator;
  } catch (error) {
    // 添加更有用的错误信息
    const html = await page.evaluate(() =>document.documentElement.outerHTML);
    console.error(`定位器 ${locator} 查找失败，当前页面HTML片段：`, html.substring(0, 1000));
    throw error;
  }
}

1. 页面对象模式中的应用

class LoginPage {
constructor(page) {
    this.page = page;
  }

// 使用自定义定位器
get usernameInput() {
    returnthis.page.locator('testId=username-input');
  }

get passwordInput() {
    returnthis.page.locator(this.page.locator.register('byLabel', {
      create(root, selector) {
        const label = Array.from(root.querySelectorAll('label'))
          .find(l => l.textContent.includes(selector));
        return label ? root.querySelector(`#${label.getAttribute('for')}`) : null;
      }
    }));
  }

async login(username, password) {
    awaitthis.usernameInput.fill(username);
    awaitthis.passwordInput.fill(password);
    awaitthis.page.locator('testId=login-btn').click();
  }
}

调试技巧

当自定义选择器不工作时，这些调试方法很有帮助：

// 1. 查看定位器匹配的元素数量
const count = await page.locator('your-selector').count();
console.log(`找到 ${count} 个元素`);

// 2. 高亮显示匹配的元素
await page.locator('your-selector').highlight();

// 3. 获取匹配元素的详细信息
const elements = await page.locator('your-selector').elementHandles();
for (const [index, element] of elements.entries()) {
const tagName = await element.evaluate(el => el.tagName);
const text = await element.textContent();
console.log(`元素 ${index}: ${tagName}, 文本: "${text}"`);
}

写在最后

自定义选择器和定位器不是银弹，但它们确实是解决复杂定位问题的强大工具。关键是要找到适合你项目的平衡点——不要过度设计，但也要避免过于脆弱的选择器。

我建议从简单的自定义选择器开始，比如基于data-testid的定位。当遇到更复杂场景时，再逐步引入更高级的技巧。记住，好的定位器应该像好代码一样：意图清晰、易于维护，并且足够健壮以应对变化。

真正的高手不是能写出最复杂的选择器，而是能用最简单的方式解决最棘手的定位问题。希望这些技巧能帮你写出更稳定、更可读的自动化测试代码。