### Register Goldenfile and Get Temp Path in Rust

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Use `new_goldenpath` to obtain a temporary file path for writing. This is useful when the code under test expects a file path instead of a `Write` implementor. The comparison happens when `Mint` is dropped.

```rust
use goldenfile::Mint;
use std::fs;

#[test]
fn test_goldenpath() {
    let mut mint = Mint::new("tests/goldenfiles");

    // Obtain a temp path that will be compared against goldenfiles/output.txt
    let path = mint.new_goldenpath("output.txt").unwrap();

    // Pass the path to any function that writes a file.
    fs::write(&path, "Hello world!\n").unwrap();

    // When mint drops, the temp file is diffed against the golden version.
}
```

--------------------------------

### Create a Mint and write to goldenfiles

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Creates a new Mint pointed at a directory for golden files. Registers new goldenfiles and writes content to them. When the Mint drops, it compares the written content against the checked-in golden versions.

```rust
use goldenfile::Mint;
use std::io::Write;

#[test]
fn test_output() {
    // Point the Mint at the directory containing checked-in golden files.
    let mut mint = Mint::new("tests/goldenfiles");

    // Register goldenfiles — returns a temporary File to write into.
    let mut file1 = mint.new_goldenfile("file1.txt").unwrap();
    let mut file2 = mint.new_goldenfile("file2.txt").unwrap();

    writeln!(file1, "Hello world!").unwrap();
    writeln!(file2, "Foo bar!").unwrap();

    // When `mint` drops here, it compares the written content against
    // tests/goldenfiles/file1.txt and tests/goldenfiles/file2.txt.
    // If they differ, the test panics with a colored diff.
}
// To approve new output: UPDATE_GOLDENFILES=1 cargo test
```

--------------------------------

### Mint::new

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Creates a new Mint instance pointed at the specified directory for goldenfile management. The directory will be created if it doesn't exist. Upon dropping the Mint, it compares registered goldenfiles against their checked-in versions and panics if any differences are found. Empty files are permitted.

```APIDOC
## Mint::new

### Description
Creates a new `Mint` pointed at the given directory. The directory is created if it does not exist. When the `Mint` drops, it compares all registered goldenfiles against their checked-in versions and panics if any differ. Empty files are allowed.

### Method
`Mint::new(path: &str)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The directory path containing the golden files.

### Request Example
```rust
use goldenfile::Mint;

let mut mint = Mint::new("tests/goldenfiles");
```

### Response
#### Success Response
A new `Mint` instance.

#### Response Example
```rust
// Mint instance is returned and managed implicitly.
```
```

--------------------------------

### Create a Mint that skips empty goldenfiles

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Creates a Mint that only writes or updates goldenfiles when the new content is non-empty. If the output is empty, any existing golden file for that path is deleted. Useful for outputs that are conditionally produced.

```rust
use goldenfile::Mint;
use std::io::Write;

#[test]
fn test_conditional_output() {
    let mut mint = Mint::new_nonempty("tests/goldenfiles");

    // This file has content — it will be checked/updated normally.
    let mut file = mint.new_goldenfile("nonempty.txt").unwrap();
    writeln!(file, "Some content").unwrap();

    // This file is left empty — on UPDATE_GOLDENFILES=1, the golden
    // file will be deleted rather than overwritten with empty content.
    mint.new_goldenfile("empty.txt").unwrap();
}
```

--------------------------------

### Generate and Compare Goldenfiles in Rust

Source: https://github.com/calder/rust-goldenfile/blob/main/README.md

Use Mint to create and write to goldenfiles. When Mint goes out of scope, it automatically compares the written content against the checked-in golden version, failing the test if differences are found. Ensure the 'tests/goldenfiles' directory exists.

```rust
use goldenfile::Mint;
use std::io::Write;

let mut mint = Mint::new("tests/goldenfiles");
let mut file1 = mint.new_goldenfile("file1.txt").unwrap();
let mut file2 = mint.new_goldenfile("file2.txt").unwrap();

writeln!(file1, "Hello world!").unwrap();
writeln!(file2, "Foo bar!").unwrap();

```

--------------------------------

### Mint::new_goldenfile

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Registers a new goldenfile using its relative path and returns a temporary `File` that can be written to. The library automatically selects a differ strategy based on the file extension: binary formats use `binary_diff`, while others use `text_diff`. The provided path must be relative.

```APIDOC
## Mint::new_goldenfile

### Description
Registers a new goldenfile by relative path and returns a writable temporary `File`. The differ is automatically chosen based on file extension: binary formats (`.bin`, `.exe`, `.gz`, `.pcap`, `.tar`, `.zip`) use `binary_diff`; all other extensions use `text_diff`. The path must be relative.

### Method
`mint.new_goldenfile(path: &str)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The relative path for the goldenfile.

### Request Example
```rust
use goldenfile::Mint;
use std::io::Write;

let mut mint = Mint::new("tests/goldenfiles");
let mut txt = mint.new_goldenfile("output.txt").unwrap();
writeln!(txt, "parser result").unwrap();

let mut bin = mint.new_goldenfile("output.bin").unwrap();
bin.write_all(b"\x00\x01\x02\x03").unwrap();
```

### Response
#### Success Response
A `std::fs::File` instance that is writable.

#### Response Example
```rust
// File instance is returned and can be written to.
```
```

--------------------------------

### Register text and binary goldenfiles

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Registers new goldenfiles by relative path, returning a writable temporary File. The differ is automatically chosen based on file extension: binary formats use `binary_diff`, others use `text_diff`. Supports files in subdirectories.

```rust
use goldenfile::Mint;
use std::io::Write;

#[test]
fn test_text_and_binary() {
    let mut mint = Mint::new("tests/goldenfiles");

    // Text file — uses text_diff (colored line-by-line diff on failure).
    let mut txt = mint.new_goldenfile("output.txt").unwrap();
    writeln!(txt, "parser result line 1").unwrap();
    writeln!(txt, "parser result line 2").unwrap();

    // Binary file — uses binary_diff (reports differing byte offset).
    let mut bin = mint.new_goldenfile("output.bin").unwrap();
    bin.write_all(b"\x00\x01\x02\x03").unwrap();

    // Files in subdirectories are supported; the subdirectory is created
    // automatically under both the temp dir and the goldenfiles dir.
    let mut sub = mint.new_goldenfile("subdir/result.txt").unwrap();
    writeln!(sub, "File in subdir").unwrap();
}
```

--------------------------------

### Mint::check_goldenfiles

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Manually triggers the comparison of all registered goldenfiles against their checked-in versions. Panics if any file differs.

```APIDOC
## Mint::check_goldenfiles

### Description
Compares all registered goldenfiles against their checked-in versions immediately, rather than waiting for the `Mint` to drop. Panics if any file differs, printing a hint to re-run with `UPDATE_GOLDENFILES=1`.

### Method
`check_goldenfiles`

### Request Example
```rust
use goldenfile::Mint;

let mut mint = Mint::new("tests/goldenfiles");
// ... register goldenfiles ...
mint.check_goldenfiles();
```

### Response
This method does not return a value on success but panics on failure.
```

--------------------------------

### Compare Binary Files with `binary_diff`

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Compares two binary files byte-by-byte. Panics if file sizes differ or if content differs, reporting the first differing byte's index. Used automatically for binary file extensions.

```rust
use goldenfile::differs::binary_diff;
use std::fs;
use tempfile::NamedTempFile;

// Direct usage (typically not needed — Mint selects this automatically):
let old = NamedTempFile::new().unwrap();
let new = NamedTempFile::new().unwrap();
fs::write(old.path(), b"\x00\x01\x02").unwrap();
fs::write(new.path(), b"\x00\x01\xFF").unwrap(); // differs at byte 3
binary_diff(old.path(), new.path());
// panics: "tests/goldenfiles/output.bin: Files differ at byte 3"

// Size mismatch example:
fs::write(new.path(), b"\x00\x01").unwrap();
binary_diff(old.path(), new.path());
// panics: "File sizes differ: Old file is 3 bytes, new file is 2 bytes"
```

--------------------------------

### Select Differ by Path with `get_differ_for_path`

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Determines the appropriate differ (`text_diff` or `binary_diff`) based on a file path's extension. Useful for custom differ pipelines that need to fall back to defaults.

```rust
use goldenfile::mint::get_differ_for_path;
use std::path::Path;

// Inspect which differ would be used for a given path:
let text_differ  = get_differ_for_path(Path::new("output.txt"));   // → text_diff
let json_differ  = get_differ_for_path(Path::new("schema.json"));  // → text_diff
let bin_differ   = get_differ_for_path(Path::new("data.bin"));     // → binary_diff
let gz_differ    = get_differ_for_path(Path::new("archive.tar.gz")); // → binary_diff

// Useful when constructing a custom differ pipeline that falls back
// to the default for unrecognized extensions:
fn my_differ_for(path: &std::path::Path) -> goldenfile::differs::Differ {
    match path.extension().and_then(|e| e.to_str()) {
        Some("json") => Box::new(|old, new| {
            // custom JSON-aware diff ...
            goldenfile::differs::text_diff(old, new);
        }),
        _ => get_differ_for_path(path),
    }
}
```

--------------------------------

### Compare Text Files with `text_diff`

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Compares two UTF-8 text files. Panics with a colored diff on mismatch. Falls back to `binary_diff` if files contain invalid UTF-8. Typically used automatically by the library.

```rust
use goldenfile::differs::text_diff;
use std::fs;
use tempfile::NamedTempFile;

// Direct usage (typically not needed — Mint selects this automatically):
let old = NamedTempFile::new().unwrap();
let new = NamedTempFile::new().unwrap();
fs::write(old.path(), "line 1\nline 2\n").unwrap();
fs::write(new.path(), "line 1\nline 2\n").unwrap();
text_diff(old.path(), new.path()); // passes silently

// On mismatch, panics with similar_asserts colored diff:
// left  (old): "line 1\nline 2\n"
// right (new): "line 1\nline 3\n"
//                       ^^^^^^
```

--------------------------------

### Mint::new_goldenpath_with_differ

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Registers a goldenfile using a path and a custom differ. It returns a `PathBuf` to a temporary file and uses the provided differ for comparison.

```APIDOC
## Mint::new_goldenpath_with_differ

### Description
Combines path-based registration with a custom `Differ`. Returns a `PathBuf` to a temporary file and registers the provided differ for the comparison step.

### Method
`new_goldenpath_with_differ`

### Parameters
- `path` (str): The path to the goldenfile.
- `differ` (Box<dyn Fn(&Path, &Path) + Send + Sync>): A custom differ function.

### Request Example
```rust
use goldenfile::Mint;
use std::path::Path;

fn byte_count_diff(old: &Path, new: &Path) {
    // ... implementation ...
}

let mut mint = Mint::new("tests/goldenfiles");
let path = mint.new_goldenpath_with_differ("archive.bin", Box::new(byte_count_diff)).unwrap();
```

### Response
Returns a `Result` containing a `PathBuf` to the temporary file or an error.
```

--------------------------------

### Mint::new_nonempty

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Similar to `Mint::new`, but goldenfiles are only written or updated if the new content is non-empty. If the generated output is empty, any existing golden file for that path will be deleted. This is useful for outputs that are conditionally generated.

```APIDOC
## Mint::new_nonempty

### Description
Creates a new `Mint` that skips empty goldenfiles. Goldenfiles will only be written/updated when the new content is non-empty. If the written output is empty, any existing golden file for that path is deleted. Useful for outputs that are conditionally produced.

### Method
`Mint::new_nonempty(path: &str)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The directory path containing the golden files.

### Request Example
```rust
use goldenfile::Mint;

let mut mint = Mint::new_nonempty("tests/goldenfiles");
```

### Response
#### Success Response
A new `Mint` instance configured to skip empty files.

#### Response Example
```rust
// Mint instance is returned and managed implicitly.
```
```

--------------------------------

### Mint::new_goldenpath

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Registers a goldenfile and returns a temporary file path. This is useful when the code under test requires a file path instead of a writeable file handle.

```APIDOC
## Mint::new_goldenpath

### Description
Registers a goldenfile, returning a `PathBuf` to the temporary file instead of an open `File` handle. This is useful when code under test accepts a file path rather than a `Write` implementor.

### Method
`new_goldenpath`

### Parameters
- `path` (str): The path to the goldenfile.

### Request Example
```rust
use goldenfile::Mint;
use std::fs;

let mut mint = Mint::new("tests/goldenfiles");
let path = mint.new_goldenpath("output.txt").unwrap();
fs::write(&path, "Hello world!\n").unwrap();
```

### Response
Returns a `Result` containing a `PathBuf` to the temporary file or an error.
```

--------------------------------

### Mint::new_goldenfile_with_differ

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Registers a goldenfile with an explicitly supplied Differ function. A Differ is a closure that compares old and new file paths and panics if they differ.

```APIDOC
## Mint::new_goldenfile_with_differ

### Description
Registers a goldenfile with an explicitly supplied `Differ` function instead of the auto-detected one. A `Differ` is `Box<dyn Fn(&Path, &Path) + Send + Sync>` that compares the old and new file paths and panics with a descriptive message if they differ.

### Method
`new_goldenfile_with_differ`

### Parameters
- `path` (str): The path to the goldenfile.
- `differ` (Box<dyn Fn(&Path, &Path) + Send + Sync>): A custom differ function.

### Request Example
```rust
use goldenfile::Mint;
use std::path::Path;

fn sorted_lines_diff(old: &Path, new: &Path) {
    // ... implementation ...
}

let mut mint = Mint::new("tests/goldenfiles");
let mut file = mint.new_goldenfile_with_differ("unordered.txt", Box::new(sorted_lines_diff)).unwrap();
```

### Response
Returns a `Result` containing an open `File` handle or an error.
```

--------------------------------

### Mint::update_goldenfiles

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Manually overwrites the checked-in golden files with the newly written content. This is equivalent to running the test with the `UPDATE_GOLDENFILES=1` environment variable.

```APIDOC
## Mint::update_goldenfiles

### Description
Overwrites the checked-in golden files with the newly written content immediately. This is the same operation triggered automatically when `UPDATE_GOLDENFILES=1`. Supports Bazel via the `BUILD_WORKSPACE_DIRECTORY` environment variable.

### Method
`update_goldenfiles`

### Request Example
```rust
use goldenfile::Mint;

let mut mint = Mint::new("tests/goldenfiles");
// ... register and write to goldenfiles ...
mint.update_goldenfiles();
```

### Response
This method does not return a value on success. It prints messages indicating which files are being updated.
```

--------------------------------

### Register Goldenfile Path with Custom Differ in Rust

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Combine path-based registration with a custom differ using `new_goldenpath_with_differ`. This returns a temporary file path and registers the provided differ for the comparison step.

```rust
use goldenfile::Mint;
use std::fs;
use std::path::Path;

fn byte_count_diff(old: &Path, new: &Path) {
    let old_len = fs::metadata(old).unwrap().len();
    let new_len = fs::metadata(new).unwrap().len();
    assert_eq!(old_len, new_len, "file sizes differ: {} vs {}", old_len, new_len);
}

#[test]
fn test_goldenpath_custom_differ() {
    let mut mint = Mint::new("tests/goldenfiles");

    let path = mint
        .new_goldenpath_with_differ("archive.bin", Box::new(byte_count_diff))
        .unwrap();

    fs::write(&path, b"\xDE\xAD\xBE\xEF" as &[u8]).unwrap();
}
```

--------------------------------

### get_differ_for_path

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Automatically selects the appropriate `Differ` for a given file path based on its extension. Binary extensions map to `binary_diff`, while others map to `text_diff`. This function is called internally by `new_goldenfile` and `new_goldenpath`.

```APIDOC
## `get_differ_for_path` — Automatic differ selection by file extension

Returns the appropriate `Differ` for a given path based on its extension. Binary extensions (`.bin`, `.exe`, `.gz`, `.pcap`, `.tar`, `.zip`) map to `binary_diff`; everything else maps to `text_diff`. Called internally by `new_goldenfile` and `new_goldenpath`.

```rust
use goldenfile::mint::get_differ_for_path;
use std::path::Path;

// Inspect which differ would be used for a given path:
let text_differ  = get_differ_for_path(Path::new("output.txt"));   // → text_diff
let json_differ  = get_differ_for_path(Path::new("schema.json"));  // → text_diff
let bin_differ   = get_differ_for_path(Path::new("data.bin"));     // → binary_diff
let gz_differ    = get_differ_for_path(Path::new("archive.tar.gz")); // → binary_diff

// Useful when constructing a custom differ pipeline that falls back
// to the default for unrecognized extensions:
fn my_differ_for(path: &std::path::Path) -> goldenfile::differs::Differ {
    match path.extension().and_then(|e| e.to_str()) {
        Some("json") => Box::new(|old, new| {
            // custom JSON-aware diff ...
            goldenfile::differs::text_diff(old, new);
        }),
        _ => get_differ_for_path(path),
    }
}
```
```

--------------------------------

### differs::binary_diff

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Compares two binary files byte-by-byte. If file sizes differ, it panics reporting both sizes. If content differs, it panics reporting the 1-based index of the first differing byte. Used automatically for binary file extensions.

```APIDOC
## `differs::binary_diff` — Built-in binary file differ

Compares two binary files byte-by-byte. If file sizes differ, panics reporting both sizes. If content differs, panics reporting the 1-based index of the first differing byte. Used automatically for `.bin`, `.exe`, `.gz`, `.pcap`, `.tar`, `.zip` extensions.

```rust
use goldenfile::differs::binary_diff;
use std::fs;
use tempfile::NamedTempFile;

// Direct usage (typically not needed — Mint selects this automatically):
let old = NamedTempFile::new().unwrap();
let new = NamedTempFile::new().unwrap();
fs::write(old.path(), b"\x00\x01\x02").unwrap();
fs::write(new.path(), b"\x00\x01\xFF").unwrap(); // differs at byte 3
binary_diff(old.path(), new.path());
// panics: "tests/goldenfiles/output.bin: Files differ at byte 3"

// Size mismatch example:
fs::write(new.path(), b"\x00\x01").unwrap();
binary_diff(old.path(), new.path());
// panics: "File sizes differ: Old file is 3 bytes, new file is 2 bytes"
```
```

--------------------------------

### differs::text_diff

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Compares two UTF-8 text files and panics with a colored, human-readable line diff if they differ. Falls back to binary_diff if UTF-8 is invalid. Used automatically for non-binary file extensions.

```APIDOC
## `differs::text_diff` — Built-in text file differ

Compares two UTF-8 text files and panics with a colored, human-readable line diff if they differ. If either file contains invalid UTF-8, falls back to `binary_diff`. Used automatically for non-binary file extensions.

```rust
use goldenfile::differs::text_diff;
use std::fs;
use tempfile::NamedTempFile;

// Direct usage (typically not needed — Mint selects this automatically):
let old = NamedTempFile::new().unwrap();
let new = NamedTempFile::new().unwrap();
fs::write(old.path(), "line 1\nline 2\n").unwrap();
fs::write(new.path(), "line 1\nline 2\n").unwrap();
text_diff(old.path(), new.path()); // passes silently

// On mismatch, panics with similar_asserts colored diff:
// left  (old): "line 1\nline 2\n"
// right (new): "line 1\nline 3\n"
//                       ^^^^^^ 
```
```

--------------------------------

### Update Goldenfiles with Environment Variable

Source: https://github.com/calder/rust-goldenfile/blob/main/README.md

To update the checked-in goldenfile versions, run your tests with the UPDATE_GOLDENFILES environment variable set to 1. This applies to both standard cargo tests and Bazel builds.

```sh
UPDATE_GOLDENFILES=1 cargo test

```

```sh
UPDATE_GOLDENFILES=1 bazel run ...

```

--------------------------------

### Register Goldenfile with Custom Differ in Rust

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Use `new_goldenfile_with_differ` to register a goldenfile with a custom comparison function. The provided `Differ` (a boxed closure) is used instead of the default auto-detection.

```rust
use goldenfile::Mint;
use goldenfile::differs::Differ;
use std::io::Write;
use std::path::Path;

fn sorted_lines_diff(old: &Path, new: &Path) {
    let mut old_lines: Vec<String> = std::fs::read_to_string(old)
        .unwrap()
        .lines()
        .map(str::to_string)
        .collect();
    let mut new_lines: Vec<String> = std::fs::read_to_string(new)
        .unwrap()
        .lines()
        .map(str::to_string)
        .collect();
    old_lines.sort();
    new_lines.sort();
    assert_eq!(old_lines, new_lines, "sorted line sets differ");
}

#[test]
fn test_custom_differ() {
    let mut mint = Mint::new("tests/goldenfiles");

    // Use a custom differ that compares files ignoring line order.
    let mut file = mint
        .new_goldenfile_with_differ("unordered.txt", Box::new(sorted_lines_diff))
        .unwrap();

    writeln!(file, "banana").unwrap();
    writeln!(file, "apple").unwrap();
    writeln!(file, "cherry").unwrap();
}
```

--------------------------------

### Manually Trigger Goldenfile Comparison in Rust

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Use `check_goldenfiles` to manually trigger comparison of all registered goldenfiles. This method panics on any difference, providing a hint to re-run with `UPDATE_GOLDENFILES=1`.

```rust
use goldenfile::Mint;
use std::io::Write;

#[test]
fn test_explicit_check() {
    let mut mint = Mint::new("tests/goldenfiles");
    let mut file = mint.new_goldenfile("result.txt").unwrap();
    writeln!(file, "expected output").unwrap();
    drop(file); // ensure write is flushed before checking

    // Explicitly check before mint goes out of scope (e.g., for early assertion).
    mint.check_goldenfiles();
    // On mismatch, panics with colored diff and message:
    // "error: goldenfile changed: result.txt"
    // "note: run with `UPDATE_GOLDENFILES=1` to update goldenfiles"
}
```

--------------------------------

### Manually Overwrite Golden Files in Rust

Source: https://context7.com/calder/rust-goldenfile/llms.txt

Use `update_goldenfiles` to immediately overwrite checked-in golden files with new content. This is equivalent to running tests with `UPDATE_GOLDENFILES=1` and supports Bazel integration.

```rust
use goldenfile::Mint;
use std::io::Write;

#[test]
fn test_explicit_update() {
    let mut mint = Mint::new("tests/goldenfiles");
    let mut file1 = mint.new_goldenfile("update1.txt").unwrap();
    let mut file2 = mint.new_goldenfile("update2.txt").unwrap();

    writeln!(file1, "Hello world!").unwrap();
    writeln!(file2, "foobar").unwrap();

    // Immediately overwrite checked-in goldenfiles with new content.
    // Prints: Updating "update1.txt". Updating "update2.txt".
    mint.update_goldenfiles();
}
// Equivalent shell invocation:
// UPDATE_GOLDENFILES=1 cargo test
// UPDATE_GOLDENFILES=1 bazel run //my:test_target
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.