Remote Debug

The Remote Debug, available since TeamCity 8.0, is a feature allowing you to remotely debug your tests on the TeamCity agent machine from the IDE on the local developer machine. This feature is of use when the agent environment is unique in some aspect, which causes a test to fail, and it is difficult to reproduce the problem locally.

Prerequisites:

1. an IntelliJ IDEA run configuration on the local developer machine with the IntelliJ Platform Plugin installed,

2. a build configuration on the TeamCity Server with the IntelliJ IDEA Project runner as one of the Configuring Build Steps

3. a remote Build Agent to run this build available to the local machine by socket connection

Debugging Tests Remotely

1. To start remote debugging of a test, select the test and choose the Debug <Test Name> Remotely on TeamCity Agent option from the context menu (the Remote Debug action is also available from the TeamCity plugin menu. The action will require you to select an IntelliJ IDEA run configuration).

2. Once you do this, the TeamCity plugin will ask you to select a build configuration where you want to start the debug session. The process is similar to starting a personal build. For example, if there are personal changes, a personal patch will be created and sent to an agent. Also, since the process is basically the same, when you select a build configuration, you can specify an agent, customize properties, etc.

   

3. If the selected configuration contains more than one IntelliJ IDEA Project build step, the plugin will ask you to choose build steps where to start the debug session.

   

4. After that a build is added to the queue and the standard IntelliJ IDEA debug tool window appears:

   

   The debug tool window works in the listening mode, i.e. it waits for the agent to connect to it. Once the agent connects, the Java process on the agent is paused and the Agent Attached notification appears in the IDE:

   

5. Now we can set some breakpoints, and actually start the debug session by clicking Start either in the notification popup or in the debug tool window. Once JVM process exits, another notification popup appears in the IDE:

   

   The debug session is not finished yet, it is possible to either repeat or finish it. Selecting Repeat will rerun the same build step again, which is much faster than starting a new debug session.