cargo-coverage-annotations v0.4.3

确保源代码包含正确反映是否被覆盖的注释。

安装

要安装

cargo install cargo-coverage-annotations

动机

代码覆盖率很重要，有很多工具用于计算和显示它。这个工具是为了任何想在第一时间看到哪些代码被/未被覆盖的人，即使不是使用专门的覆盖率查看工具，只要查看源代码本身即可。这的缺点是开发者需要保持这些注释是最新的（这个工具有助于确保这一点）。优点是使覆盖率明确，使代码更有可能被测试，暴露出代码未被访问的情况，即使测试“应该”触发它，实际上却没有，并且通常将代码覆盖率变为开发者不能忽视的东西。

运行

创建覆盖率 XML 文件

要在当前工作目录中的 cargo 项目上运行，首先在当前工作目录的任何位置生成 cobertura.xml 文件。没有标准的 cargo coverage 命令，因此此代码已针对使用 cargo tarpaulin --out Xml 进行测试，以及（很久以前）使用 cargo kcov（这些天似乎维护得较少）。

当然，其他工具生成其他覆盖率文件格式，并将它们放在不同的位置。如果你查看 CodeCov，你会看到用于检测这些文件的大于1K行的代码，并且这还不包括解析不同格式的代码。因此，如果你的 favorite 工具不受支持，欢迎 pull requests ;-)

验证覆盖率注释

为了验证代码中的覆盖率注释是否与实际覆盖率相匹配，请运行 cargo coverage-annotations。这将合并来自所有 cobertura.xml 文件的覆盖率信息，并将结果与覆盖率注释进行比较（见下文）。

覆盖率注释

覆盖率注释是表示代码行覆盖率状态的注释。默认情况下，假设代码行已被测试覆盖。未测试的行应包含显式的 // NOT TESTED 注释。在某些特殊情况下（例如，仅在特定平台上执行的行），也可以用 // MAYBE TESTED 注释标记一行。如果您愿意，可以使用 /* ... */ 替代 // ... 注释。

有时需要标记整个代码块。在这种情况下，可以用 // BEGIN NOT TESTED ... // END NOT TESTED 注释（或 // BEGIN MAYBE TESTED ... // END MAYBE TESTED）包围这些行。在这些区域内，可以使用 // TESTED、// NOT TESTED 或 // MAYBE TESTED 注释覆盖特定行的注释。

有些文件可能根本未经测试。在这种情况下，它们必须在它们的某一行包含 // FILE NOT TESTED 或 // FILE MAYBE TESTED 注释。

有时代码行实际上已经经过测试，但覆盖率工具并没有将其标记为测试（没有工具是完美的）。为了解决这个问题，可以将一行（或一个区域，或一个文件）标记为 // FLAKY TESTED。默认情况下，这被处理得与 // MAYBE TESTED 完全相同。这也可以通过使用 --flaky=maybe-tested 明确设置。您可以使用 --flaky=tested 来覆盖它，这将抱怨覆盖率工具标记错误的所有行（作为未测试的）。更有趣的是，您可以使用 --flaky=not-tested 来抱怨覆盖率工具标记正确（作为测试）的所有行，这在检查新版本的工具是否提高了其准确性时很有用。如果现在（可靠地）将行标记为测试，则可以删除 // FLAKY TESTED 注释。

覆盖率注释仅用于 src 目录和 tests 目录中的文件。它们确保在阅读代码时，人们知道哪些被测试覆盖，哪些没有被测试覆盖。当然，行覆盖率只是覆盖率跟踪的最基本形式；尽管如此，在每一步跟踪它出奇地有效，有助于隔离代码行为不符合预期的情况。

许可证

cargo-coverage-annotations 采用 GNU 通用公共许可证（版本 3.0）进行分发。详情请见 LICENSE。