README.md: more examples of (mis)using run

[kolyshkin]

This is a followup to #343 and closes #377.

After fixing some more code that uses run left and right, I am coming back
to further improve its documentation.

In particular, I try to emphasize the only use case for run (checking the output
of a command that exits with non-zero status).

I also provide a non-working example of using run with pipes.

• I have reviewed the Contributor Guidelines.
• I have reviewed the Code of Conduct and agree to abide by it

[martin-schulze-vireso]

Nice. I think that ties in well with #358.

[kolyshkin]

@sublimino PTAL

[sublimino]

Really nice work! These clear, simply stated documentation changes make the basics much easier for newcomers to bats, thanks @kolyshkin! You mentioned above:

In particular, I try to emphasize the only use case for run (checking the output
of a command that exits with non-zero status).

I use run with https://github.com/bats-core/bats-assert#assert_output a lot, so I've added a "subshell" method to the end of the list in e0e13c3 too 🙏

[martin-schulze-vireso]

Wow, I think this closes #1.

[martin-schulze-vireso]

With the discussion going on in #367, I would want to wait for a decision there, to avoid landing this and making it obsolete in the next step.

[sublimino]

@martin-schulze-vireso good point, I missed that one somehow! Will have a look over the weekend.

It could be worth merging this so there's a baseline to extend upon with #367, but don't mind either way.

[martin-schulze-vireso]

Just noticed that the above PR already tried to document some of this. We should

• check that Solved #1: Re-pointed PR 47 #33's ideas are not lost

[martin-schulze-vireso]

It could be worth merging this so there's a baseline to extend upon with #367, but don't mind either way.

I hope that when #367 is done, there is only one use case without run: Check success + get output unconditionally.

[martin-schulze-vireso]

@kolyshkin Now that #367 has landed (although the exact syntax is not settled #479), how much of this PR should we retain?

We should also consider that #467 will offer switches to alter the output behavior of run, which might complicate this further.

[kolyshkin]

I agree that (once we settle on "run with exit code check" syntax) this needs to be revised, as now there are more ways to achieve the same result.

Yet I think the documentation removal in #367 (e.g. ae26797#diff-12cfeed9f9b1cc83679dd5e693fdf109f2080614ae71c90466cace54a187082dL54) is a mistake.

Instead, it should have been modified to show how to check exit codes.

For example, writing

run command args ...
echo "$output"
[ "$status" -eq 0 ]

(the first example from the removed doc) is OK but not a good style; either command args ... or run 0 command args ... is better.

[martin-schulze-vireso]

@kolyshkin You're right. I removed that part and intended to add new documentation for it but never did. We'll let this reminder sit here until we settled on the syntax.

[martin-schulze-vireso]

@kolyshkin Would you mind having another stab at this? The run -X/run ! syntax is released now, so we can move forward.

[martin-schulze-vireso]

@kolyshkin I did not hear back from you. Do you plan to work on this again?

[martin-schulze-vireso]

I reworked this according to the new run exit code check interface and added automatic output/stderr printing on exit code errors to run. This changed in the documentation in comparison to the old code:

1. "check the command succeeded": updated command to use run's exit code check
2. "check the command failed": replaced by reference to run !
3. hide the command output: omitted, with new run exit code checking, the run command is actually shorter
4. make sure the command succeeded, and check its output: omitted, run -0 is shorter
5. "pipe using run": made an extra section instead of bullet point. However, the recommendation is about to change with Adding bats_pipe Helper Function (originally suggested adding --output-processor Flag to run Helper). #663, so we might want to reword that later on

[kolyshkin]

@martin-schulze-vireso thank you, I was just checking bats-core docs and was glad to see these examples. Sorry for not following up on this myself.

[kolyshkin]

@martin-schulze-vireso I would also appreciate adding "Co-authored-by" footer next time 😉

[martin-schulze-vireso]

@martin-schulze-vireso I would also appreciate adding "Co-authored-by" footer next time 😉

You mean in the commit message? I am sorry that this got swept away in the many revisions this has undergone. Usually I can rely on rebase to preserve this.