gitter-badger / ddt

DDT

Devious Debugging Tool

DDT is a way to add debugging to your Javascript code that can be monitored at will by any developer. It acts as a proxy for the standard browser console.

The goal of DDT is make it possible to debug specific parts of Javascript without having to commit (and later remove!) console.log statements from production source code. The developer is able to simply monitor for messages from specific components when debugging is required.

Example

There is a custom upload tool that keeps sending strange filenames and a developer is tasked with debugging the uploader to see where the error is. One option would be to add a debugging statement like this:

if (window.developer_mode) {
    console.log('Uploader was given this filename:', filename);
}

This is fine, but another developer is working on phone number validation and wants to debug the country changes. So she adds a similar statement:

if (window.developer_mode) {
    console.log('Country changed to ', country, ' with phone format ', phone_format);
}

Now both developers are seeing both debugging statements. Either the developers have to remove these statements when their task is complete, or with enough time, the browser console will be so cluttered with messages that it becomes useless.

DDT makes this easier by adding a namespace all console calls as the first argument:

ddt.log('Uploader', 'Filename changed to:', filename);

Note that namespaces are not case sensitive. The namespace from the message call is always displayed. All other operations normalize the namespace to lowercase.

There are just two changes here: using ddt.log instead of console.log and making the first argument the namespace. Once the namespace is applied, any developer can choose to watch that namespace for messages by calling DDT from the console:

> ddt.watch('uploader');
true

This can be verified by using the watching command:

> ddt.watching();
["uploader"]

Now every time a message in the "Uploader" namespace is sent, it will be displayed to this developer in the console:

[Uploader] Filename changed to: "pic01.jpg"

When the developer is done working on the uploader, he simply does an unwatch:

ddt.unwatch('uploader');

The same process can be used by creating a "PhoneDebug" namespace, or any other name that a developer chooses.

A list of all available channels can be fetched by using the channels command. This can also be used to watch all the channels on the page:

> ddt.channels();
["ddt", "uploader"]
> ddt.watch(ddt.channels());
true

Also note that internal debugging is done using the "DDT" namespace, which can be monitored at any time:

> ddt.watch('ddt');
true

Usage

The console proxies that DDT supports are: log, info, warn, error, and trace. All of these, except for trace, are direct proxies to the equivalent console command. The trace command will execute a log call followed by a trace call.

When executed on a page with iframes, DDT will attempt to use postMessage to sync the current watching list between frames. When executed inside an iframe, the sync will also travel outwards to parent windows. This feature is only available in browsers that have postMessage and JSON support!

DDT is also designed to sync your watching preferences between multiple domains by using cross-domain cookies generated by requesting an image URL from each of the separate domains.

Configuration

DDT provides the following options, all of which need to be in sync with the server:

• config.cookie is the string that names the browser cookie
• config.domains is an array that lists all of the domains you want to use
• config.server is the string that names the path to the gif server

NOTE: these config options must be in sync with the server for cookies to be accessible on both the client and the server!

To use these options, define window.ddt.config before loading DDT:

<script>
window.ddt = {
    config: {
        cookie: "oohshiny",
        domains: ["example.com", "localhost"],
        server: "/shiny/?channels="
    }
};
</script>
<script src="ddt.js"></script>

Licenses

DDT was created by deviantART. Please check the LICENSES.txt file for full details on the licensing.