E2E测试用例编写贡献指南

本项目使用 Playwright 的 Node API 实现 E2E 测试。

一、安装本地测试环境

先安装好项目的npm依赖

在项目根目录下：

pnpm install

安装测试用的浏览器

在项目根目录下：

pnpm install:browser

或者参考Playwright官网：浏览器安装教程，使用浏览器 channels

安装vscode插件（推荐）

推荐给vscode安装拓展：Playwright Test for VSCode，方便开发时使用。

二、编写E2E测试用例

我们目前使用官网文档上示例作为 E2E 测试用例的场景，每个示例文件对应着一个 E2E 测试文件。

以 PC 端的 alert 组件为例，它的测试文件和示例文件分别是：examples/sites/demos/pc/app/alert/**.spec.ts、examples/sites/demos/pc/app/alert/**.vue。

官网示例对应的本地页面地址是 http://localhost:3101/tiny-vue/zh-CN/os-theme/components/alert#[demoId]，测试用例将会运行在这个地址的页面上。

Playwright 配置文件在internals/playwright-config/src/index.js和examples/vue3/playwright.config.js。

手写测试用例代码（推荐这种方式）

Playwright官网指引：writing-tests

用现有的测试用例examples/sites/demos/pc/app/alert/basic-usage.spec.ts以及对应的示例文件examples/sites/demos/pc/app/alert/basic-usage.vue来说明:

<template>
  <div>
    <tiny-alert description="type 为默认值 info"></tiny-alert>
    <tiny-alert type="error" description="type 为 error"></tiny-alert>
    <tiny-alert type="success" description="type 为 success"></tiny-alert>
    <tiny-alert type="warning">
      <template #description> type 为 warning </template>
    </tiny-alert>
  </div>
</template>

<script>
import { Alert } from '@opentiny/vue'

export default {
  components: {
    TinyAlert: Alert
  }
}
</script>

import { test, expect } from '@playwright/test'

test('Alert 基本用法', async ({ page }) => {
  page.on('pageerror', (exception) => expect(exception).toBeNull()) // 断言页面上不出现错误
  await page.goto('alert#base') // 要测试的示例的相对地址

  // 警告可见
  const alertSuccess = page.locator('.tiny-alert--success')
  await expect(alertSuccess).toBeVisible()

  // 状态图标存在
  const icon = alertSuccess.locator('.tiny-alert__icon').first()
  await expect(icon).toBeVisible()

  // 提示内容存在
  const content = alertSuccess.locator('.tiny-alert__content')
  await expect(content).toBeVisible()

  // 点击关闭按钮，警告消失
  const close = alertSuccess.locator('.tiny-alert__close')
  await expect(close).toBeVisible()
  await close.click()
  await expect(alertSuccess).toBeHidden()
})

录制生成代码（不太推荐这种方式）

Playwright官网指引：codegen

可以使用命令启动：pnpm codegen

或者用Playwright Test for VSCode：点击vscode左侧侧边栏的“Testing”标签，在展开的面板下点击“Record new”就能打开录制功能。

三、测试用例编写规范

一个示例可以从多个功能点进行测试。每个功能点需要一个“明确的名字” 脚本结构如下：

import { test, expect } from '@playwright/test'

 test('测试Tooltip的是否能出现', async ({ page }) => {
    await page.goto('tooltip#basic-usage')
    ....
  })

 test('测试Tooltip的位置是否正确', async ({ page }) => {
    await page.goto('tooltip#basic-usage')
   .......
  })

测试路径是相对的路径

await page.goto('tooltip#basic-usage')

某些测试需要加一行等待，否则可能测试失败。建议200~500ms。

await page.waitForTimeout(1000)

每个测试，建议加一个捕获页面错误的脚本。无论什么原因，页面上出现了“红色异常”，都能显示测试不通过。

page.on('pageerror', (exception) => expect(exception).toBeNull())

不要使用page.$ $$等选择元素。尽量只使用locator来定位元素。
定位元素时，不要使用示例文件之外的选择器。

四、编写测试用例时常用手段

定位：https://playwright.dev/docs/api/class-locator

定位断言： https://playwright.dev/docs/api/class-locatorassertions

数值断言：https://playwright.dev/docs/api/class-genericassertions

断言属性值

const locator = page.locator('input');
await expect(locator).toHaveAttribute('type', 'text');

断言某元素的class属性包含某个值

<div class='selected row' id='component'></div>

const locator = page.locator('#component');
await expect(locator).toHaveClass(/selected/);
await expect(locator).toHaveClass('selected row');

断言某元素是禁用的和非禁用的

const locator = page.locator('button.submit');
await expect(locator).toBeDisabled();

断言某个元素被隐藏

const locator = page.locator('.my-element');
await expect(locator).toBeHidden();

断言是否有文本信息

const locator = page.locator('.title');
await expect(locator).toHaveText(/Welcome, Test User/);
await expect(locator).toHaveText(/Welcome, .*/);

定位有指定条件的元素

const rowLocator = page.locator('tr');
// ...
await rowLocator
    .filter({ hasText: 'text in column 1' })
    .filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
    .screenshot();

五、运行测试用例

官网参考：https://playwright.dev/docs/running-tests

可以在项目根目录执行命令：

pnpm run test:e2e3 [后面可选跟文件名/目录名]

推荐使用vsCode插件运行测试用例：

用Playwright Test for VSCode：点击vscode左侧侧边栏的“Testing”标签，在展开的面板下再展开“TEST EXPLORER”就就能有运行指定测试用例的按钮：

Provide feedback

Saved searches