Binaries: testing and documentation

I am looking for some guidelines on how to document and test binaries provided by a crate.

I have a crate that produces several executables. I'd like to have a documentation page listing them all, along with command line flags and examples. What are possible approaches to that? Any good examples of such a documentation?

Also, I'd like to have integration tests for my executables. I need to run them with specific flags and input files and then to compare the output printed on the screen with the reference one. Is such a functionality already available?

Depending on how long and verbose your documentation for all binaries combined is, you could just list them all in the top-level documentation of your library. That's what I'd do if this doesn't result in an unreasonably long page. I also started to appreciate how clap added modules like _tutorial or _faq with the sole purpose of containing different parts of the documentation that go beyond API documentation.

escargot and assert_cmd come to mind.

Terminology nitpick: no, you have a package that produces several executables, and one crate per executable.

The usual approach to tool documentation for Rust projects is mdBook. However, there’s no particularly strong reason to use it over anything else.

Yes; check out trycmd for doing exactly that.

Under the hood, all such tests depend on a particular feature of Cargo — it sets an environment variable CARGO_BIN_EXE_<name>, for every executable in your project, when running integration tests. So, you can then run the command however you like. trycmd specifically offers snapshot testing.