需求文档可执行验收标准

2026年1月21日 · 阅读需 9 分钟

Quany

软件工程师

一、什么是可执行验收标准？

可执行验收标准是将需求转化为可测试、可自动化的具体规格。它使用特定格式（通常是Given-When-Then）来描述功能的行为，可以直接转换为自动化测试用例。

二、可执行验收标准的好处

明确性：消除需求歧义
可测试性：直接转换为测试用例
自动化：支持BDD（行为驱动开发）
一致性：开发、测试、产品理解一致
可追踪：需求与测试直接对应

三、常用格式

1. Gherkin语言（Given-When-Then）

最常用的格式，被Cucumber、SpecFlow等工具支持。

Feature: 用户登录功能
  作为一个已注册用户
  我想要登录系统
  以便访问我的个人资料
  
  Scenario: 使用正确的用户名和密码登录
    Given 用户已注册且账户有效
    When 在登录页面输入正确的用户名"admin"和密码"123456"
    And 点击登录按钮
    Then 应该跳转到用户主页
    And 页面应显示欢迎信息"欢迎回来，admin"
    
  Scenario: 使用错误的密码登录
    Given 用户已注册
    When 在登录页面输入用户名"admin"和错误密码"wrong"
    And 点击登录按钮
    Then 页面应显示错误消息"密码错误"
    And 用户应该保持在登录页面

2. 表格格式

适合参数化场景和数据驱动测试。

Scenario Outline: 用户登录验证
  Given 用户"<username>"已注册
  When 输入用户名"<username>"和密码"<password>"
  And 点击登录按钮
  Then 登录结果应为"<result>"
  
  Examples:
    | username | password | result     |
    | admin    | 123456   | 成功       |
    | admin    | wrong    | 密码错误   |
    | unknown  | 123456   | 用户不存在 |
    |          | 123456   | 用户名为空 |

四、在需求文档中的具体实现

示例需求文档结构

# 需求文档：用户管理系统

## 1. 概述
- 目标：实现用户注册、登录、资料管理功能
- 范围：Web端用户管理模块
- 优先级：P0
- 预估工时：5人日

## 2. 功能需求

### 2.1 用户登录功能
**需求描述**：已注册用户可以通过用户名和密码登录系统

**验收标准**：

| ID | 描述 | 优先级 | 状态 |
|----|------|--------|------|
| UC-001 | 用户使用正确的用户名和密码登录 | P0 | 待办 |
| UC-002 | 用户使用错误的密码登录 | P0 | 待办 |
| UC-003 | 用户使用不存在的用户名登录 | P1 | 待办 |

**可执行验收标准**：

#### UC-001: 成功登录
```gherkin
Feature: 用户登录
  Scenario: 使用正确的用户名和密码登录
    Given 用户"testuser"已注册且账户状态为"active"
    And 用户在登录页面
    When 输入用户名"testuser"
    And 输入密码"Test@123"
    And 点击"登录"按钮
    Then 应该跳转到首页"/dashboard"
    And 页面应显示欢迎消息"欢迎回来，testuser"
    And 导航栏应显示"注销"按钮
    And 应该记录登录日志
    And Cookie中应设置有效的sessionId

UC-002: 密码错误

Feature: 用户登录
  Scenario: 使用错误的密码登录
    Given 用户"testuser"已注册
    And 用户在登录页面
    When 输入用户名"testuser"
    And 输入密码"WrongPassword123"
    And 点击"登录"按钮
    Then 页面应显示错误提示"用户名或密码错误"
    And 输入框应清空密码字段
    And 登录按钮应重新可用
    And URL应保持不变
    And 不应创建会话

2.2 用户注册功能

可执行验收标准：

Feature: 用户注册
  Scenario Outline: 新用户注册验证
    Given 用户访问注册页面
    When 填写注册信息：
      | 字段       | 值           |
      | 用户名     | <username>   |
      | 邮箱       | <email>      |
      | 密码       | <password>   |
      | 确认密码   | <confirm>    |
    And 点击"注册"按钮
    Then 应该<result>
    
    Examples: 有效注册
      | username | email              | password  | confirm   | result                          |
      | alice    | alice@test.com     | Pass123!  | Pass123!  | 显示成功消息并跳转到登录页面    |
      
    Examples: 无效注册
      | username | email           | password  | confirm   | result                          |
      | ab       | alice@test.com  | Pass123!  | Pass123!  | 提示"用户名长度至少3个字符"     |
      | alice    | invalid-email   | Pass123!  | Pass123!  | 提示"邮箱格式不正确"           |
      | alice    | alice@test.com  | 123456    | 123456    | 提示"密码必须包含字母和特殊字符"|
      | alice    | alice@test.com  | Pass123!  | Different | 提示"两次输入的密码不一致"     |

五、最佳实践

1. 编写原则

# ✅ DO - 好的做法
Scenario: 用户成功下单
  Given 用户已登录
  And 购物车中有商品"iPhone 15"
  When 用户点击"立即购买"
  And 选择"微信支付"
  And 点击"确认支付"
  Then 应跳转到订单详情页面
  And 订单状态应为"已支付"
  And 应发送订单确认邮件
  And 应扣减商品库存

# ❌ DON'T - 避免的做法
Scenario: 用户买东西
  Given 有东西
  When 弄一下
  Then 搞定了

2. 原子性原则

每个场景应该只测试一个具体功能点。

# ❌ 不好 - 包含多个不相关的验证
Scenario: 综合验证
  Given 用户登录
  When 修改个人资料
  And 下订单
  Then 资料应该更新
  And 订单应该创建
  
# ✅ 好 - 单一职责
Scenario: 修改个人资料
  Given 用户已登录
  When 修改邮箱为"new@email.com"
  And 点击保存
  Then 应显示"保存成功"
  And 用户邮箱应更新为"new@email.com"

3. 使用背景（Background）

避免重复的Given步骤。

Feature: 购物车管理
  
  Background: 用户已登录且有商品
    Given 用户"testuser"已登录
    And 商品"iPhone 15"存在
    And 商品"MacBook Pro"存在
    
  Scenario: 添加商品到购物车
    When 用户将商品"iPhone 15"添加到购物车
    Then 购物车中应有1件"iPhone 15"
    
  Scenario: 从购物车移除商品
    Given 购物车中有商品"iPhone 15"
    When 用户从购物车移除"iPhone 15"
    Then 购物车应为空

六、完整示例模板

# 需求文档模板

## 1. 功能名称
[功能简要描述]

### 1.1 用户故事
**作为** [角色]
**我想要** [功能]
**以便** [价值/目标]

### 1.2 功能描述
[详细描述功能]

### 1.3 验收标准
| ID | 描述 | 优先级 | 状态 | 测试负责人 |
|----|------|--------|------|------------|
| AC-001 | [标准1] | P0 | 待办 | [姓名] |
| AC-002 | [标准2] | P1 | 待办 | [姓名] |

### 1.4 可执行验收标准
```gherkin
Feature: [功能名称]
  [可选的背景描述]
  
  @smoke @P0
  Scenario: [场景1描述]
    Given [前置条件]
    When [操作步骤]
    Then [预期结果]
    
  @regression @P1  
  Scenario: [场景2描述]
    Given [前置条件]
    When [操作步骤]
    Then [预期结果]
    
  Scenario Outline: [参数化场景]
    Given [前置条件]
    When [操作步骤]
    Then [预期结果]
    
    Examples:
      | 参数1 | 参数2 | 预期结果 |
      | val1 | val2 | result1 |
      | val3 | val4 | result2 |

1.5 技术约束

[约束1]
[约束2]

1.6 非功能需求

类型	要求
性能	响应时间 < 2秒
安全性	密码加密存储
兼容性	支持 Chrome 90+

## 七、在开发流程中的使用

### 1. 需求评审阶段
```yaml
步骤：
  1. 产品经理编写验收标准草稿
  2. 开发、测试、产品一起评审
  3. 修正不清晰或不可测试的标准
  4. 确定验收条件的优先级
  
产出物：
  - 评审通过的验收标准
  - 明确的需求优先级

2. 开发实现阶段

步骤：
  1. 开发根据验收标准实现功能
  2. 测试根据验收标准编写自动化测试
  3. 运行自动化测试验证实现
  
产出物：
  - 实现的功能代码
  - 自动化测试脚本
  - 测试执行报告

3. 验收测试阶段

步骤：
  1. 执行自动化验收测试
  2. 手动验收（如有需要）
  3. 确认所有验收标准已满足
  4. 产品经理签字确认
  
产出物：
  - 验收测试报告
  - 验收确认单

八、工具支持

1. 文档工具

Confluence + Xray：需求与测试管理
JIRA + Zephyr：需求跟踪与测试管理
Azure DevOps：完整的DevOps工具链

2. BDD工具

Cucumber：Java/Ruby/JavaScript
SpecFlow：.NET平台
Behat：PHP平台
Behave：Python平台

3. 自动化测试框架

// Cucumber + Selenium 示例
const { Given, When, Then } = require('@cucumber/cucumber');
const { By, until } = require('selenium-webdriver');

Given('用户已登录', async function() {
  await this.driver.get('http://localhost:3000/login');
  await this.driver.findElement(By.id('username')).sendKeys('testuser');
  await this.driver.findElement(By.id('password')).sendKeys('password');
  await this.driver.findElement(By.id('login-btn')).click();
});

When('用户搜索{string}', async function(keyword) {
  await this.driver.findElement(By.id('search')).sendKeys(keyword);
  await this.driver.findElement(By.id('search-btn')).click();
});

九、指标和度量

1. 覆盖率指标

需求覆盖率: 95%  # (有验收标准的需求数 / 总需求数) * 100%
测试通过率: 98%  # (通过的验收测试数 / 总验收测试数) * 100%
自动化率: 85%    # (可自动化验收标准数 / 总验收标准数) * 100%

2. 质量门禁

验收标准:
  - 所有P0级验收标准必须100%通过
  - 整体验收标准通过率不低于95%
  - 关键业务场景必须包含自动化测试
  
文档质量:
  - 每个需求必须包含可执行验收标准
  - 验收标准必须经过三方评审
  - 验收标准必须清晰、可测试

十、常见错误和避免方法

1. 避免实现细节

# ❌ 不好 - 包含实现细节
When 点击class为"btn-primary"的按钮
Then 应该设置localStorage中的token

# ✅ 好 - 关注业务行为
When 点击登录按钮
Then 用户应该成功登录

2. 避免重复步骤

# ❌ 不好 - 重复步骤
Scenario: 测试A
  Given 打开浏览器
  And 访问登录页面
  # ... 其他步骤
  
Scenario: 测试B  
  Given 打开浏览器
  And 访问登录页面
  # ... 其他步骤

# ✅ 好 - 使用Background
Background:
  Given 打开浏览器
  And 访问登录页面
  
Scenario: 测试A
  # ... 测试步骤
  
Scenario: 测试B
  # ... 测试步骤

3. 保持独立性

# ❌ 不好 - 场景间有依赖
Scenario: 创建订单
  Given 用户登录
  When 创建订单
  Then 订单创建成功
  
Scenario: 查看订单
  # 依赖于上一个场景创建的订单
  When 查看订单列表
  Then 应该看到订单

# ✅ 好 - 每个场景自包含
Scenario: 查看订单
  Given 用户已登录
  And 系统中存在用户"testuser"的订单
  When 用户查看订单列表
  Then 应该看到订单

总结

在需求文档中增加可执行验收标准的价值：

对齐期望：确保所有干系人对需求理解相同
自动化基础：直接转换为自动化测试
文档即测试：需求文档本身就可以执行
持续反馈：在开发过程中持续验证
质量保证：明确的验收条件确保交付质量

通过实施可执行验收标准，团队可以显著提高需求质量、减少返工、加快交付速度，并建立持续质量保证的机制。

一、什么是可执行验收标准？​

二、可执行验收标准的好处​

三、常用格式​

1. Gherkin语言（Given-When-Then）​

2. 表格格式​

四、在需求文档中的具体实现​

示例需求文档结构​

UC-002: 密码错误​

2.2 用户注册功能​

五、最佳实践​

1. 编写原则​

2. 原子性原则​

3. 使用背景（Background）​

六、完整示例模板​

1.5 技术约束​

1.6 非功能需求​

2. 开发实现阶段​

3. 验收测试阶段​

八、工具支持​

1. 文档工具​

2. BDD工具​

3. 自动化测试框架​

九、指标和度量​

1. 覆盖率指标​

2. 质量门禁​

十、常见错误和避免方法​

1. 避免实现细节​

2. 避免重复步骤​

3. 保持独立性​

总结​

微信公众号​