|0.5.0||May 16, 2023|
#394 in Testing
295 downloads per month
Used in 6 crates (via floppy-disk)
This crate provides a generic filesystem with disk and in-memory implementations.
In the future, a module will be provided that will allow injecting errors into filesystem operations in your tests on an in-memory filesystem. This used to exist but was removed in commit 1ee34f6.
This crate is currently particularly useful becacuse it provides a solid in-memory filesystem. In the future, it will be more useful for triggering filesystem errors in your unit tests to enable testing of how your code handles filesystem errors.
See the crate documentation for a longer explanation on usage and examples of usage.
A generic filesystem with disk and in-memory implementations.
Reason for existence
std::fs module provides functions to manipulate the filesytem, and these functions are
good. However, if you have code that uses
std::fs, it is difficult to ensure that your code
handles errors properly because generally, you are not testing on an already broken machine.
You could attempt to set up FUSE, which, although doable, is involved.
This crate provides a generic filesystem with various implementations. At the moment, only normal (non-injectable) disk and in-memory implementations are provided. In the future, an error-injectable shim around the in-memory file system will be provided to help trigger filesystem errors in unit tests.
The intent of this crate is for you to use the generic
rsfs::GenFS everywhere where you use
std::fs in your code. Your
main.rs can use
rsfs::disk::FS to get default disk behavior
while your tests use
rsfs::mem::test::FS (once it exists) to get an in-memory filesystem that
can have errors injected.
An in-memory filesystem
There existed no complete in-process in-memory filesystem when I wrote this crate; the
rsfs::mem should suffice most needs.
rsfs::mem is a platform specific module that
pub uses the proper module based off the
builder's platform. To get a platform agnostic module, you need to use the in-memory platform
you desire. Thus, if you use
rsfs::mem::unix, you will get an in-memory system that follows
Unix semantics. If you use
rsfs::mem::windows, you will get an in-memory system that follows
Windows semantics (however, you would have to write that module first).
This means that
rsfs::mem aims to essentially be an in-memory drop in for
forces you to structure your code in a cross-platform way.
rsfs::mem::unix aims to be a Unix
specific drop in that buys you Unix semantics on all platforms.
The current in-memory filesystems are only implemented for Unix. This means that the only
cross-platform in-memory filesystem is specifically
rsfs::mem::unix. Window's users can help
by implementing the in-memory analog for Windows.
The in-memory filesystem is implemented using some unsafe code. I deemed this necessary after
working with the recursive data structure that is a filesystem through an
too long. The code is pretty well tested; there should be no problems. The usage of unsafe, in
my opinion, makes the code much clearer, but it did require special care in some functions.
This crate copies a lot of the documentation and examples that currently exist in
It not only makes it easier for people to migrate straight to this crate, but makes this crate
much more understandable. This crate includes Rust's MIT license in its repo for further