Bash Scripts Testing with the Sparrow Toolkit
Tags: perl, shell, tdd, sparrow
Published: 2017-10-09 12:49:18

---
title: Bash Scripts Testing with the Sparrow Toolkit
published: true
description: How to create tests for Bash scripts using Sparrow
tags: Perl, Shell, TDD, Sparrow
---

[Sparrow](https://github.com/melezhik/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](https://github.com/melezhik/outthentic) 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](https://sparrowhub.org). 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](https://github.com/melezhik/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