Files
Homelab-manager/server/test/grafanaDashboard.test.ts
bobbanandClaude Sonnet 5.5 8f5068c6e0 Add an Up for panel to the generated Grafana dashboard
One tile per server, time() - homelab_server_boot_time_seconds, in the Servers
row and following the Server picker.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 21:59:59 +01:00

186 lines
9.3 KiB
TypeScript

/**
* 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", "homelab_server_boot_time_seconds",
]) assert.ok(asked.has(m), `${m} has no panel`);
});
test("a server's time since it last started is shown, per server, in seconds, and follows the Server picker", () => {
const p = panels.find((x) => x.title === "Up for")!;
assert.ok(p, "there is an Up for panel");
assert.equal(p.type, "stat");
assert.equal(p.targets![0].expr, 'time() - homelab_server_boot_time_seconds{server=~"$server"}');
assert.equal(p.targets![0].legendFormat, "{{server}}");
assert.equal((p as unknown as { fieldConfig: { defaults: { unit: string } } }).fieldConfig.defaults.unit, "s");
});
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<Server>((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);
});
});