// Create minimal subtests to isolate and fix complex bugs. Use when a test fails and the issue is buried in complexity.
| name | subtest-isolation |
| description | Create minimal subtests to isolate and fix complex bugs. Use when a test fails and the issue is buried in complexity. |
When a test fails with complex output or multiple issues, create a minimal subtest to isolate and fix ONE specific problem at a time.
Use subtest isolation when:
Don't use for:
Look at the failing test output and pinpoint EXACTLY what's wrong:
Example from test45:
Problem identified: Bottom box has all text overlapping incorrectly.
"center" text appearing at the very top instead of middle.
Create a new test file (e.g., test45b.pikchr) with ONLY the problematic element:
# test45b.pikchr - isolate the bottom box issue
box "rjust" rjust above "center" center "ljust" ljust above \
"rjust" rjust below "ljust" ljust below big big
Key principles:
<original>b.pikchr for clarityRun the subtest and confirm it shows the SAME bug:
cargo run --example simple -- vendor/pikchr-c/tests/test45b.pikchr
# OR
mcp__pikru-test__run_pikru_test test45b
Check that:
Add targeted debug output to understand what's happening:
eprintln!("[SLOT HEIGHT] text='{}' slot={:?} font_scale={} charht={} h={}",
text.value, slot, text.font_scale(), charht, h);
eprintln!("[Y OFFSET] text='{}' slot={:?} calc=[{}] y_offset={} final_y={}",
positioned_text.value, slot, offset_calc, y_offset, center.y + svg_y_offset);
Debug output best practices:
eprintln! so it goes to stderr (doesn't corrupt SVG output)[SLOT HEIGHT], [Y OFFSET] for easy greppingRun the subtest and analyze the debug output:
cargo run --example simple -- vendor/pikchr-c/tests/test45b.pikchr 2>&1 | grep '\[SLOT'
Look for:
Example output that revealed the bug:
[SLOT HEIGHT] text='center' slot=Above2 font_scale=1 charht=0.14 h=0.14
→ BUG FOUND: "center" text assigned to Above2 instead of Center!
Run the C implementation on the same subtest:
vendor/pikchr-c/pikchr --svg-only vendor/pikchr-c/tests/test45b.pikchr | grep '<text'
Compare:
Example comparison:
C output: <text y="38.16" ...>center</text>
Rust output: <text y="12.24" ...>center</text>
→ Confirms the bug: Rust placing center text way too high
Based on debug output and comparison:
Example fix:
// BUG: wasn't checking t.center
else if t.center {
Some(TextVSlot::Center) // ← FIX: explicitly assign Center slot
}
Run the subtest again - it should now MATCH:
mcp__pikru-test__run_pikru_test test45b
Expect:
{"test_name":"test45b","status":"match","comparison":{"ssim":1.0, ...}}
Clean up the debug statements you added:
// Remove all the eprintln! statements
// Keep the code clean for production
Run the original test to confirm the fix works in context:
mcp__pikru-test__run_pikru_test test45
If it still fails:
If it passes:
Keep the subtest if:
Remove the subtest if:
Original problem:
Subtest creation:
# test45b.pikchr - just the problematic box
box "rjust" rjust above "center" center "ljust" ljust above \
"rjust" rjust below "ljust" ljust below big big
Debug output revealed:
[SLOT HEIGHT] text='center' slot=Above2 ... ← WRONG! Should be Center
Root cause found:
center text attribute wasn't being handled in slot assignmentFix applied:
// Added center field to PositionedText
// Handle TextAttr::Center in parsing
// Check t.center when assigning initial slots
Result:
Show the calculation:
eprintln!("calc=[Above: 0.5*{} + 0.5*{} = {}]", hc, ha1, offset);
Track state transitions:
eprintln!("[BEFORE] slot={:?} y_offset={}", slot, y_offset);
// ... calculation ...
eprintln!("[AFTER] y_offset={} final_y={}", y_offset, final_y);
Use structured prefixes:
[SLOT HEIGHT] // For slot height calculations
[Y OFFSET] // For y-coordinate calculations
[ASSIGNMENT] // For slot assignments
[FINAL] // For final values
If the first subtest doesn't reproduce the bug:
If you find multiple bugs:
If debug output doesn't reveal the issue:
The goal is laser focus:
Not:
Codebase organization for pikru. Use when you need to find where specific functionality lives.
Code annotation requirements for pikru. Use when writing or porting Rust functions from C code. All ported functions must have cref comments.
Debugging conventions for pikru. Use when adding debug traces or investigating issues. Important rule - leave debug traces in place.
Git command conventions for pikru. Use when running any git commands to avoid blocking on interactive pager.
Idiomatic Rust patterns for pikru C port. Use when writing or reviewing Rust code ported from C. Don't write C in Rust - the goal is correct behavior, not line-by-line translation.
Testing conventions for pikru. Use when running tests to avoid timeouts. DO NOT run the full test suite.