Performance Benchmarking Toolkit
Relevant source files
The following files were used as context for generating this wiki page:
The Performance Benchmarking Toolkit provides an automated framework for measuring, reporting, and comparing the performance of Termul applications. It captures metrics across multiple layers, including page-level interaction latency, system process resource usage, and React component commit statistics. The toolkit writes execution results to a structured JSON format and generates self-contained HTML reports for manual or automated analysis.
Sources: tools/perf/types.ts:7-14, tools/perf/report/html-report.ts:4-10
Core Architecture
The toolkit operates through a scenario-based execution model. A central harness executes scenarios, manages metric collectors, and aggregates data into a PerfRunResult. Results are saved in tools/perf/results/<run-id>/result.json.
The diagram shows the data flow from the CLI trigger through metric collection to the final report generation and comparison.
Sources: tools/perf/types.ts:7-14, tools/perf/report/html-report.ts:4-10
Data Structures and Metrics
PerfRunResult
The PerfRunResult is the primary output of a benchmarking run. It contains metadata about the environment and a list of phase results.
| Field | Type | Description |
|---|---|---|
meta | RunMeta | Execution context (Run ID, Scenario, Seed, Git Commit). |
phases | PhaseResult[] | Individual measurements for warmup, sustain, and measurement cycles. |
summary | Record<string, number> | Flattened aggregate metrics used for comparisons. |
Sources: tools/perf/types.ts:153-157
Metric Categories
The toolkit captures three distinct categories of metrics:
- Page Metrics: Includes Long Animation Frames (LoAF), interaction-to-next-paint latencies, and JS heap usage.
- Process Metrics: Tracks renderer private bytes, working set size, and CPU percentage.
- React Metrics: Measures component commit counts and render durations.
Sources: tools/perf/types.ts:71-115
Statistical Analysis
The toolkit uses linear regression to calculate trends in resource consumption, specifically for memory leaks. The slopeBytesPerSec function determines the rate of change for a metric series over time.
export function slopeBytesPerSec(samples: MetricSample[]): number {
const n = samples.length
if (n < 2) return 0
let sumX = 0, sumY = 0
for (const s of samples) {
sumX += s.t
sumY += s.value
}
const meanX = sumX / n
const meanY = sumY / n
let num = 0, den = 0
for (const s of samples) {
num += (s.t - meanX) * (s.value - meanY)
den += (s.t - meanX) ** 2
}
if (den === 0) return 0
return (num / den) * 1000
}
Sources: tools/perf/types.ts:182-205
Reporting and Comparison
The toolkit generates self-contained HTML reports that require no external dependencies or network access. These reports visualize metric series using inline SVG sparklines and identify top-blocking scripts or components.
HTML Report Components
- Headline Numbers: Summary of LoAF count, blocking totals, and interaction latencies.
- Top Scripts/Components: Lists of scripts and components by total duration or commit count.
- Sparklines: Normalized visual representations of heap and CPU usage.
Sources: tools/perf/report/html-report.ts:4-10, tools/perf/report/html-report.ts:89-146
Comparison Logic
The compare command evaluates a new run against a base run. It calculates deltas between medians and determines a verdict: improved, regressed, flat, or gap.
| Verdict | Condition |
|---|---|
improved | Metric delta is below the improvement threshold. |
regressed | Metric delta exceeds the regression threshold. |
flat | Metric delta is within neutral bounds. |
gap | Metric is missing from one of the runs. |
Sources: tools/perf/types.ts:162-171
Conclusion
The Performance Benchmarking Toolkit ensures project reliability by providing high-fidelity resource and interaction metrics. By automating the comparison of runs, it enables developers to detect regressions in memory management and UI responsiveness early in the development cycle.