doctest.js by Ian Bicking

In this example we'll access the Geonames API. First we'll want some routines to help us later on. You could put these into a separate .js file and include it, but often (especially in an example ;) it's best to be fully transparent and list all the routines out in the open...

$ apiLocation = 'http://ws.geonames.org/';
$ function query(endpoint, q) {
>   var url = apiLocation + endpoint;
>   jQuery.ajax({
>     url: url,
>     data: q,
>     dataType: "json",
>     success: Spy('success', {wait: true, ignoreThis: true}),
>     error: Spy('error')
>   });
> }

Some things to notice about this example:

• apiLocation is hard coded, but you could read it from the query string, allowing something like test.html?apiLocation=http://localhost:8080.
• We create a Spy for both success and failure, as we want to track both of these. We could just use functions, but mostly there's an advantage to being able to watch .called. If you used {writes: true} you might not need the .applies functions.
• wait can be called from anywhere. That means when you call this function doctest will wait until something is called, and will test all the output since that time (either the success or failure writeln()). Timeout is the other possibility.

$ query('postalCodeSearchJSON', {postalcode: 9011, maxRows: 5});
success({
  postalCodes: [
    {...}
  ]
}, ...)

What we do for JSON, we can also do for XML; in this case it's just fetching a static XML Atom document.

$.ajax({
  url: './.resources/example.xml',
  dataType: 'xml',
  success: function (doc) {
    gdoc = doc;
    writeln(repr(doc));
  },
  error: Spy('error')
});
wait(0.5);
/* =>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Example Feed</title>
  ...
</feed>
*/

You can also print jquery.Deferred (promise) objects once they've resolved, using the printResolved() function. This also implicitly calls wait() with the condition that all the promises be resolved. Both errors and resolved values are printed.

var def1 = $.Deferred();
var def2 = $.Deferred();
def1.resolve("Value 1!", "Value2!");
setTimeout(function () {
  def2.reject("sucka");
}, 500);
printResolved("def1", def1, "def2", def2);
// => def1 Value 1! Value2! def2 Error: sucka