To be able to add code breakpoints, it's necessary to load test_plugin.py. This can be simply opened as a file, but it's better to learn how to view the entire plugin as a PyDev project. This allows us to use Aptana as a debug and develop environment. This is done in two steps:

Creating a PyDev project called TestPlugin is done by navigating to File | New Project. This will open a wizard where we'll have to look for a PyDev Project entry. Select it and click on the Next button at the bottom. Here, the wizard will pass to the phase to insert the project name, TestPlugin, and then click on the Finish button at the bottom. A new project called TestPlugin will be shown in the PyDev Package Explorer Aptana section.

The next step is to add the folder; right- of our TestPlugin code inside the project. To add it, select the TestPlugin PyDev project click on it to add a new folder, as shown in this following screenshot:

Here, we can see the contextual menu to add a new folder for the selected project. This action will open a GUI where we can create or link a new folder. In our case, it's useful to link to the existing plugin code, which can be done using the Advanced features of the GUI, as shown here:

After linking the folder, it will appear under the TestPlugin PyDev project where we can look for the test_plugin.py code. Double-click on the file; it will be opened on the right-hand side of Aptana, as shown in the following screenshot:

Breakpoints are debugger instructions to stop execution at a specified line to allow users to investigate variable values and eventually change their values manually.

Our scope is to add a simple breakpoint and check that the plugin execution stops exactly at that point, passing control to the remote debugger.

To add a breakpoint, open the Debug perspective and double-click on the left-hand side of the line number, for example, the line with the for (id, map) code in layersDict.items(). Aptana will add a breakpoint, as shown in this screenshot:

The line where the breakpoint is added is marked by the red box on the left, and a new breakpoint will be listed in the Breakpoints list, as marked by the red box in the upper-right corner.

Now it's time to test the debug session. Let's start the PyDev debug server and connect to it, as described previously.

In QGIS, run TestPlugin; QGIS will now freeze because it's starting to execute the run() method of the test_plugin.py code and a breakpoint is encountered. So, the control is passed to the PyDev debugger; the Aptana Debug perspective will appear similar to this:

Here, the red box on the left shows where the code is stopped, adding an arrow to the previous green bullet. The Variables Aptana section, marked by the red box on the right, displays variables used in the code and their values.

There are buttons, marked in the preceding screenshot by the upper-red box, to run statements in a step-by-step way, to enter in a function or continue with an execution.

A detailed description of how to work with the PyDev Debug perspective is out of the scope of this chapter, but it's possible to find more documentation on PyDev at http://pydev.org/manual_adv_debugger.html.