Crate goldie 

Simple golden file testing for Rust.

goldie::assert!(text);

🚀 Getting started

Add goldie to your project as a dev dependency.

cargo add goldie --dev

In your test function assert the contents using goldie::assert!. The golden filename will be automatically determined based on the test file and test function name. Run tests with GOLDIE_UPDATE=1 to automatically update golden files.

#[test]
fn example() {
    let text = { /* ... run the test ... */ };

    // assert that the contents of ./testdata/example.golden
    // are equal to `text`
    goldie::assert!(text)
}

Usage

Golden file location

By default golden files are stored in a testdata directory next to the source test module. For example if your test is in src/a/tests.rs then the golden files will be stored in src/a/testdata/. This is configurable by using the Builder. For example:

goldie::new!()
    .name("custom_name")
    .build()
    .assert(text);

assert!

Compares the provided value with the contents of a golden file. The value must implement Display. If they do not match the test will fail. If the environment variable GOLDIE_UPDATE=1 is set then the golden file will be updated.

assert_alt!

Compares the provided value with the contents of a golden file. The value must implement Display. The alternate formatting ({:#}) is used. If they do not match the test will fail. If the environment variable GOLDIE_UPDATE=1 is set then the golden file will be updated.

assert_debug!

Compares the provided value with the contents of a golden file. The value must implement Debug. If they do not match the test will fail. If the environment variable GOLDIE_UPDATE=1 is set then the golden file will be updated.

assert_debug_alt!

Compares the provided value with the contents of a golden file. The value must implement Debug. The alternate formatting ({:#?}) is used. If they do not match the test will fail. If the environment variable GOLDIE_UPDATE=1 is set then the golden file will be updated.

assert_json!

Golden files containing JSON data are supported using goldie::assert_json!. Something implementing serde::Serialize needs to be provided as the actual value. The golden file will be pretty-printed JSON. You can use GOLDIE_UPDATE=1 to automatically update JSON golden files.

#[test]
fn example() {
    #[derive(Serialize)]
    struct User {
        name: &'static str,
        surname: &'static str,
    }

    let u = User { name: "Steve", surname: "Harrington" };

    // assert that the contents of ./testdata/example.golden
   // are equal to the pretty-printed JSON representation of `u`
    goldie::assert_json!(&u);
}

assert_template!

Templated golden files are also supported using goldie::assert_template!. Something implementing serde::Serialize needs to be provided as context in order to render the template. Values are rendered using upon e.g. {{ value.field }}. You cannot use GOLDIE_UPDATE=1 to automatically update templated golden files.

#[test]
fn example() {
    let text = { /* ... run the test ... */ };

    // assert that the contents of ./testdata/example.golden
    // are equal to `text` after rendering with `ctx`.
    let ctx = upon::value!{ value: "Hello World!" };
    goldie::assert_template!(&ctx, text)
}

Macros

assert

Assert the golden file matches the display output "{}"

assert_alt

Assert the golden file matches the alternate display output "{:#}".

assert_debug

Assert the golden file matches the debug output "{:?}"

assert_debug_alt

Assert the golden file matches the alternate debug output "{:#?}".

assert_json

Assert the JSON golden file matches.

assert_template

Assert the templated golden file matches.

Structs

Builder

Builder for configuring a goldie assertion.

Goldie

Configuration for a golden file assertion