Lib.rs

Golden Tests

Golden Tests是一个配置为从测试文件中创建和编辑测试，而不必触摸编译器、解释器或其他工具源代码的Golden文件测试库。

为什么使用Golden Tests？

Golden Tests允许你在文件中指定某些命令的输出，并自动确保该输出不会改变。如果确实改变了，goldentests将显示一个错误-diff，显示期望和实际输出。这样，每当某物的输出发生变化时，人类可以查看更改并决定是否应该保留或是一个错误，应该回滚。

Golden Tests有什么用途？

Golden Tests对于以文件为输入并产生某种输出的应用程序特别有用。例如：编译器和配置解析器（好吧，解析器一般）是两种可以从中受益的自动Golden Tests的应用程序。在配置解析器的情况下，你可以提供许多配置示例作为测试，并确保你的解析器能够读取文件并产生预期的stdout/stderr输出和退出代码。

示例输出

入门

从版本1.1开始，现在有两种使用goldentests的方式 - 要么作为独立的二进制文件，要么作为Rust集成测试。如果你想作为二进制文件运行它，请继续。如果不这样做，请跳到下一节。解决完这个问题后，我们可以通过以下方式安装goldentests

$ cargo install goldentests --features binary

以下是一个使用示例

$ goldentests /bin/python path-to-tests '# '

这将告诉goldentests在path-to-tests目录中的每个文件上运行/bin/python。你可能会想要用你喜欢的参数来别名这个命令，以便更容易地进行测试。以下是一个测试示例

print("Hello, World!")

# args: -b
# expected stdout:
# Hello, World!

此文件告诉goldentests运行命令/bin/python -b path-to-tests/example.py，如果命令的输出不是"Hello, World!"，则发出错误。

请注意，在注释中嵌入了一些测试关键字 args: 和 expected stdout:。这是我们在调用 goldentests 时使用的 '# ' 参数。您可以通过更改此参数来更改 goldentests 在解析文件时查找的前缀。对于大多数语言，这应该是某种类型的注释。例如，如果我们正在测试 Haskell，我们会使用 -- 作为测试行前缀。

作为 Rust 集成测试

使用 goldentests 的第二种方式是将它作为 Rust 库用于编写集成测试。使用此方法将在每次调用 goldentests 时运行 cargo test。要开始，请将以下内容放入 Cargo.toml。

goldentests = "1.1"

并在 tests/goldentests.rs 中创建一个集成测试。特定的名称无关紧要，只要测试可以被 cargo 捕获即可。典型用法如下

use goldentests::{ TestConfig, TestResult };

#[test]
fn run_golden_tests() -> TestResult<()> {
    let config = TestConfig::new("target/debug/my-binary", "my-test-path", "// ")?;
    config.run_tests()
}

这将告诉 goldentests 在 my-test-path 中递归地查找所有文件，并使用 target/debug/my-binary 以某种方式使用文件来产生预期的输出。例如，如果我们正在测试类似 C 的语言的编译器，我们的测试文件可能如下所示

puts("Hello, World!");

// args: --run
// expected stdout:
// Hello, World!

这将运行命令 target/debug/my-binary --run my-test-path/example.c，如果命令的输出不是 "Hello, World!"，将引发错误。

请注意，在注释中嵌入了一些测试关键字 args: 和 expected stdout:。这是 Rust 示例中的 "// " 参数。您可以通过更改此参数来更改 goldentests 在解析文件时查找的前缀。对于大多数语言，这应该是某种类型的注释。例如，如果我们正在测试 Haskell，我们会使用 -- 作为测试行前缀。

高级用法

以下是 goldentests 在文件中查找的全部关键字集合

• args: <single-line-string>：此关键字之后的任何内容都将用作创建 TestConfig 时指定的程序的命令行参数。
• expected stdout: <multi-line-string>：此关键字将继续读取字符，将它们追加到预期的 stdout 输出，直到遇到不以测试前缀（如上面示例中的 "//"）开头的行。如果程序运行的 stdout 与此处给出的字符串不同，将发出适当的错误，并提供给定的 diff。默认为 ""。
• 期望的stderr: <multi-line-string>：与期望的stdout:相同，但针对stderr流。默认值也为""。
• 期望的退出状态: [i32]：如果指定，goldentests将在退出状态与预期不符时发出错误。默认值为None（默认情况下忽略退出状态）。

您还可以配置要使用的特定关键字。有关更多信息，请参阅goldentest的文档这里。

自动更新测试

可选地，可以在运行goldentests作为独立程序时通过传递--overwrite标志来自动更新测试，或者在作为rust库运行时设置overwrite_tests标志。这样做将更新每个文件中的预期输出，使其与实际输出匹配。由于这是自动的，因此在使用此标志之前，请务必手动审查任何更改。