feat(json-report): enhance health check reporting with JSON output and core filtering

- Introduced JSON serialization for health check results, allowing machine-readable output for CI integration.
- Added a `--json` flag to the command line interface to enable JSON reporting.
- Implemented core filtering in the UI, allowing users to filter examples based on the core configuration.
- Enhanced the web interface to display additional metadata from the last run, including throughput and verdicts.

These changes improve the usability and integration of health checks in CI environments, providing clearer insights into test results.

Author: hiddifydeveloper

cmd/main.go

@@ -3,6 +3,7 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"io/fs"
@@ -35,8 +36,60 @@ var (
 	flagExamplesDir string
 	flagTimeout     int
 	flagQuiet       bool
+	flagJSON        bool
+	flagCore        string
 )
 
+// jsonCheck is the CI-friendly serialization of a single health check.
+type jsonCheck struct {
+	Name     string `json:"name"`
+	OK       bool   `json:"ok"`
+	Optional bool   `json:"optional"`
+	Extra    string `json:"extra,omitempty"`
+	Error    string `json:"error,omitempty"`
+}
+
+// jsonResult is the CI-friendly serialization of one variant's run.
+type jsonResult struct {
+	Dir         string      `json:"dir"`
+	Name        string      `json:"name"`
+	Variant     string      `json:"variant,omitempty"`
+	Core        string      `json:"core,omitempty"`
+	CoreVersion string      `json:"core_version,omitempty"`
+	Pass        bool        `json:"pass"`
+	Censor      string      `json:"censor,omitempty"`
+	DurationMs  int64       `json:"duration_ms"`
+	Checks      []jsonCheck `json:"checks"`
+	Error       string      `json:"error,omitempty"`
+}
+
+// jsonReport is the top-level CI output for run-all.
+type jsonReport struct {
+	Passed  int          `json:"passed"`
+	Failed  int          `json:"failed"`
+	Results []jsonResult `json:"results"`
+}
+
+func toJSONResult(dir, core string, res *runner.Result) jsonResult {
+	jr := jsonResult{
+		Dir: dir, Name: res.Name, Variant: res.Variant, Core: core,
+		CoreVersion: res.CoreVersion, Pass: res.Pass,
+		Censor:     res.Fingerprint.Verdict,
+		DurationMs: res.Duration.Milliseconds(),
+	}
+	if res.Err != nil {
+		jr.Error = res.Err.Error()
+	}
+	for _, c := range res.Checks {
+		jc := jsonCheck{Name: c.Name, OK: c.OK, Optional: c.Optional, Extra: c.Extra}
+		if c.Err != nil {
+			jc.Error = c.Err.Error()
+		}
+		jr.Checks = append(jr.Checks, jc)
+	}
+	return jr
+}
+
 func rootCmd() *cobra.Command {
 	root := &cobra.Command{
 		Use:   "hiddify-health",
@@ -62,7 +115,7 @@ func rootCmd() *cobra.Command {
 // --- run ---
 
 func runCmd() *cobra.Command {
-	return &cobra.Command{
+	c := &cobra.Command{
 		Use:   "run <example-dir>",
 		Short: "Run one example test",
 		Args:  cobra.ExactArgs(1),
@@ -71,22 +124,43 @@ func runCmd() *cobra.Command {
 			if db != nil {
 				defer db.Close()
 			}
-			return runOne(cmd.Context(), args[0], db)
+			jrs, anyFail := runOne(cmd.Context(), args[0], db)
+			if flagJSON {
+				printJSONReport(jrs)
+			}
+			if anyFail {
+				return fmt.Errorf("test failed")
+			}
+			return nil
 		},
 	}
+	c.Flags().BoolVar(&flagJSON, "json", false, "emit machine-readable JSON report (for CI)")
+	return c
 }
 
-func runOne(ctx context.Context, dir string, db *store.DB) error {
-	fmt.Printf("▶ %s\n", dir)
+// runOne runs every variant of one example, persists to db, prints the
+// human log/summary (unless --json), and returns the JSON results plus
+// whether any variant failed.
+func runOne(ctx context.Context, dir string, db *store.DB) ([]jsonResult, bool) {
 	logOut := io.Writer(os.Stdout)
-	if flagQuiet {
+	if flagQuiet || flagJSON {
 		logOut = io.Discard
 	}
+	if !flagJSON {
+		fmt.Printf("▶ %s\n", dir)
+	}
+
+	core := coreOf(dir)
 	results, err := runner.Run(ctx, dir, logOut)
-	if err != nil {
-		fmt.Printf("  ERROR: %v\n", err)
-		return err
+	if err != nil && len(results) == 0 {
+		// Hard failure before any variant produced a result.
+		if !flagJSON {
+			fmt.Printf("  ERROR: %v\n", err)
+		}
+		return []jsonResult{{Dir: dir, Name: filepath.Base(dir), Core: core, Pass: false, Error: err.Error()}}, true
 	}
+
+	var jrs []jsonResult
 	anyFail := false
 	for _, res := range results {
 		if db != nil {
@@ -104,34 +178,63 @@ func runOne(ctx context.Context, dir string, db *store.DB) error {
 			}
 			_, _ = db.Save(rec)
 		}
-		status := "PASS"
+		jrs = append(jrs, toJSONResult(dir, core, res))
 		if !res.Pass {
-			status = "FAIL"
 			anyFail = true
 		}
-		label := res.Name
-		if res.Variant != "" && res.Variant != res.Name {
-			label = res.Variant
-		}
-		fmt.Printf("  [%s] %s  duration=%s  censor=%s\n",
-			label, status, res.Duration.Round(time.Millisecond), res.Fingerprint.Verdict)
-		if res.Err != nil {
-			fmt.Printf("    error: %v\n", res.Err)
+		if !flagJSON {
+			status := "PASS"
+			if !res.Pass {
+				status = "FAIL"
+			}
+			label := res.Name
+			if res.Variant != "" && res.Variant != res.Name {
+				label = res.Variant
+			}
+			fmt.Printf("  [%s] %s  duration=%s  censor=%s\n",
+				label, status, res.Duration.Round(time.Millisecond), res.Fingerprint.Verdict)
+			if res.Err != nil {
+				fmt.Printf("    error: %v\n", res.Err)
+			}
 		}
 	}
-	if anyFail {
-		return fmt.Errorf("test failed")
+	return jrs, anyFail
+}
+
+// coreOf returns the core name declared in dir's run config ("" if unknown).
+func coreOf(dir string) string {
+	cfg, err := runner.LoadRunConfig(dir)
+	if err != nil {
+		return ""
 	}
-	return nil
+	return cfg.Core
+}
+
+func printJSONReport(results []jsonResult) {
+	rep := jsonReport{Results: results}
+	for _, r := range results {
+		if r.Pass {
+			rep.Passed++
+		} else {
+			rep.Failed++
+		}
+	}
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(rep)
 }
 
 // --- run-all ---
 
 func runAllCmd() *cobra.Command {
-	return &cobra.Command{
+	c := &cobra.Command{
 		Use:   "run-all [examples-dir]",
 		Short: "Run all examples; exit 1 if any fail",
-		Args:  cobra.MaximumNArgs(1),
+		Long: "Run all examples under the given directory (default: ./examples).\n" +
+			"Pass a subdirectory to test only that subtree, e.g.\n" +
+			"  hiddify-health run-all examples/xray\n" +
+			"Filter by core with --core, e.g. --core sing-box.",
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			root := flagExamplesDir
 			if len(args) > 0 {
@@ -141,8 +244,15 @@ func runAllCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			if flagCore != "" {
+				dirs = filterByCore(dirs, flagCore)
+			}
 			if len(dirs) == 0 {
-				fmt.Println("No run.json files found under", root)
+				if !flagJSON {
+					fmt.Println("No matching examples found under", root)
+				} else {
+					printJSONReport(nil)
+				}
 				return nil
 			}
 
@@ -151,21 +261,42 @@ func runAllCmd() *cobra.Command {
 				defer db.Close()
 			}
 
+			var allJRS []jsonResult
 			pass, fail := 0, 0
 			for _, dir := range dirs {
-				if err := runOne(cmd.Context(), dir, db); err != nil {
+				jrs, anyFail := runOne(cmd.Context(), dir, db)
+				allJRS = append(allJRS, jrs...)
+				if anyFail {
 					fail++
 				} else {
 					pass++
 				}
 			}
-			fmt.Printf("\n--- %d passed  %d failed ---\n", pass, fail)
+			if flagJSON {
+				printJSONReport(allJRS)
+			} else {
+				fmt.Printf("\n--- %d passed  %d failed ---\n", pass, fail)
+			}
 			if fail > 0 {
 				return fmt.Errorf("%d test(s) failed", fail)
 			}
 			return nil
 		},
 	}
+	c.Flags().BoolVar(&flagJSON, "json", false, "emit machine-readable JSON report (for CI)")
+	c.Flags().StringVar(&flagCore, "core", "", "only run examples for this core (e.g. sing-box, xray)")
+	return c
+}
+
+// filterByCore keeps only example dirs whose run config declares the given core.
+func filterByCore(dirs []string, core string) []string {
+	var out []string
+	for _, dir := range dirs {
+		if coreOf(dir) == core {
+			out = append(out, dir)
+		}
+	}
+	return out
 }
 
 // --- check ---

hiddify-health

@@ -304,6 +304,7 @@ func runVariant(ctx context.Context, dir string, cfg RunConfig, v Variant, out i
 		}
 		log.Printf("%s", msg)
 	}
+	res.Checks = hresults
 	res.Pass = pass
 	res.Fingerprint = detect.Passive(hresults)
 

internal/runner/runner.go

@@ -15,6 +15,7 @@
   .example.active{background:#1e2a3a}
   .ex-name{font-weight:600;font-size:.9rem}
   .ex-core{font-size:.75rem;color:#718096;margin-top:2px}
+  .ex-meta{font-size:.7rem;color:#718096;margin-top:3px}
   .badge{display:inline-block;padding:2px 7px;border-radius:9px;font-size:.7rem;font-weight:700;margin-top:4px}
   .badge.pass{background:#065f46;color:#6ee7b7}
   .badge.fail{background:#7f1d1d;color:#fca5a5}
@@ -61,6 +62,7 @@
   #btn-run-all{width:calc(100% - 32px);margin:10px 16px;background:#065f46;color:#fff}
   #btn-run-all:hover{background:#047857}
   #btn-run-all:disabled{background:#374151;color:#6b7280;cursor:not-allowed}
+  #core-filter{margin:0 16px 8px;padding:6px 8px;background:#0d1117;border:1px solid #2d3748;border-radius:6px;color:#e2e8f0;font-size:.8rem;width:calc(100% - 32px)}
   #summary-table{width:100%;border-collapse:collapse;font-size:.82rem}
   #summary-table th,#summary-table td{padding:7px 10px;text-align:left;border-bottom:1px solid #1a202c}
   #summary-table th{color:#718096;font-size:.72rem;text-transform:uppercase;position:sticky;top:0;background:#0d1117}
@@ -73,6 +75,7 @@
 <div id="sidebar">
   <h1>🛡 Hiddify Health</h1>
   <button id="btn-run-all">▶ Run All</button>
+  <select id="core-filter" title="Filter by core"><option value="">All cores</option></select>
   <div id="examples"><div class="welcome">Loading…</div></div>
 </div>
 
@@ -107,23 +110,57 @@ <h2 id="title">Select an example</h2>
   const res = await fetch('/api/examples');
   const items = await res.json() || [];
   examplesList = items;
+  // Populate the core filter dropdown (preserve current selection).
+  const sel = document.getElementById('core-filter');
+  const cur = sel.value;
+  const cores = [...new Set(items.map(i => i.core).filter(Boolean))].sort();
+  sel.innerHTML = '<option value="">All cores</option>' +
+    cores.map(c => `<option value="${c}">${c}</option>`).join('');
+  sel.value = cur;
+  renderExamples();
+}
+
+function visibleExamples() {
+  const core = document.getElementById('core-filter').value;
+  return core ? examplesList.filter(i => i.core === core) : examplesList;
+}
+
+function renderExamples() {
+  const items = visibleExamples();
   const el = document.getElementById('examples');
-  if (!items.length) { el.innerHTML='<div class="welcome">No examples found.<br>Add run.json files to the examples/ directory.</div>'; return; }
+  if (!items.length) { el.innerHTML='<div class="welcome">No examples for this filter.</div>'; return; }
   el.innerHTML = '';
   items.forEach(item => {
     const div = document.createElement('div');
     div.className = 'example';
     div.dataset.dir = item.dir;
-    let badge = '';
-    if (item.last_run) {
-      badge = `<span class="badge ${item.last_run.pass?'pass':'fail'}">${item.last_run.pass?'PASS':'FAIL'}</span>`;
-    }
-    div.innerHTML = `<div class="ex-name">${item.name}</div><div class="ex-core">${item.core||''}</div>${badge}`;
+    div.innerHTML = `<div class="ex-name">${item.name}</div><div class="ex-core">${item.core||''}</div>${lastRunMeta(item.last_run)}`;
     div.onclick = () => selectExample(item);
     el.appendChild(div);
   });
 }
 
+// lastRunMeta renders the PASS/FAIL badge plus censor verdict + throughput
+// from the last stored run (store.Record marshals fields PascalCase).
+function lastRunMeta(rec) {
+  if (!rec) return '<div class="ex-meta">not run yet</div>';
+  const badge = `<span class="badge ${rec.Pass?'pass':'fail'}">${rec.Pass?'PASS':'FAIL'}</span>`;
+  let meta = '';
+  const fp = rec.Fingerprint || {};
+  if (fp.Verdict && fp.Verdict !== 'unknown') {
+    const cls = 'fp-'+fp.Verdict;
+    meta += `<span class="fp-badge ${cls}" style="margin:4px 6px 0 0;font-size:.65rem;padding:1px 6px">${fp.Verdict}</span>`;
+  }
+  let speed = '';
+  (rec.Checks||[]).forEach(c => {
+    if ((c.Name==='download'||c.Name==='speedtest') && c.Throughput) {
+      speed = (c.Throughput/1024).toFixed(0)+' KB/s';
+    }
+  });
+  if (speed) meta += `<span class="ex-meta" style="display:inline">⚡ ${speed}</span>`;
+  return `<div style="margin-top:4px">${badge}${meta}</div>`;
+}
+
 function selectExample(item) {
   selectedDir = item.dir;
   document.getElementById('title').textContent = item.name;
@@ -314,9 +351,11 @@ <h2 id="title">Select an example</h2>
 let runAllActive = false;
 
 document.getElementById('btn-run-all').onclick = runAll;
+document.getElementById('core-filter').addEventListener('change', renderExamples);
 
 async function runAll() {
-  if (runAllActive || !examplesList.length) return;
+  const toRun = visibleExamples();
+  if (runAllActive || !toRun.length) return;
   runAllActive = true;
   const btnAll = document.getElementById('btn-run-all');
   btnAll.disabled = true;
@@ -336,7 +375,7 @@ <h2 id="title">Select an example</h2>
   document.getElementById('checks-list').innerHTML = '<h3>Results</h3>';
   const tbody = log.querySelector('tbody');
 
-  for (const item of examplesList) {
+  for (const item of toRun) {
     const phRow = document.createElement('tr');
     phRow.innerHTML = `<td>${item.name}</td><td colspan="${CHECKS_ORDER.length+4}"><span class="badge running">RUNNING</span></td>`;
     tbody.appendChild(phRow);