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

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

echo Hello World!
exit 0

$ bash /path/to/my/script.bash

Hello World!

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

bash /path/to/my/script.bash

$ cat story.check

Hello World

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

2017-10-09 14:59:06 :  [path] /
Hello World!
ok  scenario succeeded
ok  text has 'Hello World!'
STATUS  SUCCEED

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

echo Hello World!
exit 1

$ strun

2017-10-09 15:03:34 :  [path] /
Hello World!
not ok  scenario succeeded
STATUS  FAILED (1)

A failed test of check rules:

$ cat /path/to/my/script.bash

echo How are you?
exit 0

$ strun

2017-10-09 15:05:40 :  [path] /
How are you?
ok  scenario succeeded
not ok  text has 'Hello World!'
STATUS  FAILED (2)

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

regex: hello World\W

Checking Lines Sequence

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

Header
Line1
Line2
Line3
Footer

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

$ cat story.check

begin:
Header
Line1
Line2
Line3
Footer
end:

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>

The check rule would be as that:

$ cat story.check

between: <data> <\/data>
regexp: \d+

Test Suites

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

$ cat hook.bash 

run_story test1
run_story test2

.
├── hook.bash
└── modules
    ├── test1
    │   ├── story.bash
    │   └── story.check
    └── test2
        ├── story.bash
        └── story.check

3 directories, 5 files

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"
}

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

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