Skip to content

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

11.6 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'

import { documentsApi } from '@/api/client'
import { DocumentationView } from '../components/DocumentationView'
import { useDocsStore } from '../store'
import type { Doc, DocumentSummary, UpdatePreview } from '../types'

vi.mock('sonner', async () => (await import('@/test/mocks')).mockSonner())

vi.mock('@/api/client', () => ({
  documentsApi: {
    list: vi.fn(),
    coverage: vi.fn(),
    updatePreview: vi.fn(),
    updateFromDevice: vi.fn(),
    revisions: vi.fn(),
    get: vi.fn(),
    backlinks: vi.fn().mockResolvedValue({ data: [] }),
  },
  scanApi: { pending: vi.fn().mockResolvedValue({ data: [] }) },
  docsviewApi: { getConfig: vi.fn().mockResolvedValue({ data: { enabled: false, key: null } }) },
}))

const api = vi.mocked(documentsApi)
const INITIAL = useDocsStore.getState()

function doc(overrides: Partial<Doc> = {}): Doc {
  return {
    id: 'doc-1',
    kind: 'device',
    title: 'NAS',
    slug: 'nas',
    sort_order: 0,
    device_id: 'device-1',
    tags: [],
    frontmatter: {},
    starred: false,
    drifted: true,
    body: '# NAS\n\nManual backup notes.',
    created_at: '2026-01-01T00:00:00Z',
    updated_at: '2026-01-01T00:00:00Z',
    ...overrides,
  }
}

function preview(overrides: Partial<UpdatePreview> = {}): UpdatePreview {
  return {
    preview_id: 'preview-1',
    changes: [],
    proposed_body: '# NAS\n\nManual backup notes.',
    summary: [],
    unresolved: [],
    ...overrides,
  }
}

function deferred<T>() {
  let resolve!: (value: T) => void
  let reject!: (reason: unknown) => void
  const promise = new Promise<T>((done, fail) => {
    resolve = done
    reject = fail
  })
  return { promise, resolve, reject }
}

function renderView(openDoc = doc()) {
  const docs = [openDoc as DocumentSummary]
  api.list.mockResolvedValue({ data: docs } as never)
  api.coverage.mockResolvedValue({
    data: { devices: 1, documented: 1, header_only: 0, notes_unmigrated: 0 },
  } as never)
  useDocsStore.setState({
    ...INITIAL,
    docs,
    loaded: true,
    openDoc,
    preview: null,
    previewLoading: false,
    resolutions: {},
  })
  render(<DocumentationView />)
  return screen.getByRole('button', { name: 'Update from device' })
}

beforeEach(() => {
  vi.clearAllMocks()
  localStorage.clear()
})

afterEach(() => cleanup())

describe('DocumentationView — update from device', () => {
  it('shows a conflict-free update for review and applies it only once Update is clicked', async () => {
    const merged = doc({ body: '# NAS\n\nIP: 192.168.1.30\n\nManual backup notes.', drifted: false })
    api.updatePreview.mockResolvedValue({
      data: preview({
        changes: [{
          id: 'section.Network details',
          name: 'Network details',
          kind: 'section',
          status: 'auto',
          documented: 'IP: 192.168.1.20',
          device: '## Network details\n\nIP: 192.168.1.30\n\nA long generated section.',
          previous: 'IP: 192.168.1.20',
        }],
        proposed_body: merged.body,
        summary: ['Network details updated to ## Network details IP: 192.168.1.30 A long generated section.'],
      }),
    } as never)
    api.updateFromDevice.mockResolvedValue({ data: merged } as never)
    api.revisions.mockResolvedValue({ data: [] } as never)
    const { toast } = await import('sonner')

    fireEvent.click(renderView())

    // No conflict to settle, yet nothing is written until the user confirms.
    const confirm = await screen.findByRole('button', { name: 'Update the document' })
    expect(screen.getByRole('dialog')).toBeInTheDocument()
    expect(api.updateFromDevice).not.toHaveBeenCalled()
    fireEvent.click(confirm)

    await waitFor(() => expect(api.updateFromDevice).toHaveBeenCalledTimes(1))
    expect(api.updatePreview).toHaveBeenCalledTimes(1)
    expect(api.updateFromDevice).toHaveBeenCalledWith('doc-1', 'preview-1', [])
    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull())
    expect(screen.queryByRole('dialog')).toBeNull()
    expect(screen.getByText('Manual backup notes.')).toBeInTheDocument()
    expect(toast.success).toHaveBeenCalledWith(
      'Documentation updated: Network details',
      expect.objectContaining({ action: expect.objectContaining({ label: 'View history' }) }),
    )

    const options = vi.mocked(toast.success).mock.calls[0]?.[1]
    const action = options?.action
    if (!action || typeof action === 'function' || !('onClick' in action)) {
      throw new Error('Expected a history action on the update confirmation')
    }
    action.onClick({} as never)
    await waitFor(() => expect(api.revisions).toHaveBeenCalledWith('doc-1'))
  })

  it('only previews conflicts and cancelling writes nothing', async () => {
    api.updatePreview.mockResolvedValue({
      data: preview({
        changes: [{
          id: 'device-info.IP Address',
          name: 'IP address',
          kind: 'field',
          status: 'conflict',
          documented: 'nas.example.lan',
          device: '192.168.1.30',
          previous: '192.168.1.20',
        }],
        unresolved: ['device-info.IP Address'],
      }),
    } as never)

    fireEvent.click(renderView())

    expect(await screen.findByRole('dialog')).toBeInTheDocument()
    expect(screen.getByText('IP address')).toBeInTheDocument()
    expect(api.updatePreview).toHaveBeenCalledTimes(1)
    expect(api.updateFromDevice).not.toHaveBeenCalled()

    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }))
    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull())
    expect(api.updateFromDevice).not.toHaveBeenCalled()
  })

  it('retries a failed conflict preview without saving until Update is clicked', async () => {
    const conflict = {
      id: 'device-info.IP Address',
      name: 'IP address',
      kind: 'field' as const,
      status: 'conflict' as const,
      documented: 'nas.example.lan',
      device: '192.168.1.30',
      previous: '192.168.1.20',
    }
    api.updatePreview
      .mockResolvedValueOnce({
        data: preview({ changes: [conflict], unresolved: [conflict.id] }),
      } as never)
      .mockRejectedValueOnce(new Error('offline'))
      .mockResolvedValueOnce({
        data: preview({
          preview_id: 'resolved-preview',
          changes: [conflict],
          unresolved: [],
          summary: ['IP address kept as written'],
        }),
      } as never)
    api.updateFromDevice.mockResolvedValue({ data: doc({ drifted: false }) } as never)

    fireEvent.click(renderView())
    fireEvent.click(await screen.findByRole('radio', { name: 'Keep actual documentation' }))
    fireEvent.click(await screen.findByRole('button', { name: 'Try again' }))

    await waitFor(() => expect(api.updatePreview).toHaveBeenCalledTimes(3))
    expect(api.updateFromDevice).not.toHaveBeenCalled()
    fireEvent.click(screen.getByRole('button', { name: 'Update the document' }))
    await waitFor(() => expect(api.updateFromDevice).toHaveBeenCalledWith(
      'doc-1',
      'resolved-preview',
      [{ id: conflict.id, choice: 'keep' }],
    ))
  })

  it('keeps a failed comparison visible without writing', async () => {
    api.updatePreview.mockRejectedValueOnce(new Error('offline'))

    fireEvent.click(renderView())

    expect(await screen.findByText('Could not compare this document with the device.')).toBeInTheDocument()
    expect(screen.getByRole('button', { name: 'Try again' })).toBeInTheDocument()
    expect(api.updateFromDevice).not.toHaveBeenCalled()
  })

  it('shows a fresh preview after a stale apply without applying it', async () => {
    const first = preview({
      changes: [{
        id: 'device-info.IP Address',
        name: 'IP address',
        kind: 'field',
        status: 'auto',
        documented: '192.168.1.20',
        device: '192.168.1.30',
        previous: '192.168.1.20',
      }],
      summary: ['IP address updated to 192.168.1.30'],
    })
    const fresh = preview({
      preview_id: 'fresh-preview',
      changes: [{
        id: 'device-info.Hostname',
        name: 'Hostname',
        kind: 'field',
        status: 'auto',
        documented: 'nas-old',
        device: 'nas-new',
        previous: 'nas-old',
      }],
      summary: ['Hostname updated to nas-new'],
    })
    api.updatePreview
      .mockResolvedValueOnce({ data: first } as never)
      .mockResolvedValueOnce({ data: fresh } as never)
    api.updateFromDevice.mockRejectedValueOnce(Object.assign(new Error('stale'), {
      response: { status: 409 },
    }))
    api.get.mockResolvedValueOnce({ data: doc({ updated_at: '2026-01-02T00:00:00Z' }) } as never)

    fireEvent.click(renderView())
    fireEvent.click(await screen.findByRole('button', { name: 'Update the document' }))

    await waitFor(() => expect(api.updatePreview).toHaveBeenCalledTimes(2))
    expect(api.updateFromDevice).toHaveBeenCalledTimes(1)
    expect(await screen.findByRole('dialog')).toBeInTheDocument()
    expect(screen.getByText('Hostname updated to nas-new')).toBeInTheDocument()
    expect(screen.getByRole('button', { name: 'Update the document' })).toBeInTheDocument()
  })

  it('does not apply a preview that finishes after navigation', async () => {
    const comparing = deferred<{ data: UpdatePreview }>()
    api.updatePreview.mockImplementationOnce(() => comparing.promise)
    api.get.mockResolvedValueOnce({ data: doc({ id: 'doc-2', title: 'Router', slug: 'router' }) } as never)
    const { toast } = await import('sonner')

    fireEvent.click(renderView())
    await waitFor(() => expect(api.updatePreview).toHaveBeenCalledTimes(1))
    await act(async () => {
      await useDocsStore.getState().open('doc-2')
    })
    expect(screen.getByRole('heading', { name: 'Router' })).toBeInTheDocument()

    await act(async () => {
      comparing.resolve({ data: preview({ summary: ['IP address updated to 192.168.1.30'] }) })
      await comparing.promise
    })

    expect(api.updateFromDevice).not.toHaveBeenCalled()
    expect(toast.error).not.toHaveBeenCalled()
    expect(useDocsStore.getState().openDoc?.id).toBe('doc-2')
  })

  it('does not close a newer review when an old apply finishes after navigation', async () => {
    const applying = deferred<{ data: Doc }>()
    api.updatePreview.mockResolvedValueOnce({
      data: preview({
        changes: [{
          id: 'device-info.IP Address',
          name: 'IP address',
          kind: 'field',
          status: 'auto',
          documented: '192.168.1.20',
          device: '192.168.1.30',
          previous: '192.168.1.20',
        }],
        summary: ['IP address updated to 192.168.1.30'],
      }),
    } as never)
    api.updateFromDevice.mockImplementationOnce(() => applying.promise)
    api.get.mockResolvedValueOnce({ data: doc({ id: 'doc-2', title: 'Router', slug: 'router' }) } as never)
    const { toast } = await import('sonner')

    fireEvent.click(renderView())
    fireEvent.click(await screen.findByRole('button', { name: 'Update the document' }))
    await waitFor(() => expect(api.updateFromDevice).toHaveBeenCalledTimes(1))
    await act(async () => {
      await useDocsStore.getState().open('doc-2')
    })
    useDocsStore.setState({
      preview: preview({ preview_id: 'doc-2-preview', unresolved: ['new-conflict'] }),
      resolutions: { newer: { id: 'newer', choice: 'keep' } },
    })

    await act(async () => {
      applying.resolve({ data: doc({ body: '# NAS\n\nApplied late.' }) })
      await applying.promise
    })

    expect(useDocsStore.getState().openDoc?.id).toBe('doc-2')
    expect(useDocsStore.getState().preview?.preview_id).toBe('doc-2-preview')
    expect(useDocsStore.getState().resolutions).toEqual({ newer: { id: 'newer', choice: 'keep' } })
    expect(toast.success).not.toHaveBeenCalled()
  })
})