Make the documentation about how to configure tests more accessible.

[Skenvy]

🤔 What's the problem you've observed?

As a user relatively new to ruby let alone rspec and aruba, it took a lot longer than I would expect to locate accessible information regarding the potential to customise the configuration of running tests.

✨ Do you have a proposal for making it better?

Edit https://github.com/cucumber/aruba/blob/main/features/README.md to include a minimum example of, say, setting the configuration for, for example, a long running command, for each of the three examples provided.

📚 Any additional context?

I tried working on adding aruba RSpec tests to test my long running command, half a year ago when it was wrapping another package which relied on ruby 2.7. At the time, it was hitting an error like;

<ruby_gems_dir>/open3.rb:404:in `read': stream closed in another thread (IOError)

Which looks awfully similar to this ruby bug so I considered it not worth enough effort to attempt, and didn't read further into the docs than the first few examples, not assuming it was something I could fix.

Recently I've updated my command to work on ruby 3.1, and thought I'd see if the previous issue had been circumvented. The tests still yielded the same error locally, but they worked in my CI -- which let me at least know that the stream closing error was an artifact of the difference between how they were being run in my CI step vs locally, as opposed to some other more nebulous reason.

The most obvious difference likely being how long the command would take to run in the CI runner vs locally running the aruba tests, in WSL on a command that inspects files in the windows file system will ramp up the time the command takes dramatically.

So I started looking more into it, and reading through the rest of the ./features, thinking the answer must be in there. A lot of the files in there are *.feature, but not wanting the learn the cucumber syntax to be able to read those files as well as not knowing how relevant they were to me when I was using RSpec, it took me until I got to ./features/support/aruba.rb to see an example of configuring the tests that I thought I could actually use. But I still hadn't found an example of what the options meant, and had to search the code for these to know which ones I wanted to use, ecentually landing here.

The original issue of assuming that the problem was something I wouldn't even be able to circumvent could be elucidated by having something like the equivalent of ./features/support/aruba.rb in each of the examples in ./features/README.md which I would have seen the first time trying to set it up and realise much sooner it was because my commands were taking longer than some default timeout.

[Skenvy]

An alternative question to this is why the tests originally were failing with stream closed in another thread (IOError), as opposed to reporting that they failed for taking longer than the expected time to complete?

[mvz]

The documentation is actually mostly in the .feature files. Once upon a time these were hosted somewhere in a pretty format, but that is sadly no longer the case (see #752).

(Those files should also be quite readable as they are since they're mainly just English text.)

If you can still reproduce the stream closed in another thread issue it would be worthwhile opening a separate ticket for that.

[Skenvy]

I saw #752 while looking for something mentioning the docs and started to put this in there as a comment but it was more about this and not the docs site being unavailable. I can point to a commit with the stream closed in another thread issue in a bit after I merge my tests.

[Skenvy]

The issue can be reproduced in https://github.com/Skenvy/dependabot-linguist/blob/11d479e4b4dc76925ee03033a86d8b699a54da86/spec/dependabot/cli_spec.rb, if the change to the exit_timeout is removed. But it might only be reproducible on WSL, i.e. if you're not in WSL it might not be affected by the slow IO against the windows file system.

[mvz]

Thanks @Skenvy