0
@@ -1,14 +1,14 @@
0
-Screw.Unit is a Behavior-Driven Testing Framework for Javascript written by Nathan Sobo and Nick Kallen. It features nested describes. Its goals are to provide:
0
+Screw.Unit is a Behavior-Driven Testing Framework for Javascript. It features nested describes. Its goals are to provide:
0
 
0
 * a DSL for elegant, readable, organized specs;
0
-* an interactive runner which can execute focused specs and describes; 
0
+* an interactive runner that can execute focused specs and describes; 
0
 * and brief, extensible source-code.
0
 
0
 # What it is
0
 
0
 ![Test Runner](http://s3.amazonaws.com/assets.pivotallabs.com/87/original/runner.png)
0
 
0
-The testing language is inspired by JSpec (and Rspec, obviously). Consider,
0
+The testing language is closure-based. Consider,
0
 
0
     describe("Matchers", function() {
0
       it("invokes the provided matcher on a call to expect", function() {
0
@@ -17,7 +17,7 @@ The testing language is inspired by JSpec (and Rspec, obviously). Consider,
0
       });
0
     });
0
 
0
-A key feature of Screw.Unit are nested `describes` and the cascading `before` behavior that entails:
0
+A key feature of Screw.Unit are nested `describes` and the cascading `before` (and `after`) behavior that entails:
0
 
0
     describe("a nested describe", function() {
0
       var invocations = [];
0
@@ -36,12 +36,213 @@ A key feature of Screw.Unit are nested `describes` and the cascading `before` be
0
         });
0
       });
0
     });
0
-    
0
+
0
+# The Runner
0
+
0
 The Screw.Unit runner is pretty fancy, supporting focused `describes` and focused `its`:
0
 
0
 ![Focused Runner](http://s3.amazonaws.com/assets.pivotallabs.com/86/original/focused.png)
0
 
0
-You can [download the source](http://github.com/nkallen/screw-unit/tree/master) from Github. Please see the included spec (`screwunit_spec.js`) to get up and running.
0
+Click on a `describe` or `it` to run just those tests.
0
+
0
+# Global Befores and Afters
0
+
0
+A global `before` is a `before` block run before all tests in a test suite, regardless of their nesting. This is often useful to reset global variables, or blank-out DOM nodes before each test is run. Put this at the top of the your suite file or in your spec helper.
0
+
0
+    Screw.Unit(function() {
0
+      before(function() { ... });
0
+    });
0
+    
0
+Note that you can have any number of `Screw.Unit(...)` blocks in one file. Thus, you can have multiple global `befores` and `afters`.
0
+
0
+# Custom Matchers
0
+
0
+A custom matcher is a custom assertion specifically tailored to your application. These are helpful in increasing the readability and declarativity of your tests. To create a custom matcher, fill in the blanks for this code:
0
+
0
+    Screw.Matchers["be_even"] = {
0
+      match: function(expected, actual) {
0
+        return actual % 2 == 0;
0
+      },
0
+      failure_message: function(expected, actual, not) {
0
+        return 'expected ' + $.print(actual) + (not ? ' not' : '') + ' to be even';
0
+      }
0
+    }
0
+
0
+You can invoke this matcher as follows: `expect(2).to(be_even)`.
0
+
0
+# The Anatomy of Test Infrastructure
0
+
0
+Typical test infrastructure spans multiple files:
0
+
0
+* A `suite.html` file that has the necessary html, script tags, and link tags, to include your source code as well as the test infrastructure.
0
+* A `spec_helper.js` file with global `before` and `after` blocks.
0
+* A set of custom matchers.
0
+* Your individual tests.
0
+
0
+The file structure will typically look like:
0
+
0
+    spec/
0
+      suite.html
0
+      spec_helper.js
0
+      matchers/
0
+        a_matcher.js
0
+        another_matcher.js
0
+      models/
0
+        a_spec.js
0
+        another_spec.js
0
+      views/
0
+        yet_another_spec.js
0
+
0
+The `models` and `views` directories are here only for comparison. As a general rule, mirror the file structure of your source code in your spec directory. For example, if you have an MVC application and you organize your source code into `models`, `views`, and `controllers` directories, have parallel directories in your spec/ directory, with tests for your models, views, and controllers in their respective directories.
0
+
0
+# Writing Good Tests
0
+
0
+A great test maximizes these features:
0
+
0
+* it provides **documentation**, explaining the intended functioning of the system as well as how the source code works;
0
+* it supports **ongoing development**, as you bit-by-bit write a failing test and make it pass;
0
+* it supports **refactoring** and **prevents regression**;
0
+* and it **requires little modification** as the implementation of the system changes, especially changes to unrelated code.
0
+
0
+This section focuses principally on tests as documentation. **To provide documentation, as well as support future modification, a test should be readable and well organized.** Here are some recommendations on how to do it.
0
+
0
+## Use Nested Describes to Express Context
0
+
0
+Often, when you test a system (a function, an object), it behaves differently in different contexts. Use **nested** describes liberally to express the context under which you make an assertion.
0
+
0
+    describe("Caller#prioritize", function() {
0
+      describe("when there are two callers in the queue", function() {
0
+        describe("and one caller has been waiting longer than another", function() {
0
+          ...
0
+        });
0
+      });
0
+    });
0
+
0
+In addition to using nested describes to express context, use them to organize tests by the structural properties of your source code and programming language. In Javascript this is typically prototype and function. A parent describe for a prototype contains nested describes for each of its methods. If you have cross-cutting concerns (e.g., related behavior that spans across methods or prototypes), use a describe to group them conceptually.
0
+
0
+    describe("Car", function() {
0
+      describe("#start", function() {
0
+      });
0
+      
0
+      describe("#stop", function() {
0
+      });
0
+      
0
+      describe("callbacks", function() {
0
+        describe("after_purchase", function() {
0
+        });
0
+      });
0
+      
0
+      describe("logging", function() {
0
+      });
0
+    });
0
+
0
+In this example, one parent `describe` is used for all `Car` behavior. There is a describe for each method. Finally, cross-cutting concerns like callbacks and logging are grouped because of their conceptual affinity.
0
+
0
+# Test Size
0
+
0
+Individual tests should be short and sweet. It is sometimes recommended to make only one assertion per test:
0
+
0
+    it("chooses the caller who has been waiting the longest", function() {
0
+      expect(Caller.prioritize()).to(equal, caller_waiting_the_longest);
0
+    });
0
+
0
+According to some, the ideal test is one line of code. In practice, it may be excessive to divide your tests to be this small. At ten lines of code (or more), a test is difficult to read quickly. Be pragmatic, bearing in mind the aims of testing.
0
+
0
+Although one assertion per test is a good rule of thumb, feel free to violate the rule if equal clarity and better terseness is achievable:
0
+
0
+    it("returns the string representation of the boolean", function() {
0
+      expect($.print(true)).to(equal, 'true');
0
+      expect($.print(false)).to(equal, 'false');
0
+    });
0
+
0
+Two tests would be overkill in this example.
0
+
0
+## Variable Naming
0
+
0
+Name variables descriptively, especially ones that will become expected values in assertions. `caller_waiting_the_longest` is better than `c1`.
0
+
0
+## Dividing code between tests and `befores`
0
+
0
+If there is only one line of setup and it is used in only one test, it may be better to include the setup in the test itself:
0
+
0
+    it("decrements the man's luck by 5", function() {
0
+      var man = new Man({luck: 5});
0
+      
0
+      cat.cross_path(man);
0
+      expect(man.luck()).to(equal, 0);
0
+    });
0
+
0
+But in general, it's nice to keep setup code in `before` blocks, especially if the setup can be shared across tests.
0
+
0
+    describe('Man', function() {
0
+      var man;
0
+      before(function() {
0
+        man = new Man({luck: 5});
0
+      });
0
+  
0
+      describe('#decrement_luck', function() {
0
+        it("decrements the luck field by the given amount", function() {
0
+          man.decrement_luck(3);
0
+          expect(man.luck()).to(equal, 2)
0
+        });
0
+      });
0
+      ...
0
+    });
0
+
0
+## Preconditions
0
+
0
+It is ideal, if there is any chance that your preconditions are non-obvious, to make precondition asserts in your test. The last example, were it more complicated, might be better written:
0
+
0
+    it("decrements the luck field by the given amount", function() {
0
+      expect(man.luck()).to(equal, 5);
0
+
0
+      man.decrement_luck(3);
0
+      expect(man.luck()).to(equal, 2)
0
+    });
0
+
0
+Whitespace, as seen here, can be helpful in distinguishing setup and preconditions from the system under test (SUT) and its assertions. It is nice to be consistent in your use of whitespace (e.g., "always follow a group of preconditions by a newline"). But it is better to use whitespace as makes the most sense given the context. As with everything in life, do it consciously and deliberately, but change your mind frequently.
0
+
0
+## Behavioral Testing
0
+
0
+Behavioral testing, that is, asserting that certain functions are called rather than certain values returned, is best done with closures. The dynamic nature of JavaScript makes mocking frameworks mostly unnecessary.
0
+
0
+    it("invokes #decrement_luck", function() {
0
+      var decrement_luck_was_called = false;
0
+      man.decrement_luck = function(amount) {
0
+        decrement_luck_was_called = true;
0
+      });
0
+      
0
+      cat.cross_path(man);
0
+      expect(decrement_luck_was_called).to(equal, true);
0
+    });
0
+
0
+# How to Test the DOM
0
+
0
+The simplest way to test the DOM is to have a special DOM node in your `suite.html` file. Have all tests insert nodes into this node; have a global `before` reset the node between tests.
0
+
0
+In `suite.html`:
0
+
0
+    <div id="dom_test"></div>
0
+
0
+In `spec_helper.js`:
0
+
0
+    Screw.Unit(function() {
0
+      before(function() {
0
+        document.getElementById('dom_test').innerHTML = ''; // but use your favorite JS library here.
0
+      });
0
+    });
0
+    
0
+In `some_spec.js`:
0
+
0
+    describe("something that manipulates the DOM", function() {
0
+      it("is effortless to test!", function() {
0
+        var dom_test = document.getElementById('dom_test');
0
+        dom_test.innerHTML = 'awesome';
0
+        expect(dom_test.innerHTML).to(equal, 'awesome');
0
+      });
0
+    });
0
+
0
+A Javascript library like jQuery, Prototype, or YUI is a essential for testing events.
0
 
0
 # Implementation Details
0
 
0
@@ -75,22 +276,6 @@ Bind behaviors by passing a hash (see the previous example). Using CSS3 selector
0
     $('.describe, .it').fn({...}); // applies to both describe and its
0
     $('.describe .describe').fn({...}); // applies to nested describes only
0
 
0
-A typical Concrete Javascript Application is divided into 4 aspects:
0
-
0
-* a DOM data model,
0
-* CSS bound to DOM elements,
0
-* asynchronous events bound to DOM elements (`click`, `mouseover`), etc.,
0
-* synchronous behaviors bound to DOM elements (`run` and `parent` in the above example).
0
-
0
-The Concrete style is particularly well-suited to Screw.Unit; to add the ability to run a focused spec, we simply bind a click event to an `it` or a `describe`, which runs itself:
0
-
0
-    $('.describe, .it')
0
-      .click(function() {
0
-        $(this).fn('run');
0
-      })
0
-
0
-Anyway, more details about Effen / Concrete Javascript in a later post.
0
-
0
 # Extensibility
0
 
0
 Screw.Unit is designed from the ground-up to be extensible. For example, to add custom logging, simply subscribe to certain events:
0
@@ -101,7 +286,22 @@ Screw.Unit is designed from the ground-up to be extensible. For example, to add
0
       .bind('passed', function() {...})
0
       .bind('failed', function(e, reason) {...})
0
 
0
+There are also events for the `loading` and `loaded` test code code, as well as just `before` and just `after` all tests are run:
0
+
0
+  $(Screw)
0
+    .bind('loading', function() {...})
0
+    .bind('loaded', function() {...})
0
+    .bind('before', function() {...})
0
+    .bind('after', function() {...})
0
+
0
+# Download
0
+
0
+You can [download the source](http://github.com/nkallen/screw-unit/tree/master) from Github. There is are plenty of examples in the distribution.
0
+
0
 # Thanks to
0
 
0
 * Nathan Sobo
0
-* Yehuda Katz
0
\ No newline at end of file
0
+* Yehuda Katz
0
+* Brian Takita
0
+* Aman Gupta
0
+* Tim Connor
0
\ No newline at end of file

0
@@ -1,5 +1,5 @@
0
 (function($) {
0
-  $(Screw).bind('load', function() {
0
+  $(Screw).bind('loaded', function() {
0
     $('.status').fn({
0
       display: function() {
0
         $(this).text(

0
@@ -18,13 +18,12 @@ var Screw = (function($) {
0
       context: [],
0
 
0
       describe: function(name, fn) {
0
-        var describe = $('<li class="describe">');
0
-        describe.append('<h1>' + name + '</h1>');
0
-        describe
0
+        var describe = $('<li class="describe">')
0
+          .append($('<h1>').text(name))
0
           .append('<ol class="befores">')
0
           .append('<ul class="its">')
0
           .append('<ul class="describes">')
0
-          .append('<ol class="afters">')
0
+          .append('<ol class="afters">');
0
 
0
         this.context.push(describe);
0
         fn.call();
0
@@ -36,9 +35,9 @@ var Screw = (function($) {
0
       },
0
 
0
       it: function(name, fn) {
0
-        var it = $('<li class="it">');
0
-        it.append('<h2>' + name + '</h2>')
0
-        it.data('screwunit.run', fn);
0
+        var it = $('<li class="it">')
0
+          .append($('<h2>').text(name))
0
+          .data('screwunit.run', fn);
0
 
0
         this.context[this.context.length-1]
0
           .children('.its')
0
@@ -75,7 +74,7 @@ var Screw = (function($) {
0
       .appendTo('body');
0
 
0
     $(screw).dequeue();
0
-    $(screw).trigger('load');
0
+    $(screw).trigger('loaded');
0
   });
0
   return screw;
0
 })(jQuery);
0
\ No newline at end of file

0
@@ -4,90 +4,87 @@ html {
0
   background: #EDEBD5;
0
 }
0
 
0
-li {
0
-  list-style-type: none;
0
-}
0
-
0
-.focused {
0
-  background-color: #F4F2E4;
0
-}
0
-
0
-.focused * {
0
-  opacity: 1.0;
0
-}
0
-
0
-h1, h2, p {
0
-  opacity: 0.4;
0
-}
0
-
0
-.describes {
0
-  padding-left: 0;
0
-}
0
-
0
-.describes h1 {
0
-  font-size: 1.1em;
0
-  color: #877C21;
0
-  line-height: 1.8em;
0
-  margin: 0pt 0pt 0.6em;
0
-  border-bottom: 1px solid transparent;
0
-}
0
-
0
-.describes h1:hover {
0
-  cursor: pointer;
0
-  color: #000;
0
-  background-color: #F4F2E4;
0
-  border-bottom: 1px solid #9A8E51;
0
-}
0
-
0
-.describes .describe {
0
-  margin-left: 0.6em;
0
-  padding-left: 0.6em;
0
-  border: 1px dashed grey;
0
-}
0
-
0
-.describes .describe .its {}
0
-
0
-.describes .describe .its .it {
0
-  list-style-type: lower-roman;
0
-  list-style-position: outside;
0
-}
0
-
0
-.describes .describe .its .it h2 {
0
-  font-weight: normal;
0
-  font-style: italic;
0
-  padding-left: 0.5em;
0
-}
0
-
0
-.describes .describe .its .it.enqueued h2 {
0
-  background-color: #CC6600;
0
-  color: white !important;
0
-}
0
-
0
-.describes .describe .its .it.passed h2 {
0
-  background-color: #5A753D;
0
-  color: white !important;
0
-}
0
-
0
-.describes .describe .its .it.failed h2 {
0
-  background-color: #993300;
0
-  color: white !important;
0
-}
0
-
0
-.describes .describe .its .it.failed p {
0
-  margin-left: 1em;
0
-  color: #993300;
0
-}
0
-
0
-.describes .describe .its .it h2 {
0
-  font-size: 1.0em;
0
-  color: #877C21;
0
-  line-height: 1.8em;
0
-  margin: 0 0 0.5em;
0
-  border-bottom: 1px solid transparent;
0
-}
0
-
0
-.describes .describe .its .it h2:hover {
0
-  cursor: pointer;
0
-  color: #000;
0
-  border-bottom: 1px solid #9A8E51;
0
-}
0
\ No newline at end of file
0
+  li {
0
+    list-style-type: none;
0
+  }
0
+
0
+  .focused {
0
+    background-color: #F4F2E4;
0
+  }
0
+
0
+    .focused * {
0
+      opacity: 1.0;
0
+    }
0
+
0
+  h1, h2, p {
0
+    opacity: 0.4;
0
+  }
0
+
0
+  .describes {
0
+    padding-left: 0;
0
+  }
0
+
0
+    .describes h1 {
0
+      font-size: 1.1em;
0
+      color: #877C21;
0
+      line-height: 1.8em;
0
+      margin: 0pt 0pt 0.6em;
0
+      border-bottom: 1px solid transparent;
0
+    }
0
+
0
+      .describes h1:hover {
0
+        cursor: pointer;
0
+        color: #000;
0
+        background-color: #F4F2E4;
0
+        border-bottom: 1px solid #9A8E51;
0
+      }
0
+
0
+    .describes .describe {
0
+      margin-left: 0.6em;
0
+      padding-left: 0.6em;
0
+      border: 1px dashed grey;
0
+    }
0
+
0
+      .describes .describe .its {}
0
+
0
+        .describes .describe .its .it {
0
+          list-style-type: lower-roman;
0
+          list-style-position: outside;
0
+        }
0
+
0
+          .describes .describe .its .it h2 {
0
+            font-weight: normal;
0
+            font-style: italic;
0
+            padding-left: 0.5em;
0
+            font-size: 1.0em;
0
+            color: #877C21;
0
+            line-height: 1.8em;
0
+            margin: 0 0 0.5em;
0
+            border-bottom: 1px solid transparent;
0
+          }
0
+          
0
+          .describes .describe .its .it.enqueued h2 {
0
+            background-color: #CC6600;
0
+            color: white !important;
0
+          }
0
+
0
+          .describes .describe .its .it.passed h2 {
0
+            background-color: #5A753D;
0
+            color: white !important;
0
+          }
0
+
0
+          .describes .describe .its .it.failed h2 {
0
+            background-color: #993300;
0
+            color: white !important;
0
+          }
0
+
0
+          .describes .describe .its .it.failed p {
0
+            margin-left: 1em;
0
+            color: #993300;
0
+          }
0
+          
0
+          .describes .describe .its .it h2:hover {
0
+            cursor: pointer;
0
+            color: #000 !important;
0
+            border-bottom: 1px solid #9A8E51;
0
+          }
0
\ No newline at end of file

0
@@ -1,6 +1,6 @@
0
 (function($) {
0
   $(Screw)
0
-    .bind('load', function() {    
0
+    .bind('loaded', function() {    
0
       $('.describe, .it')
0
         .click(function() {
0
           document.location = location.href.split('?')[0] + '?' + $(this).fn('selector');
0
@@ -24,10 +24,9 @@
0
           $(this).addClass('passed');
0
         })
0
         .bind('failed', function(e, reason) {
0
-          $(this).addClass('failed');
0
-          $('<p class="error">')
0
-            .text(reason.toString())
0
-            .appendTo($(this));
0
+          $(this)
0
+            .addClass('failed')
0
+            .append($('<p class="error">').text(reason.toString()));
0
         })
0
     })
0
     .bind('before', function() {

0
@@ -12,7 +12,7 @@
0
     <script src="matchers_spec.js"></script>
0
     <script src="print_spec.js"></script>
0
 
0
-  	<link rel="stylesheet" href="../lib/screw.css">
0
+    <link rel="stylesheet" href="../lib/screw.css">
0
   </head>
0
   <body></body>
0
 </html>
0
\ No newline at end of file