Skip to content

Manual Testing the Dapper Debug Adapter

This guide shows how to validate Dapper manually by connecting to it as an external debug adapter, in the same way a DAP client such as VS Code would.

Quick Start

Method 1: Two-Terminal Workflow

Terminal 1 (Start debug adapter):

python -m dapper.adapter --port 4711 --log-level DEBUG

Terminal 2 (Test connection):

python test_dapper_client.py --test-only --program examples/sample_programs/simple_app.py

Terminal 2 (Run full debug session):

python test_dapper_client.py --program examples/sample_programs/simple_app.py

Method 2: VS Code Integration

  1. Start the debug adapter:
  2. Open Run and Debug panel (Ctrl+Shift+D)
  3. Select "Launch Debug Adapter (TCP)"

  4. Click the green play button

  5. Connect and debug:

  6. Open a new VS Code window or use a separate terminal
  7. Select "Test Dapper Debug Adapter" configuration
  8. This will run a DAP client that connects to your adapter

Step-by-Step Process

Step 1: Launch Debug Adapter

Start your debug adapter in server mode:

python -m dapper.adapter --port 4711 --log-level DEBUG

You should see output like:

2025-09-08 [INFO] dapper.adapter: Starting debug adapter with tcp connection
2025-09-08 [INFO] dapper.connection: TCP server listening on localhost:4711

Step 2: Test Connection

Verify the adapter is running:

python test_dapper_client.py --test-only --program examples/sample_programs/simple_app.py

Expected output:

Testing connection to debug adapter at localhost:4711...
Debug adapter is running and accepting connections
Connection test successful

Step 3: Run Debug Session

Connect to your adapter and debug a program:

python test_dapper_client.py --program examples/sample_programs/simple_app.py

This workflow will: 1. Connect to your debug adapter on port 4711 2. Send DAP initialize request 3. Send DAP launch request for the target program 4. Set breakpoints at lines 70 and 85 5. Send configurationDone and continue requests

What to Watch For

Debug Adapter Logs

In the terminal running the debug adapter, you should see:

2025-09-08 [DEBUG] dapper.server: Received request: initialize
2025-09-08 [DEBUG] dapper.server: Received request: launch
2025-09-08 [DEBUG] dapper.server: Received request: setBreakpoints
2025-09-08 [DEBUG] dapper.server: Received request: configurationDone
2025-09-08 [DEBUG] dapper.server: Received request: continue

Client Output

The test client shows the DAP communication:

Sending: initialize
   {"seq": 1, "type": "request", "command": "initialize", "arguments": {...}}
Received: response
   {"seq": 1, "type": "response", "success": true, ...}

Testing Different Scenarios

Test Simple Program

python test_dapper_client.py --program examples/sample_programs/simple_app.py

A more compact loop-focused script is also available for exercising conditional/expression breakpoints:

python test_dapper_client.py --program examples/sample_programs/loop_example.py

Test Advanced Program

python test_dapper_client.py --program examples/sample_programs/advanced_app.py

Test with Different Port

# Start adapter on different port
python -m dapper.adapter --port 5555

# Connect to different port
python test_dapper_client.py --port 5555 --program examples/sample_programs/simple_app.py

Test Subprocess IPC Transports

You can run the debuggee in a subprocess and have the adapter↔launcher communicate over IPC. The server forwards useIpc and transport options to the launcher automatically.

  • Windows (default: named pipe)
  • In your client (or launch request), set: {"useIpc": true}
  • The launcher will receive --ipc pipe --ipc-pipe \\\\.\\pipe\\dapper-...

  • Verify cleanup: on terminate, the pipe endpoints are closed.

  • macOS/Linux (default: UNIX domain socket, TCP fallback)

  • In your client (or launch request), set: {"useIpc": true}
  • The launcher will receive --ipc unix --ipc-path /tmp/dapper-....sock
  • Verify cleanup: the .sock file is removed on terminate.

Force a specific transport when needed:

// Example DAP launch arguments
{
   "program": "examples/sample_programs/simple_app.py",
   "useIpc": true,
   "ipcTransport": "tcp", // or "pipe" (Windows), "unix" (POSIX)
   "subprocessAutoAttach": true,
   "justMyCode": true,
   "strictExpressionWatchPolicy": false,
}

// Example DAP launch arguments (module target)
{
   "module": "http.server",
   "moduleSearchPaths": ["${workspaceFolder}/src"],
   "env": {
      "PYTHONPATH": "${workspaceFolder}/vendor"
   },
   "args": ["8000"],
   "useIpc": true
}

// Example DAP launch arguments (module target in virtualenv)
{
   "module": "my_app.main",
   "venvPath": "${workspaceFolder}/.venv",
   "args": ["--port", "8080"],
   "useIpc": true
}

Notes: - If ipcTransport is omitted: Windows defaults to pipe; non-Windows defaults to unix and falls back to TCP when AF_UNIX is unavailable. - The server only forwards IPC-related kwargs to the launcher when useIpc is true to preserve legacy argument ordering.

VS Code Launch Configurations

The .vscode/launch.json includes these configurations:

Configuration Purpose
Launch Debug Adapter (TCP) Start your Dapper adapter on port 4711
Test Dapper Debug Adapter Run the DAP client to test your adapter
Debug Simple App (Standard Python) Compare with VS Code's debugger

Comparing with the Standard Debugger

To verify your adapter works correctly:

  1. Debug with your adapter:
  2. Start: "Launch Debug Adapter (TCP)"

  3. Run: "Test Dapper Debug Adapter"

  4. Debug with VS Code's debugger:

  5. Run: "Debug Simple App (Standard Python)"

  6. Compare the behavior:

  7. Breakpoints hit at same lines
  8. Variable values match
  9. Step operations work similarly

Troubleshooting

Connection Refused

Failed to connect to debug adapter: [Errno 10061] No connection could be made

Solution: Make sure the debug adapter is running first.

Port Already in Use

[Errno 10048] Only one usage of each socket address is normally permitted

Solution: Kill existing processes or use a different port.

No Response from Adapter

If the client hangs waiting for a response: 1. Check debug adapter logs for errors 2. Verify your adapter implements the required DAP requests 3. Use --log-level DEBUG for detailed logging

Invalid DAP Messages

Error during debug session: JSON decode error

Solution: Check that your adapter sends properly formatted DAP responses.

Next Steps

  1. Implement missing DAP requests in your adapter
  2. Add more test scenarios to the client
  3. Test edge cases like invalid programs, connection drops, etc.
  4. Add breakpoint functionality to see actual debugging in action
  5. Test variable inspection and stepping operations

This process provides a straightforward way to verify that the adapter is handling core Debug Adapter Protocol traffic correctly.