/** * Speedtest Tracker: reading what it says (read-only, paged, newest first), what is stored once and for how long, the expected-speed numbers, what is wrong (slow, failing), the health * pass, the alerts, the page's routes and /metrics. * * Run with: npm test --workspace server */ import { test, describe, before, after } from "node:test"; import assert from "node:assert/strict"; import { createServer as createHttpServer, type Server } from "node:http"; import { mkdtempSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import type { AddressInfo } from "node:net"; const dir = mkdtempSync(join(tmpdir(), "hm-speedtest-")); process.env.DATABASE_PATH = join(dir, "test.sqlite"); process.env.SESSION_DIR = join(dir, "sessions"); process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32); process.env.HEALTH_STARTUP_GRACE_MS = "0"; const express = (await import("express")).default; const { db } = await import("../src/db/client.js"); const { users, integrations, speedtestResults } = await import("../src/db/schema.js"); const { runMigrations } = await import("../src/db/migrate.js"); const adapter = await import("../src/integrations/speedtest/adapter.js"); const st = await import("../src/services/speedtestSync.js"); const { evaluateHealth, collectSnapshot } = await import("../src/services/healthMonitor.js"); const { subjectOfConditionKey } = await import("../src/services/maintenance.js"); const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js"); const { speedtestRouter } = await import("../src/routes/speedtest.js"); const { buildMetrics } = await import("../src/services/metrics.js"); const { setInternalFlag } = await import("../src/services/settingsStore.js"); const { eq } = await import("drizzle-orm"); await runMigrations(); const MIN = 60_000; const HOUR = 60 * MIN; const MBIT = 1e6; const iso = (ms: number) => new Date(ms).toISOString(); // What Speedtest Tracker sends: bytes per second (download/upload), the same in bits, a ping in ms, a status and a time. const apiResult = (id: number, extra: Record = {}) => ({ id, service: "faker", ping: 12.5, download: 31_250_000, // 250 Mbit/s in bytes per second upload: 3_125_000, // 25 Mbit/s download_bits: 250_000_000, upload_bits: 25_000_000, healthy: true, status: "completed", scheduled: true, data: { timestamp: "2026-06-01T10:00:00Z" }, created_at: "2026-06-01 10:00:05", ...extra, }); describe("what Speedtest Tracker says", () => { test("a result: speeds in bits per second, the ping, the status in lower case, healthy true, false or not said", () => { const r = adapter.parseResult(apiResult(7, { status: "Completed", healthy: null }))!; assert.deepEqual([r.id, r.status, r.download, r.upload, r.ping, r.healthy], [7, "completed", 250_000_000, 25_000_000, 12.5, null]); assert.equal(adapter.parseResult(apiResult(8, { healthy: false }))!.healthy, false); }); test("without the bits fields the bytes are turned into bits; numbers sent as strings are read; a failed test has no speeds", () => { const r = adapter.parseResult(apiResult(1, { download_bits: undefined, upload_bits: undefined, download: "12500000", upload: 1_250_000 }))!; assert.deepEqual([r.download, r.upload], [100_000_000, 10_000_000]); const failed = adapter.parseResult({ id: 2, status: "failed", created_at: "2026-06-01 10:00:05", download: null, upload: null, ping: null })!; assert.deepEqual([failed.status, failed.download, failed.upload, failed.ping], ["failed", null, null, null]); }); test("when it was made: the time Ookla gives, else created_at taken as UTC (it has no zone); a result with no id or no time is skipped", () => { assert.equal(adapter.parseResult(apiResult(1))!.at, "2026-06-01T10:00:00.000Z"); assert.equal(adapter.parseResult(apiResult(1, { data: null }))!.at, "2026-06-01T10:00:05.000Z"); assert.equal(adapter.parseResult(apiResult(1, { data: null, created_at: "2026-06-01T10:00:05+02:00" }))!.at, "2026-06-01T08:00:05.000Z"); assert.equal(adapter.parseResult({ status: "completed", created_at: "2026-06-01 10:00:05" }), null); assert.equal(adapter.parseResult({ id: 3, status: "completed" }), null); assert.deepEqual(adapter.parseResults({ data: [apiResult(1), "junk", { id: 9 }] }).map((r) => r.id), [1]); assert.deepEqual(adapter.parseResults(null), []); }); describe("the adapter against a Speedtest Tracker that answers", () => { let fake: Server; let url = ""; let tokenStatus = 200; let sizeStatus = 200; let total = 70; const seen: { method: string | undefined; path: string; auth: string | undefined }[] = []; before(async () => { fake = createHttpServer((req, res) => { const u = new URL(req.url ?? "", "http://x"); seen.push({ method: req.method, path: u.pathname + u.search, auth: req.headers.authorization }); const send = (code: number, body: unknown) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(body)); }; if (u.pathname === "/api/healthcheck") return send(200, { message: "Speedtest Tracker is running!" }); if (tokenStatus !== 200) return send(tokenStatus, { message: "no" }); if (u.pathname === "/api/v1/results") { if (u.searchParams.has("page[size]") && sizeStatus === 422) return send(422, { message: "Validation failed." }); const size = Number(u.searchParams.get("page[size]") ?? 15); const page = Number(u.searchParams.get("page[number]") ?? 1); const ids = Array.from({ length: size }, (_, i) => total - (page - 1) * size - i).filter((id) => id > 0); return send(200, { data: ids.map((id) => apiResult(id)), links: {}, meta: {} }); } send(404, {}); }); await new Promise((resolve) => fake.listen(0, "127.0.0.1", resolve)); url = `http://127.0.0.1:${(fake.address() as AddressInfo).port}`; }); after(() => fake.close()); test("pages of 30 are read, newest first, until a short page; with the token as a Bearer and only ever GET — never the run endpoint", async () => { seen.length = 0; const r = await adapter.createSpeedtestAdapter({ url, token: "tok" }).read(5); assert.deepEqual([r.results.length, r.results[0].id, r.results.at(-1)!.id], [70, 70, 1]); assert.deepEqual(seen.map((s) => s.path.replace(/&page\[number\]=\d+|&?sort=-created_at/g, "")).length, 3, "three pages: 30, 30 and a short 10"); assert.ok(seen.every((s) => s.method === "GET" && s.auth === "Bearer tok")); assert.ok(!seen.some((s) => s.path.includes("/speedtests/run"))); }); test("one page by default; a Speedtest Tracker that allows fewer per page (422) is asked again without a size", async () => { assert.equal((await adapter.createSpeedtestAdapter({ url, token: "tok" }).read()).results.length, 30); sizeStatus = 422; const r = await adapter.createSpeedtestAdapter({ url, token: "tok" }).read(); assert.equal(r.results.length, 15); sizeStatus = 200; }); test("a token that is refused, one without the ability, and a dead address are said; ping tries the address without a login and the token on a page of one", async () => { tokenStatus = 401; let ping = await adapter.createSpeedtestAdapter({ url, token: "bad" }).ping(); assert.match(ping.error ?? "", /did not accept the token/); tokenStatus = 403; ping = await adapter.createSpeedtestAdapter({ url, token: "weak" }).ping(); assert.match(ping.error ?? "", /results:read/); tokenStatus = 200; seen.length = 0; ping = await adapter.createSpeedtestAdapter({ url, token: "tok" }).ping(); assert.equal(ping.ok, true); assert.deepEqual(seen.map((s) => [s.path.split("?")[0], s.auth === undefined]), [["/api/healthcheck", true], ["/api/v1/results", false]]); assert.equal((await adapter.createSpeedtestAdapter({ url: "http://127.0.0.1:1", token: "t" }).ping()).ok, false); }); }); }); describe("what you tell it the line is sold at", () => { test("numbers in Mbit/s (a comma is accepted), nothing or nonsense is 'not said', and the share defaults to 60%", () => { assert.deepEqual(st.expectedOf({ expectedDownload: "300", expectedUpload: "27,5", minPercent: "" }), { downloadMbps: 300, uploadMbps: 27.5, minPercent: 60 }); assert.deepEqual(st.expectedOf({ expectedDownload: "fast", expectedUpload: "-3" }), { downloadMbps: null, uploadMbps: null, minPercent: 60 }); assert.deepEqual(st.expectedOf(null), { downloadMbps: null, uploadMbps: null, minPercent: 60 }); assert.equal(st.expectedOf({ minPercent: "75" }).minPercent, 75); assert.equal(st.expectedOf({ minPercent: "500" }).minPercent, 100, "kept within 1 to 100"); }); }); describe("what is wrong", () => { const row = (status: string, down: number | null, up: number | null = 25) => ({ status, downloadBps: down === null ? null : down * MBIT, uploadBps: up === null ? null : up * MBIT }); const completed = (...downs: number[]) => downs.map((d) => row("completed", d)); const expected = (downloadMbps: number | null, uploadMbps: number | null = null, minPercent = 60) => ({ downloadMbps, uploadMbps, minPercent }); const keys = (list: ReturnType) => list.map((p) => p.key); test("nothing is judged without what the line is sold at", () => { assert.deepEqual(st.speedtestProblems(1, "Home", completed(10, 10, 10), expected(null)), []); }); test("the middle of the newest three under the share is slow, saying what it was and what it should be; at or over the share is fine", () => { const p = st.speedtestProblems(1, "Home", completed(120, 130, 125), expected(300)); assert.deepEqual(keys(p), ["speedtest-slow:1"]); assert.equal(p[0].message, "Home: the internet is slow — download 125 Mbit/s, 42% of the 300 Mbit/s it is sold at (the middle of the last 3 tests)"); assert.deepEqual(st.speedtestProblems(1, "Home", completed(190, 200, 195), expected(300)), [], "65% is over 60%"); assert.deepEqual(keys(st.speedtestProblems(1, "Home", completed(190, 200, 195), expected(300, null, 70))), ["speedtest-slow:1"], "the share can be raised"); }); test("one slow test among three is not slow (the middle is judged), and only the newest three count", () => { assert.deepEqual(st.speedtestProblems(1, "Home", completed(20, 290, 300), expected(300)), []); assert.deepEqual(st.speedtestProblems(1, "Home", completed(290, 295, 300, 10, 10, 10), expected(300)), [], "older tests do not weigh"); }); test("a direction is judged only when its number is given; both can be slow in one alert; fewer than two completed tests are not judged", () => { const up = st.speedtestProblems(1, "Home", [row("completed", 300, 5), row("completed", 300, 6), row("completed", 300, 4)], expected(300, 30)); assert.match(up[0].message, /^Home: the internet is slow — upload 5\.0 Mbit\/s, 17% of the 30 Mbit\/s it is sold at/); assert.doesNotMatch(up[0].message, /download/); const both = st.speedtestProblems(1, "Home", [row("completed", 100, 5), row("completed", 100, 5)], expected(300, 30)); assert.match(both[0].message, /download 100 Mbit\/s, 33% of the 300 Mbit\/s it is sold at; upload 5\.0 Mbit\/s/); assert.deepEqual(st.speedtestProblems(1, "Home", completed(10), expected(300)), []); }); test("failed, skipped and unfinished tests are not speeds", () => { const mixed = [row("failed", null, null), row("skipped", null, null), ...completed(290, 300), row("running", null, null)]; assert.deepEqual(st.speedtestProblems(1, "Home", mixed, expected(300)), []); }); test("the newest three tests all failing is a warning; a completed one among them, or fewer than three, is not; skipped ones say nothing", () => { const failed = row("failed", null, null); assert.deepEqual(keys(st.speedtestProblems(1, "Home", [failed, failed, failed, ...completed(300)], expected(null))), ["speedtest-failing:1"]); assert.match(st.speedtestProblems(1, "Home", [failed, failed, failed], expected(null))[0].message, /the last 3 speed tests failed — the internet may be down, or Speedtest Tracker cannot reach Ookla/); assert.deepEqual(st.speedtestProblems(1, "Home", [failed, row("completed", 300), failed, failed], expected(null)), []); assert.deepEqual(st.speedtestProblems(1, "Home", [failed, failed], expected(null)), []); assert.deepEqual(keys(st.speedtestProblems(1, "Home", [failed, row("skipped", null, null), failed, failed], expected(null))), ["speedtest-failing:1"]); }); }); describe("what is stored", () => { let id = 0; let fake: Server; let url = ""; const reads: number[] = []; before(async () => { fake = createHttpServer((req, res) => { const u = new URL(req.url ?? "", "http://x"); res.writeHead(200, { "content-type": "application/json" }); if (u.pathname !== "/api/v1/results") return void res.end("{}"); const page = Number(u.searchParams.get("page[number]") ?? 1); reads.push(page); const now = Date.now(); // 100 results, one every 20 minutes, newest first; ids 100 .. 1 const ids = Array.from({ length: 30 }, (_, i) => 100 - (page - 1) * 30 - i).filter((n) => n > 0); res.end(JSON.stringify({ data: ids.map((n) => apiResult(n, { data: { timestamp: iso(now - (100 - n) * 20 * MIN) } })) })); }); await new Promise((r) => fake.listen(0, "127.0.0.1", r)); url = `http://127.0.0.1:${(fake.address() as AddressInfo).port}`; id = (await db.insert(integrations).values({ type: "speedtest", name: "Tracker", baseUrl: url, config: JSON.stringify({ url, token: "t", expectedDownload: "300" }) }).returning({ id: integrations.id }))[0].id; }); after(() => fake.close()); const count = async () => (await db.select().from(speedtestResults).where(eq(speedtestResults.integrationId, id))).length; test("the first read goes three pages back; later reads one page, and a result already stored is not stored again", async () => { reads.length = 0; assert.equal((await st.syncSpeedtest(id)).ok, true); assert.deepEqual([reads.length, await count()], [3, 90]); reads.length = 0; await st.syncSpeedtest(id); assert.deepEqual([reads.length, await count()], [1, 90], "the same results again add nothing"); }); test("results older than 90 days are forgotten, and each is kept as it was first read", async () => { const old = Date.now() - 91 * 24 * HOUR; await db.insert(speedtestResults).values({ integrationId: id, resultId: 5000, at: iso(old), status: "completed", downloadBps: 1, uploadBps: 1, pingMs: 1, healthy: true }); await st.storeResults(id, [adapter.parseResult(apiResult(5001, { download_bits: 999, data: { timestamp: iso(Date.now()) } }))!], new Date()); const rows = await db.select().from(speedtestResults).where(eq(speedtestResults.integrationId, id)); assert.ok(!rows.some((r) => r.resultId === 5000), "the old one is gone"); await st.storeResults(id, [adapter.parseResult(apiResult(5001, { download_bits: 123, data: { timestamp: iso(Date.now()) } }))!], new Date()); assert.equal((await db.select().from(speedtestResults).where(eq(speedtestResults.resultId, 5001)))[0].downloadBps, 999, "a test does not change afterwards"); }); test("a read that failed is said, and what was stored is left alone", async () => { const before_ = await count(); const failed = await st.syncSpeedtest(id, new Date(), async () => { throw new Error("connection refused"); }); assert.deepEqual([failed.ok, failed.error, await count()], [false, "connection refused", before_]); assert.equal(st.isSpeedtestFresh((await st.speedtestSyncStatuses())[id], Date.now() + 2 * HOUR), false); await st.syncSpeedtest(id); }); test("a row of another type is refused, not read", async () => { const other = (await db.insert(integrations).values({ type: "hetzner", name: "H", baseUrl: "", config: "{}" }).returning({ id: integrations.id }))[0].id; const r = await st.syncSpeedtest(other); assert.deepEqual([r.ok, r.error], [false, "not a Speedtest Tracker integration"]); }); }); describe("the health pass, the page and /metrics", () => { let stId = 0; let app: Server; let base = ""; const fresh = () => setInternalFlag("speedtestSync", JSON.stringify({ [stId]: { at: new Date().toISOString(), ok: true, error: null } })); const stale = () => setInternalFlag("speedtestSync", JSON.stringify({ [stId]: { at: new Date(Date.now() - 2 * HOUR).toISOString(), ok: true, error: null } })); const put = async (rows: { n: number; status?: string; down?: number | null; agoMin: number }[]) => { await db.delete(speedtestResults).where(eq(speedtestResults.integrationId, stId)); for (const r of rows) await db.insert(speedtestResults).values({ integrationId: stId, resultId: r.n, at: iso(Date.now() - r.agoMin * MIN), status: r.status ?? "completed", downloadBps: r.down === undefined ? 100 * MBIT : r.down === null ? null : r.down * MBIT, uploadBps: 20 * MBIT, pingMs: 14, healthy: null }); }; before(async () => { await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }]); stId = (await db.insert(integrations).values({ type: "speedtest", name: "Home line", baseUrl: "http://x", config: JSON.stringify({ url: "http://x", expectedDownload: "300", expectedUpload: "30" }) }).returning({ id: integrations.id }))[0].id; await put([{ n: 1, agoMin: 10 }, { n: 2, agoMin: 130 }, { n: 3, agoMin: 250 }, { n: 4, agoMin: 4 * 24 * 60 }, { n: 5, status: "failed", down: null, agoMin: 300 }]); await fresh(); const a = express(); a.use((req, _res, next) => { (req as unknown as { session: unknown }).session = { user: { sub: "viewer" } }; next(); }); a.use("/api/speedtest", speedtestRouter); app = await new Promise((resolve) => { const s = a.listen(0, "127.0.0.1", () => resolve(s)); }); base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/speedtest`; }); after(() => { app.close(); try { rmSync(dir, { recursive: true, force: true }); } catch { // Windows keeps the database file locked until the process exits. } }); test("the health pass judges it from what is stored with the numbers from the integration, and holds it when the last read is old", async () => { let { snapshot, held } = await collectSnapshot(); assert.deepEqual(snapshot.speedtest?.map((s) => s.integrationId), [stId]); const list = evaluateHealth(snapshot, { serverOfflineMinutes: 60, diskUsagePercent: 90 }, Date.now(), { skipServers: true }); const c = list.find((x) => x.key === `speedtest-slow:${stId}`)!; assert.deepEqual([c.severity, c.source], ["warning", `speedtest:${stId}`]); assert.match(c.message, /^Home line: the internet is slow — download 100 Mbit\/s, 33% of the 300 Mbit\/s it is sold at \(the middle of the last 3 tests\)$/); assert.doesNotMatch(c.message, /upload/, "67% of what is paid for upload is over the 60% share"); for (const k of ["slow", "failing"]) assert.equal(subjectOfConditionKey(`speedtest-${k}:${stId}`), `integration:${stId}`, "maintenance on it silences the alert"); await stale(); ({ snapshot, held } = await collectSnapshot()); assert.deepEqual([snapshot.speedtest ?? [], held.has(`speedtest:${stId}`)], [[], true]); await fresh(); }); test("the Alerts page shows it under Monitoring with a link to the page", async () => { invalidateAlertsCache(); const a = (await getAlerts(true)).alerts.find((x) => x.id === `monitoring:speedtest-slow:${stId}`)!; assert.ok(a); assert.deepEqual([a.severity, a.category, a.source, a.link, a.target?.type, a.target?.id], ["warning", "monitoring", "Speedtest", "/speedtest", "integration", stId]); }); test("a line that is as fast as it is sold raises nothing, and tests that keep failing do", async () => { await put([{ n: 1, down: 290, agoMin: 10 }, { n: 2, down: 300, agoMin: 130 }, { n: 3, down: 280, agoMin: 250 }]); invalidateAlertsCache(); assert.ok(!(await getAlerts(true)).alerts.some((x) => x.id.includes("speedtest-"))); await put([{ n: 1, status: "failed", down: null, agoMin: 10 }, { n: 2, status: "failed", down: null, agoMin: 130 }, { n: 3, status: "failed", down: null, agoMin: 250 }]); invalidateAlertsCache(); assert.ok((await getAlerts(true)).alerts.some((x) => x.id === `monitoring:speedtest-failing:${stId}`)); await put([{ n: 1, agoMin: 10 }, { n: 2, agoMin: 130 }, { n: 3, agoMin: 250 }, { n: 4, agoMin: 4 * 24 * 60 }, { n: 5, status: "failed", down: null, agoMin: 300 }]); }); test("the page: the newest completed test, the middle of the last few, what it is sold at, and what is wrong; an old reading says nothing is wrong", async () => { const body = (await (await fetch(base)).json()) as { speedtests: { id: number; fresh: boolean; expected: { downloadMbps: number; uploadMbps: number; minPercent: number }; state: { latest: { download: number; ping: number }; middle: { count: number; download: number }; lastTest: { status: string }; stored: number }; problems: { key: string }[] }[] }; const s = body.speedtests.find((x) => x.id === stId)!; assert.deepEqual([s.fresh, s.expected.downloadMbps, s.expected.uploadMbps, s.expected.minPercent], [true, 300, 30, 60]); assert.deepEqual([s.state.latest.download, s.state.latest.ping, s.state.middle.count, s.state.middle.download, s.state.lastTest.status, s.state.stored], [100 * MBIT, 14, 3, 100 * MBIT, "completed", 5]); assert.deepEqual(s.problems.map((p) => p.key), [`speedtest-slow:${stId}`]); await stale(); const old = (await (await fetch(base)).json()) as typeof body; assert.deepEqual(old.speedtests.find((x) => x.id === stId)!.problems, []); await fresh(); }); test("the history for the charts is Mbit/s and ms, oldest first, completed tests only, within the days asked", async () => { const day = (await (await fetch(`${base}/${stId}/history?days=1`)).json()) as { days: number; points: { t: string; download: number; upload: number; ping: number }[] }; assert.equal(day.days, 1); assert.deepEqual(day.points.map((p) => [p.download, p.upload, p.ping]), [[100, 20, 14], [100, 20, 14], [100, 20, 14]], "three completed tests in the last day; the failed one is left out"); assert.ok(day.points[0].t < day.points[2].t); const week = (await (await fetch(`${base}/${stId}/history?days=7`)).json()) as typeof day; assert.equal(week.points.length, 4); assert.equal(((await (await fetch(`${base}/${stId}/history?days=900`)).json()) as typeof day).days, 90, "no more than the 90 days kept"); assert.equal((await fetch(`${base}/99999/history`)).status, 404); assert.equal((await fetch(`${base}/abc/history`)).status, 400); }); test("/metrics has the newest completed test — only while the reading is recent", async () => { let text = await buildMetrics(new Date()); assert.match(text, /homelab_speedtest_download_bits_per_second\{name="Home line"\} 100000000|homelab_speedtest_download_bits_per_second\{name="Home line"\} 1e\+8/); assert.match(text, /homelab_speedtest_ping_seconds\{name="Home line"\} 0\.014/); await stale(); text = await buildMetrics(new Date()); assert.doesNotMatch(text, /homelab_speedtest/); await fresh(); }); test("taking the integration away takes what was read with it", async () => { await st.forgetSpeedtest(stId); assert.equal((await st.speedtestSyncStatuses())[stId], undefined); await db.delete(integrations).where(eq(integrations.id, stId)); assert.deepEqual(await db.select().from(speedtestResults).where(eq(speedtestResults.integrationId, stId)), []); }); });