<html>
<head>
<title>QED Overview</title>
<style>
#container{ margin: 0 auto; width: 800px; }
/* Debug borders */
/* p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { border: 1px solid red; } */
body { font-size: 14px; line-height: 20px; margin: 1em 5% 1em 5%; font-family: Verdana, Arial, Helvetica, sans-serif; }
a { color: #336; text-decoration: underline; }
a:visited { color: #334; }
em { font-style: italic; }
strong { font-weight: bold; }
tt { color: navy; }
h1, h2, h3, h4, h5, h6 { color: #223; margin-top: 1.2em; margin-bottom: 0.5em; line-height: 1.3; }
h1 { border-bottom: 2px solid silver; }
h2 { border-bottom: 2px solid silver; padding-top: 0.5em; }
hr { border: 1px solid silver; }
p { color: #222; text-align: justify; margin-top: 0.5em; margin-bottom: 0.5em; line-height: 1.4em; }
pre { padding: 10; margin: 0; font-family: monospace; font-size: 0.9em; }
pre.pass { color: green; }
pre.fail { color: red; }
pre.error { color: red; font-weight: bold; }
span#author { color: #527bbd; font-weight: bold; font-size: 1.1em; }
span#email { }
span#revision { }
div#footer { font-size: small; border-top: 2px solid silver; padding-top: 0.5em; margin-top: 4.0em; }
div#footer-text { float: left; padding-bottom: 0.5em; }
div#footer-badges { float: right; padding-bottom: 0.5em; }
/* Block element content. */
div.content { padding: 0; }
/* Block element titles. */
h1.title { font-weight: bold; text-align: left; font-size: 3em; margin-top: 1.0em; margin-bottom: 0.5em; }
/* Block element titles. */
div.title, caption.title { font-weight: bold; text-align: left; margin-top: 1.0em; margin-bottom: 0.5em; }
div.title + * { margin-top: 0; }
td div.title:first-child { margin-top: 0.0em; }
div.content div.title:first-child { margin-top: 0.0em; }
div.content + div.title { margin-top: 0.0em; }
div.sidebarblock > div.content { background: #ffffee; border: 1px solid silver; padding: 0.5em; }
img { border-style: none; }
dl { margin-top: 0.8em; margin-bottom: 0.8em; }
dt { margin-top: 0.5em; margin-bottom: 0; font-style: italic; }
dd > *:first-child { margin-top: 0; }
ul, ol { list-style-position: outside; }
thead { font-weight: bold; }
tfoot { font-weight: bold; }
</style>
<!-- TODO: only include if these files exists -->
<link href="../assets/styles/spec.css" type="text/css" rel="stylesheet">
<!-- spec.css might be a problem with clobber -->
<link href="spec.css" type="text/css" rel="stylesheet">
<!-- JQuery is needed -->
<script src="jquery.js" type="text/javascript" language="javascript"></script>
</head>
<body>
<!-- Side Table of Contents -->
<div id="sidebar" style="position: fixed; top: 10; right: 10; background: white;">
<a href="javascript: toc_toggle();">
<img src="img/icon/book.jpg" height="30px;" style="border: none;" alt="TOC" align="right"/>
</a>
<div id="toc_side" class="toc">
</div>
</div>
<div id="container">
<div id="header">
<img src="img/icon/book.jpg" align="left" style="padding-right: 10px;" alt=""/>
<h1 class="title">QED Overview</h1>
<h1>Table of Contents</h1>
<div class="toc">
</div>
</div>
<div id="content">
<h1>Standard Sections</h1>
<p>
QED demos are light-weight specification documents, suitable for
Interface-driven Development. The documents are divided up into clauses
separated by blank lines. Clauses that are flush to the left margin are
always explanation or comment clauses. Indented clauses are always
executable code.
</p>
<p>
Each code section is executed in order of appearance, within a rescue
wrapper that captures any failures or errors. If neither a failure or error
occur then the code gets a “pass”.
</p>
<p>
For example, the following passes:
</p>
<pre>
(2 + 2).assert == 4
</pre>
<p>
While the following would “fail”, as indicated by the raising
of an Assertion error:
</p>
<pre>
expect Assertion do
(2 + 2).assert == 5
end
</pre>
<p>
And this would have raised a NameError:
</p>
<pre>
expect NameError do
nobody_knows_method
end
</pre>
<h1>Neutral Code</h1>
<p>
There is no means of specifying that a code clause is neutral code, i.e.
that it should be executed but not tested. So far this such a feature has
proven to be a YAGNI. Yet we may add such a feature in the future if it is
ultimately deemed necessary.
</p>
<h1>Defining Custom Assertions</h1>
<p>
The context in which the QED code is run is a self-extended module, thus
reusable macros can be created simply by defining a method.
</p>
<pre>
def assert_integer(x)
x.assert.is_a? Integer
end
</pre>
<p>
Now lets try out our new macro definition.
</p>
<pre>
assert_integer(4)
</pre>
<p>
Let’s prove that it can also fail:
</p>
<pre>
expect Assertion do
assert_integer("IV")
end
</pre>
<h1>Helper File</h1>
<p>
If you create a file called `qed_helper.rb` located in the directory with
the QED documents you are running via the `qed` command, it will be loaded
first. You can use that to load optional AE features, or define your own
specialized assertion methods.
</p>
<h1>Before and After Clauses</h1>
<p>
QED supports <b>before</b> and <b>after</b> clauses in a specification
through the use of before and after code blocks. Before and after clauses
are executed at the beginning and at the end of each subsequent step.
</p>
<p>
We use a <b>before</b> clause if we want to setup some code at the start of
each step.
</p>
<pre>
a, z = nil, nil
before do
a = "BEFORE"
end
</pre>
<p>
And an <b>after</b> clause to tear down objects after a step.
</p>
<pre>
after do
z = "AFTER"
end
</pre>
<p>
Notice we assigned <tt>a</tt> and <tt>z</tt> before the block. This was to
ensure their visibility in the scope later. Now, lets verify this the
<b>before</b> and <b>after</b> clause work.
</p>
<pre>
a.assert == "BEFORE"
a = "A"
z = "Z"
</pre>
<p>
And now.
</p>
<pre>
z.assert == "AFTER"
</pre>
<p>
There can only be one before or after clause at a time. So if we define a
new <b>before</b> or <b>after</b> clause later in the document, it will
replace the current clause(s) in use.
</p>
<p>
As a demonstration of this:
</p>
<pre>
before do
a = "BEFORE AGAIN"
end
</pre>
<p>
We will see it is the case.
</p>
<pre>
a.assert == "BEFORE AGAIN"
</pre>
<p>
Only use <b>before</b> and <b>after</b> clauses when necessary
—specifications are generally more readable without them. Indeed,
some developers make a policy of avoiding them altogether. YMMV.
</p>
<h1>Tabular Steps</h1>
<p>
Finally we will demonstrate a tabular step. <tt>table</tt> method is used
for this. We supply a file name to the method telling QED where to find the
table data to be used in the test. All table files are looked for relative
to the location of the document. If no name is given the
’<doc-name>.yaml’ is assumed.
</p>
<p>
The arity of the table block determines the number of columns each row in
the table should have. Each row is assigned in turn and run through the
coded step. Consider the following example:
</p>
<p>
Every row in ‘table.yaml’ will be assigned to the block
parameters and run through the following assertion.
</p>
<pre>
table do |x,y|
x.upcase.assert == y
end
</pre>
<p>
This concludes the basic overview of QED’s specification system,
which is itself a QED document. Yes, we eat our own dog food.
</p>
<p>
Q.E.D.
</p>
</div>
</div>
</body>
</html>
<script src="../assets/scripts/spec.js" type="text/javascript" language="javascript"></script>
<script type="text/javascript" language="javascript">
/*****************************************************************
* $.toc()
* by rebecca murphey
* rmurphey gmail com
*
* This function is called on its own and takes as an argument
* a list of selectors with which it will build a table of
* contents.
*
* The first selector will make up the top level of the TOC;
* the second selector will make up the second level of the TOC;
* etc.
*
* This function returns a div containing nested unordered lists;
* each list item is linked to an anchor tag added before the item
* on the page.
*
* usage: $.toc('h1,h2,h3').prependTo('body');
************************************************************************/
(function($) {
$.toc = function(tocList) {
$(tocList).addClass('jquery-toc');
var tocListArray = tocList.split(',');
$.each(tocListArray, function(i,v) { tocListArray[i] = $.trim(v); });
var $elements = $('.jquery-toc');
$('body').append('<div></div>');
var $toc = $('body div:last');
var lastLevel = 1;
$toc.append('<ul class="jquery-toc-1"></ul>');
$elements.each(function() {
var $e = $(this);
var text = $e.text();
var anchor = text.replace(/ /g,'-');
$e.before('<a name="' + anchor + '"></a>');
var level;
$.each(tocListArray, function(i,v) {
if (v.match(' ')) {
var vArray = v.split(' ');
var e = vArray[vArray.length - 1];
} else { e = v; }
if ($e.is(e)) { level = i+1; }
});
var className = 'jquery-toc-' + level;
var li = '<li><a href="#' + anchor + '">' + text + '</a></li>';
if (level == lastLevel) {
$('ul.' + className + ':last',$toc).append(li);
} else if (level > lastLevel) {
var parentLevel = level - 1;
var parentClassName = 'jquery-toc-' + parentLevel;
$('ul.' + parentClassName + ':last',$toc).
append('<ul class="' + className + '"></ul>');
$('ul.' + className + ':last',$toc).append(li);
} else if (level < lastLevel) {
$('ul.' + className + ':last',$toc).append(li);
}
lastLevel = level;
});
var $toc_ul = $('ul.jquery-toc-1',$toc);
$toc.remove();
return($toc_ul);
}
})(jQuery);
</script>
<script>
function toc_toggle() {
$('#toc_side').toggle();
$("pre").addClass("pass");
$("pre:contains('FAIL:')").addClass("fail");
$("pre:contains('ERROR:')").addClass("error");
};
$.toc('#content h1,h2,h3,h4').appendTo('.toc');
toc_toggle();
</script>