从源代码控制仪器

有时需要仅对源代码的某些区域应用 CoverageScanner 设置，例如排除文件的一部分进行仪器化。

以下章节描述了执行此操作的几种方法。

注释

源代码注释是特定的注释，可让您选择要验证的源代码部分。存在两种注释类型

• 注释：注释是简单的代码注释，可以用于给测试者提供建议。它们对代码覆盖率没有影响
• 手动验证：手动验证表示某些代码行应该被视为已验证。手动验证对代码覆盖率的影响与执行源代码行相同

可以使用 CoverageBrowser 直接编辑源代码注释，或通过在源代码中写入特定的注释来生成。

注释

要为单个源代码行生成注释，以关键字 coco 开始 C 或 C++ 注释。这将在此行的所有仪器化中插入注释。

在以下示例中，将在第 4 行的仪器化中添加 为了测试失败，将当前工作目录更改为只读目录 的注释。

void write_log( const char *text )
{
   FILE * f = fopen( "log.txt", "a+" );
   if ( f ) /* coco: To test the failure,
                     change the current working
                     directory to a read-only directory */
   {
       fputs( text, f ):
       fclose( f );
   }
}

也可以使用关键字 coco begin 和 coco end 为多行源代码生成注释。

在以下示例中，将 为了测试失败，将当前工作目录更改为只读目录 的注释添加到函数 write_log() 的行。

void write_log( const char *text )
{
   /* coco begin:  To test the failure,
                   change the current working
                   directory to a read-only directory */
   FILE * f = fopen( "log.txt", "a+" );
   if ( f )
   {
       fputs( text, f ):
       fclose( f );
   }
   /* coco end */
}

手动验证

可以使用代码中关键字 coco validated: <comment> 开始的强制注释生成手动验证的仪器化。该评论将随后出现在覆盖率报告中。要验证多行代码区域，请使用以下形式的注释

// coco begin validated: <comment>
...
// coco end

C 风格注释（《code translate="no">/* ... */）也是可能的。

为了与 PureCoverage 调整兼容，CoverageScanner 也识别以关键字 inspected 或 tested 开头的 purecov 行注释，或作为替代，可以使用多行注释的形式 begin inspected / "begin tested" 和 "end inspected" / "end tested"。

在以下示例中，注释 "这个函数不需要测试，仅用于调试。" 将被添加到函数 write_log() 的代码插桩中。

void write_log( const char *text )
{
   // coco begin validated: This function does not need to be tested, only used for debugging.
   FILE * f = fopen( "log.txt", "a+" );
   if ( f )
   {
       fputs( text, f ):
       fclose( f );
   }
}
// coco end

请注意，coco end 注释放在函数结尾之后。这是因为 Coco 测量函数的代码覆盖范围是在函数的最后一个括号处，即函数的结束位置。当我们想要标记一个完整的函数已被覆盖时，我们需要在手动验证注释之间包括最后一个结束括号。

在函数前放置 coco begin 注释以包含函数头不是必需的。

已知限制

目前无法标记决策的单个结果为手动验证。

如果一个 "if (<decision>)" 或 "while (<decision>)" 语句被 "coco validated:" 和 "coco end" 注释包围，那么当 <decision> 为真和为假的情况都被计为手动验证。否则，它们都没有经过验证。在 CoverageBrowser 中标记为已验证的 if 或 while 语句也是同样的道理。

复杂决策的条件也遵循同样的规则：对于一个形式为 "if ((a && b) || c)" 的语句，无法声明当 a 和 b 为假而 c 为真时的情况是手动验证的。

C 和 C++ 预处理器

CoverageScanner 定义了 C 和 C++ 预处理器来在编译期间控制插桩。所有控制预处理器都在堆栈中处理。它们在源文件结束或遇到 #pragma CoverageScanner(pop) 命令之前都有效。

预处理器有以下语法

• #pragma CoverageScanner(<string>)
• __pragma (CoverageScanner(<string>))
• _Pragma (CoverageScanner(<string>))

支持的预处理器列表

• #pragma CoverageScanner(cov-on)：启用代码覆盖率插桩。
• #pragma CoverageScanner(cov-off)：禁用代码覆盖率插桩。
• #pragma CoverageScanner(cov-hit)：使用代码覆盖率命中进行插桩。
• #pragma CoverageScanner(cov-count)：使用代码覆盖率计数进行插桩。
• #pragma CoverageScanner(cov-statement-block)：选择语句块覆盖作为插桩方法。
• #pragma CoverageScanner(cov-decision)：选择决策覆盖作为插桩方法。
• #pragma CoverageScanner(cov-condition)：选择条件覆盖作为插桩方法。
• #pragma CoverageScanner(cov-partial-instrumentation)：条件和不决策的部分插桩。
• #pragma CoverageScanner(cov-full-instrumentation)：条件和不决策的全量插桩。
• #pragma CoverageScanner(cov-assignment-on)：在赋值中插桩布尔表达式。
• #pragma CoverageScanner(cov-assignment-off)：在赋值中不插桩布尔表达式。
• #pragma CoverageScanner(cov-return-on)：在返回语句中插桩布尔表达式。
• #pragma CoverageScanner(cov-return-off)：在返回语句中不插桩布尔表达式。
• #pragma CoverageScanner(cov-switch-case-off)：不插桩 switch 语句的所有情况。
• #pragma CoverageScanner(cov-switch-case-on)：插桩 switch 语句的所有情况。
• #pragma CoverageScanner(pop)：从最新的 CoverageScanner 预 处理指令的调用之前恢复 仪 行式 选项。

C# 区域

CoverageScanner 定义了 C# 对 #region 关 键 字 的 扩 展，这些 扩 展 在 编 译 时 控 制 了 仪 行 式 的 生成。

#region 扩 展具有以下 语 法

#region CoverageScanner (<字 符 串>)

#endregion 关 键 字 恢 复生 成 选项。

支持的 区域 列 表

• #region CoverageScanner(cov-on)： 启用 代 码 覆 盖 仪 行 式。
• #region CoverageScanner(cov-off)： 禁用 代 码 覆 盖 仪 行 式。
• #region CoverageScanner(cov-hit)： 使用 代 码 覆 盖 击 中 仪 行 式。
• #region CoverageScanner(cov-count)： 使用 代 码 覆 盖 数 量 仪 行 式。
• #region CoverageScanner(cov-statement-block)： 将 语 句 块 覆 盖 作 为 仪 行 式 方 法。
• #region CoverageScanner(cov-decision)： 将 决 定 覆 盖 作 为 仪 行 式 方 法。
• #region CoverageScanner(cov-condition)： 将 条 件 覆 盖 作 为 仪 行 式 方 法。
• #region CoverageScanner(cov-partial-instrumentation)： 条 件 和 决 定 的 部 分 仪 行 式。
• #region CoverageScanner(cov-full-instrumentation)： 条 件 和 决 定 的 完 全 仪 行 式。
• #region CoverageScanner(cov-assignment-on)： 在 分 配 中 仪 行 式 布尔 表 达 式。
• #region CoverageScanner(cov-assignment-off)： 在 分 配 中 不 仪 行 式 布尔 表 达 式。
• #region CoverageScanner(cov-switch-case-off)： 在 switch 语 句 中 不 仪 行 式 所 有 情况。
• #region CoverageScanner(cov-switch-case-on)： 在 switch 语 句 中 仪 行 式 所 有 情况。