goldentests/lib.rs
1//! A testing library utilizing golden tests.
2//!
3//! ### Why golden tests?
4//!
5//! Golden tests allow you to specify the output of
6//! some command within a file and automatically ensure
7//! that that output doesn't change. If it does, goldentests
8//! will show an error-diff showing the expected and actual
9//! output. This way, whenever the output of something changes
10//! a human can see the change and decide if it should be kept
11//! or is a bug and should be reverted.
12//!
13//! ### What are golden tests useful for?
14//!
15//! Golden tests are especially useful for applications that
16//! take a file as input and produce output of some kind. For
17//! example: compilers and config-parsers (well, parsers in general)
18//! are two such applications that can benefit form automated golden
19//! tests. In the case of a config parser, you would be able to
20//! provide many config examples as tests and ensure that your
21//! parser was able to read the files with the expected stdout/stderr
22//! output and exit code.
23//!
24//! ### How do I get started?
25//!
26//! Include a test in your program that looks something like this:
27//!
28//! ```rust
29//! use goldentests::{ TestConfig, TestResult };
30//!
31//! #[test]
32//! fn run_goldentests() -> TestResult<()> {
33//! // Replace "// " with your language's/parser's comment syntax.
34//! // This tells golden tests to embed its keywords in lines beginning with "// "
35//! let config = TestConfig::new("target/debug/my-binary", "directory/with/tests", "// ")?;
36//! config.run_tests()
37//! }
38//! ```
39//!
40//! Now you can start adding tests to `directory/with/tests` and each test should
41//! be automatically found and ran by goldentests whenever you run `cargo test`.
42//! Here's a quick example of a test file that uses most of goldentest's features:
43//!
44//! ```python
45//! import sys
46//!
47//! print("hello!\nfriend!")
48//! print("error!", file=sys.stderr)
49//! sys.exit(3)
50//!
51//! # Assuming 'python' is the command passed to TestConfig::new:
52//! # args: -B
53//! # expected exit status: 3
54//! # expected stdout:
55//! # hello!
56//! # friend!
57//!
58//! # expected stderr: error!
59//! ```
60pub mod config;
61mod config_file;
62mod diff_printer;
63pub mod error;
64mod runner;
65
66pub use config::TestConfig;
67pub use error::TestResult;