How can I run an example as part of `cargo test`?

Question

I have a Rust library with an example, and I want to test against the example as an indirect way to verify my library code.

I want to use assert_cmd as described in this tutorial to perform the test, however I cannot structure it in a way such that cargo test or cargo test --example ... will also build and update the example binary.

The test runs, but often times it is run with a stale version of the example binary. The example project also gets built, which I know because if I add compile_error! in the code, it will not let me run the tests. But for some reason the binary executed by Command::cargo_bin(...) is not updated.

Is there some configuration I am missing that can be used to convince cargo to rebuild the example binary?

Here's my directory structure:

project-dir
  - examples
    - example_one
      - main.rs
      - test.rs
  - src
    - lib.rs
  - Cargo.toml

Answer 1

Here a topic from IRLO discussing the problem that examples aren't build when running cargo test or cargo test --examples: https://internals.rust-lang.org/t/examples-and-tests/14347. Quote from this topic:

Unfortunately there isn't a good story for automated testing of example programs. The examples are not guaranteed to be built for an integration test.

That being said assert_cmd has this section in its documentation about its limitations. To quote:

Only works with cargo binaries (cargo test ensures they are built).

Now the problem you are facing is that cargo test does not ensure that examples are built.

assert_cmd urges you to use escargot when you run into its limitations, which has a more flexible API. AFAICT you can use escargot like this to build and run an example (see documentation here):

extern crate escargot;

escargot::CargoBuild::new()
    .example("example_fixture")
    .manifest_path("tests/fixtures/example/Cargo.toml")
    .exec()
    .unwrap();

I hope this will allow you to test your examples properly.