Playwright 故障排查 #

Error: locator.click: Timeout 30000ms exceeded.
waiting for locator('button.submit')

// 1. 检查元素是否存在
const count = await page.locator('button.submit').count();
console.log(`找到 ${count} 个元素`);

// 2. 使用更可靠的选择器
await page.getByRole('button', { name: 'Submit' }).click();

// 3. 等待元素出现
await page.locator('button.submit').waitFor({ state: 'visible' });

// 4. 检查是否在 iframe 中
const frame = page.frameLocator('iframe');
await frame.locator('button.submit').click();

// 5. 增加超时时间
await page.locator('button.submit').click({ timeout: 60000 });

Error: element is not visible

// 1. 等待元素可见
await page.locator('.element').waitFor({ state: 'visible' });

// 2. 滚动到元素
await page.locator('.element').scrollIntoViewIfNeeded();

// 3. 强制操作（不推荐）
await page.locator('.element').click({ force: true });

// 4. 检查可见性
const isVisible = await page.locator('.element').isVisible();
console.log(`元素可见: ${isVisible}`);

Error: element is not enabled

// 1. 等待元素启用
await expect(page.locator('button')).toBeEnabled();

// 2. 检查元素状态
const isEnabled = await page.locator('button').isEnabled();
console.log(`元素启用: ${isEnabled}`);

// 3. 检查是否有覆盖层
const overlay = await page.locator('.overlay').isVisible();
if (overlay) {
  await page.locator('.overlay').click();
}

Error: Test timeout of 30000ms exceeded.

// 1. 增加测试超时
test('慢速测试', async ({ page }) => {
  test.setTimeout(60000);
  // 测试代码
});

// 2. 标记为慢测试
test('慢速测试', async ({ page }) => {
  test.slow(); // 超时时间翻三倍
  // 测试代码
});

// 3. 全局配置
// playwright.config.ts
export default defineConfig({
  timeout: 60000,
});

Error: expect(received).toBeVisible()
Timeout: 5000ms

// 1. 增加断言超时
await expect(page.locator('.element')).toBeVisible({
  timeout: 10000,
});

// 2. 全局配置
// playwright.config.ts
export default defineConfig({
  expect: {
    timeout: 10000,
  },
});

Error: page.goto: Timeout 30000ms exceeded.

// 1. 增加导航超时
await page.goto('/', { timeout: 60000 });

// 2. 等待特定状态
await page.goto('/', { waitUntil: 'domcontentloaded' });

// 3. 全局配置
// playwright.config.ts
export default defineConfig({
  use: {
    navigationTimeout: 60000,
  },
});

Error: browserType.launch: Executable doesn't exist

# 安装浏览器
npx playwright install

# 安装系统依赖
npx playwright install-deps

# 检查安装
npx playwright --version

Error: Host system is missing dependencies

# Ubuntu/Debian
sudo npx playwright install-deps

# 或手动安装
sudo apt-get install -y \
  libnss3 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
  libxdamage1 libxfixes3 libxrandr2 libgbm1 \
  libasound2 libpango-1.0-0 libcairo2

Error: Out of memory

// 1. 减少 workers
// playwright.config.ts
export default defineConfig({
  workers: 1,
});

// 2. 关闭浏览器上下文
test.afterEach(async ({ context }) => {
  await context.close();
});

// 3. 禁用视频录制
export default defineConfig({
  use: {
    video: 'off',
  },
});

Error: page.goto: net::ERR_CONNECTION_REFUSED

// 1. 检查服务器是否运行
const response = await page.goto('/', { waitUntil: 'networkidle' });
console.log(`状态码: ${response?.status()}`);

// 2. 使用正确的 URL
await page.goto('http://localhost:3000');

// 3. 忽略 HTTPS 错误
// playwright.config.ts
export default defineConfig({
  use: {
    ignoreHTTPSErrors: true,
  },
});

// 1. 确保在导航前设置路由
await page.route('**/api/users', route => {
  route.fulfill({ status: 200, body: '[]' });
});
await page.goto('/');

// 2. 检查 URL 匹配
await page.route('**/api/**', route => {
  console.log(`拦截请求: ${route.request().url()}`);
  route.continue();
});

// 3. 清理路由
await page.unrouteAll();

// 1. 确保测试隔离
test.describe.configure({ mode: 'parallel' });

// 2. 使用独立数据
test('测试', async ({ page, request }) => {
  // 创建独立测试数据
  const uniqueId = Date.now();
  await request.post('/api/users', {
    data: { email: `test-${uniqueId}@example.com` },
  });
});

// 3. 清理测试数据
test.afterEach(async ({ request }) => {
  await request.delete('/api/test-data');
});

// 1. 使用正确的等待
await page.click('button');
await expect(page.locator('.result')).toBeVisible();

// 2. 等待网络请求
const responsePromise = page.waitForResponse('**/api/data');
await page.click('button');
await responsePromise;

// 3. 使用 Promise.all
await Promise.all([
  page.waitForResponse('**/api/data'),
  page.click('button'),
]);

# 启用追踪
npx playwright test --trace on

# 查看追踪
npx playwright show-trace trace.zip

test('调试', async ({ page }) => {
  await page.goto('/');
  await page.pause(); // 打开 Inspector
});

test('调试', async ({ page }) => {
  // 监听控制台
  page.on('console', msg => console.log(`浏览器: ${msg.text()}`));
  
  // 监听请求
  page.on('request', req => console.log(`请求: ${req.url()}`));
  
  // 监听响应
  page.on('response', res => console.log(`响应: ${res.status()}`));
  
  await page.goto('/');
});

test('截图调试', async ({ page }) => {
  await page.goto('/');
  await page.screenshot({ path: 'debug.png', fullPage: true });
});

test.afterEach(async ({ page }, testInfo) => {
  if (testInfo.status === 'failed') {
    const html = await page.content();
    require('fs').writeFileSync('debug.html', html);
  }
});

// ✅ 推荐
await page.getByRole('button', { name: 'Submit' }).click();

// ❌ 不推荐
await page.locator('#btn-123').click();

// ✅ 推荐
await expect(page.locator('.result')).toBeVisible();

// ❌ 不推荐
await page.waitForTimeout(2000);

// ✅ 推荐
export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    // 设置
    await use(page);
    // 清理
  },
});

// playwright.config.ts
export default defineConfig({
  timeout: 30000,
  expect: { timeout: 5000 },
  use: {
    actionTimeout: 10000,
    navigationTimeout: 30000,
  },
});