Improve docs on installation and proper usage for new users
sirosen opened this issue · comments
First of all, thanks for this project! I'm very excited by the prospect of being able to "level up" some of our shell testing from unstructured scripts.
However, getting started with no prior experience using shunit2, I found some things confusing about usage.
Mainly, the issue I had was this: How do I "install" shunit2?
At first I assumed that the right thing was to pull in just the shunit2 file itself, but I noticed lib/ and found this confusing. Although I'm now pretty sure that the shunit2 file is all I need -- that's what I find in other repos -- I think the readme could have clarified.
I'm also aware that some platforms have a system-packaged version of shunit2, but that test scripts are sourcing shunit2. These two things are apparently in conflict.
It seems to me that things would be clearer if the sourcing of shunit2 were explicitly stated as one of two methods of invocation.
As I experiment with usages, I find shunit2 is sensitive to where and how it's invoked. As a result, it's a little confusing to have example scripts which source shunit2.
I think it would be nice to have a complete, simple example of a suite of tests which uses a pattern similar to the usage in shflags. Because right now I'm reading test_runner in shflags to try to figure out how to build on shunit2, which is not a great experience.
One of the results of this is that when a user who isn't clear on what correct usage looks like hits an error, it's not obvious if I did it wrong or if it's a bug. Simple example, I'm seeing this:
$ ./lib/shunit2 suites/simple_test.sh baz
testFoo
testBar
Ran 2 tests.
OKSo, did I do something strange, or is shunit2 not respecting a test function name (baz) given on the command-line? I can't tell. And shflags' usage never passes an individual test name as far as I see, so my approach of referring to that as a guide doesn't help.
Possible duplicate of: #93
Yes, sorry about that. I didn't find #93 while looking for an issue on this, somehow.
I think I have some detail in here which isn't in that issue. I'll try to review this tonight and copy any useful content over. I'm going to self-close as a duplicate though.