Debugger

To help implement and maintain a robust UI, ACE provides the optional ACE Debugger and Debug Bar.

ACE Debugger tests a range of ACE implementation errors and some key HTML errors such as duplicate IDs or missing ALT text on images. The tool is designed to catch common errors which we have seen regularly in real world development. It complements but does not replace other code quality tools.

Debugging in the browser

The simplest way to use the Debugger is with the standalone bookmarklet in your web browser. Simply drag the button below into your bookmarks bar and then click it to add the debugger to the page you're viewing (or manually create a bookmarklet using the link below).

New Feature! ACE Debuggerdrag this onto your bookmarks bar!

Note you may need to accept security warnings in some browsers the first time you run this bookmarklet.

Debugging in your dev environment

For ongoing projects it is recommended that you run the Debugger automatically in your development and testing environments. This will show the debug bar at all times, confirming that the tool has been run.

It will show bright red when an error has been detected. There are controls to highlight errors, re-run the debugger or hide the bar (eg. to present a demo).

When you get errors, the best place to begin is with a review of the full error list.

Where possible there will be a jump link to take you to the affected element; otherwise there will be a message describing how to locate the element that triggered the error. The debugger can highlight problem elements so long as they remain visible in the page:

Invisible elements will still have an error ID applied to them, so you can inspect generated source and search for the ID.

Note that some errors will show more than once - for example all instances of duplicate IDs will generate an error.

Fixing one error may expose or create a related error, so always re-run the debugger after making changes. A common example is fixing a duplicate ID on a form input, which subsequently throws a missing label error if the label wasn't updated to match.

ID template strings

In some cases the markup will need to include templates with string replacement markers for the ID. To avoid throwing spurious duplicate ID errors, the debugger will ignore IDs wrapped in double square or curly braces:

<span id="prefix_[[template]]"></span>
<span id="prefix_{{template}}"></span>

Enable the debug bar

The debugger must be loaded, initialised and run once the DOM has been rendered and all DOM scripting is complete.

In virtual DOM applications, note the Debugger requires jQuery and it will need to be run again after each render cycle. It inspects the browser DOM, not the virtual DOM.

Load the following resource in the HEAD:

<link rel="stylesheet" href="dist/debug/ace-debug.css" media="all">

Load the JavaScript as late as possible in the document (must be called after jQuery, ACE and all other DOM scripts):

<script src="dist/debug/ace-debug.js"></script>
<script>
(function(ACEDEBUG){
  // setTimeout 0 used to help ensure debugger executes after other JS
  setTimeout(function() { 
    // required: init and run the debugger
    ACEDEBUG.init();
    ACEDEBUG.debug($('html'));
    // optional: automatically highlight errors inline
    ACEDEBUG.highlightErrors();
  },0);
})(window.ACEDEBUG);
</script>

It is highly recommended that you only load the debugger resources in dev and test environments. If there is any chance of the debugger leaking into production, add a location check to avoid calling the Debugger in production:

if ( document.location.hostname === 'dataroom.ansarada.dev' ) { 
  ACEDEBUG.init(); 
  ACEDEBUG.debug(); 
}

JavaScript methods

The Debugger can be called directly. This does mean it's possible to load the debug resources in an instance and call it manually; or call it from your SPA while it's in dev mode.

ACEDEBUG.init();

// default
ACEDEBUG.debug();

// scoped to a DOM context
var $appContext = $('#appcontext');
ACEDEBUG.debug(appContext);

ACEDEBUG.checkCCD();

ACEDEBUG.highlightErrors();

ACEDEBUG.clearErrors();

Logging results

The debugger writes each error to the browser console, and ACEDEBUG.debug() returns a stringified JSON object with a summary of results. Results are stringified due to some logging tools not being able to consume the object directly.

To use the results:

var results;
ACEDEBUG.init();
results = JSON.parse(ACEDEBUG.debug());
console.log(results.errorCount); // 0 means happy days

Example of results:

{ 
  "url": "http://localhost:8135/tests/debug-test.html", 
  "timestamp": "1479258410054", 
  "time": "Wed Nov 16 2016 12:06:50 GMT+1100 (AEDT)", 
  "browser": "chrome", 
  "browserVersion": "54.0.2840.98", 
  "os": "mac", 
  "aceVersion": "1.30.0", 
  "errorCount": "1", 
  "errors": { 
    "error-1": { 
      "message": "Element uses duplicate ID #foo. ID attributes must be unique in the DOM.", 
      "element": "<p id=\"foo\">foo1 </p>", 
      "hidden": "false" }
  },
  "exclusionCount": "2" 
}

Notes:

• Timestamp is provided in two formats to make life a little easier for humans.
• Browser information is determined via ACE.browser()
• aceVersion will usually be a SemVer number for a production release. In some cases it may contain a dev version like 201611150311-DEV, noting these versions should be considered unstable.
• errorCount will be 0 for an error-free page or a positive integer for a page with errors. Remember that this may not reflect the state of an updated DOM, particularly in SPAs. To ensure accuracy, call ACEDEBUG.debug() immediately before querying the results.
• Each error is self-contained with a timestamp and URL, to enable detailed logging.
• Exclusions are rare and cover some legacy code that could not be changed, plus some doc pages (documenting patterns sometimes requires technically invalid structures). In any new project, exclusions should not appear.

Errors

While most errors are self-explanatory, the following information is for those errors which may need more information.