This PR adds integration tests for the ASCII renderer in d2renderers/d2ascii/. The goal? Make sure we don’t accidentally break it while trying to be smart. Think of it as a safety net, like wearing a helmet while ASCII biking.

/claim #924

What’s Inside

A Pretty Capable ASCII Renderer

• in d2renderers/d2ascii/
• Can draw all kinds of shapes:
  • Circles (●), diamonds (◆), cylinders, hexagons, you name it
• Knows how to route arrows and labels like a GPS with good manners
• Handles fancy layouts like the bike diagram

Fully Plugged into the D2 System

• Uses the same d2target.Diagram interface as the SVG renderer
• Works smoothly with d2lib.Compile()
• Fits in with the rest of the architecture like it was always meant to be there

Test Suite

• File: ascii_integration_test.go
• Auto-discovers all .d2 files in testdata/
• Uses golden file comparison (so we know when the output changes)
• Easy to update when you mean to change something

Test Architecture

We have two types of tests working together:

Unit Tests (d2ascii_test.go)

• Tests individual functions in isolation
• TestSortObjects() - Object sorting logic
• TestGrid() - Grid data structure
• TestDrawShapes() - Individual shape drawing functions
• Fast, focused tests that catch logic errors

Integration Tests (ascii_integration_test.go)

• Tests the complete D2 → ASCII pipeline
• Uses real .d2 files as input
• Golden file comparison for visual verification
• Catches system-level issues and regressions

Test Coverage

Covers all this:

• simple.d2: Just a -> b to keep it humble
• bike.d2: ASCII bicycle with all the bells and whistles
• shapes.d2: Every shape we support
• test.d2: Routing test
• example.d2: Your classic user-server-database setup
• Plus any .d2 files you drop into testdata/ going forward

How to Run Tests

Run all integration tests:

go test ./d2renderers/d2ascii/ -run TestIntegration -v

Check which tests were picked up:

go test ./d2renderers/d2ascii/ -run TestIntegration -v | grep "=== RUN"

Run just one test:

go test ./d2renderers/d2ascii/ -run TestIntegration/bike

Add Your Own Test Case

# Create a new test file
echo "api -> database -> cache" > d2renderers/d2ascii/testdata/api.d2

# Generate golden output for it
TESTDATA_ACCEPT=1 go test ./d2renderers/d2ascii/ -run TestIntegration/api

# Check that it works
go test ./d2renderers/d2ascii/ -run TestIntegration/api

Update Golden Files

# When you know the output should change
TESTDATA_ACCEPT=1 go test ./d2renderers/d2ascii/ -run TestIntegration

Example Test Output

When Things Go Well

=== RUN   TestIntegration
=== RUN   TestIntegration/simple
=== RUN   TestIntegration/bike
=== RUN   TestIntegration/shapes
=== RUN   TestIntegration/test
=== RUN   TestIntegration/example
--- PASS: TestIntegration (0.00s)
    --- PASS: TestIntegration/simple (0.18s)
    --- PASS: TestIntegration/bike (0.22s)
    --- PASS: TestIntegration/shapes (0.21s)
    --- PASS: TestIntegration/test (0.19s)
    --- PASS: TestIntegration/example (0.20s)
PASS

When Things Go Weird

--- FAIL: TestIntegration/bike (0.24s)
    ascii_integration_test.go:103: unexpected error: diff:
        --- expected/bike/ascii.exp.txt
        +++ actual output
        @@ -15,7 +15,7 @@
        -●●● Front Wheel ●●●
        +### Front Wheel ###

Why This Matters

• Catches regressions before they escape into the wild
• Makes it easy to check your changes
• Covers all types of diagrams, simple to complex
• Golden files give a visual reference
• Can be run in CI without drama

Checklist

• All tests pass
• Golden files match the expected output
• .d2 files are auto-discovered
• TESTDATA_ACCEPT=1 updates golden files as needed
• You can run individual tests
• Output looks good in plain old ASCII

👉 Watch demo video on YouTube