介绍 Exemplar：用于自动化样本测试的工具
引言
本文介绍了一个名为 Exemplar 的新库。Exemplar 的目标是确保用户获得您期望看到的输出。它处理样本发现、规范化（语义等效结果，可能来自不同环境）和灵活的输出验证。它调用环境中任何命令行工具。例如，您还可以调用 curl 来验证服务 API 响应。
Gradle 使用此库来验证文档和指南中的示例，并消除集成测试中的样板代码。
Exemplar 可以使用 JUnit 测试运行器（推荐）或使用其 API 进行配置。请参阅以下示例和 Exemplar GitHub 存储库 中的示例。
Exemplar 的用例 #
文档样本的准确性很重要。想象一下，当您尝试学习新东西而示例却无法正常工作时，那种沮丧。
我们认为 Exemplar 作为文档检查机制效果最佳。但它并非旨在替代其他形式的集成测试。
Exemplar 的独特之处在于它允许发现嵌入在结构化文档中的样本，以及 OutputNormalizers（捆绑和自定义），方便在“更传统”的集成测试中使用样本项目（通过 @UsesSample("path/to/sample")），并且允许在执行前对样本进行程序化修改（可能用于额外的环境设置）（SampleModifier）。
Exemplar 专注于日志记录和退出代码输出，验证其他副作用很麻烦（检查创建的文件可能需要额外的命令）。此外，尽管 Exemplar 可以用于任何工具，但它只为 JVM 项目提供 API。
样本项目测试入门 #
Exemplar 中的 sample-discovery 库会将样本根目录下包含 *.sample.conf 文件的任何目录视为样本项目。
样本配置文件以 HOCON 编写，并告诉 sample-check 如何运行样本项目。它可以很简单
executable: echo
args: "Hello World"
...也可以更复杂，包含多个步骤
commands: [{
executable: gradle
args: originalInputs incrementalReverse
expected-output-file: originalInputs.out
allow-additional-output: true
}, {
executable: gradle
args: --quiet removeOutput incrementalReverse
expected-output-file: incrementalTaskRemovedOutput.out
allow-disordered-output: true
}]
请参阅文档中的样本配置参考，了解可用的选项。
然后 JUnit 测试声明哪些 @SampleRunner 和样本测试的其他方面。
@RunWith(GradleSamplesRunner.class)
@SamplesRoot("src/docs/samples")
@SamplesOutputNormalizers({JavaObjectSerializationOutputNormalizer.class, FileSeparatorOutputNormalizer.class})
public class SamplesIntegrationTest {}
执行此测试将发现并运行外部（即非嵌入式）样本项目，并生成您期望的 JUnit 测试报告。
嵌入式样本测试入门 #
Exemplar 可以使用 Asciidoctor 的 AST 发现 Asciidoctor 源文件中的样本。这是一个示例，它也使用 SampleModifiers 来设置样本环境。
.Sample title
====
[.testable-sample] (1)
=====
.hello.rb (2)
[source,ruby] (3)
-----
puts "hello, #{ARGV[0]}" (4)
-----
[.sample-command] (5)
-----
$ ruby hello.rb world (6)
hello, world (7)
-----
=====
====
请阅读嵌入式样本文档，了解实现此功能所需的 Asciidoctor 元素。
我们使用 EmbeddedSamplesRunner 运行此测试，指向 docs/ 根目录，Exemplar 将在该目录中查找文档文件。
@RunWith(EmbeddedSamplesRunner.class)
@SamplesRoot("docs")
@SampleModifiers({SetupEnvironmentSampleModifier.class, ExtraCommandArgumentsSampleModifier.class})
public class EmbeddedSamplesIntegrationTest {}
执行此测试将从 Asciidoctor 中提取代码到临时项目，运行它，并验证它是否与文档中声明的输出匹配。
采用和贡献 #
最佳入门方法是阅读 Exemplar 文档，并查看 Exemplar 的样本和样本测试。
撰写本文时，Exemplar 的版本为 0.6，这意味着在 1.0 版本之前 API 可能会发生变化。尽管如此，考虑到 API 已经经历了一些修订并已被 Gradle 采用，在 1.0 版本之前不太可能出现重大更改。
以下是一些可能对库进行良好扩展的方面，如果您渴望提交想法或向 gradle/exemplar GitHub 存储库 提交拉取请求，我将非常乐意获得您的帮助。
- 更多标准规范器，例如日期、时间或持续时间规范化
- 生成结构化元数据用于搜索索引
- 允许将预期输出内联到样本配置文件中
- Markdown 或其他文档格式中嵌入的样本发现 (#2938)
如果您需要采用或贡献此项目的指导，请联系我（Twitter 上的 @eriwen）。