Performing Remote Debugging
TeamCity provides the remote debug option to 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
an IntelliJ IDEA run configuration on the local developer machine with the TeamCity plugin for IntelliJ IDEA installed
a build configuration on the TeamCity Server with the IntelliJ IDEA Project or Ant runner as one of the build steps
a remote TeamCity agent to run this build available to the local machine by the socket connection
To debug tests remotely
Select a 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).
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.
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.
After that a build is added to the queue and the standard IntelliJ IDEA debug tool becomes active:
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 TeamCity Agent Attached to Debug Session notification appears in the IDE.
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 the JVM process exits, the TeamCity Agent Detached from Debug Session 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.