aer Local Apex Debugger

Debug Apex locally with aer using VS Code's built-in debugging interface, and get language features like autocompletion, hover information, and go-to-definition.

Features

Debugging 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

Language Features (LSP)

• Autocompletion for Apex classes, methods, and fields
• Hover information for symbols
• Go to definition
• Find references
• Document symbols

Requirements

• aer must be installed and available in your PATH (the extension will offer to download the latest release if it cannot find aer)
• VS Code 1.75.0 or later

The extension will periodically check GitHub for newer aer releases and prompt you to update the locally cached binary when one is available.

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".

Configuration

You can configure the extension in your VS Code settings (optional):

{
	"aer.path": "/path/to/aer"
}

Configuration Options

• aer.path: Path to the aer executable (default: "aer", uses PATH)

  • Optional: only needed if aer is not in your PATH

• aer.asNamespace: Treat loaded code as if it belongs to the specified namespace (default: "")

  • Useful for managed package development where your code references namespaced custom objects and fields using its own namespace
  • This setting has resource scope, so it can be set per-workspace in .vscode/settings.json
  • Example for a managed package with namespace oslog:

    {
      "aer.asNamespace": "oslog"
    }
    

  • When set, the LSP server, test runner, and debugger will:
    • Treat all Apex classes as belonging to the namespace
    • Apply the namespace prefix to custom objects and fields in the schema
    • Resolve references like oslog__MyObject__c and oslog__MyField__c

• aer.lsp.sourcePaths: Specific directories to scan for Apex files (default: [])

  • Usually not needed - the LSP server automatically detects project roots
  • When you open an Apex file, the server walks up the directory tree looking for:
    1. sfdx-project.json (SFDX projects)
    2. package.xml (Metadata API projects)
    3. If the file is in a classes or triggers directory, uses the parent directory
  • Only set this if you need to override the automatic detection
  • Example (rarely needed):

    {
      "aer.lsp.sourcePaths": [
        "/custom/path/to/apex/files"
      ]
    }
    

• aer.lsp.trace: Trace communication between VS Code and the aer language server (default: "off")

  • Useful for debugging LSP issues
  • Values: "off", "messages", "verbose"
  • Trace output goes to a separate "aer Language Server Trace" output channel
  • Example:

    {
      "aer.lsp.trace": "verbose"
    }
    

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

1. Run aer exec --debug from your project directory (optional: pass a snippet to prefill the prompt, e.g. aer exec --debug "Integer x = 5; System.debug('x = ' + x);").
2. VS Code opens with a "Debug Anonymous Apex" configuration; press F5 and enter your Apex code when prompted.
3. The debugger stops on entry so you can set breakpoints and step through the code.

You can:

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

Running Apex Tests in VS Code

You can run and debug Apex tests directly from VS Code's Testing view (beaker icon) using the built-in Apex test controller:

1. Open your project in VS Code and make sure aer is on your PATH (or set aer.path in settings).
2. Open the Testing view. The extension discovers .cls files with @isTest classes or test methods and populates the Apex Tests tree.
3. Use the run (triangle) or debug (bug) icons in the tree or inline next to a class/method to execute just that scope. The top-level controls run or debug everything under the selected workspace folder.
4. Results show inline and in the Testing panel with pass/fail status, durations, and error messages linked to file locations (the extension runs aer test --json under the hood).
5. Debug runs start aer test --debug ... and stop on entry so you can immediately hit breakpoints in your tests.

Using Language Features

The extension automatically starts the Apex language server when you open an Apex file (.cls or .trigger). You'll have access to:

• Autocompletion: Press Ctrl+Space to trigger IntelliSense
• Hover Information: Hover over a symbol to see its documentation
• Go to Definition: F12 or Ctrl+Click to jump to a symbol's definition
• Find References: Shift+F12 to find all references to a symbol
• Document Symbols: Ctrl+Shift+O to see all symbols in the current file

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

• Cannot modify variables during debugging
• Debugging sessions without a valid license are limited to 5 minutes