Implementation for new language features (NLF) are often intrusive and affect many parts of V8. This sometimes causes the debugger to not work seamlessly with the NLF out of the box. We generally make the distinction between Basic functionality and Extended functionality when talking about debugger support:
Proxy trap handler should be possible.Promises.This document attempts to list all relevant aspects of V8’s JavaScript debugger that constitute basic functionality (checkout this document for V8's WebAssembly debugger features). Items on the list may not apply to every language feature, depending on its nature.
DevTools offers a REPL through the Console panel. Logging a value should print reasonable output.
All NLFs that affect how values should be printed in a REPL, such as NLFs that introduce new primitives, new RegExp flags, etc.
Open DevTools, select the Console panel, and enter a source snippet with the NLF. The printed result should look alright.
Example CL that adds printing support for a new RegExp flag
DevTools provides syntax highlighting and pretty-printing for JavaScript sources.
All NLFs that introduce new syntax.
Open DevTools, select the Sources panel, and create a new source snippet with the NLF. The syntax highlighting of the source should look alright. This is handled by CodeMirror inside of Chromium DevTools.
Clicking on the pretty-printing button on the bottom left (“{}”) should yield reasonable results. The formatting relies on the acorn parser, which needs to support the NLF in question for this to work.
Stack traces is the most often used way for developers to debug issues. Aside from the default Error.stack string, we also offer a way for user code to override how to format the stack property, and collect a more detailed structured stack trace for DevTools.
Sometimes, due to the way a feature is implemented, there may be stack frames that show up on the stack trace when they should not, or vice versa.
For runtime exceptions, we look for the closest code position that has a source position attached. That source position is used as expression position for the exception. For syntax errors, we should report the correct location of the syntax error via MessageHandler::ReportMessage().
Note that Error.stack is only collected for Error objects, at the time the Error object is constructed. This may be different than the stack trace passed to DevTools via JSMessageObject.
NLFs that can cause an exception to be thrown, or can call into another function that throws.
When throwing inside the NLF, or with it on the stack, the stack trace including source positions should make sense. Also check the structured stack trace when the exception is not caught and logged into Chrome's DevTools console.
Repeat with the “Disable async stack traces” checkbox in the Preferences checked.
Test cases for stack traces is mandatory, if there is any way the NLF can interact with throwing exceptions. For examples look for mjsunit tests with stack-trace in their names.
Design doc for debugging support for tail-calls
DevTools offers a way to show async stack traces by stitching together stack traces collected at the location where the callback is passed, and the actual location of the exception inside the callback.
The canonical example of this is throwing inside a setTimeout callback. The async stack trace will consist of the stack trace of the error plus a stack trace captured at the setTimeout call-site.
The instrumentation is based on four ayncTask* methods. Namely asyncTaskScheduled, asyncTaskStarted, asyncTaskFinished and asyncTaskCancelled. V8 has a higher-level interface that translates Promise events (such as await, .then, etc) to these for asyncTask* methods.
NLFs touching promises or callback scheduling.
Throw or pause inside a new language feature and check either the call stack sidebar panel in “Sources” or use a console.trace and check the async stack trace in the console.
Test cases for async stack traces are mandatory, if there is any way the NLF interacts with callback scheduling or Promises. For examples look in V8 inspector tests with async-stack in their name (e.g. here).
Aside from offering stack traces, V8‘s debugger supports DevTools’ pause-on-exception feature. This comes in two flavors: pause on all exceptions, and pause on uncaught exceptions. In both cases, we break at the throw site (not at the catch, or any rethrow via try-finally).
For the former, this is as easy as breaking in the debugger on Isolate::Throw(). For the latter, we have to predict whether the thrown exception will be caught or otherwise handled (for example by a Promise's catch handler).
NLFs that can cause an exception to be thrown, or can call into another function that throws.
When pause-on-exception is enabled, and throwing inside the NLF or with it on the stack, the script should pause as expected.
Repeat with the “pause on caught exception” checkbox checked.
Test cases for exception prediction is mandatory, if there is any way the NLF can interact with exceptions, be it by throwing exceptions, or by relying on try-catch or try-finally in its implementation. Look for mjsunit tests that contain the string setBreakOnException or setBreakOnUncaughtException.
Design doc for exception prediction for async-await
One of the most important features is setting break points. The semantics should be obvious.
Break locations are function calls, return sites, and statements. Special care are necessary for loops: for example, in for-loops we do want to be able to break separately at the loop entry, condition evaluation, and increment.
When setting a break point at an arbitrary source position, we actually check for the closest breakable source position, and move the break point there. Consecutive debug break events at the same source position are ignored by the debugger.
NLFs that change generated code, and especially once that introduce new break locations.
Open DevTools and set break points in parts of script related to the NLF, then run the script.
Look for mjsunit tests with debug-break in their names.
Stepping is the logical consequence to breakpoints, and is based on the same mechanism in the debugger. We differentiate between
NLFs that are affect breakpoints
Break inside the part of script related to the NLF, and try stepping in, next, and out.
Look for mjsunit tests with debug-step in their names.
Design doc on stepping in async-await
The frame inspector in V8 offers a way to a way to introspect frames on the call stack at the debug break. For the top-most frame, the break location is that of the debug break. For frames below the break location is the call site leading to the frame above.
For each frame, we can
For optimized code, we use the deoptimizer to get hold of receiver, arguments and stack locals, but this is often not possible, and we get the optimzed_out sentinel value.
NLFs that affect the way V8 calls functions.
When paused inside the function affected by the NLF, the Call Stack view in the DevTools' Source panel should show useful information.
Take a look at test/mjsunit/wasm/frame-inspection.js.
The scope iterator in V8 offers a way to introspect the scope chain at the break location. It includes not only the scopes outside of the current function, but also scopes inside it, for example inner block scopes, catch scopes, with scopes, etc.
For each scope inside the current function, we can materialize an object representing local variables belonging to it. For scopes outside the current function this is not possible.
We can use the scope iterator to alter the value of local variables, unless we are inside an optimized frame.
NLFs that introduce new scopes.
When paused in DevTools inside the scope introduced by the NLF, the “Scope” view on the Sources panel should show useful information. Scopes that are introduced by the NLF for desugaring purposes may better be hidden.
Take a look at test/mjsunit/debug-scopes.js.
CL that introduces hidden scopes
With debug-evaluate, V8 offers a way to evaluate scripts at a break, attempting to behave as if the script code was executed right at the break location. It is based on the frame inspector and the scope iterator.
It works by creating a context chain that not only references contexts on the current context chain, but also contains the materialized stack, including arguments object and the receiver. The script is then compiled and executed inside this context chain.
There are some limitations, and special attention has to be paid to variable name shadowing.
Side-effect-free debug-evaluate statically determines whether a function should throw. You should check whether to update the whitelist in src/debug/debug-evaluate.cc.
NLFs that are also affected by the scope iterator and frame inspector.
Use the DevTools console to run scripts at a debug break. In particular the preview shown in the DevTools console by default indicates whether the side-effect detection works correctly (i.e. whether you updated the whitelist correctly).
Look for mjsunit tests with “debug-evaluate” in their names.
This tea-and-crumpets presentation
Debug-evaluate without side effect doc and presentation
Code coverage gathers execution counts and exposes them to developers through the Inspector protocol.
NLFs that contain control flow (e.g branches, loops, etc.).
Run d8 with --lcov and check whether the produced coverage information is correct. E.g. like this:
./d8 --lcov=cov.info test.js genhtml cov.info -o coverage
Then navigate your browser to coverage/index.html.
test/mjsunit/code-coverage-block.js
Design doc: go/v8-designdoc-block-code-coverage
The heap profiler is a tool usually used to find out what is taking so much memory, and find potential memory leaks. It is an object graph visitor.
NLFs that change object layouts or introduce new object types
Take a heap Snapshot in DevTools' Profiler panel and inspect the result. Objects related to the NLF should fan out to all objects it references to.
Take a look at test/cctest/test-heap-profiler.cc.
DevTools allows restarting of some stack frames, not just the top-level one. The feature is implemented by throwing a termination exception and unwinding the stack until after the function we want to restart, and then re-invoking the function. This only works for certain functions, e.g. async functions can't be restarted as that would require rolling back the underlying generator.
NLFs that change function execution or require a function to carry state (e.g. async functions need a generator that can't be reset).
While paused, right click a stack frame with the NLF in the call stack view and select “Restart frame”. If the NLF prevents the frame from being restarted, then the “Restart frame” menu item must be disabled, otherwise the frame must be properly restarted.
Take a look in test/inspector/debugger/restart-frame/*.
LiveEdit is a feature that allows for script content to be replaced during its execution. While it has many limitations, the most often use case of editing the function we are paused in and restarting said function afterwards.
NLFs that affect code execution
Open DevTools and break inside the part of script affected by the NLF. Change the code inside the function with the NLF and save the script.
Look for mjsunit tests with liveedit in their names.