Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

18.1 KB
Raw Blame
import type { Node } from '@xyflow/react'
import { describe, expect, it } from 'vitest'

import type { Design, InventoryEntry, NodeData } from '@/types'
import {
  bucketsFor,
  buildDeviceTree,
  buildLibraryTree,
  buildLinkedDocTree,
  canMoveInto,
  deviceLabel,
  docState,
  filterGroups,
  filterTree,
  nodeFactsByDevice,
  physicality,
  slash24,
  splitIps,
  subnetsOf,
} from '../tree'
import type { DocumentSummary } from '../types'

function device(overrides: Partial<InventoryEntry> = {}): InventoryEntry {
  return {
    id: 'dev-1',
    ip: '192.168.1.20',
    mac: null,
    hostname: 'nas-01.lan',
    os: null,
    services: [],
    suggested_type: null,
    status: 'approved',
    discovered_at: '2026-01-01T00:00:00Z',
    label: 'nas-01',
    ...overrides,
  }
}

function doc(overrides: Partial<DocumentSummary> = {}): DocumentSummary {
  return {
    id: 'doc-1',
    kind: 'device',
    title: 'nas-01',
    slug: 'nas-01',
    sort_order: 0,
    tags: [],
    frontmatter: {},
    starred: false,
    created_at: '2026-01-01T00:00:00Z',
    updated_at: '2026-01-01T00:00:00Z',
    ...overrides,
  }
}

function node(id: string, data: Partial<NodeData>): Node<NodeData> {
  return {
    id,
    position: { x: 0, y: 0 },
    data: { label: id, type: 'server', status: 'unknown', services: [], ...data } as NodeData,
  }
}

// The public documentation view is handed no inventory, no canvas and no racks,
// so it cannot use `buildDeviceTree`. This builder groups the same documents by
// what they carry themselves.
describe('buildLinkedDocTree', () => {
  it('puts everything under one bucket when flat', () => {
    const groups = buildLinkedDocTree([doc(), doc({ id: 'doc-2', title: 'switch-01' })], 'flat')
    expect(groups).toHaveLength(1)
    expect(groups[0].label).toBe('All documents')
    expect(groups[0].items.map((i) => i.label)).toEqual(['nas-01', 'switch-01'])
  })

  it('leaves the Library out — those are filed by hand, not pivoted', () => {
    const groups = buildLinkedDocTree(
      [doc(), doc({ id: 'doc-2', kind: 'page' }), doc({ id: 'doc-3', kind: 'folder' })],
      'flat',
    )
    expect(groups[0].items.map((i) => i.id)).toEqual(['doc-1'])
  })

  it('files a document under each of its tags, and the untagged together', () => {
    const groups = buildLinkedDocTree(
      [
        doc({ id: 'doc-1', title: 'nas-01', tags: ['storage', 'prod'] }),
        doc({ id: 'doc-2', title: 'switch-01', tags: ['prod'] }),
        doc({ id: 'doc-3', title: 'printer' }),
      ],
      'tag',
    )
    const byLabel = Object.fromEntries(groups.map((g) => [g.label, g.items.map((i) => i.title ?? i.label)]))
    expect(byLabel['prod']).toEqual(['nas-01', 'switch-01'])
    expect(byLabel['storage']).toEqual(['nas-01'])
    expect(byLabel['Untagged']).toEqual(['printer'])
  })

  it('sorts the last-resort bucket to the bottom', () => {
    const groups = buildLinkedDocTree(
      [doc({ id: 'doc-1', tags: ['zzz'] }), doc({ id: 'doc-2' })],
      'tag',
    )
    expect(groups.map((g) => g.label)).toEqual(['zzz', 'Untagged'])
  })

  it('badges an overdue document, and never a drifted one', () => {
    // Drift is decided against the inventory row, which this view has no access
    // to — so the badge can only ever say written / header-only / overdue.
    const groups = buildLinkedDocTree([doc({ edited_at: '2026-01-02T00:00:00Z' })], 'flat', {
      overdue: new Set(['doc-1']),
    })
    expect(groups[0].items[0].state).toBe('overdue')
  })
})

const designs: Design[] = [
  { id: 'design-1', name: 'Home network', design_type: 'network' } as Design,
]

const emptyContext = { nodes: [], designs, activeDesignId: 'design-1' as string | null }

// ── helpers ─────────────────────────────────────────────────────────────────

describe('physicality', () => {
  it('calls a guest virtual', () => {
    expect(physicality('vm')).toBe('Virtual')
    expect(physicality('lxc')).toBe('Virtual')
    expect(physicality('docker_container')).toBe('Virtual')
  })

  it('calls a hypervisor a host', () => {
    expect(physicality('proxmox')).toBe('Host')
    expect(physicality('docker_host')).toBe('Host')
  })

  it('falls back to a container drawing when the type is generic', () => {
    expect(physicality('server', { hasChildren: true })).toBe('Host')
    expect(physicality('server', { containerMode: true })).toBe('Host')
  })

  it('is physical otherwise, including for an unknown type', () => {
    expect(physicality('nas')).toBe('Physical')
    expect(physicality(null)).toBe('Physical')
  })
})

describe('splitIps', () => {
  it('splits the comma-separated column and drops blanks', () => {
    expect(splitIps('10.0.0.1, 192.168.1.2 ,')).toEqual(['10.0.0.1', '192.168.1.2'])
    expect(splitIps(null)).toEqual([])
  })
})

describe('slash24', () => {
  it('is the network of an IPv4 address', () => {
    expect(slash24('192.168.1.20')).toBe('192.168.1.0/24')
  })

  it('is null for anything that is not IPv4', () => {
    expect(slash24('fe80::1')).toBeNull()
    expect(slash24('not-an-ip')).toBeNull()
  })
})

describe('subnetsOf', () => {
  it('prefers a configured range over the guessed /24', () => {
    expect(subnetsOf(device({ ip: '10.0.5.7' }), ['10.0.0.0/16'])).toEqual(['10.0.0.0/16'])
  })

  it('guesses a /24 when no range matches', () => {
    expect(subnetsOf(device({ ip: '10.0.5.7' }), ['192.168.1.0/24'])).toEqual(['10.0.5.0/24'])
  })

  it('places a multi-homed device under every subnet it reaches', () => {
    const found = subnetsOf(device({ ip: '10.0.0.5, 192.168.1.20' }), [])
    expect(found).toEqual(['10.0.0.0/24', '192.168.1.0/24'])
  })

  it('falls back to a single bucket for a device with no usable address', () => {
    expect(subnetsOf(device({ ip: null }), [])).toEqual(['Ungrouped'])
  })
})

describe('deviceLabel', () => {
  it('falls back through the names a device can carry', () => {
    expect(deviceLabel(device())).toBe('nas-01')
    expect(deviceLabel(device({ label: null }))).toBe('nas-01.lan')
    expect(deviceLabel(device({ label: null, hostname: null }))).toBe('192.168.1.20')
    expect(deviceLabel(device({ label: null, hostname: null, ip: null }))).toBe('Unnamed device')
  })
})

describe('docState', () => {
  it('reports what the badge should say', () => {
    expect(docState(undefined)).toBe('none')
    expect(docState(doc())).toBe('header-only')
    expect(docState(doc({ edited_at: '2026-02-01T00:00:00Z' }))).toBe('written')
    expect(docState(doc(), { drifted: true })).toBe('drifted')
    expect(docState(doc(), { overdue: true })).toBe('overdue')
  })

  it('reports drift ahead of an overdue review — it is the more actionable one', () => {
    expect(docState(doc(), { drifted: true, overdue: true })).toBe('drifted')
  })
})

// ── canvas facts ────────────────────────────────────────────────────────────

describe('nodeFactsByDevice', () => {
  it('walks up to the nearest zone and the nearest group', () => {
    const nodes = [
      node('zone', { type: 'groupRect', label: 'Garage' }),
      node('group', { type: 'group', label: 'Storage', parent_id: 'zone' }),
      node('nas', { type: 'nas', label: 'nas-01', parent_id: 'group', device_id: 'dev-1' }),
    ]
    const facts = nodeFactsByDevice({ ...emptyContext, nodes })
    expect(facts['dev-1'].zone).toBe('Garage')
    expect(facts['dev-1'].group).toBe('Storage')
  })

  it('ignores furniture, which describes nothing', () => {
    const nodes = [node('zone', { type: 'groupRect', label: 'Garage', device_id: 'dev-1' })]
    expect(nodeFactsByDevice({ ...emptyContext, nodes })).toEqual({})
  })

  it('names the canvas the loaded nodes belong to', () => {
    const nodes = [node('nas', { type: 'nas', device_id: 'dev-1' })]
    expect(nodeFactsByDevice({ ...emptyContext, nodes })['dev-1'].canvas).toBe('Home network')
  })

  it('survives a parent cycle rather than recursing forever', () => {
    const nodes = [
      node('a', { type: 'groupRect', label: 'A', parent_id: 'b' }),
      node('b', { type: 'groupRect', label: 'B', parent_id: 'a' }),
      node('nas', { type: 'nas', parent_id: 'a', device_id: 'dev-1' }),
    ]
    expect(() => nodeFactsByDevice({ ...emptyContext, nodes })).not.toThrow()
  })
})

// ── the pivots ──────────────────────────────────────────────────────────────

describe('bucketsFor', () => {
  const facts = { zone: 'Garage', group: 'Storage', hasChildren: false, containerMode: false }

  it('groups by zone, falling back when there is none', () => {
    expect(bucketsFor(device(), 'zone', facts, undefined, emptyContext)).toEqual(['Garage'])
    expect(bucketsFor(device(), 'zone', undefined, undefined, emptyContext)).toEqual(['Unzoned'])
  })

  it('groups by the curated type before the guessed one', () => {
    expect(bucketsFor(device({ type: 'nas', suggested_type: 'server' }), 'type', facts, undefined, emptyContext)).toEqual(['nas'])
    expect(bucketsFor(device({ type: null, suggested_type: 'server' }), 'type', facts, undefined, emptyContext)).toEqual(['server'])
    expect(bucketsFor(device({ type: null, suggested_type: null }), 'type', facts, undefined, emptyContext)).toEqual(['Untyped'])
  })

  it('groups by every discovery source that saw the device', () => {
    const merged = device({ discovery_sources: ['arp', 'proxmox'] })
    expect(bucketsFor(merged, 'source', facts, undefined, emptyContext)).toEqual(['arp', 'proxmox'])
  })

  it('falls back to the single source column on an older row', () => {
    const legacy = device({ discovery_sources: [], discovery_source: 'mdns' })
    expect(bucketsFor(legacy, 'source', facts, undefined, emptyContext)).toEqual(['mdns'])
  })

  it('groups by rack when one mounts the device', () => {
    const context = { ...emptyContext, racksByDevice: { 'dev-1': 'Rack-A' } }
    expect(bucketsFor(device(), 'rack', facts, undefined, context)).toEqual(['Rack-A'])
    expect(bucketsFor(device(), 'rack', facts, undefined, emptyContext)).toEqual(['Not racked'])
  })

  it('groups by the tags on the document, not on the device', () => {
    expect(bucketsFor(device(), 'tag', facts, doc({ tags: ['storage', 'loud'] }), emptyContext)).toEqual([
      'storage',
      'loud',
    ])
    expect(bucketsFor(device(), 'tag', facts, doc(), emptyContext)).toEqual(['Untagged'])
  })

  it('puts everything in one bucket when flat', () => {
    expect(bucketsFor(device(), 'flat', facts, undefined, emptyContext)).toEqual(['All devices'])
  })
})

describe('buildDeviceTree', () => {
  it('groups devices and sorts them inside each group', () => {
    const devices = [
      device({ id: 'a', label: 'zeta', ip: '10.0.0.1' }),
      device({ id: 'b', label: 'alpha', ip: '10.0.0.2' }),
    ]
    const groups = buildDeviceTree({ groupBy: 'flat', devices, docs: [], context: emptyContext })
    expect(groups).toHaveLength(1)
    expect(groups[0].items.map((i) => i.label)).toEqual(['alpha', 'zeta'])
  })

  it('marks a device with no document so the tree shows the gap', () => {
    const groups = buildDeviceTree({ groupBy: 'flat', devices: [device()], docs: [], context: emptyContext })
    expect(groups[0].items[0].kind).toBe('device-without-doc')
    expect(groups[0].items[0].state).toBe('none')
    expect(groups[0].items[0].docId).toBeUndefined()
  })

  it('attaches the document a device already has', () => {
    const groups = buildDeviceTree({
      groupBy: 'flat',
      devices: [device()],
      docs: [doc({ device_id: 'dev-1', edited_at: '2026-02-01T00:00:00Z' })],
      context: emptyContext,
    })
    expect(groups[0].items[0].docId).toBe('doc-1')
    expect(groups[0].items[0].state).toBe('written')
  })

  it('shows the name the document gives itself, not the inventory label', () => {
    const groups = buildDeviceTree({
      groupBy: 'flat',
      devices: [device({ label: 'nas-01' })],
      docs: [doc({ device_id: 'dev-1', title: 'The big NAS' })],
      context: emptyContext,
    })
    expect(groups[0].items[0].label).toBe('The big NAS')
  })

  it('falls back to the inventory label while there is nothing to open', () => {
    const groups = buildDeviceTree({
      groupBy: 'flat',
      devices: [device({ label: 'nas-01' })],
      docs: [doc({ device_id: 'dev-1', title: '  ' })],
      context: emptyContext,
    })
    expect(groups[0].items[0].label).toBe('nas-01')
  })

  it('lists a multi-homed device under each of its subnets', () => {
    const groups = buildDeviceTree({
      groupBy: 'subnet',
      devices: [device({ ip: '10.0.0.5, 192.168.1.20' })],
      docs: [],
      context: emptyContext,
    })
    expect(groups.map((g) => g.label)).toEqual(['10.0.0.0/24', '192.168.1.0/24'])
  })

  it('sinks the catch-all bucket to the bottom', () => {
    const devices = [
      device({ id: 'a', label: 'in-a-zone' }),
      device({ id: 'b', label: 'loose' }),
    ]
    const nodes = [
      node('zone', { type: 'groupRect', label: 'Garage' }),
      node('n', { type: 'nas', parent_id: 'zone', device_id: 'a' }),
    ]
    const groups = buildDeviceTree({
      groupBy: 'zone',
      devices,
      docs: [],
      context: { ...emptyContext, nodes },
    })
    expect(groups.map((g) => g.label)).toEqual(['Garage', 'Unzoned'])
  })

  it('flags drift and overdue review from the sets it is given', () => {
    const groups = buildDeviceTree({
      groupBy: 'flat',
      devices: [device()],
      docs: [doc({ device_id: 'dev-1' })],
      context: emptyContext,
      drifted: new Set(['doc-1']),
    })
    expect(groups[0].items[0].state).toBe('drifted')
  })
})

// ── the library ─────────────────────────────────────────────────────────────

describe('buildLibraryTree', () => {
  it('nests pages under their folder', () => {
    const tree = buildLibraryTree([
      doc({ id: 'f', kind: 'folder', title: 'Runbooks' }),
      doc({ id: 'p', kind: 'page', title: 'Reboot', parent_id: 'f' }),
    ])
    expect(tree).toHaveLength(1)
    expect(tree[0].children?.[0].label).toBe('Reboot')
  })

  it('leaves device documents out — they are placed by their pivot', () => {
    expect(buildLibraryTree([doc({ kind: 'device', device_id: 'dev-1' })])).toEqual([])
  })

  it('orders by sort_order, then by title', () => {
    const tree = buildLibraryTree([
      doc({ id: 'b', kind: 'page', title: 'Beta', sort_order: 0 }),
      doc({ id: 'a', kind: 'page', title: 'Alpha', sort_order: 1 }),
      doc({ id: 'c', kind: 'page', title: 'Aardvark', sort_order: 0 }),
    ])
    expect(tree.map((t) => t.label)).toEqual(['Aardvark', 'Beta', 'Alpha'])
  })

  it('keeps an empty folder, which is the point of storing folders as rows', () => {
    const tree = buildLibraryTree([doc({ id: 'f', kind: 'folder', title: 'Empty' })])
    expect(tree[0].children).toEqual([])
  })

  it('does not recurse forever on a cycle', () => {
    const tree = buildLibraryTree([
      doc({ id: 'a', kind: 'folder', title: 'A', parent_id: 'b' }),
      doc({ id: 'b', kind: 'folder', title: 'B', parent_id: 'a' }),
    ])
    expect(tree).toEqual([])
  })
})

// ── filtering ───────────────────────────────────────────────────────────────

describe('filterTree', () => {
  const tree = buildLibraryTree([
    doc({ id: 'f', kind: 'folder', title: 'Runbooks' }),
    doc({ id: 'p', kind: 'page', title: 'Reboot the NAS', parent_id: 'f' }),
    doc({ id: 'o', kind: 'page', title: 'VLAN plan' }),
  ])

  it('keeps the folder that leads to a match', () => {
    const filtered = filterTree(tree, 'reboot')
    expect(filtered).toHaveLength(1)
    expect(filtered[0].label).toBe('Runbooks')
    expect(filtered[0].children?.[0].label).toBe('Reboot the NAS')
  })

  it('is case-insensitive and returns everything for an empty query', () => {
    expect(filterTree(tree, 'VLAN')).toHaveLength(1)
    expect(filterTree(tree, '  ')).toEqual(tree)
  })

  it('returns nothing when nothing matches', () => {
    expect(filterTree(tree, 'zzz')).toEqual([])
  })
})

describe('filterGroups', () => {
  const groups = buildDeviceTree({
    groupBy: 'flat',
    devices: [device({ id: 'a', label: 'nas-01' }), device({ id: 'b', label: 'switch-core' })],
    docs: [],
    context: emptyContext,
  })

  it('narrows a group to its matching items', () => {
    expect(filterGroups(groups, 'nas')[0].items.map((i) => i.label)).toEqual(['nas-01'])
  })

  it('keeps every item when the group name itself matches', () => {
    expect(filterGroups(groups, 'All devices')[0].items).toHaveLength(2)
  })

  it('drops a group that ends up empty', () => {
    expect(filterGroups(groups, 'zzz')).toEqual([])
  })
})

describe('canMoveInto', () => {
  const root = doc({ id: 'root', kind: 'folder', title: 'Runbooks' })
  const nested = doc({ id: 'nested', kind: 'folder', title: 'Restores', parent_id: 'root' })
  const page = doc({ id: 'page', kind: 'page', title: 'Restore the NAS', parent_id: null })
  const all = [root, nested, page]

  it('files a top-level page under a folder', () => {
    expect(canMoveInto(all, page, 'root')).toBe(true)
  })

  it('takes a filed page back out to the root', () => {
    expect(canMoveInto(all, { ...page, parent_id: 'root' }, null)).toBe(true)
  })

  it('refuses the parent it already has', () => {
    expect(canMoveInto(all, { ...page, parent_id: 'root' }, 'root')).toBe(false)
    expect(canMoveInto(all, page, null)).toBe(false)
  })

  it('refuses a page as a parent — only folders take children', () => {
    expect(canMoveInto(all, nested, 'page')).toBe(false)
  })

  it('refuses a folder into itself or its own subtree', () => {
    expect(canMoveInto(all, root, 'root')).toBe(false)
    expect(canMoveInto(all, root, 'nested')).toBe(false)
  })

  it('refuses a device document, which the Library does not hold', () => {
    expect(canMoveInto(all, doc({ id: 'dev-doc', kind: 'device' }), 'root')).toBe(false)
  })

  it('refuses a parent that is not there', () => {
    expect(canMoveInto(all, page, 'gone')).toBe(false)
  })
})