pub struct Jail { /* private fields */ }
test
only.Expand description
A “sandboxed” environment with isolated env and file system namespace.
Jail
creates a pseudo-sandboxed (not actually sandboxed) environment for
testing configurations. Specifically, Jail
:
- Synchronizes all calls to
Jail::expect_with()
andJail::try_with()
to prevent environment variables races. - Switches into a fresh temporary directory (
Jail::directory()
) where files can be created withJail::create_file()
. - Keeps track of environment variables created with
Jail::set_env()
and clears them when theJail
exits. - Deletes the temporary directory and all of its contents when exiting.
Additionally, because Jail
expects functions that return a Result
,
the ?
operator can be used liberally in a jail:
use figment::{Figment, Jail, providers::{Format, Toml, Env}};
figment::Jail::expect_with(|jail| {
jail.create_file("Cargo.toml", r#"
name = "test"
authors = ["bob"]
publish = false
"#)?;
jail.set_env("CARGO_NAME", "env-test");
let config: Config = Figment::new()
.merge(Toml::file("Cargo.toml"))
.merge(Env::prefixed("CARGO_"))
.extract()?;
Ok(())
});
Implementations
sourceimpl Jail
impl Jail
sourcepub fn expect_with<F: FnOnce(&mut Jail) -> Result<()>>(f: F)
pub fn expect_with<F: FnOnce(&mut Jail) -> Result<()>>(f: F)
Creates a new jail that calls f
, passing itself to f
.
Panics
Panics if f
panics or if Jail::try_with(f)
returns
an Err
; prints the error message.
Example
figment::Jail::expect_with(|jail| {
/* in the jail */
Ok(())
});
sourcepub fn directory(&self) -> &Path
pub fn directory(&self) -> &Path
Returns the directory the jail has switched into. The contents of this
directory will be cleared when Jail
is dropped.
Example
figment::Jail::expect_with(|jail| {
let tmp_directory = jail.directory();
Ok(())
});
sourcepub fn create_file<P: AsRef<Path>>(&self, path: P, contents: &str) -> Result<File>
pub fn create_file<P: AsRef<Path>>(&self, path: P, contents: &str) -> Result<File>
Creates a file with contents contents
in the jail’s directory. The
file will be deleted with the jail is dropped.
Example
figment::Jail::expect_with(|jail| {
jail.create_file("MyConfig.json", "contents...");
Ok(())
});
sourcepub fn set_env<K: AsRef<str>, V: Display>(&mut self, k: K, v: V)
pub fn set_env<K: AsRef<str>, V: Display>(&mut self, k: K, v: V)
Set the environment variable k
to value v
. The variable will be
removed when the jail is dropped.
Example
const VAR_NAME: &str = "my-very-special-figment-var";
assert!(std::env::var(VAR_NAME).is_err());
figment::Jail::expect_with(|jail| {
jail.set_env(VAR_NAME, "value");
assert!(std::env::var(VAR_NAME).is_ok());
Ok(())
});
assert!(std::env::var(VAR_NAME).is_err());
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Jail
impl Send for Jail
impl Sync for Jail
impl Unpin for Jail
impl UnwindSafe for Jail
Blanket Implementations
sourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more