feat: add HTML report timestamps and titles

Author: mktbsh

README.md

@@ -46,22 +46,23 @@ unispeedtest
 Options:
 
 - `-html <path>`: write a self-contained HTML report
+- `-html-title <title>`: append a title to the HTML report (requires `-html`)
 - `-json`: output compact JSON
 - `-pretty`: output indented JSON (implies `-json`)
 - `-v`, `--version`: print the CLI version and exit
 
 Examples:
 
 ```sh
-unispeedtest -html report.html
+unispeedtest -html report.html -html-title "Home Wi-Fi"
 unispeedtest -json
 unispeedtest -pretty
 unispeedtest --version
 ```
 
 ## HTML report
 
-`-html <path>` writes a responsive, self-contained report with no external assets or JavaScript. Normal terminal or JSON output is preserved, so the flag can be combined with `-json` or `-pretty`. An existing file at the path is overwritten.
+`-html <path>` writes a responsive, self-contained report with no external assets. The measurement time is stored as Unix epoch milliseconds and formatted in the viewer's locale and time zone by inline JavaScript. `-html-title "Home Wi-Fi"` changes the document title and heading to `Internet Speed Report - Home Wi-Fi`. Normal terminal or JSON output is preserved, so the flag can be combined with `-json` or `-pretty`. An existing file at the path is overwritten.
 
 ## JSON output shape
 

ROADMAP.md

@@ -35,6 +35,7 @@ Build a fast, reliable, script-friendly speed test CLI that supports multiple pr
 ## Phase 3: CLI and Output Enhancements
 
 - [x] Add self-contained HTML report export with `-html <path>`.
+- [x] Add measurement time and an optional title to HTML reports.
 - [ ] Add machine-readable metadata (`timestamp`, `provider`, `version`).
 - [ ] Add NDJSON / compact streaming output mode for automation pipelines.
 - [ ] Add optional result export (`--out` JSON file).

cmd/unispeedtest/main.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"os/signal"
 	"runtime/debug"
+	"time"
 
 	"github.com/hsblabs/universal-speedtest-cli/internal/cloudflare"
 	"github.com/hsblabs/universal-speedtest-cli/internal/color"
@@ -18,7 +19,7 @@ import (
 var (
 	version         = ""
 	buildInfoReader = debug.ReadBuildInfo
-	benchmarkMain   = func(jsonOut, prettyOut bool, htmlPath string, stdout, stderr io.Writer) int {
+	benchmarkMain   = func(jsonOut, prettyOut bool, htmlPath, htmlTitle string, stdout, stderr io.Writer) int {
 		if prettyOut {
 			jsonOut = true
 		}
@@ -49,7 +50,7 @@ var (
 
 		progress("%sInitializing Cloudflare Speed Test...%s\n\n", color.Bold, color.Reset)
 
-		var result reporter.Result
+		result := reporter.Result{MeasuredAtUnixMs: time.Now().UnixMilli()}
 		var warnings []string
 
 		meta, err := cloudflare.FetchMeta()
@@ -136,7 +137,7 @@ var (
 		result.Warnings = warnings
 
 		if htmlPath != "" {
-			if err := writeHTMLReport(htmlPath, result); err != nil {
+			if err := writeHTMLReport(htmlPath, htmlTitle, result); err != nil {
 				fmt.Fprintf(stderr, "error writing HTML report: %v\n", err)
 				return 1
 			}
@@ -184,9 +185,9 @@ func main() {
 	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
 }
 
-func writeHTMLReport(path string, result reporter.Result) error {
+func writeHTMLReport(path, title string, result reporter.Result) error {
 	var report bytes.Buffer
-	if err := reporter.PrintHTML(&report, result); err != nil {
+	if err := reporter.PrintHTML(&report, result, title); err != nil {
 		return err
 	}
 	return os.WriteFile(path, report.Bytes(), 0o644)
@@ -204,15 +205,20 @@ func run(args []string, stdout, stderr io.Writer) int {
 	jsonOut := fs.Bool("json", false, "Output results in JSON format")
 	prettyOut := fs.Bool("pretty", false, "Output pretty-printed JSON (implies -json)")
 	htmlPath := fs.String("html", "", "Write a self-contained HTML report to path")
+	htmlTitle := fs.String("html-title", "", "Set the HTML report title suffix (requires -html)")
 
 	if err := fs.Parse(args); err != nil {
 		if err == flag.ErrHelp {
 			return 0
 		}
 		return 2
 	}
+	if *htmlTitle != "" && *htmlPath == "" {
+		fmt.Fprintln(stderr, "error: -html-title requires -html")
+		return 2
+	}
 
-	return benchmarkMain(*jsonOut, *prettyOut, *htmlPath, stdout, stderr)
+	return benchmarkMain(*jsonOut, *prettyOut, *htmlPath, *htmlTitle, stdout, stderr)
 }
 
 func float64Ptr(value float64) *float64 {

cmd/unispeedtest/main_test.go

@@ -93,7 +93,7 @@ func TestRunVersionFlagPrintsAndExits(t *testing.T) {
 	})
 
 	version = "v1.2.3"
-	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath string, stdout, stderr io.Writer) int {
+	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath, htmlTitle string, stdout, stderr io.Writer) int {
 		t.Fatal("benchmark path should not run for version flags")
 		return 1
 	}
@@ -122,7 +122,7 @@ func TestRunShortVersionFlagPrintsAndExits(t *testing.T) {
 	})
 
 	version = "v9.9.9"
-	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath string, stdout, stderr io.Writer) int {
+	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath, htmlTitle string, stdout, stderr io.Writer) int {
 		t.Fatal("benchmark path should not run for version flags")
 		return 1
 	}
@@ -149,7 +149,7 @@ func TestRunHelpFlagPrintsUsageAndExitsZero(t *testing.T) {
 		benchmarkMain = oldBenchmark
 	})
 
-	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath string, stdout, stderr io.Writer) int {
+	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath, htmlTitle string, stdout, stderr io.Writer) int {
 		t.Fatal("benchmark path should not run for help flags")
 		return 1
 	}
@@ -170,21 +170,44 @@ func TestRunHelpFlagPrintsUsageAndExitsZero(t *testing.T) {
 	}
 }
 
-func TestRunHTMLFlagPassesOutputPath(t *testing.T) {
+func TestRunHTMLFlagsPassOutputOptions(t *testing.T) {
 	oldBenchmark := benchmarkMain
 	t.Cleanup(func() {
 		benchmarkMain = oldBenchmark
 	})
 
-	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath string, stdout, stderr io.Writer) int {
+	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath, htmlTitle string, stdout, stderr io.Writer) int {
 		if htmlPath != "report.html" {
 			t.Fatalf("htmlPath = %q, want %q", htmlPath, "report.html")
 		}
+		if htmlTitle != "Home" {
+			t.Fatalf("htmlTitle = %q, want %q", htmlTitle, "Home")
+		}
 		return 0
 	}
 
-	if exitCode := run([]string{"-html", "report.html"}, io.Discard, io.Discard); exitCode != 0 {
-		t.Fatalf("run(-html report.html) exit code = %d, want 0", exitCode)
+	if exitCode := run([]string{"-html", "report.html", "-html-title", "Home"}, io.Discard, io.Discard); exitCode != 0 {
+		t.Fatalf("run() exit code = %d, want 0", exitCode)
+	}
+}
+
+func TestRunRejectsHTMLTitleWithoutHTMLPath(t *testing.T) {
+	oldBenchmark := benchmarkMain
+	t.Cleanup(func() {
+		benchmarkMain = oldBenchmark
+	})
+
+	benchmarkMain = func(jsonOut, prettyOut bool, htmlPath, htmlTitle string, stdout, stderr io.Writer) int {
+		t.Fatal("benchmark path should not run for invalid flags")
+		return 1
+	}
+
+	var stderr bytes.Buffer
+	if exitCode := run([]string{"-html-title", "Home"}, io.Discard, &stderr); exitCode != 2 {
+		t.Fatalf("run() exit code = %d, want 2", exitCode)
+	}
+	if got := stderr.String(); !strings.Contains(got, "-html-title requires -html") {
+		t.Fatalf("stderr = %q, want dependency error", got)
 	}
 }
 
@@ -195,7 +218,7 @@ func TestWriteHTMLReport(t *testing.T) {
 		t.Fatalf("os.WriteFile() error = %v", err)
 	}
 
-	if err := writeHTMLReport(path, reporter.Result{DownloadMbps: &download}); err != nil {
+	if err := writeHTMLReport(path, "Home", reporter.Result{DownloadMbps: &download}); err != nil {
 		t.Fatalf("writeHTMLReport() error = %v", err)
 	}
 
@@ -206,6 +229,9 @@ func TestWriteHTMLReport(t *testing.T) {
 	if output := string(data); !strings.Contains(output, "123.40") {
 		t.Fatalf("HTML report missing download speed:\n%s", output)
 	}
+	if output := string(data); !strings.Contains(output, "Internet Speed Report - Home") {
+		t.Fatalf("HTML report missing custom title:\n%s", output)
+	}
 	if strings.Contains(string(data), "old report") {
 		t.Fatalf("HTML report did not replace existing file:\n%s", data)
 	}

docs/README/ja.md

@@ -46,22 +46,25 @@ unispeedtest
 オプション:
 
 - `-html <path>`: 自己完結 HTML レポートを保存
+- `-html-title <title>`: HTML レポートへタイトルを追加（`-html` が必要）
 - `-json`: JSON（1行）で出力
 - `-pretty`: 整形済み JSON で出力（`-json` を含む）
 - `-v`, `--version`: CLI バージョンを表示して終了
 
 例:
 
 ```sh
-unispeedtest -html report.html
+unispeedtest -html report.html -html-title "自宅 Wi-Fi"
 unispeedtest -json
 unispeedtest -pretty
 unispeedtest --version
 ```
 
 ## HTML レポート
 
-`-html <path>` は、外部アセットと JavaScript を使わないレスポンシブな単一 HTML レポートを保存します。
+`-html <path>` は、外部アセットを使わないレスポンシブな単一 HTML レポートを保存します。
+計測日時は Unix エポックミリ秒で記録し、インライン JavaScript が閲覧環境のロケールとタイムゾーンに合わせて表示します。
+`-html-title "自宅 Wi-Fi"` を指定すると、文書タイトルと見出しは `Internet Speed Report - 自宅 Wi-Fi` になります。
 通常のターミナル出力や JSON 出力は維持されるため、`-json` または `-pretty` と併用できます。
 指定パスに既存ファイルがある場合は上書きします。
 

internal/reporter/html.go

@@ -14,7 +14,7 @@ var htmlReportTemplate = template.Must(template.New("report").Funcs(template.Fun
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Internet Speed Report</title>
+  <title>{{.Title}}</title>
   <style>
     :root {
       color-scheme: light dark;
@@ -27,6 +27,7 @@ var htmlReportTemplate = template.Must(template.New("report").Funcs(template.Fun
     main { width: min(960px, calc(100% - 32px)); margin: 0 auto; padding: 48px 0; }
     header { margin-bottom: 24px; }
     h1 { margin: 0; font-size: clamp(1.75rem, 4vw, 2.5rem); letter-spacing: -0.04em; }
+    .measured-at { margin: 8px 0 0; color: #65718a; font-size: 0.9rem; }
     h2 { margin: 0; font-size: 0.8rem; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase; color: #65718a; }
     .speed-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 16px; }
     .card, .panel { background: #fff; border: 1px solid #dde3ed; border-radius: 16px; box-shadow: 0 8px 24px rgba(26, 39, 64, 0.06); }
@@ -59,7 +60,7 @@ var htmlReportTemplate = template.Must(template.New("report").Funcs(template.Fun
     @media (prefers-color-scheme: dark) {
       :root { color: #edf2fa; background: #101522; }
       body { background: #101522; }
-      h2, .speed-value span, .metric dt, .metric dd span, .network dt { color: #9da9bf; }
+      h2, .measured-at, .speed-value span, .metric dt, .metric dd span, .network dt { color: #9da9bf; }
       .card, .panel { background: #171e2e; border-color: #2a3448; box-shadow: none; }
       .metric { background: #101522; }
       .warnings { background: #2a2213; border-color: #765b27; }
@@ -68,7 +69,10 @@ var htmlReportTemplate = template.Must(template.New("report").Funcs(template.Fun
 </head>
 <body>
   <main>
-    <header><h1>Internet Speed Report</h1></header>
+    <header>
+      <h1>{{.Title}}</h1>
+      <p class="measured-at">Measured <time data-unix-ms="{{.MeasuredAtUnixMs}}">{{.MeasuredAtUnixMs}}</time></p>
+    </header>
 
     <section class="speed-grid" aria-label="Transfer speed">
       <article class="card speed-card download">
@@ -109,13 +113,29 @@ var htmlReportTemplate = template.Must(template.New("report").Funcs(template.Fun
     </section>
     {{end}}
   </main>
+  <script>
+    const measuredAt = document.querySelector("[data-unix-ms]");
+    const measuredAtDate = new Date(Number(measuredAt.dataset.unixMs));
+    measuredAt.dateTime = measuredAtDate.toISOString();
+    measuredAt.textContent = measuredAtDate.toLocaleString();
+  </script>
 </body>
 </html>
 `))
 
+type htmlReportData struct {
+	Result
+	Title string
+}
+
 // PrintHTML writes a self-contained HTML report to w.
-func PrintHTML(w io.Writer, r Result) error {
-	return htmlReportTemplate.Execute(w, r)
+func PrintHTML(w io.Writer, r Result, title string) error {
+	if title == "" {
+		title = "Internet Speed Report"
+	} else {
+		title = "Internet Speed Report - " + title
+	}
+	return htmlReportTemplate.Execute(w, htmlReportData{Result: r, Title: title})
 }
 
 func formatHTMLNumber(value *float64, precision int) string {

internal/reporter/printer.go

@@ -10,6 +10,7 @@ import (
 
 // Result holds all measurements from a speed test run.
 type Result struct {
+	MeasuredAtUnixMs  int64
 	DownloadMbps      *float64
 	UploadMbps        *float64
 	UnloadedLatency   *float64

internal/reporter/printer_test.go

@@ -72,21 +72,26 @@ func TestPrintHTMLRendersResultAndEscapesContent(t *testing.T) {
 	network := "Example <Network>"
 
 	result := reporter.Result{
-		DownloadMbps: &download,
-		UploadMbps:   &upload,
-		PacketLoss:   &packetLoss,
-		NetworkASOrg: &network,
-		Warnings:     []string{"measurement <script>alert(1)</script>"},
+		MeasuredAtUnixMs: 1723456789012,
+		DownloadMbps:     &download,
+		UploadMbps:       &upload,
+		PacketLoss:       &packetLoss,
+		NetworkASOrg:     &network,
+		Warnings:         []string{"measurement <script>alert(1)</script>"},
 	}
 
 	var buf bytes.Buffer
-	if err := reporter.PrintHTML(&buf, result); err != nil {
+	if err := reporter.PrintHTML(&buf, result, "Home <Lab>"); err != nil {
 		t.Fatalf("PrintHTML() error = %v", err)
 	}
 
 	output := buf.String()
 	for _, want := range []string{
 		"<!doctype html>",
+		"<title>Internet Speed Report - Home &lt;Lab&gt;</title>",
+		"<h1>Internet Speed Report - Home &lt;Lab&gt;</h1>",
+		`data-unix-ms="1723456789012"`,
+		"toLocaleString()",
 		"225.14",
 		"102.87",
 		"Example &lt;Network&gt;",
@@ -99,9 +104,19 @@ func TestPrintHTMLRendersResultAndEscapesContent(t *testing.T) {
 	if strings.Contains(output, "<script>alert(1)</script>") {
 		t.Fatalf("PrintHTML() output contains unescaped warning\n%s", output)
 	}
-	for _, forbidden := range []string{"<script", " src=", " href="} {
+	for _, forbidden := range []string{" src=", " href="} {
 		if strings.Contains(output, forbidden) {
 			t.Fatalf("PrintHTML() output contains external or executable content %q\n%s", forbidden, output)
 		}
 	}
 }
+
+func TestPrintHTMLUsesDefaultTitle(t *testing.T) {
+	var buf bytes.Buffer
+	if err := reporter.PrintHTML(&buf, reporter.Result{}, ""); err != nil {
+		t.Fatalf("PrintHTML() error = %v", err)
+	}
+	if output := buf.String(); !strings.Contains(output, "<title>Internet Speed Report</title>") {
+		t.Fatalf("PrintHTML() output missing default title\n%s", output)
+	}
+}