Permalink
Browse files

Writing docs while drinking lots of beer is a bad thing

  • Loading branch information...
1 parent 437451d commit 4bc3b5ba3f7976ae06992174e089f5b17794329b @foobarfighter committed Jun 21, 2011
Showing with 15 additions and 15 deletions.
  1. +15 −15 site/www/src/documents/documentation.html
@@ -24,21 +24,21 @@ <h3>The Basics</h3>
describe, it, before, after, expect, mock
</pre>
-Theres another class of foounit keywords for asynchronous testing, but these are explained in the <a href="#async-awesomeness">async awesomeness</a> section.
+There's another class of foounit keywords for asynchronous testing, but these are explained in the <a href="#async-awesomeness">async awesomeness</a> section.
<pre class="code">
waitFor, run, waitForTimeout
</pre>
<p>
- These are the basic building blocks of foounit and asynchronous BDD style testing.
+ These are the basic foounit building blocks.
</p>
<a name="it"></a>
<a name="example"></a>
<h3>it (aka example)</h3>
<p>
- In BDD speak an <em>it</em> block is an example that defines usage of a particular feature. So let's say we want to test that a string is less than 10 characters. You might create an <em>it</em> block that looks like this:
+ In BDD-speak an <em>it</em> block is an example that defines usage of a particular feature. So let's say we want to test that a string is less than 10 characters. You might create an <em>it</em> block that looks like this:
<pre class="code">
it('returns true', function (){
@@ -51,11 +51,11 @@ <h3>it (aka example)</h3>
</p>
<p>
- So you might think that an <em>it</em> block is overkill for a test like this, but also realize that this is a contrived example. The nice thing about using <em>it</em> is that you are able to label this test with a description for the next developer that touches this code.
+ You might think that an <em>it</em> block is overkill for a test like this, but this is a contrived example. The nice thing about using <em>it</em> blocks are that you are able provide descriptions for the next developer working on the code.
</p>
<p>
- If you just want to play around with foounit to get an idea for how this will work, you can run something like this. Create a file called <em>test.js</em> with this code:
+ If you just want to play around with foounit, you can try this example. Create a file called <em>test.js</em> with this code:
<pre class="code">
var foounit = require('foounit').globalize();
@@ -81,11 +81,11 @@ <h3>it (aka example)</h3>
<h3>describe (aka group)</h3>
<p>
- Internally, <em>describe</em> creates a group of <em><a href="#example">examples</a></em>. All ths really means to you is that <em>describe</em> actually defines a particular behavior. Let me explain...
+ Internally, <em>describe</em> creates a group of <em><a href="#example">examples</a></em>. <em>describe</em>s describe a group of related behavior.
</p>
<p>
- Let's say you have a signup form widget that allows you to submit a form when you have a password that is 8 or more characters, but it shows an error message if you have password that is less than 8 characters. You might have a test that looks like this:
+ Let's say you have a signup form widget that lets you submit a form when you have a password that is 8 or more characters, but it shows an error message if you have password that is less than 8 characters. You'll have a test that looks like this:
<pre class="code">
describe('when the password is 8 or more characters', function (){
@@ -103,7 +103,7 @@ <h3>describe (aka group)</h3>
</p>
<p>
- You can also nest <em>describe</em>s if your code has nested behaviors (or nested <em>if</em> statements). Nested describes look something like this:
+ You can nest <em>describe</em>s if your code has nested behaviors (or nested <em>if</em> statements). Nested describes look something like this:
<pre class="code">
describe('when foo is not falsy', function (){
@@ -134,7 +134,7 @@ <h3>describe (aka group)</h3>
<h3>expect (aka assertion)</h3>
<p>
- The <em>expect </em> <a href="#keywords">keyword</a> is just another way of creating an assertion. An assertion is a way to test that a particular value is what you expect that it should be. Here is a breakdown of how <em>expect</em> works:
+ The <em>expect </em> <a href="#keywords">keyword</a> creates an assertion. An assertion tests that a value is the value you expect it to be. Here is a breakdown of how <em>expect</em> works:
<pre class="code">
expect(
@@ -172,7 +172,7 @@ <h3>expect (aka assertion)</h3>
<h3>before (aka setup)</h3>
<p>
- A <em>before</em> block is something that sets up a particular test. A <em>before</em> block is run once for each group and they can be nested. <em>before</em> blocks are great for asserting that a test is setup properly before an <em>example</em> is run and for removing clutter from your tests. <em>before</em> blocks can be nested within <em>describe</em>s and are run in order for each <em>example</em>.
+ A <em>before</em> block is a function that sets up a test. A <em>before</em> block is run once for each group, and it can exist within nested groups. <em>before</em> blocks are great for asserting that a test is setup properly before an <em>example</em> runs, and they remove clutter from your tests. Nested groups will run <em>before</em> blocks in the order in which the groups are nested.
<pre class="code">
describe('when foo is 1', function (){
@@ -203,7 +203,7 @@ <h3>before (aka setup)</h3>
<h3>after (aka teardown)</h3>
<p>
- <em>after</em> runs after each test. It's great for cleaning up the environment and it runs even when the test fails.
+ <em>after</em> runs after each test. It should be used for cleaning up the previous test and it runs regardless of whether the example passes or fails.
</p>
<p>
@@ -231,7 +231,7 @@ <h3>after (aka teardown)</h3>
</p>
<p>
- These <em>keywords</em> are 90% of what you need to write tests in BDD style using foounit. There is a lot more to foounit than just these keywords but you can get by without learning about additional matchers and asynchronousness if you are just experimenting. If anything in this guide is unclear, then please email the group.
+ These <em>keywords</em> are 90% of what you need to write tests in BDD-style using foounit. There is a lot more to foounit than just these keywords but you can get by without learning about additional matchers and asynchronous testing if you are just experimenting. If anything in this guide is unclear, then please email <a href="http://groups.google.com/group/foounit">group</a>.
</p>
<!-- /Syntax Overview -->
@@ -261,13 +261,13 @@ <h3>waitFor</h3>
</pre>
<p>
- In this example, an xhr request is made to get the JSON data at <em>http://localhost:5057/data.json</em>. We have mocked the success callback and we wait for the response to succeed and call our callback to be called. If the request succeeds then the test will pass, but if the request is unsuccessful then the test will fail. The <em>waitFor</em> keyword waits for the function it is passed to run without failing. If the <em>waitFor</em> block fails, then it is retried until a timeout is reached. If the timeout is reached then the test fails and a kitten dies.
+ In this example, an xhr request is made to get the JSON data at <em>http://localhost:5057/data.json</em>. We have mocked the success callback and we wait for the response to succeed and call our callback. If the request succeeds then the test will pass, but if the request is unsuccessful then the test will fail. The <em>waitFor</em> keyword waits for the function it is passed to run without failing. If the <em>waitFor</em> block fails, then it is retried until a timeout is reached. If the timeout is reached then the test fails and a kitten dies.
</p>
<h3>run</h3>
<p>
- There's more to asynchronous testing than just <em>waitFor</em> but <em>waitFor</em> will generally get you pretty far. Another common use-case is to wait for an expectation to be met, then do something else and wait for another expectation. In this case you can use <em>run</em> to insert yourself into foounit's asynchronous execution queue. Here is an example:
+ There's more to asynchronous testing than just <em>waitFor</em> but <em>waitFor</em> will generally get you pretty far. Another common use-case is to wait for an expectation to be met, then do something else and wait for another expectation. In this case you can use <em>run</em> to insert a block into foounit's asynchronous execution queue. Here is an example:
<pre class="code">
it('does a lot of async stuff', function (){
@@ -437,7 +437,7 @@ <h3>match</h3>
<a name="throwError"></a>
<h3>throwError</h3>
<p>
- Asserts that the a function throws an error. The error message can be matched against to assert that the correct error message was thrown.
+ Asserts that the a function throws an error. The error message can be matched with a regex to assert that the correct error message was thrown.
<pre class="code">
expect(function (){ throw new Error(); }).to(throwError); // passes
expect(function (){ throw new Error('HEY NOW'); }).to(throwError, /Fuuuuuu/); // fails

0 comments on commit 4bc3b5b

Please sign in to comment.