pub struct Settings { /* private fields */ }
Expand description

Configures how insta operates at test time.

Settings are always bound to a thread and some default settings are always available. These settings can be changed and influence how insta behaves on that thread. They can either temporarily or permanently changed.

This can be used to influence how the snapshot macros operate. For instance it can be useful to force ordering of maps when unordered structures are used through settings.

Some of the settings can be changed but shouldn’t as it will make it harder for tools like cargo-insta or an editor integration to locate the snapshot files.

Settings can also be configured with the with_settings! macro.

Example:

use insta;

let mut settings = insta::Settings::clone_current();
settings.set_sort_maps(true);
settings.bind(|| {
    // runs the assertion with the changed settings enabled
    insta::assert_snapshot!(...);
});

Implementations

Returns the default settings.

It’s recommended to use clone_current instead so that already applied modifications are not discarded.

Returns a copy of the current settings.

Enables forceful sorting of maps before serialization.

Note that this only applies to snapshots that undergo serialization (eg: does not work for assert_debug_snapshot!.)

The default value is false.

Returns the current value for map sorting.

Disables prepending of modules to the snapshot filename.

By default the filename of a snapshot is <module>__<name>.snap. Setting this flag to false changes the snapshot filename to just <name>.snap.

The default value is true.

Returns the current value for module name prepending.

Allows the glob! macro to succeed if it matches no files.

By default the glob macro will fail the test if it does not find any files to prevent accidental typos. This can be disabled when fixtures should be conditional.

The default value is false.

Returns the current value for the empty glob setting.

Sets the snapshot suffix.

The snapshot suffix is added to all snapshot names with an @ sign between. For instance if the snapshot suffix is set to "foo" and the snapshot would be named "snapshot" it turns into "snapshot@foo". This is useful to separate snapshots if you want to use test parameterization.

Removes the snapshot suffix.

Returns the current snapshot suffix.

Sets the input file reference.

This value is completely unused by the snapshot testing system but it lets you store some meta data with a snapshot that refers you back to the input file. The path stored here is made relative to the workspace root before storing with the snapshot.

Removes the input file reference.

Returns the current input file reference.

Sets the description.

The description is stored alongside the snapshot and will be displayed in the diff UI. When a snapshot is captured the Rust expression for that snapshot is always retained. However sometimes that information is not super useful by itself, particularly when working with loops and generated tests. In that case the description can be set as extra information.

See also set_info.

Removes the description.

Returns the current description

Available on crate feature serde only.

Sets the info.

The info is similar to description but for structured data. This is stored with the snapshot and shown in the review UI. This for instance can be used to show extended information that can make a reviewer better understand what the snapshot is supposed to be testing.

As an example the input parameters to the function that creates the snapshot can be persisted here.

Alternatively you can use set_raw_info instead.

Sets the info from a content object.

This works like set_info but does not require serde.

Removes the info.

Returns the current info

If set to true, does not retain the expression in the snapshot.

Returns true if expressions are omitted from snapshots.

Available on crate feature redactions only.

Registers redactions that should be applied.

This can be useful if redactions must be shared across multiple snapshots.

Note that this only applies to snapshots that undergo serialization (eg: does not work for assert_debug_snapshot!.)

Available on crate feature redactions only.

Registers a replacement callback.

This works similar to a redaction but instead of changing the value it asserts the value at a certain place. This function is internally supposed to call things like assert_eq!.

This is a shortcut to add_redaction(selector, dynamic_redaction(...));

Available on crate feature redactions only.

A special redaction that sorts a sequence or map.

This is a shortcut to add_redaction(selector, sorted_redaction()).

Available on crate feature redactions only.

Replaces the currently set redactions.

The default set is empty.

Available on crate feature redactions only.

Removes all redactions.

Available on crate feature filters only.

Adds a new filter.

Filters are similar to redactions but are applied as regex onto the final snapshot value. This can be used to perform modifications to the snapshot string that would be impossible to do with redactions because for instance the value is just a string.

The first argument is the regex pattern to apply, the second is a replacement string. The replacement string has the same functionality as the second argument to Regex::replace.

This is useful to perform some cleanup procedures on the snapshot for unstable values.

settings.add_filter(r"\b[[:xdigit:]]{32}\b", "[UID]");
Available on crate feature filters only.

Replaces the currently set filters.

The default set is empty.

Available on crate feature filters only.

Removes all filters.

Sets the snapshot path.

If not absolute it’s relative to where the test is in.

Defaults to snapshots.

Returns the snapshot path.

Runs a function with the current settings bound to the thread.

This is an alternative to bind_to_scope which does not require holding on to a drop guard. The return value of the closure is passed through.

let mut settings = Settings::clone_current();
settings.set_sort_maps(true);
settings.bind(|| {
    // do stuff here
});

Like bind but for futures.

This lets you bind settings for the duration of a future like this:

let settings = Settings::new();
settings.bind_async(async {
    // do assertions here
}).await;

Binds the settings to the current thread and resets when the drop guard is released.

This is the recommended way to temporarily bind settings and replaces the earlier bind_to_scope and relies on drop guards. An alterantive is bind which binds for the duration of the block it wraps.

let mut settings = Settings::clone_current();
settings.set_sort_maps(true);
let _guard = settings.bind_to_scope();
// do stuff here

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.