Using the debugger

Note: The debugger is currently available as part of our Early Access program, which when enabled gives you access to cutting-edge and potentially unstable features. It requires opting-in; navigate to your account settings by clicking on your username or GitHub avatar in the sidebar. Click ADVANCED and choose Early Access.

In this section we'll explore both the various elements of the debugger's user interface and steps invovled in actually debugging a transaction. Let's explore an example of the Truffle Teams debugger interface, wherein a simple ERC721 token implementation is being debugged.

Teams Debugger Interface
The Truffle Teams Debugger Interface.

The first thing to note is the transaction hash (0x82f668a...) in the page header. The header includes a visual representation of whether the transaction ultimately succeeded or failed . This is a useful reference as it allows you to preemptively know whether to expect a status message when execution completes. More on this in the Status Messages section.

From within the debugger interface you'll find the debugger's control palette.

Teams Debugger Control Palette
The Truffle Teams Debugger Control Palette.

From left to right, the controls, with a description of their associated action, are as follows. Note that you can also hover a control to display its associated name. Note that the brackets contain the corresponding keyboard shortcuts for each command.

  • Continue - continue until the next breakpoint is reached or the last line is executed ("c" or "F8")
  • Step Over - steps over the current line ("o" or "F10")
  • Step Into - steps into the function call or contract creation currently being evaluated ("i" or "F11")
  • Step Out - steps out of the currently running function ("u" or "Shift+F11")
  • Restart - restarts the debugger session ("r")

The source files that will be accessed as part of the transactions execution path will be represented by tabs with the contract file names. It's worth noting that it's likely your project may contain more files than are displayed here.

Teams Debugger Source File Tabs
The Truffle Teams Debugger Source File Tabs.

There are two noteworthy visual cues with the debugger tabs. The first is that of an "open tab", which means that you're looking at the file's code below and is represented with a light green background. The second is that of "active tab" which is represented by an orange circle which indicates that the debugger is currently paused within this file.

As you use the debugger's controls to step through a transaction you will likely see the active tab update. Note that the open tab will also update when the code steps into it.

As the core of the Truffle Teams Debugger is the source viewport. This is a read-only display of the code that the transaction will be stepping through as part of its execution.

Teams Debugger Source Viewport
The Truffle Teams Debugger Source Viewport.

The main thing to note is the active line which is highlighted in yellow. As your step through your transaction this will update accordingly.

The variable inspector shows the variable values for the current transaction execution context, including contract state, local function, and global variables. The inspector uses a tree-like explorer enabling you to drill down by clicking on a given branch, represented by the green right-facing caret icon .

Teams Debugger Variable Inspector
The Truffle Teams Debugger Variable Inspector.

Located in the lower right corner of the screen is the breakpoint tray. Breakpoints are added to the tray by clicking on a given line number or just to the left in the line's "gutter". They can subsequently be removed by clicking in the same location or on the circular cross to the right of the breakpoint entry in the tray itself.

Teams Debugger Breakpoints
The Truffle Teams Debugger Breakpoints.

Functionally, breakpoints will cause code execution to stop (or break) upon being reached. At this point it's common to inspect state via the Variable Inspector or continue stepping through to ensure your code is behaving as expected or when tracking down a bug.

Lastly, note that clicking on a given breakpoint within the tray will jump you to the corresponding tab and line. This is particularly useful when navigating more complex contracts that comprise of multiple files.

If your transaction's execution ultimately fails, a banner appear after the REVERT happens. An associated status message or reason string will be shown if one exists.

Teams Debugger Status Message
The Truffle Teams Debugger Status Message.

As shown in the example, the transaction failed with the ERC721: token already minted reason string.