Description
Summary
- Give better overview of what this crate is and how it works
- Do a better job explaining why this crate is better than hand-rolling a solution
Going under the "Why don't you use this crate" category as linked from assert_cmd.
Foremost, while the rustdoc is good as a reference, the upfront documentation is severely lacking. The readme is practically useless both for figuring out what this is (beyond the title, which is only helpful if one knows what all the words mean), and figuring out what it can do (and hence, whether it can be used for one's usecase). Going to the docs.rs page in some hope of more is equally discouraging (and also non-obvious from github as it's only linked through the badge), as the crate top-level documentation is an extremely succinct "overview" that doesn't really explain anything.
Specifically, but not exhaustively, there's no obvious documentation for how this crate works (or how it doesn't work), for example whether it's just manipulating real files or offering a fake filesystem, whether it does any magic or introduces any behaviour we'd need to be careful around, that kinda thing. There's no explanation of what fixtures are or why they're useful, nor even a link to a discussion of that. There's also nothing that argues in favour of using this crate rather than rolling one's own testing code.
Running commands and dealing with output can be complex in many many ways, so assert_cmd smoothing that is excellent, very much welcome, and improves ergonomics significantly. File I/O is a lot more bread-and-butter and assert_fs doesn't feel, on the outset, as significant enough to add or rewrite in, especially when it's not obvious what it does, really.