node package manager


literate-jasmine Build Status


var PI;


PI = 22/7;

add can add numbers

var a = 1,
    b = 2;

expect(a + b).toBe(3);

can divide numbers

var a = 6,
    b = 2;

And a comment here doesn't break things:


calculates the circumference of a circle

Note that we reference the variable PI below that is defined in the code block at the top of this describe (so right under "Mathematics").

var circumference = function(radius) {
  return 2 * PI * radius;

expect(circumference(5)).toBe(2 * 22/7 * 5);


appending works with +

var text = "abc";

expect(text + "d").toBe("abcd");


works with done

setTimeout(function() {
}, 50);

The file you are currently reading has a markdown structure (which includes the main header above and the other parts below) that is parsed into a tree:

  • literate-jasmine
    • Mathematices
      • add can add numbers (level 3 header)
      • add can add numbers
      • calculates the circumference of a circle
    • Strings
      • appending works with +
    • Asynchronous
      • works with done

Which is then uses the Jasmine describe, it and beforeEach to setup the tests and then run them.

Note that there is a convention -- a hard rule that there will be a top header (top describe), one or more headers below that (describes) and one or more header below each of those (it blocks).*

screen shot of convention

This hard limitation makes sense:

  • forces documentation to be simple
  • nested describes indicate that extracted some code to helper functions is probably a sensible solution instead of adding more nesting
  • easier to parse both as a human and as a computer
  • keeps everything simple


screen shot of running literate-jasmine on this

(If you're working on this project, run ./bin/literate-jasmine instead.)

Take a close look at how scope works for globals. In the Mathematics section below, we reference PI to reset it as a beforeEach so every test has PI reset to the correct value. The actual declaration of PI as a variable happens on the fourth line of this README. The root describe treats any code blocks after it as global setup.