Compat Inspector User Guide

Use Compat Inspector to quickly identify which Internet Explorer platform changes affect your site.

  1. About
  2. Getting Started
  3. Verifying an Issue
  4. Debugging an Issue
  5. Identifying Frames
  6. JavaScript Libraries
  7. Last Steps

About

Compat Inspector is a JavaScript-based testing tool that analyzes your site while it runs. Compat Inspector reports patterns of interaction which can cause issues in recent modes. This allows you to identify problems quickly without memorizing a bunch of documentation or searching through the entirety of your site's code. The IE team developed Compat Inspector during the course of IE9 to speed up the process of recognizing common issues across different sites. Now you can use it too. Check out the Compat Inspector Test Drive to try it out before using it on your own site.

Compat Inspector is designed to help sites migrating to IE9 mode and up, not those running in legacy modes. You may still need to refer to documentation such as the Internet Explorer 9 Compatibility Cookbook and the Internet Explorer 10 Guide for Developers for some issues. The best pattern is to use Compat Inspector first, then fall back to documentation if nothing is found.

Getting Started

Run Compat Inspector by adding the following script before all other scripts on each page you want to test:

<script src="http://ie.microsoft.com/testdrive/HTML5/CompatInspector/inspector.js"></script>

Alternatively you can use Fiddler to automatically inject Compat Inspector on pages you visit by adding this snippet to your Fiddler Script. Then you can toggle Compat Inspector on and off from the "Rules" menu.

Screenshot of 'Use Compat Inspector' in the 'Rules' menu of Fiddler.

After you have the above script in place, open your page in IE9 or IE10. Compat Inspector will immediately start analyzing the page. Note that identification of some issues requires execution of the related code. So you should also explicitly test any interactions known to be working incorrectly.

Compat Inspector will keep a running total of messages associated with detected issues. A summary view in the upper right hand corner of the page displays the results:

A screenshot of the Compat Inspector summary view showing one error, one warning, and zero info messages.

Click on this view to expand it and obtain detailed information about each detected issue with links to relevant documentation:

A screenshot of the Compat Inspector details view. The view has three categories: "Messages", "Tests", and "Help". The "Messages" section is active. Within this section one warning and one error message are displayed. Each message contains two unchecked checkboxes labeled "Verify" and "Debug".

Most errors and warnings also provide two additional actions for further investigation: "Verify" and "Debug."

Verifying an Issue

Some test cases have built-in "verifiers" that emulate legacy behavior. This allows you to confirm the root cause of an issue before making any changes to your code.

Prerequisite: Compat Inspector is opened in the detailed information view and displaying an error or warning message containing a checkbox labeled "Verify."

  1. Click the "Verify" checkbox for the issue you want to confirm
    Another screenshot of a warning. This time the checkbox labeled "Verify" is checked.
  2. Refresh the page (You will see a notification indicating the verifier has been enabled)
    A screenshot of an informational message explaining that the issue is being verified. This message contains a single checkbox labeled "Verify" which is checked.
  3. Repeat the steps that originally triggered the error or warning
  4. If the issue still occurs
    1. If error or warning messages are still displayed, repeat steps 1-4 for each remaining message
    2. Otherwise, Compat Inspector cannot fully identify this issue. Refer to the Internet Explorer 9 Compatibility Cookbook and the Internet Explorer 10 Guide for Developers for additional help.
  5. Otherwise, you've identified the root cause of the issue
    1. Uncheck all "Verify" checkboxes
      Another screenshot of the informational message. This time the checkbox labeled "Verify" is unchecked.
    2. Refresh the page
    3. Follow the steps for debugging an issue below to locate the source of each message in your code
    4. Follow the instructions in the displayed error/warn messages to resolve the issue
    5. Note: Also look for any "if IE" checks controlling the execution of the problematic code. IE9 and up typically work best when given the same code as other modern browsers.

Debugging an Issue

Compat Inspector can also help you isolate where things went wrong via the "debug" feature.

Prerequisite: Compat Inspector is opened in the detailed information view and displaying an error or warning message containing a checkbox labeled "Debug."

  1. Click the "Debug" checkbox for the issue you want to investigate
    Another screenshot of a warning. This time the checkbox labeled "Debug" is checked.
  2. Open the F12 developer tools by pressing the F12 key
    A screenshot showing the initial view of the F12 tools.
  3. Switch to the "Script" tab
    A screenshot showing the "Script" tab as focused in the F12 tools.
  4. Click "Start debugging"
    A screenshot showing the "Start Debugging" button as focused in the F12 tools.
  5. Repeat the steps that originally triggered the error or warning (This will invoke the script debugger)
    A screenshot showing a snippet of JavaScript paused in the F12 tools. The code contains the JavaScript statement "debugger;" with a comment informing readers that the break point was triggered by Compat Inspector with instructions to look at the next item up in the call stack.
  6. Switch to the "Call stack" sub-tab located in the right half of the F12 developer tools
    A screenshot of the "Call stack" sub-tab of the "Script" tab in the F12 tools. The call stack contains two entries (from top to bottom): "inspectorFunction" and "JScript global code". The entry "inspectorFunction" is selected.
  7. Double-click the entry visually below the highlighted entry in the call stack
    Another screenshot of the "Call stack" sub-tab of the "Script" tab in the F12 tools. This time the entry "JScript global code" is selected.
  8. Look over at the left hand side of the F12 developer tools to see the code that triggered the error or warning
    A screenshot showing the JavaScript code: document.createElement("<div>").

Identifying Frames

Many pages embed frames, some from other sources. These frames also produce messages if you're using Fiddler to inject Compat Inspector. Compat Inspector helps you isolate which frame or frames triggered a message. Just click a message to open it in the "Details" view. The view will display an entry for each frame that triggered the message. Each entry will contain the URL of the frame plus scoped "Verify" and "Debug" options. Use the options to investigate issues only in the frames you care about.

A screenshot showing the 'Details' view of a message with a list of frame URLs below it.

JavaScript Libraries

One common problem is using out-of-date versions of JavaScript libraries. Compat Inspector helps here in two ways. First, it detects the presence of common libraries and reports the version in use. Second, it provides a "Verify" checkbox to substitute the latest version of the detected library. Using this you can quickly identify if an old version of a library is the root cause of an issue.

A screenshot showing a message indicating jQuery was detected. The message has a checkbox labeled 'Verify' which is checked.

Note: Substitution may not work if the library has been concatenated with other scripts.

Last Steps

Remove the Compat Inspector script from all your pages before publishing. Compat Inspector is a test tool and should not be used in production. After that keep an eye on the IE blog for update announcements.