| shcov -- A Shell Script Coverage Tool |
|
|
|
DESCRIPTION The shcov tool provides a means to generate a line by line execution trace of a bash shell script by sourcing the file "traps.sh" into the top of the script to be traced. The trace, which is captured in the file "trace.log", contains a line-by-line trace of the script's execution. This data, in turn, is used by the shell script "shcov.sh" to determine and display execution coverage of the traced script(s). This trace may also be useful for general debugging. The result is a *.html file for each shell script thus traced. This html file contains a summary at the top giving the date and time the coverage was run, the script filename and path, and a set of statistics pertaining to the coverage of the file. The text of the script file is displayed, with executed lines hilighted in green, and non-executed but executable lines hilighted in red. Non-executable lines are not highlighted. Note that some keywords, if on a line by themselves, are not actually executed, such as "fi", "done", "do", "if", "then", and "else". They are therefore not highlighted. Since the trace.log file is appended to rather than over-written, multiple test runs may be accumulated in a single trace file, and multiple trace files may be combined by "cat" to produce a single file, which may then be analyzed by "shcov.sh" to display overall coverage of a suite of tests.
The shunit2 shell script test tool USAGE Each bash script to be traced must source traps.sh at the top ot the file. Only those files sourcing traps.sh will be traced. This permits "uninteresting" script files that call or are called by the "interesting" scripts to not be traced. This can be used to reduce the "noise" in the trace.log file. Once traps.sh has been edited into the interesting scripts, the top level scrip file in the set of scripts being traced is run the normal way. A trace will only be produced if the bash environment variable __KSH_TRACE__ is set to "yes". If__KSH_TRACE__ is unset or contains anything other than "yes", no trace.log file will be produced. This permits leaving the sourcing of the traps.sh file in the affected scripts with no execution time penalty unless __KSH_TRACE__ == "yes". Once the trace.log file ahs been produced, it may be examined, if desired, for debugging purposes, etc. To produce html files displaying coverage, after the trace.log file has been produced, run the script shcov.sh to produce a *.html file for each traced script file in the directory. These html files may be viewed in a browser such as firefox. When viewed, the *.html files will contain a grey header displaying summary information, followed by the coverage display. The original shell script file that was traced will be displayed with source line numbers to the left. To the left of that a count of the number of times that line was executed will be displayed, with executed lines hilited in green, and executable but unexecuted lines displayed hilited in red. EXAMPLE The following example shows how to run scripts to produce a normal execution, and to produce a trace followed by coverage display.
rj@onesimus ~/shcov/new $ echo ${__KSH_TRACE__}
rj@onesimus ~/shcov/new $ # run without tracing
rj@onesimus ~/shcov/new $ ./foo.sh
START
entering foo PID = 21362
entering bar PID = 21363
entering baz PID = 21364
f = 1
f = 2
f = 3
f = 4
f = 5
f = 6
./baz.sh: line 18: BARF: command not found
ERR [21364] /home/rj/shcov/new/./baz.sh:18: trapped 0.
ERR [21363] /home/rj/shcov/new/./bar.sh:11: trapped 0.
ERR [21362] /home/rj/shcov/new/./foo.sh:20: trapped 0.
rj@onesimus ~/shcov/new $ ls -l trace.log
ls: cannot access 'trace.log': No such file or directory
rj@onesimus ~/shcov/new $ # run with tracing
rj@onesimus ~/shcov/new $ __KSH_TRACE__="yes" ./foo.sh
START
entering foo PID = 21859
entering bar PID = 21875
entering baz PID = 21886
f = 1
f = 2
f = 3
f = 4
f = 5
f = 6
./baz.sh: line 18: BARF: command not found
ERR [21886] /home/rj/shcov/new/./baz.sh:18: trapped 0.
ERR [21875] /home/rj/shcov/new/./bar.sh:11: trapped 0.
ERR [21859] /home/rj/shcov/new/./foo.sh:20: trapped 0.
rj@onesimus ~/shcov/new $ ls -l trace.log
-rw-r--r-- 1 rj ssmtp 2476 Oct 21 11:17 trace.log
rj@onesimus ~/shcov/new $ ./shcov.sh
rj@onesimus ~/shcov/new $ ls -l *.html
-rw-r--r-- 1 rj ssmtp 3769 Oct 21 11:20 bar.sh.html
-rw-r--r-- 1 rj ssmtp 5895 Oct 21 11:20 baz.sh.html
-rw-r--r-- 1 rj ssmtp 5497 Oct 21 11:20 foo.sh.html
rj@onesimus ~/shcov/new $
The trace.log file may be viewed with less or your favorite editor.
rj@onesimus ~/shcov/new $ head trace.log
/home/rj/shcov/new/./foo.sh:7: echo START
/home/rj/shcov/new/./foo.sh:9: echo entering foo PID = $$
/home/rj/shcov/new/./foo.sh:20: ./bar.sh
/home/rj/shcov/new/./bar.sh:7: echo entering bar PID = $$
/home/rj/shcov/new/./bar.sh:11: ./baz.sh
/home/rj/shcov/new/./baz.sh:7: echo entering baz PID = $$
/home/rj/shcov/new/./baz.sh:14: for ((f=1 ; f<=9 ; f=f+1)) ; do
/home/rj/shcov/new/./baz.sh:14: for ((f=1 ; f<=9 ; f=f+1)) ; do
/home/rj/shcov/new/./baz.sh:15: echo f = $f
/home/rj/shcov/new/./baz.sh:16: sleep 1
rj@onesimus ~/shcov/new $
You can view the coverage display file with firefox like this:
rj@onesimus ~/shcov/new $ firefox file:
This wil open a firefox window on the current directory. To view a coverage display file, click on the associated *.html file. NOTES There are now numerous "hits" on google for "shcov", but when I originally wrote this, I was unable to find any open source tool that could provide coverage display for shell scripts. This tool was originally written for the Korn shell (ksh); it was updated to work with the born again shell (bash).
The sh2html.sh script
|
|
