3、第一个测试用例：编写并运行简单的测试用例，理解测试用例的组成（关键字、参数、返回值）与执行流程

在掌握了 Robot Framework 的环境搭建与基础语法之后，我们正式进入自动化测试的核心实践环节。本章将带领你从零编写并运行第一个完整的测试用例，深入剖析测试用例的三大组成要素——关键字、参数与返回值，并梳理从用例编写到报告生成的完整执行流程。理解这些基础概念，是后续构建复杂测试套件、设计数据驱动测试和封装业务关键字的基石。

3.1 测试用例的核心组成：关键字、参数与返回值

Robot Framework 的测试用例本质上是一系列关键字（Keyword）的调用序列。关键字是执行特定操作的最小单元，它可以是框架内置的（如 Log、Should Be Equal），也可以来自第三方测试库（如 SeleniumLibrary 中的 Open Browser），还可以是用户自定义的关键字。每个关键字都可以接收参数（Argument）来定制其行为，并在执行后返回返回值（Return Value）供后续步骤使用。

理解三者的关系是编写有效测试用例的前提。关键字定义了“做什么”，参数定义了“怎么做”，返回值则提供了“结果如何”的证据。例如，Should Be Equal 关键字接收两个参数（期望值和实际值），如果两者不一致，该关键字会抛出断言错误，导致测试用例失败。这种设计使得测试用例的意图非常清晰，且易于维护。

3.2 编写第一个测试用例：从需求到脚本

我们以一个最简单的场景为例：验证两个数字相加的结果。这个场景虽然简单，但完整地展示了测试用例的编写规范和执行流程。首先，我们需要创建一个 .robot 文件，并在其中定义测试套件（Suite）和测试用例（Test Case）。

*** Settings ***
Documentation    这是一个简单的数学运算测试套件
Library          Collections

*** Variables ***
${NUMBER_A}    10
${NUMBER_B}    20

*** Test Cases ***
验证两个数字相加
    [Documentation]    验证 10 + 20 的结果等于 30
    [Tags]    smoke    math
    ${sum}=    Evaluate    ${NUMBER_A} + ${NUMBER_B}
    Should Be Equal As Integers    ${sum}    30
    Log    ${sum}    计算完成

在上述代码中，*** Settings *** 部分引入了 Collections 库（虽然本例未直接使用，但展示了库的导入方式）。*** Variables *** 定义了全局变量。*** Test Cases *** 下是具体的测试用例。用例中，Evaluate 关键字执行 Python 表达式并返回结果，Should Be Equal As Integers 断言返回值与期望值相等，Log 关键字将结果输出到日志。

运行该测试用例的命令非常简单：在终端中切换到文件所在目录，执行 robot 文件名.robot。Robot Framework 会自动解析文件，执行用例，并生成 output.xml、log.html 和 report.html 三个文件。其中，report.html 是概要报告，log.html 是详细日志，包含每个关键字的执行时间、参数和状态。

3.3 案例拆解：一个带前置条件与清理步骤的完整用例

在实际项目中，测试用例往往需要前置条件（Setup）和清理步骤（Teardown）。例如，测试一个 Web 登录功能，我们需要先打开浏览器，测试结束后关闭浏览器。Robot Framework 提供了 [Setup] 和 [Teardown] 来管理这些步骤。下面是一个更贴近实战的案例：

*** Settings ***
Library    SeleniumLibrary
Test Setup       Open Browser    https://example.com/login    chrome
Test Teardown    Close All Browsers

*** Variables ***
${VALID_USER}    admin
${VALID_PWD}     secret123

*** Test Cases ***
用户使用有效凭证登录
    [Documentation]    验证有效用户能够成功登录
    [Tags]    login    regression
    Input Text    id=username    ${VALID_USER}
    Input Text    id=password    ${VALID_PWD}
    Click Button    id=login-btn
    Wait Until Page Contains    Welcome, admin
    Page Should Contain    Dashboard

在这个案例中，Test Setup 和 Test Teardown 定义了每个测试用例执行前后的固定操作。测试用例本身只关注业务步骤：输入用户名、输入密码、点击登录、验证页面内容。这种结构将“环境准备”与“业务验证”分离，大大提高了用例的稳定性和可维护性。

我们来看一下执行过程中的关键数据流：Input Text 关键字接收两个参数（定位器和输入值），Click Button 接收一个参数（定位器），Wait Until Page Contains 接收一个参数（期望出现的文本）。这些关键字执行后，SeleniumLibrary 会返回操作结果（成功或失败），但通常我们不需要显式接收返回值，因为如果操作失败，关键字会直接抛出异常，导致用例失败。

3.4 常见误区与执行流程复盘

初学者在编写第一个测试用例时，常会遇到以下几类问题：

• 空格使用不当：Robot Framework 使用两个或更多空格作为参数分隔符。如果只使用一个空格，框架会将整个内容视为一个参数，导致关键字找不到或参数错误。
• 变量作用域混淆：在 *** Variables *** 中定义的变量是全局的，而在测试用例中通过 ${var}= 创建的变量是局部于该用例的。如果需要在多个用例间共享数据，应使用 Suite 或 Global 级别的变量。
• 忽略返回值：有些关键字（如 Get Text）会返回页面上的文本内容。如果不接收返回值，就无法进行后续断言。正确的做法是使用 ${text}= Get Text 语法。
• 断言不充分：只验证操作成功（如点击按钮）而不验证结果（如页面跳转、数据变化），会导致测试用例失去意义。应始终使用 Should ... 系列关键字进行结果验证。

为了帮助大家更好地理解执行流程，我们复盘一个典型的失败场景：假设上述登录用例中，Input Text 的定位器 id=username 写错了，实际页面的 id 是 user-name。执行流程如下：

1. Test Setup 打开浏览器，成功。
2. 执行 Input Text，SeleniumLibrary 尝试查找 id=username 元素，未找到。
3. 关键字抛出 Element not found 异常，该用例立即终止。
4. Test Teardown 执行，关闭所有浏览器。
5. 用例状态为 FAIL，报告和日志中记录了失败原因和堆栈信息。

通过查看 log.html，我们可以清晰地看到每个关键字的执行状态、耗时和错误信息。这正是 Robot Framework 强大的可调试性所在。建议读者在编写用例后，养成查看日志的习惯，尤其是关注 FAIL 关键字前后的上下文。