Documentation feels like spaghetti - hard to digest

[azriel91]

Hiya! I've appeared here since assert_cli is deprecated, and tried swapping over from assert_cli 0.6 to assert_cmd 0.9

My really short experience (so far) has been something like this:

1. Let's swap over the assert_cli to assert_cmd in the imports
2. Okay, so Commands from std are extended by traits, cool!
3. How do I get environment stuff in? It's not mentioned in these docs, let me check std, okay it's there.
4. How do I write things to stdin? Searched and found CommandStdInExt.
5. What's .with_stdin().buffer("..").unwrap()? Why can't I call .buffer("") twice? Oh we're no longer the builder.
6. Is this unwrap() the assertion? No wait it just gives me the StdinCommand
7. How do I assert? Searched and found OutputAssertExt.
8. The example on the output extension page is a trivial example. How did it get an Output again? Oh it's a std type.
9. Okay I had a StdinCommand, or was it a Result<StdinCommand>.
10. Oh man. I have successfully been confused.
11. Let's open many tabs.
12. No wait let's open an issue.

There's a lot of jumping around trying to figure out "what type do I have, is it a Builder, a Result, a normal type by extended by some trait". Also, the Result's errors aren't all the same type (and aren't convertible), so I can't easily go main_binary()? and then later on .output()?.assert().success().

I think we need an example on the first page (and perhaps README.md) that does a complete test. The piecewise explanations are good on their own, but it's hard to tie them together. That is, literally every method call gives me a different type:

extern crate assert_cmd;

use assert_cmd::{cargo::CargoError, prelude::*};
use std::process::Command;

#[test]
fn integration_test() -> Result<(), CargoError> {
    Command::main_binary()?
        .env("APP_VAR", "value") // https://doc.rust-lang.org/std/process/struct.Command.html#method.env
        .with_stdin()            // https://docs.rs/assert_cmd/0.9.1/assert_cmd/trait.CommandStdInExt.html
        .buffer("exit\n")        // https://docs.rs/assert_cmd/0.9.1/assert_cmd/struct.StdInCommandBuilder.html#method.buffer
        .output()                // https://docs.rs/assert_cmd/0.9.1/assert_cmd/struct.StdInCommand.html#method.output
        .unwrap()                // Gives you back the `Output`
        .assert()                // https://docs.rs/assert_cmd/0.9.1/assert_cmd/assert/trait.OutputAssertExt.html#tymethod.assert
        .success();              // https://docs.rs/assert_cmd/0.9.1/assert_cmd/assert/struct.Assert.html#method.success
    Ok(())
}

FWIW I was trying to port this test over:

let environment =
    assert_cli::Environment::inherit().insert("APP_DIR", env!("CARGO_MANIFEST_DIR"));

assert_cli::Assert::main_binary()
    .with_env(&environment)
    .stdin("exit\n")
    .unwrap();

_{Off topic, CONTRIBUTING.md looks like it might have been copied from something called stager.}

[azriel91]

ah, I missed #37 when opening this, idm pushing discussion over there 😄!