CAPL 编程系列教程 - 第三十三期 测试模块 (Test Module) 入门

CAPL 编程 - 第 33 期：测试模块 (Test Module) 入门

目标: 本期开始介绍 CANoe 中用于结构化、自动化测试的核心特性——CAPL 测试模块 (Test Module)。学习如何在 CANoe 中创建、配置测试模块，并编写基本的测试脚本，包括测试用例和执行控制。

1. 测试模块 (Test Module) 概念

• 是什么: Test Module 是 CANoe 提供的一个框架，允许使用 CAPL 语言编写、组织、执行自动化测试用例，并自动生成结构化的测试报告。它将测试逻辑与执行控制和结果评估分离开来。
• 目的: 从通用的 CAPL 编程转向专门面向测试验证的脚本开发，实现自动化测试流程。

2. 创建与配置测试模块

• 创建:
  • 在 CANoe 的 "Simulation Setup" (仿真设置) 窗口中，右键点击仿真总线或空白区域。
  • 选择 "Insert CAPL Test Module"。
• 配置:
  • 右键单击新创建的 Test Module 节点，选择 "Configuration"。
  • General (通用) Tab:
    • Name: 为测试模块设置一个描述性的名称 (例如: "Demo Test Module")。
    • File: 关联一个 CAPL 脚本文件 (.can)。点击 "Edit" 或 "..." 选择或创建一个新的 .can 文件。
      • 推荐: 在项目工程目录下创建专门的子文件夹 (如 Test Modules) 来存放测试脚本文件，保持结构清晰。
  • Test Report (测试报告) Tab:
    • Output file: 配置测试报告的生成路径和文件名。
      • 推荐: 在项目工程目录下创建专门的子文件夹 (如 Test Reports) 来存放报告文件，将脚本与报告分离。
    • 默认生成的文件格式通常是 Vector Test Report Viewer 可以打开的格式。
• 文件结构: 建议在 CANoe 工程根目录下创建 Test Modules (存放 .can 脚本) 和 Test Reports (存放报告) 文件夹。

3. 编写测试脚本 (.can 文件)

• CAPL Browser 结构: 当编辑与 Test Module 关联的 .can 文件时，CAPL Browser 会显示特定的测试相关节点，如 Test Functions, Test Cases, Test Control。
• 核心组件:
  • 测试用例函数 (testcase):
    • 目的: 定义一个独立的、可执行的测试场景。
    • 语法: 使用 testcase 关键字代替 void 或其他返回类型来声明。函数名通常以 Test 或 TC_ 开头，便于识别。
      Code snippet

      testcase MyTestCase01()
      {
        // Test logic here...
      }
      

    • 内容: 包含执行测试步骤、调用被测功能、检查结果并记录测试步骤状态的代码。
  • 测试步骤断言/记录函数 (TestStepPass, TestStepFail):
    • 目的: 在 testcase 函数内部，根据检查结果显式地记录某个测试步骤是通过还是失败。
    • 常用函数:
      • TestStepPass(char stepID[], char descriptionFormat[], ...): 记录一个成功的步骤。
      • TestStepFail(char stepID[], char descriptionFormat[], ...): 记录一个失败的步骤。
    • 参数:
      • stepID: 一个字符串，用于标识测试步骤 (例如 "1.1", "Check Init State")。
      • descriptionFormat: 描述性文本，可以包含格式说明符 (如 %d, %s)，类似于 write 函数。
      • ...: 可变参数，用于填充 descriptionFormat 中的说明符。
    • 作用: 这些函数的调用结果会直接记录在最终的测试报告中，并影响测试用例的整体判定 (Verdict)。
  • 主测试函数 (MainTest):
    • 目的: 作为测试模块执行的入口点，定义测试用例的执行顺序和流程。
    • 语法: 必须命名为 MainTest，返回类型为 void，通常无参数。位于 CAPL Browser 的 Test Control 节点下。
      Code snippet

      void MainTest()
      {
        // Call test cases in desired order
        MyTestCase01();
        MyTestCase02();
      }
      

    • 实现: 在函数体内按顺序调用需要执行的 testcase 函数。
• 其他元素: 仍然可以在测试脚本中使用 includes, variables 以及定义普通的辅助 functions (例如，被测函数本身或用于测试逻辑的帮助函数)。

4. 执行测试与查看报告

• 执行:
  1. 启动 CANoe 测量 (点击工具栏的“Start”按钮)。
  2. 打开 Test Module 执行面板：双击 Simulation Setup 中的 Test Module 节点，或右键点击选择 "Execution"，或通过 "Test" 菜单访问。
  3. 在 Test Module 执行面板中，点击 "Run" (▶) 按钮。
  4. 流程: CANoe 会执行关联 .can 文件中的 MainTest 函数，进而按顺序执行 MainTest 中调用的 testcase 函数。
• Test Module 执行面板: 实时显示正在执行/已执行的测试用例列表、每条用例的最终判定结果 (Verdict - 通常是 Pass/Fail 图标) 以及执行耗时。
• 测试报告:
  • 生成: 测试执行完毕后自动生成。
  • 查看: 在 Test Module 执行面板中点击 "Open Test Report" 按钮，或直接打开配置文件中指定的报告文件。报告通常使用 "Vector CANoe Test Report Viewer" 查看。
  • 内容: 包含测试概览（通过/失败数量、总用例数、执行时间等）和详细信息（每个测试模块、测试用例及测试步骤的执行结果、由 TestStepPass/Fail 记录的描述信息）。

5. 实例总结 (来自讲座)

• 讲座中演示了测试一个简单的 add 函数。
• 创建了 TestAdd01 (测试 3+5=8，预期通过) 和 TestAdd02 (测试 3.2+5.4=8.6，但因函数返回 long 导致截断，预期失败)。
• 在 MainTest 中调用了这两个 testcase。
• 执行后，在 Test Module 面板看到一条 Pass，一条 Fail。
• 在 Test Report Viewer 中查看详细报告，确认了每条用例及步骤的结果和描述信息，验证了 TestStepPass/Fail 的作用。

总结: 本期介绍了 CANoe Test Module 的基本概念和使用流程：创建模块、配置脚本和报告路径、编写包含 testcase (使用 TestStepPass/Fail 记录结果) 和 MainTest (控制执行流程) 的 CAPL 脚本、执行测试并查看结果面板和详细报告。这是使用 CAPL 进行自动化测试的基础。