RFC: Stopping behaviors in ignored code

[jecfish]

Author: Eric Leese (@EricSL), Jecelyn Yeen (@jecfish), Meysam Sarabadani (@Meysamsarabadani)
Posted: Jul 21, 2023
Status: Open
Chrome bug tracker: https://crbug.com/1442855

The goal of this RFC is to validate the design with the community, solicit feedback on open questions.

Complete: This RFC is now complete. See a summary (comment).

Motivation

By default, Chrome DevTools (the debugger) skips over code that is configured to be ignored during debugging.

However, what if there are exceptions in those ignored files? Should the debugger stop, continue, or show hints? In this RFC, we will share a few tricky scenarios and discuss the expected behaviors.

Goals

• To gather feedback from the community about stopping behavior of the debugger when dealing with ignore-listed code.
• To decide about the stopping conditions and behaviors and to plan implementation based on decisions made from the feedback.

Background: What is the ignore list?

(Skip to the next section if you already know what the ignore list is.)

Here is a demo application. When debugging a button click in a web application built with frameworks (e.g. React, Vue, Angular), it may first lead you to the framework or third-party code in the node_modules which could be irrelevant to you.

Left: frames from your code. Right: frames from third-party libraries.

Stepping into irrelevant code is annoying and may slow down your debugging process. From Chrome 112 onwards, you can tell the debugger to ignore irrelevant code by right clicking on the frame in the call stack or the folder in the page tree, select Add script/ directory to ignore list. DevTools also work with tools like Vite, Rollup Nuxt and Angular to configure the ignore list by default.

Left: Ignore a frame in the call stack. Right: Add script or directory to the ignore list.

Once you do that, DevTools will skip the ignored code, and hide those frames in the Call Stack. You can enable the Show ignore-listed frames checkbox to view the ignored frames if you want to, and those frames are grayed out by default.

Left: Hide ignored frames in the Call Stack. Right: Show ignored frames in the Call Stack.

In any situation, if you want to debug the ignored files, you can remove it from the ignore list by:

• Right click it in the page tree and select Remove from ignore list, or
• Open the file, remove it from the warning dialog, or configure the ignore list.

You can remove a file from the ignore list in the page tree and in the file warning dialog.

Proposal / Design

Here is how we structure the proposal to facilitate the discussion. We will share 4 main scenarios with some additional “what if” scenarios ⚠️.

For each scenario, we will first explain what and why, then show a demo, followed by some questions:

• ✳️ What. Explain the proposed behavior.
• 🤔 Why. Explain the reason for the behavior.
• ▶️ Demo. Give an example.
• 🙋🏽‍♀️ Questions. Questions for discussion.

Scenarios

Case 1: What happens when you set a breakpoint in an ignored file?

In this case, we focus specifically on line of code breakpoint and conditional breakpoint.

Setting a breakpoint and a conditional breakpoint in an ignored file.

• ✳️ The debugger will stop on the breakpoint in the ignored code.
• 🤔 It’s a clear signal. If you set a breakpoint in an ignored file, the assumption is you want to debug it.
• ▶️ Example: In the screenshot above, the file was ignored. The debugger still pauses in line 273 because of the breakpoint.
• 🙋🏽‍♀️ Questions:
  • 1a. Do you really want to stop? These could be breakpoints leftover from the old debugging sessions.

⚠️ What if… Extending from the question above, what happens when you start stepping from this breakpoint?

From the conditional breakpoint, what happens when you start stepping?

• ✳️ Here is what we propose:

  • Step over: The debugger will pause in the next line in the same function. If stepping causes the debugger to leave the function, then the debugger will continue until the next non-ignored code.
  • Step in or Step: The debugger will step until the next non-ignored code or until the next line of code - whichever comes first.
  • Step out: The debugger keeps stepping out until the next non-ignored code.

• 🤔 Why:

  • It’s a clear signal. If you step over, the assumption is that you are trying to debug the current function, so we exclude the current function from the ignore-list.
    -No clear signals. However, if you step (in and out) to a different function, the ignore-list rules take precedence.

• ▶️ Example:

  • Step over: In the screenshot above, the debugger will move from line 274 to line 278 callWithAsyncErrorHandling if you step over.
    
    Step over form the conditional breakpoint to the next line in the same function.

  • Step in: Click step in from callWithAsyncErrorHandling will jump to line 285 instead of patchStopImediatePropagation (line 289) because the patchStopImediatePropagation is in the ignored file and it is outside of the current function.
    
    Skip the ignore code during step in and step into next line in the current function.

  • Step out: The debugger cannot find the next breakpoint or non-ignored frames, so the debugging session ends.

• 🙋🏽‍♀️ Questions:

  • 1b. Do you want to step in all ignored code instead? That means disable ignore listing for the whole debugging session.
  • 1c. Do you want all stepping (over, in, out) to be consistent? That means, apart from the breakpoint, the debugger should ignore all the code including the current function and immediately take you to non-ignore-listed code instead.

Case 2: What happens when you set an event listener breakpoint, and the breakpoint is an ignored file?

Add a mouse click event listener breakpoint.

• ✳️ The debugger will stop at the first non-ignored code. The debugger will not stop in any ignored code.
• 🤔 No clear signal that developers want to stop in ignored code. This will most commonly be a wrapper function in a framework, and stepping until we hit code that is not ignored will take us into the wrapped event handler that is more likely to be familiar to the user.
• ▶️ From the screenshot above, given that node_modules is disabled, the mouse click breakpoint will pause at line 13 in the ListPage.vue file (your code), instead of random files in the node_modules (e.g. runtime-dom…js)
• 🙋🏽‍♀️ Questions:
  • 2a. Is this what you expected?

⚠️ What if… All the code in the event handler in the ignored list?

• ✳️ The event handler will be fired as usual but the debugger wil not stop at all. Developers should unignore those files or disable ignore-list entirely in the settings.
• 🤔 This is considered to be an edge case that rarely happens.
• ▶️ Example: In the coffee-cart.app, disable the node_modules and src, then click on a coffee.
• 🙋🏽‍♀️ Questions:
  • 2b. Should we notify you that the event handler fired but we didn't stop?
  • 2c. Would it be better to have event handler breakpoints always break immediately, even in ignore listed code? (For users of many web frameworks this would result in stopping in callback wrapper code from the framework rather than any code they would recognize, and it may not be obvious how to step into the developer's code.)

Case 3: What happens when you toggle the “Show ignore listed frames” in the call stack?

Before and after enabling the Show ignore-listed frames checkbox.

• ✳️ The toggle merely shows and hides the frames in the UI. There are no changes in the debugger stop behavior, the debugger will skip the ignored code as it should regardless of the toggle.
• 🤔 Why: No clear signal that developers want to stop in ignored files. The assumption is that you just want to view the code.
• ▶️ Example: In the coffee-cart.app, ignore the node_modules, set a mouse click event listener, then click on a coffee.
• 🙋🏽‍♀️ Questions:
  • 3a. Is this what you expected or would it be better if we rename it to Show & pause in ignore-listed frames and change the behavior to disregard the ignore list settings when stepping. This means, we will step into all the code.

Case 4: What happens when there are exceptions thrown in ignored code given you enable the pause on exceptions breakpoints?

Enabled the two “pause on exceptions” checkboxes.

• ✳️ Here is what we propose:

  • The debugger will stop in the ignored file if the call stack has non-ignored code that the exception will pass through. In this case the exception is affecting code that the user is interested in debugging.
  • The debugger will not stop if all code on the call stack is ignored. In this case an uncaught exception will print to the console. If the user wants to debug that exception, they can remove the files from the ignore list, and then reproduce the error.

• 🤔 No clear signal that developers always want to stop in ignored files even if there are exceptions.

• ▶️ Example:

  • In this example below, the error is thrown in the ignored file library.js > throwException and caught in the same ignored file at errorWrapper. In this case we will not stop on the exception because every function it passed through was ignored.
    
    A call stack with consecutive ignored frames.

  • In this example below, the error is thrown in the ignored file library.js > throwException and caught in the same ignored file in errorWrapper. However, there are non-ignored functions on the call stack between where the exception is thrown and where it is caught. In this case, the debugger will stop at library.js:15.
    
    A call stack with non-ignored frames interspersed with ignored frames.

• 🙋🏽‍♀️ Questions:

  • 4a. Should we always stop in ignored code if you enable pause on exceptions?
  • 4b. Should we automatically switch to a non-ignored call frame if possible? In the above examples, we could show the user the function doWithError instead of throwException. However, the behavior of stepping may be confusing because you might end up stopping in a totally different place that you intended to. (we are stepping from the hidden frame on top of the call stack instead of the frame that we selected to show the user.)

Additional resources

The scenarios we show above are a compressed list of all the complex scenarios we are working on. Here is a longer list of test cases for various stopping behaviors.

-- THE END --

[alexkozy]

historically the useful metaphor for me was to consider ignored code as builtin V8 code.

1. All breakpoints in the ignored files should be disabled; in an attempt to enable them, UI can show a hint that the file should be removed from the ignored list first.
2. Automatically switch to the first not ignored call frame, and stepping should behave as it was called from this frame.

the idea is that pausing inside the ignored code should not be possible- it helps avoid complicated semantics for stepping from this line.

what is about debugger statement? should it have the same semantics as the breakpoint set from UI?

[CyberAP]

I would love to see a consistent behaviour for the stepping functions. By optimising for the best scenario it would become really hard to understand what the button will actually do.

I think the problem can be solved by doing these:

1. Stop at every breakpoint (even for ignored files)
2. Make sure every step button adheres to the same rules
3. Introduce modality into the stepping logic
4. Provide visual feedback for the buttons depending on the mode

DevTools could have a consistent default behaviour when it comes to the stepping buttons: they either always ignore or respect the ignored files (I prefer the first option). In order to change that behaviour for all the buttons a user could apply a modifier key (Alt or Shift) which will change the current mode (ignore or respect) and click a button with the modifier key pressed. In addition to that there should be a visual indication that the stepping buttons work differently now (a yellow tint would be enough I think).

That way users won't have to guess what the button will do and can control the behaviour depending on their current needs (which may differ from the best scenario).

[jecfish]

It is been a while! We're closing this RFC as we have collect enough feedback both online and offline.
We will use these feedback to guide changes in DevTools around catch prediction. We would like to thank everyone for your feedback and for your help in shaping Chrome DevTools!