smalltalk-debugger

Smalltalk Debugger

Systematic debugging techniques for Smalltalk (Pharo/Squeak) development using AI editors.

Core Debugging Workflow

When tests fail or errors occur, follow this systematic approach:

1. Identify Error Location

From error message, confirm:

• Error type (MessageNotUnderstood, KeyNotFound, etc.)
• Stack trace - where error occurred
• Expected vs Actual - what went wrong

2. Verify with Partial Execution

Use /st-eval tool to execute relevant code incrementally.

Basic error capture pattern:

| result |
result := Array new: 2.
[ | ret |
  ret := objA doSomething.
  result at: 1 put: ret printString.
] on: Error do: [:ex | result at: 2 put: ex description].
^ result

Interpreting results:

• result at: 1 - Normal result (success case)
• result at: 2 - Error description (failure case)

3. Check Intermediate Values

Inspect state at each step:

| step1 step2 |
step1 := self getData.
step2 := step1 select: [:each | each isValid].
{
    'step1 count' -> step1 size.
    'step2 count' -> step2 size.
    'step2 result' -> step2 printString
} asDictionary printString

4. Fix and Re-test

1. Fix in Tonel file (never in the Smalltalk image)
2. Re-import with import_package
3. Re-test with run_class_test

When Operations Stop Responding

When an MCP call times out, follow this escalation sequence:

Step 1: Health Check

Run a quick eval to verify the Smalltalk image is still responsive:

mcp__smalltalk-interop__eval: 'Smalltalk version'

If this succeeds, the Smalltalk image is alive — a debugger window may have opened (see below).

Step 2: Try read_screen

If eval also times out, check the UI state:

mcp__smalltalk-interop__read_screen: target_type='world'

If read_screen responds, inspect the output for debugger windows (see "Detecting Hidden Debuggers" below).

Step 3: Process Hang — Ask User to Restart

If read_screen itself times out, the Smalltalk image has hung at the process level. MCP tools cannot recover from this state.