881 lines
34 KiB
HTML
881 lines
34 KiB
HTML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
|
<title>shUnit2 2.1.x Documentation</title>
|
|
<style type="text/css">
|
|
|
|
/*
|
|
:Author: David Goodger
|
|
:Contact: goodger@users.sourceforge.net
|
|
:Date: $Date: 2007-04-11 11:48:16 +0100 (Wed, 11 Apr 2007) $
|
|
:Revision: $Revision: 2791 $
|
|
:Copyright: This stylesheet has been placed in the public domain.
|
|
:Modified by: Kate Ward <kate.ward@forestent.com>
|
|
|
|
Default cascading style sheet for the HTML output of Docutils.
|
|
|
|
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
|
|
customize this style sheet.
|
|
*/
|
|
|
|
/* used to remove borders from tables and images */
|
|
.borderless, table.borderless td, table.borderless th {
|
|
border: 0 }
|
|
|
|
table.borderless td, table.borderless th {
|
|
/* Override padding for "table.docutils td" with "! important".
|
|
The right padding separates the table cells. */
|
|
padding: 0 0.5em 0 0 ! important }
|
|
|
|
.first {
|
|
/* Override more specific margin styles with "! important". */
|
|
margin-top: 0 ! important }
|
|
|
|
.last, .with-subtitle {
|
|
margin-bottom: 0 ! important }
|
|
|
|
.hidden {
|
|
display: none }
|
|
|
|
a.toc-backref {
|
|
text-decoration: none ;
|
|
color: black }
|
|
|
|
blockquote.epigraph {
|
|
margin: 2em 5em ; }
|
|
|
|
dl.docutils dd {
|
|
margin-bottom: 0.5em }
|
|
|
|
/* Uncomment (and remove this text!) to get bold-faced definition list terms
|
|
dl.docutils dt {
|
|
font-weight: bold }
|
|
*/
|
|
|
|
div.abstract {
|
|
margin: 2em 5em }
|
|
|
|
div.abstract p.topic-title {
|
|
font-weight: bold ;
|
|
text-align: center }
|
|
|
|
div.admonition, div.attention, div.caution, div.danger, div.error,
|
|
div.hint, div.important, div.note, div.tip, div.warning {
|
|
margin: 2em ;
|
|
border: medium outset ;
|
|
padding: 1em }
|
|
|
|
div.admonition p.admonition-title, div.hint p.admonition-title,
|
|
div.important p.admonition-title, div.note p.admonition-title,
|
|
div.tip p.admonition-title {
|
|
font-weight: bold ;
|
|
font-family: sans-serif }
|
|
|
|
div.attention p.admonition-title, div.caution p.admonition-title,
|
|
div.danger p.admonition-title, div.error p.admonition-title,
|
|
div.warning p.admonition-title {
|
|
color: red ;
|
|
font-weight: bold ;
|
|
font-family: sans-serif }
|
|
|
|
/* Uncomment (and remove this text!) to get reduced vertical space in
|
|
compound paragraphs.
|
|
div.compound .compound-first, div.compound .compound-middle {
|
|
margin-bottom: 0.5em }
|
|
|
|
div.compound .compound-last, div.compound .compound-middle {
|
|
margin-top: 0.5em }
|
|
*/
|
|
|
|
div.dedication {
|
|
margin: 2em 5em ;
|
|
text-align: center ;
|
|
font-style: italic }
|
|
|
|
div.dedication p.topic-title {
|
|
font-weight: bold ;
|
|
font-style: normal }
|
|
|
|
div.figure {
|
|
margin-left: 2em ;
|
|
margin-right: 2em }
|
|
|
|
div.footer, div.header {
|
|
clear: both;
|
|
font-size: smaller }
|
|
|
|
div.line-block {
|
|
display: block ;
|
|
margin-top: 1em ;
|
|
margin-bottom: 1em }
|
|
|
|
div.line-block div.line-block {
|
|
margin-top: 0 ;
|
|
margin-bottom: 0 ;
|
|
margin-left: 1.5em }
|
|
|
|
div.sidebar {
|
|
margin-left: 1em ;
|
|
border: medium outset ;
|
|
padding: 1em ;
|
|
background-color: #ffffee ;
|
|
width: 40% ;
|
|
float: right ;
|
|
clear: right }
|
|
|
|
div.sidebar p.rubric {
|
|
font-family: sans-serif ;
|
|
font-size: medium }
|
|
|
|
div.system-messages {
|
|
margin: 5em }
|
|
|
|
div.system-messages h1 {
|
|
color: red }
|
|
|
|
div.system-message {
|
|
border: medium outset ;
|
|
padding: 1em }
|
|
|
|
div.system-message p.system-message-title {
|
|
color: red ;
|
|
font-weight: bold }
|
|
|
|
div.topic {
|
|
margin: 2em }
|
|
|
|
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
|
|
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
|
|
margin-top: 0.4em }
|
|
|
|
h1.title {
|
|
text-align: center }
|
|
|
|
h2.subtitle {
|
|
text-align: center }
|
|
|
|
hr.docutils {
|
|
width: 75% }
|
|
|
|
img.align-left {
|
|
clear: left }
|
|
|
|
img.align-right {
|
|
clear: right }
|
|
|
|
ol.simple, ul.simple {
|
|
margin-bottom: 1em }
|
|
|
|
ol.arabic {
|
|
list-style: decimal }
|
|
|
|
ol.loweralpha {
|
|
list-style: lower-alpha }
|
|
|
|
ol.upperalpha {
|
|
list-style: upper-alpha }
|
|
|
|
ol.lowerroman {
|
|
list-style: lower-roman }
|
|
|
|
ol.upperroman {
|
|
list-style: upper-roman }
|
|
|
|
p.attribution {
|
|
text-align: right ;
|
|
margin-left: 50% }
|
|
|
|
p.caption {
|
|
font-style: italic }
|
|
|
|
p.credits {
|
|
font-style: italic ;
|
|
font-size: smaller }
|
|
|
|
p.label {
|
|
white-space: nowrap }
|
|
|
|
p.rubric {
|
|
font-weight: bold ;
|
|
font-size: larger ;
|
|
color: maroon ;
|
|
text-align: center }
|
|
|
|
p.sidebar-title {
|
|
font-family: sans-serif ;
|
|
font-weight: bold ;
|
|
font-size: larger }
|
|
|
|
p.sidebar-subtitle {
|
|
font-family: sans-serif ;
|
|
font-weight: bold }
|
|
|
|
p.topic-title {
|
|
font-weight: bold }
|
|
|
|
pre.address {
|
|
margin-bottom: 0 ;
|
|
margin-top: 0 ;
|
|
font-family: serif ;
|
|
font-size: 100% }
|
|
|
|
pre.literal-block, pre.doctest-block {
|
|
margin-left: 2em ;
|
|
margin-right: 2em ;
|
|
background-color: #eeeeee }
|
|
|
|
span.classifier {
|
|
font-family: sans-serif ;
|
|
font-style: oblique }
|
|
|
|
span.classifier-delimiter {
|
|
font-family: sans-serif ;
|
|
font-weight: bold }
|
|
|
|
span.interpreted {
|
|
font-family: sans-serif }
|
|
|
|
span.option {
|
|
white-space: nowrap }
|
|
|
|
span.pre {
|
|
white-space: pre }
|
|
|
|
span.problematic {
|
|
color: red }
|
|
|
|
span.section-subtitle {
|
|
/* font-size relative to parent (h1..h6 element) */
|
|
font-size: 80% }
|
|
|
|
table.citation {
|
|
border-left: solid 1px gray;
|
|
margin-left: 1px }
|
|
|
|
table.docinfo {
|
|
margin: 2em 4em }
|
|
|
|
/*
|
|
table.docutils {
|
|
margin-top: 0.5em ;
|
|
margin-bottom: 0.5em }
|
|
*/
|
|
|
|
table.footnote {
|
|
border-left: solid 1px black;
|
|
margin-left: 1px ;
|
|
font-size: 80% }
|
|
}
|
|
|
|
table.docutils td, table.docutils th,
|
|
table.docinfo td, table.docinfo th {
|
|
padding-left: 0.5em ;
|
|
padding-right: 0.5em ;
|
|
vertical-align: top }
|
|
|
|
table.docutils th.field-name, table.docinfo th.docinfo-name {
|
|
font-weight: bold ;
|
|
text-align: left ;
|
|
white-space: nowrap ;
|
|
padding-left: 0 }
|
|
|
|
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
|
|
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
|
|
font-size: 100% }
|
|
|
|
/*
|
|
tt.docutils {
|
|
background-color: #eeeeee }
|
|
*/
|
|
|
|
ul.auto-toc {
|
|
list-style-type: none }
|
|
|
|
/* customizations by kward */
|
|
|
|
h1 { font-size: 133%; border-top:1px solid #CCCCFF; }
|
|
h1.title { font-size: 150%; border-top:0px; padding-top: 1em; }
|
|
/* div.document { font-size: 90% } */
|
|
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="document" id="shunit2-2-1-x-documentation">
|
|
<h1 class="title">shUnit2 2.1.x Documentation</h1>
|
|
|
|
<div class="section" id="abstract">
|
|
<h1><a class="toc-backref" href="#id1">Abstract</a></h1>
|
|
<p><a class="reference external" href="http://shunit2.googlecode.com/">shUnit2</a> is a <a class="reference external" href="http://en.wikipedia.org/wiki/XUnit">xUnit</a> unit test framework for Bourne based shell scripts, and it
|
|
is designed to work in a similar manner to <a class="reference external" href="http://www.junit.org/">JUnit</a>, <a class="reference external" href="http://pyunit.sourceforge.net/">PyUnit</a>, etc.. If you have
|
|
ever had the desire to write a unit test for a shell script, shUnit2 can do the
|
|
job.</p>
|
|
<div class="contents topic" id="table-of-contents">
|
|
<p class="topic-title first">Table of Contents</p>
|
|
<ul class="simple">
|
|
<li><a class="reference internal" href="#abstract" id="id1">Abstract</a></li>
|
|
<li><a class="reference internal" href="#introduction" id="id2">Introduction</a><ul>
|
|
<li><a class="reference internal" href="#credits-contributors" id="id3">Credits / Contributors</a></li>
|
|
<li><a class="reference internal" href="#feedback" id="id4">Feedback</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#quickstart" id="id5">Quickstart</a></li>
|
|
<li><a class="reference internal" href="#function-reference" id="id6">Function Reference</a><ul>
|
|
<li><a class="reference internal" href="#general-info" id="id7">General Info</a></li>
|
|
<li><a class="reference internal" href="#asserts" id="id8">Asserts</a></li>
|
|
<li><a class="reference internal" href="#failures" id="id9">Failures</a></li>
|
|
<li><a class="reference internal" href="#setup-teardown" id="id10">Setup/Teardown</a></li>
|
|
<li><a class="reference internal" href="#skipping" id="id11">Skipping</a></li>
|
|
<li><a class="reference internal" href="#suites" id="id12">Suites</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#advanced-usage" id="id13">Advanced Usage</a><ul>
|
|
<li><a class="reference internal" href="#some-constants-you-can-use" id="id14">Some constants you can use</a></li>
|
|
<li><a class="reference internal" href="#error-handling" id="id15">Error handling</a></li>
|
|
<li><a class="reference internal" href="#including-line-numbers-in-asserts-macros" id="id16">Including Line Numbers in Asserts (Macros)</a></li>
|
|
<li><a class="reference internal" href="#test-skipping" id="id17">Test Skipping</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#appendix" id="id18">Appendix</a><ul>
|
|
<li><a class="reference internal" href="#getting-help" id="id19">Getting help</a></li>
|
|
<li><a class="reference internal" href="#zsh" id="id20">Zsh</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="introduction">
|
|
<h1><a class="toc-backref" href="#id2">Introduction</a></h1>
|
|
<p>shUnit2 was originally developed to provide a consistent testing solution for
|
|
<a class="reference external" href="http://log4sh.sourceforge.net/">log4sh</a>, a shell based logging framework similar to <a class="reference external" href="http://logging.apache.org/">log4j</a>. During the
|
|
development of that product, a repeated problem of having things work just fine
|
|
under one shell (<tt class="docutils literal">/bin/bash</tt> on Linux to be specific), and then not working
|
|
under another shell (<tt class="docutils literal">/bin/sh</tt> on Solaris) kept coming up. Although several
|
|
simple tests were run, they were not adequate and did not catch some corner
|
|
cases. The decision was finally made to write a proper unit test framework after
|
|
multiple brown-bag releases were made. <em>Research was done to look for an
|
|
existing product that met the testing requirements, but no adequate product was
|
|
found.</em></p>
|
|
<p>Tested Operating Systems (varies over time)</p>
|
|
<ul class="simple">
|
|
<li>Cygwin</li>
|
|
<li>FreeBSD (user supported)</li>
|
|
<li>Linux (Gentoo, Ubuntu)</li>
|
|
<li>Mac OS X</li>
|
|
<li>Solaris 8, 9, 10 (inc. OpenSolaris)</li>
|
|
</ul>
|
|
<p>Tested Shells</p>
|
|
<ul class="simple">
|
|
<li>Bourne Shell (<strong>sh</strong>)</li>
|
|
<li>BASH - GNU Bourne Again SHell (<strong>bash</strong>)</li>
|
|
<li>DASH (<strong>dash</strong>)</li>
|
|
<li>Korn Shell (<strong>ksh</strong>)</li>
|
|
<li>pdksh - Public Domain Korn Shell (<strong>pdksh</strong>)</li>
|
|
<li>zsh - Zsh (<strong>zsh</strong>) (since 2.1.2) <em>please see the Zsh shell errata for more
|
|
information</em></li>
|
|
</ul>
|
|
<p>See the appropriate Release Notes for this release
|
|
(<tt class="docutils literal"><span class="pre">doc/RELEASE_NOTES-X.X.X.txt</span></tt>) for the list of actual versions tested.</p>
|
|
<div class="section" id="credits-contributors">
|
|
<h2><a class="toc-backref" href="#id3">Credits / Contributors</a></h2>
|
|
<p>A list of contributors to shUnit2 can be found in the source archive in
|
|
<tt class="docutils literal">doc/contributors.txt</tt>. Many thanks go out to all those who have contributed
|
|
to make this a better tool.</p>
|
|
<p>shUnit2 is the original product of many hours of work by Kate Ward, the primary
|
|
author of the code. For other products by her, look up <a class="reference external" href="http://log4sh.sourceforge.net/">log4sh</a> or <a class="reference external" href="http://shflags.googlecode.com/">shFlags</a>, or
|
|
visit her website at <a class="reference external" href="http://forestent.com/">http://forestent.com/</a>.</p>
|
|
</div>
|
|
<div class="section" id="feedback">
|
|
<h2><a class="toc-backref" href="#id4">Feedback</a></h2>
|
|
<p>Feedback is most certainly welcome for this document. Send your additions,
|
|
comments and criticisms to the <a class="reference external" href="mailto:shunit2-users@google.com">shunit2-users@google.com</a> mailing list.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="quickstart">
|
|
<h1><a class="toc-backref" href="#id5">Quickstart</a></h1>
|
|
<p>This section will give a very quick start to running unit tests with shUnit2.
|
|
More information is located in later sections.</p>
|
|
<p>Here is a quick sample script to show how easy it is to write a unit test in
|
|
shell. <em>Note: the script as it stands expects that you are running it from the
|
|
``examples`` directory.</em></p>
|
|
<pre class="literal-block">
|
|
#! /bin/sh
|
|
# file: examples/equality_test.sh
|
|
|
|
testEquality()
|
|
{
|
|
assertEquals 1 1
|
|
}
|
|
|
|
# load shunit2
|
|
. ../src/shell/shunit2
|
|
</pre>
|
|
<p>Running the unit test should give results similar to the following.</p>
|
|
<pre class="literal-block">
|
|
testEquality
|
|
|
|
Ran 1 test.
|
|
|
|
OK
|
|
</pre>
|
|
<p>W00t! You've just run your first successful unit test. So, what just happened?
|
|
Quite a bit really, and it all happened simply by sourcing the <tt class="docutils literal">shunit2</tt>
|
|
library. The basic functionality for the script above goes like this:</p>
|
|
<ul class="simple">
|
|
<li>When shUnit2 is sourced, it will walk through any functions defined whose
|
|
namestart with the string <tt class="docutils literal">test</tt> and add those to an internal list of tests
|
|
to execute. Once a list of test functions to be run has been determined,
|
|
shunit2 will go to work.</li>
|
|
<li>Before any tests are executed, shUnit2 again looks for a function, this time
|
|
one named <tt class="docutils literal">oneTimeSetUp()</tt>. If it exists, it will be run. This function is
|
|
normally used to setup the environment for all tests to be run. Things like
|
|
creating directories for output or setting environment variables are good to
|
|
place here. Just so you know, you can also declare a corresponding function
|
|
named <tt class="docutils literal">oneTimeTearDown()</tt> function that does the same thing, but once all
|
|
the tests have been completed. It is good for removing temporary directories,
|
|
etc.</li>
|
|
<li>shUnit2 is now ready to run tests. Before doing so though, it again looks for
|
|
another function that might be declared, one named <tt class="docutils literal">setUp()</tt>. If the
|
|
function exists, it will be run before each test. It is good for resetting the
|
|
environment so that each test starts with a clean slate. At this stage, the
|
|
first test is finally run. The success of the test is recorded for a report
|
|
that will be generated later. After the test is run, shUnit2 looks for a final
|
|
function that might be declared, one named <tt class="docutils literal">tearDown()</tt>. If it exists, it
|
|
will be run after each test. It is a good place for cleaning up after each
|
|
test, maybe doing things like removing files that were created, or removing
|
|
directories. This set of steps, <tt class="docutils literal">setUp()</tt> > <tt class="docutils literal">test()</tt> > <tt class="docutils literal">tearDown()</tt>, is
|
|
repeated for all of the available tests.</li>
|
|
<li>Once all the work is done, shUnit2 will generate the nice report you saw
|
|
above. A summary of all the successes and failures will be given so that you
|
|
know how well your code is doing.</li>
|
|
</ul>
|
|
<p>We should now try adding a test that fails. Change your unit test to look like
|
|
this.</p>
|
|
<pre class="literal-block">
|
|
#! /bin/sh
|
|
# file: examples/party_test.sh
|
|
|
|
testEquality()
|
|
{
|
|
assertEquals 1 1
|
|
}
|
|
|
|
testPartyLikeItIs1999()
|
|
{
|
|
year=`date '+%Y'`
|
|
assertEquals "It's not 1999 :-(" \
|
|
'1999' "${year}"
|
|
}
|
|
|
|
# load shunit2
|
|
. ../src/shell/shunit2
|
|
</pre>
|
|
<p>So, what did you get? I guess it told you that this isn't 1999. Bummer, eh?
|
|
Hopefully, you noticed a couple of things that were different about the second
|
|
test. First, we added an optional message that the user will see if the assert
|
|
fails. Second, we did comparisons of strings instead of integers as in the first
|
|
test. It doesn't matter whether you are testing for equality of strings or
|
|
integers. Both work equally well with shUnit2.</p>
|
|
<p>Hopefully, this is enough to get you started with unit testing. If you want a
|
|
ton more examples, take a look at the tests provided with <a class="reference external" href="http://log4sh.sourceforge.net/">log4sh</a> or <a class="reference external" href="http://shflags.googlecode.com/">shFlags</a>.
|
|
Both provide excellent examples of more advanced usage. shUnit2 was after all
|
|
written to help with the unit testing problems that <a class="reference external" href="http://log4sh.sourceforge.net/">log4sh</a> had.</p>
|
|
</div>
|
|
<div class="section" id="function-reference">
|
|
<h1><a class="toc-backref" href="#id6">Function Reference</a></h1>
|
|
<div class="section" id="general-info">
|
|
<h2><a class="toc-backref" href="#id7">General Info</a></h2>
|
|
<p>Any string values passed should be properly quoted -- they should must be
|
|
surrounded by single-quote (') or double-quote (") characters -- so that the
|
|
shell will properly parse them.</p>
|
|
</div>
|
|
<div class="section" id="asserts">
|
|
<h2><a class="toc-backref" href="#id8">Asserts</a></h2>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal">assertEquals [message] expected actual</tt></dt>
|
|
<dd>Asserts that <em>expected</em> and <em>actual</em> are equal to one another. The <em>expected</em>
|
|
and <em>actual</em> values can be either strings or integer values as both will be
|
|
treated as strings. The <em>message</em> is optional, and must be quoted.</dd>
|
|
<dt><tt class="docutils literal">assertNotEquals [message] expected actual</tt></dt>
|
|
<dd>Asserts that <em>unexpected</em> and <em>actual</em> are not equal to one another. The
|
|
<em>unexpected</em> and <em>actual</em> values can be either strings or integer values as
|
|
both will be treaded as strings. The <em>message</em> is optional, and must be
|
|
quoted.</dd>
|
|
<dt><tt class="docutils literal">assertSame [message] expected actual</tt></dt>
|
|
<dd>This function is functionally equivalent to <tt class="docutils literal">assertEquals</tt>.</dd>
|
|
<dt><tt class="docutils literal">assertNotSame [message] unexpected actual</tt></dt>
|
|
<dd>This function is functionally equivalent to <tt class="docutils literal">assertNotEquals</tt>.</dd>
|
|
<dt><tt class="docutils literal">assertNull [message] value</tt></dt>
|
|
<dd>Asserts that <em>value</em> is <em>null</em>, or in shell terms, a zero-length string. The
|
|
<em>value</em> must be a string as an integer value does not translate into a
|
|
zero-length string. The <em>message</em> is optional, and must be quoted.</dd>
|
|
<dt><tt class="docutils literal">assertNotNull [message] value</tt></dt>
|
|
<dd>Asserts that <em>value</em> is <em>not null</em>, or in shell terms, a non-empty string. The
|
|
<em>value</em> may be a string or an integer as the later will be parsed as a
|
|
non-empty string value. The <em>message</em> is optional, and must be quoted.</dd>
|
|
<dt><tt class="docutils literal">assertTrue [message] condition</tt></dt>
|
|
<dd><p class="first">Asserts that a given shell test <em>condition</em> is <em>true</em>. The condition can be as
|
|
simple as a shell <em>true</em> value (the value <tt class="docutils literal">0</tt> -- equivalent to
|
|
<tt class="docutils literal">${SHUNIT_TRUE}</tt>), or a more sophisticated shell conditional expression. The
|
|
<em>message</em> is optional, and must be quoted.</p>
|
|
<p>A sophisticated shell conditional expression is equivalent to what the <strong>if</strong>
|
|
or <strong>while</strong> shell built-ins would use (more specifically, what the <strong>test</strong>
|
|
command would use). Testing for example whether some value is greater than
|
|
another value can be done this way.</p>
|
|
<pre class="literal-block">
|
|
assertTrue "[ 34 -gt 23 ]"
|
|
</pre>
|
|
<p>Testing for the ability to read a file can also be done. This particular test
|
|
will fail.</p>
|
|
<pre class="literal-block">
|
|
assertTrue 'test failed' "[ -r /some/non-existant/file' ]"
|
|
</pre>
|
|
<p>As the expressions are standard shell <strong>test</strong> expressions, it is possible to
|
|
string multiple expressions together with <tt class="docutils literal"><span class="pre">-a</span></tt> and <tt class="docutils literal"><span class="pre">-o</span></tt> in the standard
|
|
fashion. This test will succeed as the entire expression evaluates to <em>true</em>.</p>
|
|
<pre class="literal-block">
|
|
assertTrue 'test failed' '[ 1 -eq 1 -a 2 -eq 2 ]'
|
|
</pre>
|
|
<p class="last"><em>One word of warning: be very careful with your quoting as shell is not the
|
|
most forgiving of bad quoting, and things will fail in strange ways.</em></p>
|
|
</dd>
|
|
<dt><tt class="docutils literal">assertFalse [message] condition</tt></dt>
|
|
<dd><p class="first">Asserts that a given shell test <em>condition</em> is <em>false</em>. The condition can be
|
|
as simple as a shell <em>false</em> value (the value <tt class="docutils literal">1</tt> -- equivalent to
|
|
<tt class="docutils literal">${SHUNIT_FALSE}</tt>), or a more sophisticated shell conditional expression.
|
|
The <em>message</em> is optional, and must be quoted.</p>
|
|
<p class="last"><em>For examples of more sophisticated expressions, see ``assertTrue``.</em></p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="failures">
|
|
<h2><a class="toc-backref" href="#id9">Failures</a></h2>
|
|
<p>Just to clarify, failures <strong>do not</strong> test the various arguments against one
|
|
another. Failures simply fail, optionally with a message, and that is all they
|
|
do. If you need to test arguments against one another, use asserts.</p>
|
|
<p>If all failures do is fail, why might one use them? There are times when you may
|
|
have some very complicated logic that you need to test, and the simple asserts
|
|
provided are simply not adequate. You can do your own validation of the code,
|
|
use an <tt class="docutils literal">assertTrue ${SHUNIT_TRUE}</tt> if your own tests succeeded, and use a
|
|
failure to record a failure.</p>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal">fail [message]</tt></dt>
|
|
<dd>Fails the test immediately. The <em>message</em> is optional, and must be quoted.</dd>
|
|
<dt><tt class="docutils literal">failNotEquals [message] unexpected actual</tt></dt>
|
|
<dd><p class="first">Fails the test immediately, reporting that the <em>unexpected</em> and <em>actual</em>
|
|
values are not equal to one another. The <em>message</em> is optional, and must be
|
|
quoted.</p>
|
|
<p class="last"><em>Note: no actual comparison of unexpected and actual is done.</em></p>
|
|
</dd>
|
|
<dt><tt class="docutils literal">failSame [message] expected actual</tt></dt>
|
|
<dd><p class="first">Fails the test immediately, reporting that the <em>expected</em> and <em>actual</em> values
|
|
are the same. The <em>message</em> is optional, and must be quoted.</p>
|
|
<p class="last"><em>Note: no actual comparison of expected and actual is done.</em></p>
|
|
</dd>
|
|
<dt><tt class="docutils literal">failNotSame [message] expected actual</tt></dt>
|
|
<dd><p class="first">Fails the test immediately, reporting that the <em>expected</em> and <em>actual</em> values
|
|
are not the same. The <em>message</em> is optional, and must be quoted.</p>
|
|
<p class="last"><em>Note: no actual comparison of expected and actual is done.</em></p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="setup-teardown">
|
|
<h2><a class="toc-backref" href="#id10">Setup/Teardown</a></h2>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal">oneTimeSetUp</tt></dt>
|
|
<dd><p class="first">This function can be be optionally overridden by the user in their test suite.</p>
|
|
<p class="last">If this function exists, it will be called once before any tests are run. It
|
|
is useful to prepare a common environment for all tests.</p>
|
|
</dd>
|
|
<dt><tt class="docutils literal">oneTimeTearDown</tt></dt>
|
|
<dd><p class="first">This function can be be optionally overridden by the user in their test suite.</p>
|
|
<p class="last">If this function exists, it will be called once after all tests are completed.
|
|
It is useful to clean up the environment after all tests.</p>
|
|
</dd>
|
|
<dt><tt class="docutils literal">setUp</tt></dt>
|
|
<dd><p class="first">This function can be be optionally overridden by the user in their test suite.</p>
|
|
<p class="last">If this function exists, it will be called before each test is run. It is
|
|
useful to reset the environment before each test.</p>
|
|
</dd>
|
|
<dt><tt class="docutils literal">tearDown</tt></dt>
|
|
<dd><p class="first">This function can be be optionally overridden by the user in their test suite.</p>
|
|
<p class="last">If this function exists, it will be called after each test completes. It is
|
|
useful to clean up the environment after each test.</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="skipping">
|
|
<h2><a class="toc-backref" href="#id11">Skipping</a></h2>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal">startSkipping</tt></dt>
|
|
<dd>This function forces the remaining <em>assert</em> and <em>fail</em> functions to be
|
|
"skipped", i.e. they will have no effect. Each function skipped will be
|
|
recorded so that the total of asserts and fails will not be altered.</dd>
|
|
<dt><tt class="docutils literal">endSkipping</tt></dt>
|
|
<dd>This function returns calls to the <em>assert</em> and <em>fail</em> functions to their
|
|
default behavior, i.e. they will be called.</dd>
|
|
<dt><tt class="docutils literal">isSkipping</tt></dt>
|
|
<dd>This function returns the current state of skipping. It can be compared
|
|
against <tt class="docutils literal">${SHUNIT_TRUE}</tt> or <tt class="docutils literal">${SHUNIT_FALSE}</tt> if desired.</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="suites">
|
|
<h2><a class="toc-backref" href="#id12">Suites</a></h2>
|
|
<p>The default behavior of shUnit2 is that all tests will be found dynamically. If
|
|
you have a specific set of tests you want to run, or you don't want to use the
|
|
standard naming scheme of prefixing your tests with <tt class="docutils literal">test</tt>, these functions
|
|
are for you. Most users will never use them though.</p>
|
|
<dl class="docutils">
|
|
<dt><tt class="docutils literal">suite</tt></dt>
|
|
<dd><p class="first">This function can be optionally overridden by the user in their test suite.</p>
|
|
<p class="last">If this function exists, it will be called when <tt class="docutils literal">shunit2</tt> is sourced. If it
|
|
does not exist, shUnit2 will search the parent script for all functions
|
|
beginning with the word <tt class="docutils literal">test</tt>, and they will be added dynamically to the
|
|
test suite.</p>
|
|
</dd>
|
|
<dt><tt class="docutils literal">suite_addTest name</tt></dt>
|
|
<dd>This function adds a function named <em>name</em> to the list of tests scheduled for
|
|
execution as part of this test suite. This function should only be called from
|
|
within the <tt class="docutils literal">suite()</tt> function.</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="advanced-usage">
|
|
<h1><a class="toc-backref" href="#id13">Advanced Usage</a></h1>
|
|
<p>This section covers several advanced usage topics.</p>
|
|
<div class="section" id="some-constants-you-can-use">
|
|
<h2><a class="toc-backref" href="#id14">Some constants you can use</a></h2>
|
|
<p>There are several constants provided by shUnit2 as variables that might be of
|
|
use to you.</p>
|
|
<p>Predefined</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="23%" />
|
|
<col width="77%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal">SHUNIT_VERSION</tt></td>
|
|
<td>The version of shUnit2 you are running.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal">SHUNIT_TRUE</tt></td>
|
|
<td>Standard shell <em>true</em> value (the integer value 0).</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal">SHUNIT_FALSE</tt></td>
|
|
<td>Standard shell <em>false</em> value (the integer value 1).</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal">SHUNIT_ERROR</tt></td>
|
|
<td>The integer value 2.</td>
|
|
</tr>
|
|
<tr><td><tt class="docutils literal">SHUNIT_TMPDIR</tt></td>
|
|
<td>Path to temporary directory that will be automatically
|
|
cleaned up upon exit of shUnit2.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>User defined</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="23%" />
|
|
<col width="77%" />
|
|
</colgroup>
|
|
<tbody valign="top">
|
|
<tr><td><tt class="docutils literal">SHUNIT_PARENT</tt></td>
|
|
<td>The filename of the shell script containing the tests. This
|
|
is needed specifically for Zsh support.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="error-handling">
|
|
<h2><a class="toc-backref" href="#id15">Error handling</a></h2>
|
|
<p>The constants values <tt class="docutils literal">SHUNIT_TRUE</tt>, <tt class="docutils literal">SHUNIT_FALSE</tt>, and <tt class="docutils literal">SHUNIT_ERROR</tt> are
|
|
returned from nearly every function to indicate the success or failure of the
|
|
function. Additionally the variable <tt class="docutils literal">flags_error</tt> is filled with a detailed
|
|
error message if any function returns with a <tt class="docutils literal">SHUNIT_ERROR</tt> value.</p>
|
|
</div>
|
|
<div class="section" id="including-line-numbers-in-asserts-macros">
|
|
<h2><a class="toc-backref" href="#id16">Including Line Numbers in Asserts (Macros)</a></h2>
|
|
<p>If you include lots of assert statements in an individual test function, it can
|
|
become difficult to determine exactly which assert was thrown unless your
|
|
messages are unique. To help somewhat, line numbers can be included in the
|
|
assert messages. To enable this, a special shell "macro" must be used rather
|
|
than the standard assert calls. <em>Shell doesn't actually have macros; the name is
|
|
used here as the operation is similar to a standard macro.</em></p>
|
|
<p>For example, to include line numbers for a <tt class="docutils literal">assertEquals()</tt> function call,
|
|
replace the <tt class="docutils literal">assertEquals()</tt> with <tt class="docutils literal">${_ASSERT_EQUALS_}</tt>.</p>
|
|
<p>Example -- Asserts with and without line numbers</p>
|
|
<pre class="literal-block">
|
|
#! /bin/sh
|
|
# file: examples/lineno_test.sh
|
|
|
|
testLineNo()
|
|
{
|
|
# this assert will have line numbers included (e.g. "ASSERT:[123] ...")
|
|
echo "ae: ${_ASSERT_EQUALS_}"
|
|
${_ASSERT_EQUALS_} 'not equal' 1 2
|
|
|
|
# this assert will not have line numbers included (e.g. "ASSERT: ...")
|
|
assertEquals 'not equal' 1 2
|
|
}
|
|
|
|
# load shunit2
|
|
. ../src/shell/shunit2
|
|
</pre>
|
|
<p>Notes:</p>
|
|
<ol class="arabic">
|
|
<li><p class="first">Due to how shell parses command-line arguments, all strings used with macros
|
|
should be quoted twice. Namely, single-quotes must be converted to
|
|
single-double-quotes, and vice-versa. If the string being passed is
|
|
absolutely for sure not empty, the extra quoting is not necessary.</p>
|
|
<p>Normal <tt class="docutils literal">assertEquals</tt> call.</p>
|
|
<pre class="literal-block">
|
|
assertEquals 'some message' 'x' ''
|
|
</pre>
|
|
<p>Macro <tt class="docutils literal">_ASSERT_EQUALS_</tt> call. Note the extra quoting around the <em>message</em>
|
|
and the <em>null</em> value.</p>
|
|
<pre class="literal-block">
|
|
_ASSERT_EQUALS_ '"some message"' 'x' '""'
|
|
</pre>
|
|
</li>
|
|
<li><p class="first">Line numbers are not supported in all shells. If a shell does not support
|
|
them, no errors will be thrown. Supported shells include: <strong>bash</strong> (>=3.0),
|
|
<strong>ksh</strong>, <strong>pdksh</strong>, and <strong>zsh</strong>.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="test-skipping">
|
|
<h2><a class="toc-backref" href="#id17">Test Skipping</a></h2>
|
|
<p>There are times where the test code you have written is just not applicable to
|
|
the system you are running on. This section describes how to skip these tests
|
|
but maintain the total test count.</p>
|
|
<p>Probably the easiest example would be shell code that is meant to run under the
|
|
<strong>bash</strong> shell, but the unit test is running under the Bourne shell. There are
|
|
things that just won't work. The following test code demonstrates two sample
|
|
functions, one that will be run under any shell, and the another that will run
|
|
only under the <strong>bash</strong> shell.</p>
|
|
<p>Example -- math include</p>
|
|
<pre class="literal-block">
|
|
# available as examples/math.inc
|
|
|
|
add_generic()
|
|
{
|
|
num_a=$1
|
|
num_b=$2
|
|
|
|
expr $1 + $2
|
|
}
|
|
|
|
add_bash()
|
|
{
|
|
num_a=$1
|
|
num_b=$2
|
|
|
|
echo $(($1 + $2))
|
|
}
|
|
</pre>
|
|
<p>And here is a corresponding unit test that correctly skips the <tt class="docutils literal">add_bash()</tt>
|
|
function when the unit test is not running under the <strong>bash</strong> shell.</p>
|
|
<p>Example -- math unit test</p>
|
|
<pre class="literal-block">
|
|
#! /bin/sh
|
|
# available as examples/math_test.sh
|
|
|
|
testAdding()
|
|
{
|
|
result=`add_generic 1 2`
|
|
assertEquals \
|
|
"the result of '${result}' was wrong" \
|
|
3 "${result}"
|
|
|
|
# disable non-generic tests
|
|
[ -z "${BASH_VERSION:-}" ] && startSkipping
|
|
|
|
result=`add_bash 1 2`
|
|
assertEquals \
|
|
"the result of '${result}' was wrong" \
|
|
3 "${result}"
|
|
}
|
|
|
|
oneTimeSetUp()
|
|
{
|
|
# load include to test
|
|
. ./math.inc
|
|
}
|
|
|
|
# load and run shUnit2
|
|
. ../src/shell/shunit2
|
|
</pre>
|
|
<p>Running the above test under the <strong>bash</strong> shell will result in the following
|
|
output.</p>
|
|
<pre class="literal-block">
|
|
$ /bin/bash math_test.sh
|
|
testAdding
|
|
|
|
Ran 1 test.
|
|
|
|
OK
|
|
</pre>
|
|
<p>But, running the test under any other Unix shell will result in the following
|
|
output.</p>
|
|
<pre class="literal-block">
|
|
$ /bin/ksh math_test.sh
|
|
testAdding
|
|
|
|
Ran 1 test.
|
|
|
|
OK (skipped=1)
|
|
</pre>
|
|
<p>As you can see, the total number of tests has not changed, but the report
|
|
indicates that some tests were skipped.</p>
|
|
<p>Skipping can be controlled with the following functions: <tt class="docutils literal">startSkipping()</tt>,
|
|
<tt class="docutils literal">stopSkipping()</tt>, and <tt class="docutils literal">isSkipping()</tt>. Once skipping is enabled, it will
|
|
remain enabled until the end of the current test function call, after which
|
|
skipping is disabled.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="appendix">
|
|
<h1><a class="toc-backref" href="#id18">Appendix</a></h1>
|
|
<div class="section" id="getting-help">
|
|
<h2><a class="toc-backref" href="#id19">Getting help</a></h2>
|
|
<p>For help, please send requests to either the <a class="reference external" href="mailto:shunit2-users@googlegroups.com">shunit2-users@googlegroups.com</a>
|
|
mailing list (archives available on the web at
|
|
<a class="reference external" href="http://groups.google.com/group/shunit2-users">http://groups.google.com/group/shunit2-users</a>) or directly to
|
|
Kate Ward <kate dot ward at forestent dot com>.</p>
|
|
</div>
|
|
<div class="section" id="zsh">
|
|
<h2><a class="toc-backref" href="#id20">Zsh</a></h2>
|
|
<p>For compatibility with Zsh, there is one requirement that must be met -- the
|
|
<tt class="docutils literal">shwordsplit</tt> option must be set. There are three ways to accomplish this.</p>
|
|
<ol class="arabic">
|
|
<li><p class="first">In the unit-test script, add the following shell code snippet before sourcing
|
|
the <tt class="docutils literal">shunit2</tt> library.</p>
|
|
<pre class="literal-block">
|
|
setopt shwordsplit
|
|
</pre>
|
|
</li>
|
|
<li><p class="first">When invoking <strong>zsh</strong> from either the command-line or as a script with
|
|
<tt class="docutils literal">#!</tt>, add the <tt class="docutils literal"><span class="pre">-y</span></tt> parameter.</p>
|
|
<pre class="literal-block">
|
|
#! /bin/zsh -y
|
|
</pre>
|
|
</li>
|
|
<li><p class="first">When invoking <strong>zsh</strong> from the command-line, add <tt class="docutils literal"><span class="pre">-o</span> shwordsplit <span class="pre">--</span></tt> as
|
|
parameters before the script name.</p>
|
|
<pre class="literal-block">
|
|
$ zsh -o shwordsplit -- some_script
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
<!-- generate HTML using rst2html from Docutils of -->
|
|
<!-- http://docutils.sourceforge.net/ -->
|
|
<!-- -->
|
|
<!-- vim:fileencoding=latin1:ft=rst:spell:sts=2:sw=2:tw=80 -->
|
|
<!-- $Revision: 233 $ -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|