| name | compare-render |
| description | Visually verify graphviz2drawio conversion fidelity by rendering a Graphviz source as both native Graphviz PNG and converted draw.io PNG, then inspecting the images. Use when modifying graphviz2drawio conversion or rendering code, updating specs, fixing layout, style, text, edge, or cluster bugs, or answering whether converted output looks right, improved, or regressed. Always perform a visual check before declaring conversion changes done. |
Compare Render
Purpose
Use this repo-specific workflow for /Users/haroldmartin/Downloads/graphviz2drawio. Correctness is visual: the draw.io render should match Graphviz's own render, and XML diffs or unit checks can miss visible regressions.
Do not create bundled helper scripts for this skill. Use the repository scripts already present under scripts/.
Core Workflow
-
Work from the repo root:
cd /Users/haroldmartin/Downloads/graphviz2drawio
-
Pick 1-3 relevant Graphviz inputs under test/. Prefer one small focused case and, when risk is broader, one stress or integration case.
-
Render the comparison:
./scripts/compare_render.sh test/directed/hello.gv.txt tmp_render/hello
This writes:
<base>_graphviz.png: Graphviz reference rendered by dot<base>_drawio.png: converted draw.io XML exported as PNG<base>.xml: intermediate draw.io XML
-
Inspect both PNGs with Codex image tooling. Prefer view_image and pass absolute paths, for example:
/Users/haroldmartin/Downloads/graphviz2drawio/tmp_render/hello/hello_graphviz.png
/Users/haroldmartin/Downloads/graphviz2drawio/tmp_render/hello/hello_drawio.png
-
Compare deliberately:
- Overall layout: node positions and relative arrangement
- Node geometry: shapes, sizes, fills, borders, and colors
- Edges: routing, curvature, attachment points, arrowheads, and direction
- Labels: text content, placement, font size, and edge-label placement
- Clusters/subgraphs: bounding boxes and whether they enclose the right nodes
-
Report concrete observations and a clear fidelity verdict. Name specific visible matches or differences; do not summarize as only "looks good".
Choosing Inputs
| Feature area | Good inputs |
|---|
| Minimal smoke test | test/directed/hello.gv.txt |
| Node shapes and polygons | test/directed/fsm.gv.txt, test/directed/switch.gv.txt |
| Clusters and subgraphs | test/directed/cluster.gv.txt, test/directed/compound.gv.txt, test/directed/subgraph_multiple.gv.txt |
| Colors | test/directed/Twelve_colors.gv.txt |
| Gradients | test/gradient/colors.gv.txt, test/gradient/radial_angle.gv.txt |
| Edge routing and curves | test/undirected/polylines.gv.txt, test/undirected/polylines_curved.gv.txt |
| Ports | test/directed/port.gv.txt |
| Labels and multi-labels | test/directed/multilabel.gv.txt, test/directed/tooltip.gv.txt |
| Records and HTML tables | test/directed/datastruct.gv.txt, test/directed/UML_Class_diagram.gv.txt, test/directed/subgraph_with_tables.gv.txt |
| Radial layouts | test/twopi/twopi2.gv.txt, test/undirected/networkmap_twopi.gv.txt |
| Large or stress graphs | test/directed/Linux_kernel_diagram.gv.txt, test/directed/world.gv.txt |
Broader Regression Checks
When specs changed or the implementation touches shared layout, style, labels, edges, or XML generation, run the textual spec check:
uv run ./scripts/test_specs.sh test tmp_out
Treat diffs as evidence to inspect, not automatic failure. If the new output is intentionally better, update specs through the repo's normal process.
For changed specs, render before/new/reference trios:
./scripts/render_specs.sh test specs tmp_render
Inspect generated _new.png, _old.png, and _reference.png files with view_image before claiming the new render improves fidelity.
Failure Handling
- If
compare_render.sh reports missing dot, draw.io CLI, or uv, report the exact missing dependency and stop the visual verdict.
- If the draw.io PNG is blank or missing, inspect the generated XML before assuming the renderer is wrong.
- Keep generated output in
tmp_render/ or tmp_out/; those paths are gitignored and should not be committed.
Forward-Test Prompts
Use these realistic prompts when validating changes to this skill:
Use $compare-render at /Users/haroldmartin/Downloads/graphviz2drawio/.codex/skills/compare-render to check test/directed/cluster.gv.txt and report what differs visually.Use $compare-render at /Users/haroldmartin/Downloads/graphviz2drawio/.codex/skills/compare-render to investigate whether arrowheads look wrong in test/directed/fsm.gv.txt.Use $compare-render at /Users/haroldmartin/Downloads/graphviz2drawio/.codex/skills/compare-render to verify edge routing fidelity for test/undirected/polylines.gv.txt and test/undirected/polylines_curved.gv.txt.
