The following is an excerpt of ScrewUnit's new copious documentation:

Writing Good Tests

A great test maximizes these features:

• it provides documentation, explaining the intended functioning of the system as well as how the source code works;
• it supports ongoing development, as you bit-by-bit write a failing test and make it pass;
• it supports later refactorings and prevents regression as you add other features;
• and it requires little modification as the implementation of the system changes, especially changes to unrelated code.

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 just that.

Use Nested Describes to Express Context

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.

describe("Caller#prioritize", function() {
  describe("when there are two callers in the queue", function() {
    describe("and one caller has been waiting longer than another", function() {
      ...
    });
  });
});

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.

describe("Car", function() {
  describe("#start", function() {
  });

  describe("#stop", function() {
  });

  describe("callbacks", function() {
    describe("after_purchase", function() {
    });
  });

  describe("logging", function() {
  });
});

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.

Test Size

Individual tests should be short and sweet. It is sometimes recommended to make only one assertion per test:

it("chooses the caller who has been waiting the longest", function() {
  expect(Caller.prioritize()).to(equal, caller_waiting_the_longest);
});

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.

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:

it("returns the string representation of the boolean", function() {
  expect($.print(true)).to(equal, 'true');
  expect($.print(false)).to(equal, 'false');
});

Two tests would be overkill in this example.

Variable Naming

Name variables descriptively, especially ones that will become expected values in assertions. caller_waiting_the_longest is better than c1.

Dividing code between tests and befores

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:

it("decrements the man's luck by 5", function() {
  var man = new Man({luck: 5});

  cat.cross_path(man);
  expect(man.luck()).to(equal, 0);
});

But in general, it's nice to keep setup code in before blocks, especially if the setup can be shared across tests.

describe('Man', function() {
  var man;
  before(function() {
    man = new Man({luck: 5});
  });

  describe('#decrement_luck', function() {
    it("decrements the luck field by the given amount", function() {
      man.decrement_luck(3);
      expect(man.luck()).to(equal, 2)
    });
  });
  ...

});

Preconditions

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:

it("decrements the luck field by the given amount", function() {
  expect(man.luck()).to(equal, 5);

  man.decrement_luck(3);
  expect(man.luck()).to(equal, 2)
});

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.

Behavioral Testing

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.

it("invokes #decrement_luck", function() {
  var decrement_luck_was_called = false;
  man.decrement_luck = function(amount) {
    decrement_luck_was_called = true;
  });

  cat.cross_path(man);
  expect(decrement_luck_was_called).to(equal, true);
});

Extensive Documentation for ScrewUnit is now available. Download it here:

http://github.com/nkallen/screw-unit/tree/master

One of The Blabs' most controversial articles was Lovely Demeter, Meter Maid, in which Pivotal and Thoughtworks battle over which Agile consultancy has the better understanding of the Law of Demeter, and which has better hair and music taste (seriously).

I have never found this "law" very persuasive.

• The bizarre, culturally loaded analogy about a paperboy and a wallet says nothing insightful about encapsulation boundaries as they arise in real software systems.
• The blogosphere's endless scholastic hermeneutics of the law's 4 allowances for message sending is a masturbatory philosophical enterprise with nothing relevant to real-world software.
• The Mockist's insistence on easy mockability is of dubious merit--build better mocking frameworks!
• And the few practical, real merits that arise in from following the Law of Demeter are better arrived at using other techniques, such as "Tell, Don't Ask".

Here Are Two Examples, one where I violate the Law of Demeter, and another where I don't.

I wrote this code recently, in flagrant violation of the Law:

cookies[:store_id] = @login.store.id

Suppose @login is not an ActiveRecord object, it does not automatically have a #store_id method. Should I create a delegator for this?

class Login
  def store_id
    store.id
  end
end

This is pretty silly. The store_id is not an attribute of the login; rather it's an attribute of the store, and the store is an attribute of the login. The delegator is needless code cruft to replace a dot with an underscore, it smells of the endless boilerplate Java code of my youth. Demeter be damned.

On the other hand, here is a refactoring I did, incidentally complying with the law of Demeter:

Here is the original, Demeter-violating code:

def find_attribute_given_name(name)
  attributes.detect { |a| a.name_or_alias == name }
end

The call to == here is the violation of Demeter. I later replaced this with:

attributes.detect { |a| a.named?(name) }

The latter complies with the "law". And it's much better code. But was I lead to the improvement to this by Demeter? No, I was lead to it by a better understanding of the encapsulation boundaries of the object (#name_or_alias became private) and by a desire to have my code be more terse and clear. a.named?(name) is the most terse explanation of the intended computation that I can think of.

Demeter be damned.

Screw.Unit 0.3 is now available. I'm skipping 0.2 since there have been two milestones worth of additions to the new version of Screw.Unit. New features:

• test suite functionality
• afters
• global befores and afters
• enhanced error messages
• new matchers

Here's how to do a global before:

Screw.Unit(function() {
  before(function() {
    $("#screw_unit_content").html("");
    ActiveAjaxRequests.length = 0;
    PainPoint.instances = [];
    delete window._token;
  });
});

Put this, for instance, in your spec_helper.js file.

Here is how to manage a suite:

Have a suite.html file that requires the Screw.Unit source, your spec helper, and your various test files.

<html>
  <head>
    <script src="../lib/jquery-1.2.3.js"></script>
    <script src="../lib/jquery.fn.js"></script>
    <script src="../lib/jquery.print.js"></script>
    <script src="../lib/screw.builder.js"></script>
    <script src="../lib/screw.matchers.js"></script>
    <script src="../lib/screw.events.js"></script>
    <script src="../lib/screw.behaviors.js"></script>
    <script src="spec_helper.js"></script> <!-- SPEC HELPER -->
    <script src="behaviors_spec.js"></script><!-- A SPEC -->
    <script src="matchers_spec.js"></script> <!-- ANOTHER SPEC -->
    <link rel="stylesheet" href="../lib/screw.css">
    </head>
    <body></body>
  </html>

Have a test file (for example, matchers_spec.js):

Screw.Unit(function() {
  var global_before_invoked = false;
  before(function() { global_before_invoked = true });

  describe('Behaviors', function() {
    describe('#run', function() {
      describe("a simple [describe]", function() {
        it("invokes the global [before] before an [it]", function() {
          expect(global_before_invoked).to(equal, true);
        });
  ...
});

Extra Powerful Matchers

// hash equality
expect({a: 'b', c: 'd'}).to(equal, {a: 'b', c: 'd'});

// recursive array equality
expect([{a: 'b'}, {c: 'd'}]).to(equal, [{a: 'b'}, {c: 'd'}]);

// regular expressions and string inclusion
expect("The wheels of the bus").to(match, /bus/);
expect("The wheels of the bus").to(match, "wheels");

// array emptiness:
expect([]).to(be_empty);
expect([1]).to_not(be_empty);

Thanks To

• Brian Takita for the ideas and much of the implementation.