The DevTools docs have moved! For the latest tutorials, docs and updates head over to the new home of Chrome DevTools.

Blackbox JavaScript Source Files

Like everyone, you get bugs in your application code. You start debugging, but when you step through your code line-by-line, the debugger sometimes jumps into a source file that's not your focus (such as a third-party JS library). I'm sure you've experienced the annoyance of stepping through the library code before getting back to your own application code.

Blackboxing gives you a first-class way to denote library (or other abstraction) code so that the debugger can route around it. When you blackbox a source file, the debugger will not jump into that file when stepping through code you're debugging.

The screenshot above shows that app.js opened, where a breakpoint was set. When stepping into that code, backbone.js opened, then underscore.js. This can be a time-consuming process and an undesirable one, too.

What happens when you blackbox a script?

  • Exceptions thrown from library code will not pause (if Pause on exceptions is enabled),
  • Stepping into/out/over bypasses the library code,
  • Event listener breakpoints don't break in library code,
  • The debugger will not pause on any breakpoints set in library code.

The end result is you are debugging your application code instead of third party resources.

How to blackbox scripts

There are two ways you can add scripts to the blackbox blacklist:

  1. Using the Settings panel
  2. Right-clicking on any script in the Sources panel

Settings panel

Use the Settings panel to configure blackboxed scripts. Open the DevTools Settings and under Sources click Manage framework blackboxing.

This will open up a dialog where you can input file names of scripts that you would like to add to the blacklist. You can do this a couple of ways:

  • enter the name of a file,
  • use regular expressions to target:
    • files that contain a specific name /backbone\.js$,
    • certain types of files like \.min\.js$
  • or enter in an entire folder that contains scripts you want to blackbox such as bower_components.

You may want to temporarily unblackbox a rule for testing purposes. You can do this by changing the behavior to Disabled. If you wanted to remove a rule entirely you can click X to delete it.

Context menus

To use the Settings panel for adding files to the blacklist, you can use the context menu when working in the Sources panel. When viewing a file you can right-click in the editor. And you can right-click on a file in the file navigator. From there choose Blackbox Script. This will add the file to the list in the Settings panel.

 

When you view a blackboxed script in the editor on the Sources panel, you will see a yellow bar indicating that it's blackboxed. Clicking on more expands the bar showing a bit more info about what it means, and how you can disable it.

When paused on a breakpoint, in the call stack you will see a message stating the number of frames which are blackboxed. You can show these frames if you want, but since they are calls made from a blackboxed script they are hidden unless you click show.

 

Conclusion

Blackboxing scripts can help increase your productivity and help keep your focus on the code you care about. It is easy to enable using any workflow and just as easy to disable if the need to do so arises.

We want to make sure your debugging experience when working with JS frameworks is excellent. Please file a ticket after trying blackboxing if you have ideas on how it can be improved or address your use cases better.