/** * The Grafana dashboard: that it is a dashboard Grafana will import, that every panel sits on the grid, and — the point of building it * here — that it only asks for series `/metrics` really serves, so renaming one can't quietly blank a panel. * * Run with: npm test --workspace server */ import { test, describe, before, after } from "node:test"; import assert from "node:assert/strict"; import { mkdtempSync, readFileSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import type { AddressInfo } from "node:net"; import type { Server } from "node:http"; const dir = mkdtempSync(join(tmpdir(), "hm-grafana-")); process.env.DATABASE_PATH = join(dir, "test.sqlite"); process.env.SESSION_DIR = join(dir, "sessions"); process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32); const express = (await import("express")).default; const { db } = await import("../src/db/client.js"); const { users } = await import("../src/db/schema.js"); const { runMigrations } = await import("../src/db/migrate.js"); const { buildGrafanaDashboard } = await import("../src/services/grafanaDashboard.js"); const { metricsTokensRouter } = await import("../src/routes/metrics.js"); await runMigrations(); type Panel = { id: number; type: string; title: string; gridPos: { h: number; w: number; x: number; y: number }; targets?: { expr: string; legendFormat: string; refId: string; datasource: { uid: string } }[]; datasource?: { uid: string } }; const dashboard = buildGrafanaDashboard() as { panels: Panel[]; templating: { list: { name: string }[] }; __inputs: { name: string }[]; uid: string; title: string; schemaVersion: number }; const panels = dashboard.panels; const withQueries = panels.filter((p) => p.targets); const exprs = withQueries.flatMap((p) => p.targets!.map((t) => t.expr)); // What /metrics can serve: every series the code that builds it adds. const here = dirname(fileURLToPath(import.meta.url)); const served = new Set([...readFileSync(join(here, "..", "src", "services", "metrics.ts"), "utf8").matchAll(/out\.add\(\s*"(homelab_[a-z0-9_]+)"/g)].map((m) => m[1])); describe("the dashboard is one Grafana will import", () => { test("it has a title, a fixed id, asks which Prometheus to use, and every query uses that choice", () => { assert.equal(dashboard.title, "Homelab Manager"); assert.equal(dashboard.uid, "homelab-manager"); assert.ok(dashboard.schemaVersion >= 36); assert.deepEqual(dashboard.__inputs.map((i) => i.name), ["DS_PROMETHEUS"]); for (const p of withQueries) { assert.equal(p.datasource?.uid, "${DS_PROMETHEUS}", p.title); for (const t of p.targets!) assert.equal(t.datasource.uid, "${DS_PROMETHEUS}", `${p.title} / ${t.refId}`); } }); test("it survives being written out and read back, as an import does", () => { const again = JSON.parse(JSON.stringify(dashboard)); assert.equal(again.panels.length, panels.length); assert.ok(panels.length >= 30, `${panels.length} panels`); }); test("every panel has an id of its own, a title, and sits on the 24-column grid without overlapping another", () => { assert.equal(new Set(panels.map((p) => p.id)).size, panels.length, "ids are unique"); for (const p of panels) { assert.ok(p.title, `panel ${p.id} has no title`); const g = p.gridPos; assert.ok(g.x >= 0 && g.w >= 1 && g.x + g.w <= 24, `${p.title} sits outside the grid: ${JSON.stringify(g)}`); assert.ok(g.h >= 1 && g.y >= 0); } for (let i = 0; i < panels.length; i++) { for (let j = i + 1; j < panels.length; j++) { const a = panels[i].gridPos; const b = panels[j].gridPos; const overlap = a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h; assert.equal(overlap, false, `${panels[i].title} overlaps ${panels[j].title}`); } } }); test("it is in rows, and the rows come in a sensible order", () => { const rows = panels.filter((p) => p.type === "row").map((p) => p.title); assert.deepEqual(rows, ["Needs attention", "Servers", "Disks", "Backups", "Secrets, power and the app itself"]); const ys = panels.filter((p) => p.type === "row").map((p) => p.gridPos.y); assert.deepEqual([...ys].sort((a, b) => a - b), ys, "top to bottom"); }); }); describe("what it asks for", () => { test("it asks only for series /metrics serves (and says so if one is renamed)", () => { assert.ok(served.size >= 30, `found ${served.size} served series in metrics.ts`); const asked = new Set(exprs.flatMap((e) => e.match(/\bhomelab_[a-z0-9_]+\b/g) ?? [])); assert.ok(asked.size >= 25, `the dashboard uses ${asked.size} series`); const missing = [...asked].filter((m) => !served.has(m)); assert.deepEqual(missing, [], `series the dashboard uses that /metrics doesn't serve: ${missing.join(", ")}`); }); test("the big groups of series are all covered", () => { const asked = new Set(exprs.flatMap((e) => e.match(/\bhomelab_[a-z0-9_]+\b/g) ?? [])); for (const m of [ "homelab_alerts", "homelab_incidents_open", "homelab_server_up", "homelab_server_disk_used_percent", "homelab_server_disk_days_to_full", "homelab_server_disk_healthy", "homelab_server_zfs_pool_online", "homelab_backup_guests", "homelab_backup_last_age_seconds", "homelab_selfbackup_last_success_timestamp_seconds", "homelab_secret_expiry_days", "homelab_integration_up", "homelab_server_uptime_ratio_30d", "homelab_server_pending_updates", ]) assert.ok(asked.has(m), `${m} has no panel`); }); test("each query is well-formed: not empty, brackets and quotes balanced, no stray template text", () => { for (const p of withQueries) { for (const t of p.targets!) { const e = t.expr; assert.ok(e.trim().length > 0, `${p.title}: empty query`); for (const [open, close] of [["(", ")"], ["{", "}"], ["[", "]"]]) assert.equal(e.split(open).length, e.split(close).length, `${p.title}: unbalanced ${open}${close} in ${e}`); assert.equal(e.split('"').length % 2, 1, `${p.title}: an unclosed quote in ${e}`); assert.doesNotMatch(e, /undefined|\[object/, `${p.title}: ${e}`); } } }); test("the server picker exists, takes its values from the series, and everything that uses it is told how", () => { const names = dashboard.templating.list.map((v) => v.name); assert.deepEqual(names, ["server"]); const variable = dashboard.templating.list[0] as unknown as { query: { query: string }; allValue: string; multi: boolean }; assert.equal(variable.query.query, "label_values(homelab_server_up, server)"); assert.equal(variable.multi, true); assert.equal(variable.allValue, ".+", "all servers, including ones with no label at all, matches"); const using = exprs.filter((e) => e.includes("$server")); assert.ok(using.length >= 10); for (const e of using) assert.match(e, /\{server=~"\$server"\}/); }); test("series that exist only once something happens use 'or vector(0)' where a stat would otherwise read 'No data'", () => { for (const title of ["Critical alerts", "Warnings", "Servers down", "Integrations failing", "Servers up"]) { const p = withQueries.find((x) => x.title === title)!; assert.match(p.targets![0].expr, /or vector\(0\)/, title); } }); }); describe("downloading it", () => { let app: Server; let base = ""; let who = "ada"; before(async () => { await db.insert(users).values([ { oidcSub: "ada", name: "Ada", role: "admin" }, { oidcSub: "olle", name: "Olle", role: "operator" }, ]); const a = express(); a.use(express.json()); a.use((req, _res, next) => { (req as unknown as { session: unknown }).session = { user: { sub: who } }; next(); }); a.use("/api/metrics-tokens", metricsTokensRouter); app = await new Promise((resolve) => { const x = a.listen(0, "127.0.0.1", () => resolve(x)); }); base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/metrics-tokens`; }); after(() => { app.close(); try { rmSync(dir, { recursive: true, force: true }); } catch { // Windows keeps the database file locked until the process exits. } }); test("an administrator gets it as a file; nobody else does", async () => { who = "olle"; assert.equal((await fetch(`${base}/grafana-dashboard.json`)).status, 403); who = "ada"; const res = await fetch(`${base}/grafana-dashboard.json`); assert.equal(res.status, 200); assert.match(res.headers.get("content-disposition") ?? "", /attachment; filename="homelab-manager-dashboard\.json"/); assert.match(res.headers.get("content-type") ?? "", /application\/json/); const body = await res.json(); assert.equal(body.uid, "homelab-manager"); assert.equal(body.panels.length, panels.length); }); });