Moving key points to reference.md

Author: gvwilson

01-basics.html

@@ -27,7 +27,7 @@
       <div class="row">
         <div class="col-md-10 col-md-offset-1">
                     <a href="index.html"><h1 class="title">Testing</h1></a>
-          <h2 class="subtitle">Basics of testing</h2>
+          <h2 class="subtitle">Basics of Testing</h2>
           <section class="objectives panel panel-warning">
 <div class="panel-heading">
 <h2><span class="glyphicon glyphicon-certificate"></span>Learning Objectives</h2>
@@ -46,8 +46,11 @@ <h2><span class="glyphicon glyphicon-certificate"></span>Learning Objectives</h2
 <li>The act of writing tests can help clarify how the software should be perform when you are done.</li>
 <li>In fact, starting to write the tests <em>before</em> you even write the software might be advisable. (Such a practice is called <em>test-driven development</em>, which we will discuss in greater detail <a href="09-tdd.html">later in the lesson</a>.)</li>
 </ul>
-<blockquote>
-<h3>What Kinds of Tests Exist</h3>
+<aside class="callout panel panel-info">
+<div class="panel-heading">
+<h2><span class="glyphicon glyphicon-pushpin"></span>What Kinds of Tests Exist</h2>
+</div>
+<div class="panel-body">
 <p>There are many ways to test software, such as:</p>
 <ul>
 <li>Assertions</li>
@@ -56,22 +59,12 @@ <h3>What Kinds of Tests Exist</h3>
 <li>Regresson Tests</li>
 <li>Integration Tests</li>
 </ul>
-</blockquote>
+</div>
+</aside>
 <p><em>Exceptions and Assertions</em>: While writing code, <code>exceptions</code> and <code>assertions</code> can be added to sound an alarm as runtime problems come up. These kinds of tests, are embedded in the software iteself and handle, as their name implies, exceptional cases rather than the norm.</p>
 <p><em>Unit Tests</em>: Unit tests investigate the behavior of units of code (such as functions, classes, or data structures). By validating each software unit across the valid range of its input and output parameters, tracking down unexpected behavior that may appear when the units are combined is made vastly simpler.</p>
 <p><em>Regression Tests</em>: Regression tests defend against new bugs, or regressions, which might appear due to new software and updates.</p>
 <p><em>Integration Tests</em>: Integration tests check that various pieces of the software work together as expected.</p>
-<blockquote>
-<h2>Key Points</h2>
-<ul>
-<li>Tests compare that the result observed from running code is the same as what was expected ahead of time.</li>
-<li>Tests should be written at the same time as the code they are testing is written.</li>
-<li>Assertions and exceptions are like alarm systems embedded in the software, guarding against exceptional bahavior.</li>
-<li>Unit tests try to test the smallest pieces of code possible, usually functions and methods.</li>
-<li>Integration tests make sure that code units work together properly.</li>
-<li>Regression tests ensure that everything works the same today as it did yesterday.</li>
-</ul>
-</blockquote>
         </div>
       </div>
       </article>

01-basics.md

@@ -1,7 +1,7 @@
 ---
 layout: page
 title: Testing
-subtitle: Basics of testing
+subtitle: Basics of Testing
 minutes: 5
 ---
 > ## Learning Objectives {.objectives}
@@ -24,7 +24,8 @@ This is analogous to experiment design in the experimental science world:
   might be advisable. (Such a practice is called _test-driven development_, 
   which we will discuss in greater detail [later in the lesson](09-tdd.html).)
 
-> ### What Kinds of Tests Exist
+> ## What Kinds of Tests Exist {.callout}
+>
 > There are many ways to test software, such as:
 >
 > - Assertions
@@ -49,14 +50,3 @@ which might appear due to new software and updates.
 
 *Integration Tests*: Integration tests check that various pieces of the
 software work together as expected. 
-
-
-> ## Key Points {.keypoints}
-> 
-> - Tests compare that the result observed from running code is the same as what was expected ahead of time.
-> - Tests should be written at the same time as the code they are testing is written.
-> - Assertions and exceptions are like alarm systems embedded in the software, guarding against exceptional bahavior.
-> - Unit tests try to test the smallest pieces of code possible, usually functions and methods.
-> - Integration tests make sure that code units work together properly.
-> - Regression tests ensure that everything works the same today as it did yesterday.
-

02-assertions.html

@@ -55,7 +55,7 @@ <h2><span class="glyphicon glyphicon-certificate"></span>Learning Objectives</h2
 <p>Also, input checking may require decending a rabbit hole of exceptional cases. What happens when the input provided to the mean function is a string, rather than a list of numbers?</p>
 <section class="challenge panel panel-success">
 <div class="panel-heading">
-<h2><span class="glyphicon glyphicon-pencil"></span>Challenge Insert an Assertion</h2>
+<h2><span class="glyphicon glyphicon-pencil"></span>Insert an Assertion</h2>
 </div>
 <div class="panel-body">
 <ol style="list-style-type: decimal">
@@ -73,7 +73,7 @@ <h2><span class="glyphicon glyphicon-pencil"></span>Challenge Insert an Assertio
 <p>Assertions are also helpful for catching abnormal behaviors, such as those that arise with floating point arithmetic.</p>
 <section class="challenge panel panel-success">
 <div class="panel-heading">
-<h2><span class="glyphicon glyphicon-pencil"></span>Challenge: Almost Equal</h2>
+<h2><span class="glyphicon glyphicon-pencil"></span>Almost Equal</h2>
 </div>
 <div class="panel-body">
 <p>Assertions are also helpful for catching abnormal behaviors, such as those that arise with floating point arithmetic. Using the assert keyword, how could you test whether some value is almost the same as another value?</p>
@@ -90,24 +90,13 @@ <h2><span class="glyphicon glyphicon-pencil"></span>Challenge: Almost Equal</h2>
 </div>
 </section>
 <p>To help with situations such as those above, there are classes of more helpful assertions that we will use often in later parts of this testing lesson as the building blocks of our tests. The nose testing package contains many of them.</p>
-<h3 id="nose">Nose</h3>
+<h2 id="nose">Nose</h2>
 <p>The nose testing framework has built-in assertion types implementing <code>assert_almost_equal</code>, <code>assert_true</code>, <code>assert_false</code>, <code>assert_raises</code>, <code>assert_is_instance</code>, and others.</p>
 <pre class="sourceCode python"><code class="sourceCode python"><span class="ch">from</span> nose.tools <span class="ch">import</span> assert_almost_equal
 <span class="ch">from</span> mynum <span class="ch">import</span> a
 assert_almost_equal(a, <span class="dv">2</span>, places=<span class="dv">2</span>)
 assert_almost_equal(a, <span class="dv">2</span>, delta=<span class="fl">0.003</span>)</code></pre>
 <p>These assertions give much more helpful error messages and have much more powerful features than the simple assert keyword. An even more powerful sibling of the assertion is the <em>exception</em>. We’ll learn about those in the next lesson.</p>
-<blockquote>
-<h2>Key Points</h2>
-<ul>
-<li>Assertions are one line tests embedded in code.</li>
-<li>The <code>assert</code> keyword is used to set an assertion.</li>
-<li>Assertions halt execution if the argument is false.</li>
-<li>Assertions do nothing if the argument is true.</li>
-<li>The <code>nose.tools</code> package provides more informative assertions.</li>
-<li>Assertions are the building blocks of tests.</li>
-</ul>
-</blockquote>
         </div>
       </div>
       </article>

02-assertions.md

@@ -48,9 +48,7 @@ Also, input checking may require decending a rabbit hole of exceptional cases.
 What happens when the input provided to the mean function is a string, rather 
 than a list of numbers?
 
-
-> ## Challenge Insert an Assertion {.challenge}
->
+> ## Insert an Assertion {.challenge}
 >
 > 1. Open an IPython Notebook
 > 2. Create the following function:
@@ -70,7 +68,8 @@ than a list of numbers?
 Assertions are also helpful for catching abnormal behaviors, such as those that 
 arise with floating point arithmetic.
 
-> ## Challenge: Almost Equal {.challenge}
+> ## Almost Equal {.challenge}
+>
 > Assertions are also helpful for catching abnormal behaviors, such as those
 > that arise with floating point arithmetic. Using the assert keyword, how could
 > you test whether some value is almost the same as another value?
@@ -91,7 +90,7 @@ To help with situations such as those above, there are classes of more helpful
 assertions that we will use often in later parts of this testing lesson as the
 building blocks of our tests. The nose testing package contains many of them.
 
-### Nose
+## Nose
 
 The nose testing framework has built-in assertion types implementing
 `assert_almost_equal`, `assert_true`, `assert_false`, `assert_raises`,
@@ -108,13 +107,3 @@ These assertions give much more helpful error messages and have much more
 powerful features than the simple assert keyword. An even more powerful sibling 
 of the assertion is the _exception_. We'll learn about those in the next 
 lesson.
-
-
-> ## Key Points {.keypoints}
->
-> -   Assertions are one line tests embedded in code.
-> -   The `assert` keyword is used to set an assertion.
-> -   Assertions halt execution if the argument is false.
-> -   Assertions do nothing if the argument is true.
-> -   The `nose.tools` package provides more informative assertions.
-> -   Assertions are the building blocks of tests.

03-exceptions.html

@@ -71,7 +71,7 @@ <h2><span class="glyphicon glyphicon-certificate"></span>Learning Objectives</h2
         <span class="kw">raise</span> <span class="ot">TypeError</span>(detail.<span class="ot">__str__</span>() + <span class="st">&quot;</span><span class="ch">\n</span><span class="st">&quot;</span> +  msg)</code></pre>
 <section class="challenge panel panel-success">
 <div class="panel-heading">
-<h2><span class="glyphicon glyphicon-pencil"></span>Challenge: What Else Can Go Wrong?</h2>
+<h2><span class="glyphicon glyphicon-pencil"></span>What Else Can Go Wrong?</h2>
 </div>
 <div class="panel-body">
 <ol style="list-style-type: decimal">
@@ -82,7 +82,7 @@ <h2><span class="glyphicon glyphicon-pencil"></span>Challenge: What Else Can Go
 </section>
 <section class="challenge panel panel-success">
 <div class="panel-heading">
-<h2><span class="glyphicon glyphicon-pencil"></span>Challenge: Cause all of the errors</h2>
+<h2><span class="glyphicon glyphicon-pencil"></span>Cause All of the Errors</h2>
 </div>
 <div class="panel-body">
 <ul>
@@ -91,14 +91,6 @@ <h2><span class="glyphicon glyphicon-pencil"></span>Challenge: Cause all of the
 </div>
 </section>
 <p>Exceptions have the advantage of being simple to include and powerfully helpful to the user. However, not all behaviors can or should be found with runtime exceptions. Most behaviors should be validated with unit tests.</p>
-<blockquote>
-<h2>Key Points</h2>
-<ul>
-<li>Exceptions are effectively specialized runtime tests</li>
-<li>Exceptions can be caught and handled with a try-except block</li>
-<li>Many built-in Exception types are available</li>
-</ul>
-</blockquote>
         </div>
       </div>
       </article>

03-exceptions.md

@@ -71,23 +71,17 @@ def mean(num_list):
         raise TypeError(detail.__str__() + "\n" +  msg)
 ~~~
 
-> ## Challenge: What Else Can Go Wrong? {.challenge}
+> ## What Else Can Go Wrong? {.challenge}
+>
 > 1. Think of some other type of exception that could be raised by the try 
 > block.
 > 2. Guard against it by adding an except clause.
 
-> ## Challenge: Cause all of the errors {.challenge}
+> ## Cause All of the Errors {.challenge}
 > 
 > - Use the mean function in three different ways, so that you cause each
 > exceptional case.
 
 Exceptions have the advantage of being simple to include and powerfully helpful
 to the user. However, not all behaviors can or should be found with runtime
 exceptions. Most behaviors should be validated with unit tests.
-
-> ## Key Points {.keypoints}
->
-> -   Exceptions are effectively specialized runtime tests
-> -   Exceptions can be caught and handled with a try-except block
-> -   Many built-in Exception types are available 
-

04-units.html

@@ -66,7 +66,7 @@ <h2 id="unit-tests-are-just-functions">Unit Tests Are Just Functions</h2>
 <p>A unit test suite is made up of many tests just like this one. A single implemented function may be tested in numerous ways.</p>
 <section class="challenge panel panel-success">
 <div class="panel-heading">
-<h2><span class="glyphicon glyphicon-pencil"></span>Challenge: Write a File Full of Tests</h2>
+<h2><span class="glyphicon glyphicon-pencil"></span>Write a File Full of Tests</h2>
 </div>
 <div class="panel-body">
 <ol style="list-style-type: decimal">
@@ -112,16 +112,6 @@ <h2><span class="glyphicon glyphicon-pencil"></span>Challenge: Write a File Full
 </div>
 </section>
 <p>Well, <strong>that</strong> was tedious.</p>
-<blockquote>
-<h2>Key Points</h2>
-<ul>
-<li>Functions are the atomistic unit of software.</li>
-<li>Simpler units are easier to test than complex ones.</li>
-<li>A single unit test is a function containing assertions.</li>
-<li>Such a unit test is run just like any other function.</li>
-<li><strong>Running tests one at a time is pretty tedious.</strong> (let’s use a framework instead)</li>
-</ul>
-</blockquote>
         </div>
       </div>
       </article>

04-units.md

@@ -25,6 +25,7 @@ be made any simpler logically (you cannot split apart the addition operator) or
 practically (a function is self-contained and well defined), then it is a unit. 
 
 > ## Functions are Like Paragraphs {.callout}
+>
 > Recall that humans can only hold a few ideas in our heads at once. Paragraphs
 > in books, for example, become unwieldy after a few lines. Functions, generaly,
 > shouldn't be longer than paragraphs.
@@ -69,7 +70,8 @@ The test above:
 A unit test suite is made up of many tests just like this one. A single 
 implemented function may be tested in numerous ways. 
 
-> ## Challenge: Write a File Full of Tests {.challenge}
+> ## Write a File Full of Tests {.challenge}
+>
 > 1. In a file called `test_mean.py`, implement the following code:
 > 
 > ~~~ {.python}
@@ -113,13 +115,3 @@ implemented function may be tested in numerous ways.
 > 
 
 Well, **that** was tedious.
-
-> ## Key Points {.keypoints}
->
-> -   Functions are the atomistic unit of software.
-> -   Simpler units are easier to test than complex ones.
-> -   A single unit test is a function containing assertions.
-> -   Such a unit test is run just like any other function.
-> -   **Running tests one at a time is pretty tedious.** (let's use a framework 
-> instead)
-

05-nose.html

@@ -110,17 +110,6 @@ <h2><span class="glyphicon glyphicon-pencil"></span>Fix The Failing Code</h2>
 </div>
 </section>
 <p>As we write more code, we would write more tests, and <em>nosetests</em> would produce more dots. Each passing test is a small, satisfying reward for having written quality scientific software. Now that you know how to write tests, let’s go into what can go wrong.</p>
-<blockquote>
-<h2>Key Points</h2>
-<ul>
-<li>The <code>nosetests</code> command collects and runs tests starting with <code>Test-</code>, <code>test_</code>, and similar names.</li>
-<li><code>.</code> means the test passed</li>
-<li><code>F</code> means the test failed</li>
-<li><code>E</code> encountered an error</li>
-<li><code>K</code> is a known failure</li>
-<li><code>S</code> is a purposefully skipped test</li>
-</ul>
-</blockquote>
         </div>
       </div>
       </article>

05-nose.md

@@ -103,6 +103,7 @@ will print summary information.
 
 
 > ## Fix The Failing Code {.challenge}
+>
 > Without changing the tests, alter the mean.py file from the previous section until it passes. 
 > When it passes, _nosetests_ will produce results like the following:
 >
@@ -121,13 +122,3 @@ As we write more code, we would write more tests, and _nosetests_ would produce
 more dots.  Each passing test is a small, satisfying reward for having written
 quality scientific software. Now that you know how to write tests, let's go
 into what can go wrong.
-
-
-> ## Key Points {.keypoints}
->
-> -   The `nosetests` command collects and runs tests starting with `Test-`, `test_`, and similar names.
-> -   `.` means the test passed
-> -   `F` means the test failed
-> -   `E` encountered an error
-> -   `K` is a known failure
-> -   `S` is a purposefully skipped test