DEV Community ๐Ÿ‘ฉโ€๐Ÿ’ป๐Ÿ‘จโ€๐Ÿ’ป

Alexey Melezhik
Alexey Melezhik

Posted on

Bash Scripts Testing with the Sparrow Toolkit

Sparrow is a scripting system designed for rapid script development and distribution across Linux environments.

Here I am going to show how one can write tests for your Bash/Shell scripts with no fussing using nifty Sparrow framework.

Install Sparrow

Sparrow is written on Perl and thus installed as CPAN module:

$ cpanm Sparrow
Enter fullscreen mode Exit fullscreen mode

That is it, you are all set up.

Given a Bash/Shell script

Given you have a script called script.bash to do something useful.

$ cat /path/to/my/script.bash
Enter fullscreen mode Exit fullscreen mode
echo Hello World!
exit 0
Enter fullscreen mode Exit fullscreen mode
$ bash /path/to/my/script.bash
Enter fullscreen mode Exit fullscreen mode
Hello World!
Enter fullscreen mode Exit fullscreen mode

According to the Sparrow testing approach (black box testing?) all we should care about is that script exits with 0 exit code and produces some output. In this case we want that the output contain <Hello World!> string.

Create Test (Sparrow) Scenario

Ok, lets create a test scenario for our script.

The scenario would consist of two distinct files:

  • Scenario file ( or story ) - which is just a wrapper to run script.bash

  • Check file - which contains check rules to validate script.bash output

Here is the code:

$ cat story.bash
Enter fullscreen mode Exit fullscreen mode
bash /path/to/my/script.bash
Enter fullscreen mode Exit fullscreen mode
$ cat story.check
Enter fullscreen mode Exit fullscreen mode
Hello World
Enter fullscreen mode Exit fullscreen mode

Run Test Scenario

Sparrow comes with strun - a tool to execute Sparrow scenarios, just run strun from the directory where we've create a pair of files story.bash and story.check:

$ strun
Enter fullscreen mode Exit fullscreen mode
2017-10-09 14:59:06 :  [path] /
Hello World!
ok  scenario succeeded
ok  text has 'Hello World!'
STATUS  SUCCEED
Enter fullscreen mode Exit fullscreen mode

Reporting test failures

When Sparrow test scenario fails that means one of two things:

  • Underling Bash script has returned none zero exit code
  • An output generated has not passed check rules

Let's see the both cases in action:

A none zero exit code:

$ cat /path/to/my/script.bash
Enter fullscreen mode Exit fullscreen mode
echo Hello World!
exit 1
Enter fullscreen mode Exit fullscreen mode
$ strun
Enter fullscreen mode Exit fullscreen mode
2017-10-09 15:03:34 :  [path] /
Hello World!
not ok  scenario succeeded
STATUS  FAILED (1)
Enter fullscreen mode Exit fullscreen mode

A failed test of check rules:

$ cat /path/to/my/script.bash
Enter fullscreen mode Exit fullscreen mode
echo How are you?
exit 0
Enter fullscreen mode Exit fullscreen mode
$ strun
Enter fullscreen mode Exit fullscreen mode
2017-10-09 15:05:40 :  [path] /
How are you?
ok  scenario succeeded
not ok  text has 'Hello World!'
STATUS  FAILED (2)
Enter fullscreen mode Exit fullscreen mode

More Complicated Tests

Of one can create more sophisticated scenarios using Sparrow. It's hard to cover all the ground here, I will brief you on some cool Sparrow features and then we finish with how to publish your tests and share with the rest of the team.

Using regular expressions

Say you want to check script output against some regular expressions, well it's pretty easy:

$ cat story.check
Enter fullscreen mode Exit fullscreen mode
regex: hello World\W
Enter fullscreen mode Exit fullscreen mode

Checking Lines Sequence

What if your script generate generates a sequence of lines, like:

Header
Line1
Line2
Line3
Footer
Enter fullscreen mode Exit fullscreen mode

It's possible to checks this by using so called "block checks":

$ cat story.check
Enter fullscreen mode Exit fullscreen mode
begin:
Header
Line1
Line2
Line3
Footer
end:
Enter fullscreen mode Exit fullscreen mode

Checks Inside Ranges

What if you need to set up the context for line search, say your script generate some entries or blocks and you want to check the content ( numbers ) inside the entries:

<data>
1
2
3
A
B
</data>
Enter fullscreen mode Exit fullscreen mode

The check rule would be as that:

$ cat story.check
Enter fullscreen mode Exit fullscreen mode
between: <data> <\/data>
regexp: \d+

Enter fullscreen mode Exit fullscreen mode

Test Suites

You also may run more than one test and organise a test code on per project or suite basis:

$ cat hook.bash 
Enter fullscreen mode Exit fullscreen mode
run_story test1
run_story test2

Enter fullscreen mode Exit fullscreen mode
.
รขโ€ล“รขโ€โ‚ฌรขโ€โ‚ฌ hook.bash
รขโ€โ€รขโ€โ‚ฌรขโ€โ‚ฌ modules
    รขโ€ล“รขโ€โ‚ฌรขโ€โ‚ฌ test1
    รขโ€โ€šร‚ ร‚  รขโ€ล“รขโ€โ‚ฌรขโ€โ‚ฌ story.bash
    รขโ€โ€šร‚ ร‚  รขโ€โ€รขโ€โ‚ฌรขโ€โ‚ฌ story.check
    รขโ€โ€รขโ€โ‚ฌรขโ€โ‚ฌ test2
        รขโ€ล“รขโ€โ‚ฌรขโ€โ‚ฌ story.bash
        รขโ€โ€รขโ€โ‚ฌรขโ€โ‚ฌ story.check

3 directories, 5 files
Enter fullscreen mode Exit fullscreen mode

There are a lot of other examples on the documenation pages. I encourage you to read this one!

Publishing Tests

One of the killer feature of the Sparrow is once you've finished your work, you may publish your tests and let other to run them:

Upload tests

Just create a Sparrow meta file inside the root directory with test suite and then give it a run sparrow plg upload command

$ cat sparrow.json

{

   "name" : "my-test-suite",
   "version" : "0.0.1",
   "description" : "Some tests for my Bash scripts"
}
Enter fullscreen mode Exit fullscreen mode

if everything ok, you tests suite will be packaged and uploaded as Sparrow plugin into central Sparrow repository called SparrowHub. Anticipating possible questions I also say - "Yes. it's possible to publish Sparrow plugins privately", but this might be topic for my next post.

There is more information on publishing and downloading Sparrow scripts on Sparrow documentation pages.

Finally, your team mates can download and run the test suite as simple as following two commands:


$ sparrow plg install my-test-suite
$ sparrow plg run my-test-suite
Enter fullscreen mode Exit fullscreen mode

Conclusion

Sparrow is Linux scripting platform with many batteries included. It makes it possible to develop tests scenarios for Bash/Shell scripts with no fussing, and encourages to distribute the test scripts among teams.

Ideas, questions, comments are very appreciated.

Regards

The Author

Top comments (1)

Collapse
 
spigell profile image
Spigell

Thanks for explanation of check files.

Forem

๐Ÿ— We built a 100% open source community software called Forem.

ย 
You can contribute to the codebase or host your own.