aer Local Apex Debugger

Debug Apex locally with aer using VS Code's built-in debugging interface.

Features

• Debug Apex tests locally
• Debug anonymous Apex code
• Set breakpoints in Apex classes and triggers
• Step through code (step in, step over, step out)
• Inspect variables (locals, instance fields, static fields)
• Evaluate Apex expressions in the debug console
• View call stack with line numbers

Requirements

• aer must be installed and available in your PATH
• VS Code 1.75.0 or later

Installation

The VS Code extension is automatically installed when you run aer with debugging enabled for the first time. No manual installation is required.

When you run a debug command (such as aer test --debug or aer exec --debug), aer will:

1. Check if the extension is installed in VS Code
2. Automatically install or update the extension if needed
3. Start the debug session

The extension will be available in VS Code's Extensions view as "aer Local Apex Debugger".

Usage

Quick Start - Debugging Tests

The fastest way to debug Apex tests is from the command line:

1. Open a terminal in your Apex project directory
2. Run aer with debugging enabled:

   aer test --debug ./force-app/main/default/classes
   

3. VS Code will automatically open and connect to the debugger
4. The debugger will pause at the first line of your test (stopOnEntry mode)
5. Set breakpoints by clicking in the gutter next to line numbers
6. Use the debug controls to step through your code (F5=Continue, F10=Step Over, F11=Step Into)

Quick Start - Debugging Anonymous Apex

The fastest way to debug anonymous Apex is using the --exec flag:

aer exec --debug --exec "Integer x = 5; System.debug('x = ' + x);"

VS Code will automatically open, and you can:

• Set breakpoints in the "Anonymous Apex" source view
• Step through your code using the debug controls

Debugging Features

Breakpoints

• Click in the gutter to set/remove breakpoints
• Breakpoints are verified when the debug session starts
• Conditional breakpoints and logpoints are not yet supported

Stepping

• Step Over (F10): Execute the current line and move to the next line
• Step Into (F11): Step into method calls
• Step Out (Shift+F11): Step out of the current method
• Continue (F5): Continue execution until the next breakpoint

Variable Inspection

The Variables view shows:

• Locals: Local variables in the current method
• This: Instance fields of the current object
• Static: Static fields of the current class

Hover over variables in the editor to see their values.

Watch Expressions

Add Apex expressions to the Watch view to evaluate them:

• myVar.size()
• this.expectedValue
• MyClass.staticField

Debug Console

Evaluate Apex expressions in the Debug Console:

> myList.get(0)
> this.accountName
> System.now()

Call Stack

The Call Stack view shows:

• Current execution location
• Method call hierarchy
• File names and line numbers

Troubleshooting

"Failed to start aer" error

Make sure aer is installed and in your PATH:

which aer
aer --version

"Failed to connect to aer debug server"

This usually means aer couldn't start or the DAP server didn't initialize. Check:

1. The path you provided contains test classes or valid Apex code
2. aer can run tests normally: aer test ./your-test-path

Breakpoints not working

1. Make sure you're setting breakpoints in .cls files that are being executed
2. Verify the file path matches between VS Code and the test execution
3. Check that the line has executable code (not comments or blank lines)

Variables show as "undefined"

This can happen if:

• You're viewing variables from a frame that hasn't been fully initialized
• The variable hasn't been assigned yet in the execution flow
• Static fields haven't been initialized

Examples

Example Test Class

@isTest
public class MyTest {
	@TestSetup
	static void setup() {
		Account acc = new Account(Name = 'Test');
		insert acc;
	}

	@isTest
	static void testAccountCreation() {
		List<Account> accounts = [SELECT Id, Name FROM Account];
		System.assertEquals(1, accounts.size());
		System.assertEquals('Test', accounts[0].Name);
	}
}

Set a breakpoint on the System.assertEquals line and run the debugger. When it pauses:

• Inspect accounts in the Variables view
• Add accounts.size() to the Watch view
• Step through the assertions

Known Limitations

• Tests run in single-threaded mode when debugging
• Conditional breakpoints are not yet supported
• Hit count breakpoints are not yet supported
• Cannot modify variables during debugging
• Debugging sessions without a valid license are limited to 5 minutes