---
title: "测试用例编写指南以及最佳实践 - Playwright"
language: "zh"
url: "https://docs.testany.io/zh/docs/managing-test-case-playwright/"
markdown_url: "https://docs.testany.io/zh/docs/managing-test-case-playwright.md"
translation: "https://docs.testany.io/en/docs/managing-test-case-playwright.md"
last_updated: "2026-03-26T15:39:24+08:00"
---

# 测试用例编写指南以及最佳实践 - Playwright

## **概述**

Playwright 是一个用于 Web 应用程序的端到端测试框架。本文档展示了如何在 Testany 中编写 Playwright 测试用例。

Testany 的 Playwright 执行器简化了端到端测试生命周期——从录制测试场景，到跨多个浏览器执行，再到统一界面中查看和分析测试结果。

## **使用 Playwright 执行器**

### **方法一：直接上传**

#### **准备测试用例**

与其他测试相似，您需要准备以下文件：

1. **测试代码文件**：例如 `e2e-demo.spec.ts`
2. **配置文件**：`playwright.config.ts`
3. **项目依赖文件**：`package.json`

**测试文件示例** (`tests/e2e-demo.spec.ts`)：

```typescript
import { test, expect } from '@playwright/test';

test('homepage has correct title', async ({ page }) => {
  const baseUrl = process.env.BASE_URL || 'https://example.com';

  await page.goto(baseUrl);
  await expect(page).toHaveTitle(/Example/);
});

test('login with credentials', async ({ page }) => {
  const baseUrl = process.env.BASE_URL;
  const username = process.env.TEST_USERNAME;
  const password = process.env.TEST_PASSWORD;

  await page.goto(`${baseUrl}/login`);
  await page.fill('input[name="username"]', username);
  await page.fill('input[name="password"]', password);
  await page.click('button[type="submit"]');

  await expect(page).toHaveURL(`${baseUrl}/dashboard`);
});
```


> **提示**
>
> **环境变量配置**
>
> 代码中使用的环境变量（如 `BASE_URL`、`TEST_USERNAME`）必须在**两处**配置：
> 1. **Test Case 详情页** → **Environment Variables** 部分：定义变量名和值
> 2. **测试脚本代码**：使用 `process.env.VARIABLE_NAME` 读取值
>
> 请参阅[《管理测试用例》](https://docs.testany.io/zh/docs/managing-test-case.md)了解如何在平台上配置环境变量。


**配置文件示例** (`playwright.config.ts`)：

```typescript
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30000,
  use: {
    headless: true,
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  reporter: [['html', { outputFolder: 'playwright-report' }]],
});
```

#### **打包测试用例**

在将 Playwright 测试脚本上传到 Testany 平台前，**必须保证相关的文件结构完整**，以便平台能正确识别入口、配置和依赖。

```text
playwright/                        ← ✅ 必须打包的根目录
├── node_modules/                  ← ⛔ 不打包
├── playwright-report/             ← ⛔ 不打包
│   └── ...
├── test-results/                  ← ⛔ 不打包
│   └── ...
├── tests/                         ← ✅ 必须打包的存放测试脚本的目录
│   └── e2e-demo.spec.js           ← ✅ 必须打包的示例测试用例
├── playwright.config.js           ← ✅ 必须打包的配置文件
└── package.json                   ← ✅ 必须打包的项目依赖声明
```

为了后续成功上传测试用例到 Testany 平台，请确保所有必需文件均被打包到一个 ZIP 压缩包中，例如 `e2e-demo.zip`。

#### **注册Testany测试用例**

准备好 ZIP 文件后，您就可以在 Testany 平台上注册测试用例。有关注册测试用例的详细步骤，请参阅我们文档中心的 [管理测试用例指南](https://docs.testany.io/zh/docs/managing-test-case.md)。


> **说明**
>
> 请确保测试用例的`meta`信息被正确维护：


- **执行器（Executor）**：`Playwright`
- **执行路径（Trigger Path）**：测试脚本的完整路径，从根目录开始（不允许包含空格），例如：`playwright/tests/e2e-demo.spec.js`
- **配置文件路径（Config path）**：`playwright.config.js`文件的完整路径，从根目录开始，例如：`playwright/playwright.config.js`

### 方法二：**从 Git 导入**

#### 提交代码至 Git

在使用 Git 导入前，**必须保证相关的文件及结构已完整上传至 Git**，以便平台能正确识别入口、配置和依赖。

```text
playwright/                        ← ✅ Must include root directory
├── node_modules/                  ← ⛔ Optional
├── playwright-report/             ← ⛔ Optional
│   └── ...
├── test-results/                  ← ⛔ Optional
│   └── ...
├── tests/                         ← ✅ Must include directory of your test files
│   └── e2e-demo.spec.js           ← ✅ Must include your test files
├── playwright.config.js           ← ✅ Must include Playwright config
└── package.json                   ← ✅ Must include project dependencies
```

#### **通过 Git 导入自动注册 Testany测试用例**

在代码已经推送到 Git 后，请根据您团队使用的导入方式选择对应文档：

- [Import from Git V1 与 V2](https://docs.testany.io/zh/docs/import-from-git-v1-vs-v2.md)
- [Import from Git V2：连接 GitHub 并创建导入](https://docs.testany.io/zh/docs/import-from-git-v2-create-import.md)
- [Import from Git V1（基于凭证的 Sync Link）](https://docs.testany.io/zh/docs/bulk-import-test-cases-from-git.md)

## **在 Testany 查看测试报告**

### **访问报告**

1. **通过点击执行历史记录页面的”View log“按钮打开 log 窗口**

   ![image-20250422-100612.png](https://docs.testany.io/docs/images/zh/image-20250422-100612_33f55778.png)
2. 点击”Artifacts“标签页

   ![image-20250422-100801.png](https://docs.testany.io/docs/images/zh/image-20250422-100801_e0e8ab86.png)
3. 点击”**Open report**”按钮，或展开“playwright-report”后点击”index.html“打开测试报告

   ![image-20250422-101002.png](https://docs.testany.io/docs/images/zh/image-20250422-101002_7dcf8069.png)

### 解读报告

#### **报告首页结构（概览页）**

测试文件和测试用例的列表：

- 绿色 ✅：测试通过
- 红色 ❌：测试失败

点击某一个测试文件或测试用例，会展开详细信息面板。

#### 详细信息面板

- **❗ Errors（错误详情）：**如果一个测试失败，这一部分会展示：**错误信息、期望值 vs 实际值** 的对比、**出错的代码位置。**

- 📝 **Test Steps（测试步骤）**：这一部分列出 Playwright 为您记录的每一步测试操作。每条操作都显示耗时，**绿色表示成功，红色表示失败**。您可以逐行回顾测试流程。
- **🎥 Videos（测试录屏）：**如果您启用了 video 录制（如 video: 'on' 或 'retain-on-failure'），您可播放整个测试过程的录屏，让您直观观察自动化操作了什么。
- **🔁 Traces（操作轨迹）：**如果您启用了 trace（如 trace: 'on' 或 'on-first-retry'），您可以点击”trace“链接下载 trace.zip 文件至本地查看。

×

## 本页术语

- [测试用例 (Test Case)](https://docs.testany.io/zh/docs/glossary.md#test-case)
- [执行器（Executor）](https://docs.testany.io/zh/docs/glossary.md#executor)
- [执行 (Execution)](https://docs.testany.io/zh/docs/glossary.md#execution)
- [环境 (Environment)](https://docs.testany.io/zh/docs/glossary.md#environment)
- [测试脚本 (Test Script)](https://docs.testany.io/zh/docs/glossary.md#test-script)
- [路径（Path）](https://docs.testany.io/zh/docs/glossary.md#path)