How It Works

Vizb converts go test -bench output into a structured JSON format, then embeds it in a self-contained HTML file with a Vue.js visualization app.

Pipeline

go test -bench .  →  raw text  →  parser  →  Benchmark struct  →  JSON / HTML
  Vitest output   ↘              ↓                        ↓
  Criterion output →         registry            (grouping applied)

Source Structure

• Directorycmd/

  • root.go CLI entry point, flag definitions, parser discovery
  • merge.go Merge command
  • html.go HTML generation command
• Directorypkg/

  • Directoryparser/

    • registry.go Parser registration (ParseFunc, Parsers map)
    • bench_data.go ParseBenchmarkData, ConvertGoJsonBenchToText
    • parse_pattern.go GroupBenchmarkName, ParseBenchmarkNameWithRegex
    • Directorygolang/ Go testing.B parser (default)

      • …
    • Directoryjavascript/ Vitest and TinyBench parsers

      • …
    • Directoryrust/ Criterion and Divan parsers

      • …
  • Directorytemplate/

    • generate-ui.go HTML template generation
    • vizb-ui.gen.go Built Vue UI (auto-generated from ui/dist)
  • Directorystyle/

    • style.go Terminal styling (lipgloss)
• Directoryshared/

  • bench.go Benchmark, BenchmarkData, Stat structs
  • merge.go MergeBenchmarks function
  • dimension.go Dimension type (n, x, y)
  • flag_state.go CLI flag state
• Directoryui/ Vue 3 + TypeScript visualization app

  • Directorysrc/composables/

    • Directorycharts/ Bar, line, and pie chart rendering (ECharts)

      • …
    • useSettingsStore.ts Reactive chart settings (scale, sort, labels)
    • useChartOptions.ts Chart composable routing
  • Directorysrc/components/

    • ChartCard.vue Individual chart container
    • ScaleSelector.vue Linear/log toggle (hidden for pie charts)
    • SelectionTabs.vue Metric/chart-type picker
  • Directorysrc/views/

    • Dashboard.vue Full multi-chart dashboard layout

Data Structures

Stat

A single metric value extracted from a benchmark result:

{
  "type": "Execution Time (ns/op)",
  "value": 1523.4
}

BenchmarkData

A single benchmark entry with dimensions and stats:

{
  "name": "Sort",
  "xAxis": "1024",
  "yAxis": "QuickSort",
  "stats": [
    { "type": "Execution Time (ns/op)", "value": 1523.4 },
    { "type": "Memory Usage (B/op)", "value": 256 },
    { "type": "Allocations (op)", "value": 4 }
  ]
}

Benchmark

The top-level output struct containing metadata and all benchmark data:

{
  "tag": "v1.1.0",
  "timestamp": "2025-01-15T10:30:00Z",
  "name": "MyBenchmarks",
  "description": "Sorting algorithm comparison",
  "history": [
    { "tag": "v0.9.0", "timestamp": "2024-12-01T08:00:00Z" },
    { "tag": "v1.0.0", "timestamp": "2025-01-15T10:30:00Z" }
  ],
  "cpu": { "name": "Apple M2", "cores": 8 },
  "os": "darwin",
  "arch": "arm64",
  "pkg": "github.com/example/sort",
  "settings": {
    "charts": ["bar", "line", "pie"],
    "sort": { "enabled": true, "order": "asc" },
    "showLabels": false,
    "scale": "linear"
  },
  "data": [
    { "name": "Sort", "xAxis": "1024", "yAxis": "QuickSort", "stats": [...] },
    { "name": "Sort", "xAxis": "1024", "yAxis": "MergeSort", "stats": [...] }
  ]
}

Input Detection

Vizb auto-detects the input format:

Raw Text

Standard go test -bench output. Parsed line by line using golang.org/x/perf/benchfmt.

go test -bench . > bench.txt
vizb bench.txt -o output.html

JSON Bench Events

go test -bench -json output. Vizb extracts the output field from each event and converts to text before parsing.

go test -bench . -json | vizb -o output.html

Vizb JSON

Previously generated vizb JSON output. Loaded directly without re-parsing.

vizb bench.txt -o data.json
vizb data.json -o output.html

Processing Steps

1. Input — file argument or stdin pipe written to temp file
2. Preprocess — JSON bench events converted to text (if needed)
3. Detect Parser — maps input to a language-specific parser via the registry (Go/Vitest/TinyBench/Criterion/Divan)
4. Parse — language-specific parser extracts name and stats from the benchmark output
5. Group — --group-pattern or --group-regex splits benchmark names into dimensions (n, x, y)
6. Build — assemble Benchmark struct with metadata and settings
7. Output — JSON (json.Marshal) or HTML (Vue template + embedded JSON)