Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
import { describe, expect, it, vi } from 'vitest';
import {
docAssetUrlForPath,
docRouteForPath,
extractDocTitle,
normalizeDocPath,
renderDocMarkdown,
resolveDocLink,
scrollToDocFragment,
stripLeadingTitle,
wrapTables,
} from '../docMarkdown';
describe('normalizeDocPath', () => {
it('strips the docs prefix, leading slashes, and the .md suffix', () => {
expect(normalizeDocPath('/docs/INSTALL.md')).toBe('INSTALL');
expect(normalizeDocPath('docs/i18n/de/README.md')).toBe('i18n/de/README');
expect(normalizeDocPath('INSTALL')).toBe('INSTALL');
expect(normalizeDocPath(' /FAQ.md ')).toBe('FAQ');
});
});
describe('doc URLs', () => {
it('separates the viewer route from the raw asset', () => {
expect(docRouteForPath('INSTALL.md')).toBe('/docs/INSTALL');
expect(docAssetUrlForPath('INSTALL')).toBe('/docs/INSTALL.md');
expect(docAssetUrlForPath('i18n/de/README.md')).toBe('/docs/i18n/de/README.md');
});
});
describe('resolveDocLink', () => {
it('resolves sibling documents', () => {
expect(resolveDocLink('README', 'INSTALL.md')).toBe('/docs/INSTALL');
expect(resolveDocLink('README', './FAQ.md')).toBe('/docs/FAQ');
});
it('resolves relative to the containing document', () => {
expect(resolveDocLink('i18n/de/README', '../README.md')).toBe('/docs/i18n/README');
expect(resolveDocLink('i18n/de/README', 'CONFIGURATION.md')).toBe(
'/docs/i18n/de/CONFIGURATION',
);
});
// Repo docs are authored for GitHub, where docs/ sits inside the repository,
// so they climb out of the docs directory. Under the shipped root there is
// nothing above it and those files ship flat, so the climb clamps.
it('clamps links that climb above the docs root', () => {
expect(resolveDocLink('README', '../SECURITY.md')).toBe('/docs/SECURITY');
expect(resolveDocLink('README', '../../TERMS.md')).toBe('/docs/TERMS');
});
// Documents shipped from the repository root, such as CONTRIBUTING.md, link
// as docs/X.md because that is the path from the root. They ship flat into
// the docs root, so the prefix has to collapse rather than nest.
it('collapses the docs/ prefix used by root-level documents', () => {
expect(resolveDocLink('CONTRIBUTING', 'docs/AI_TRANSPARENCY.md')).toBe('/docs/AI_TRANSPARENCY');
expect(resolveDocLink('CONTRIBUTING', 'SECURITY.md')).toBe('/docs/SECURITY');
});
it('preserves fragments', () => {
expect(resolveDocLink('README', 'CONFIGURATION.md#api-tokens')).toBe(
'/docs/CONFIGURATION#api-tokens',
);
});
it('ignores anything that is not an intra-doc markdown link', () => {
expect(resolveDocLink('README', 'https://example.com/page.md')).toBeNull();
expect(resolveDocLink('README', 'https://github.com/rcourtman/Pulse')).toBeNull();
expect(resolveDocLink('README', '#section')).toBeNull();
expect(resolveDocLink('README', 'mailto:[email protected]')).toBeNull();
});
});
describe('renderDocMarkdown', () => {
it('does not turn hard-wrapped prose into visible line breaks', () => {
// The AI chat renderer sets breaks: true, which would put a <br> between
// these two lines. Documentation is hard-wrapped, so that would break
// every paragraph in the shipped set.
const html = renderDocMarkdown('A wrapped\nparagraph.', 'README');
expect(html).not.toContain('<br');
expect(html).toContain('A wrapped\nparagraph.');
});
it('renders standard markdown structure', () => {
const html = renderDocMarkdown('# Title\n\n- one\n- two\n', 'README');
expect(html).toContain('<h1');
expect(html).toContain('<li>one</li>');
});
it('creates stable GitHub fragments from heading text, including duplicate headings', () => {
const source = '## Resource **Maintenance**\n\n## Resource Maintenance\n\n## Привет 你好';
const container = document.createElement('div');
container.innerHTML = renderDocMarkdown(source, 'API');
expect(Array.from(container.querySelectorAll('h2'), (heading) => heading.id)).toEqual([
'resource-maintenance',
'resource-maintenance-1',
'привет-你好',
]);
// Rendering another document must not inherit the first one's counters.
expect(renderDocMarkdown('## Resource Maintenance', 'OTHER')).toContain(
'id="resource-maintenance"',
);
});
it('keeps explicit anchors and avoids assigning their IDs to another heading', () => {
const container = document.createElement('div');
container.innerHTML = renderDocMarkdown(
'<a id="maintenance"></a>\n\n## Maintenance\n\n## Maintenance',
'API',
);
expect(container.querySelector('a')?.id).toBe('maintenance');
expect(Array.from(container.querySelectorAll('h2'), (heading) => heading.id)).toEqual([
'maintenance-1',
'maintenance-2',
]);
});
it('points intra-doc links at the viewer and marks them for routing', () => {
const html = renderDocMarkdown('[Install](INSTALL.md)', 'README');
expect(html).toContain('href="/docs/INSTALL"');
expect(html).toContain('data-doc-link');
expect(html).not.toContain('target="_blank"');
});
it('opens external links in a new tab', () => {
const html = renderDocMarkdown('[Site](https://example.com)', 'README');
expect(html).toContain('target="_blank"');
expect(html).toContain('rel="noopener noreferrer"');
});
it('strips scripts and event handlers', () => {
const html = renderDocMarkdown(
'<script>alert(1)</script>\n\n<img src=x onerror="alert(1)">\n\n[x](javascript:alert(1))',
'README',
);
expect(html).not.toContain('<script');
expect(html).not.toContain('onerror');
expect(html).not.toContain('javascript:');
});
it('neutralizes an advisory-shaped nested resource payload before link rewriting', () => {
const html = renderDocMarkdown(
[
'<footer>',
' <img src="x" onload="alert(1)" onerror="alert(2)">',
'</footer>',
'<div><a href="INSTALL.md">safe link</a></div>',
].join('\n'),
'README',
);
const template = document.createElement('template');
template.innerHTML = html;
expect(template.content.querySelector('footer, [onload], [onerror], script')).toBeNull();
const image = template.content.querySelector('img');
expect(image?.getAttribute('src')).toBe('x');
const link = template.content.querySelector('a');
expect(link?.getAttribute('href')).toBe('/docs/INSTALL');
expect(link?.hasAttribute('data-doc-link')).toBe(true);
});
});
describe('scrollToDocFragment', () => {
it('scrolls and moves keyboard focus to an encoded fragment in the rendered document', () => {
const container = document.createElement('article');
container.innerHTML = renderDocMarkdown('## Привет 你好', 'API');
document.body.appendChild(container);
const heading = container.querySelector('h2')!;
heading.scrollIntoView = vi.fn();
try {
scrollToDocFragment(container, `#${encodeURIComponent(heading.id)}`);
expect(heading.scrollIntoView).toHaveBeenCalledWith({ block: 'start' });
expect(document.activeElement).toBe(heading);
expect(heading.tabIndex).toBe(-1);
} finally {
container.remove();
}
});
it('ignores absent or malformed fragments without moving focus', () => {
const container = document.createElement('article');
container.innerHTML = '<h2 id="maintenance">Maintenance</h2>';
const heading = container.querySelector('h2')!;
heading.scrollIntoView = vi.fn();
for (const hash of ['', '#', '#missing', '#%invalid']) scrollToDocFragment(container, hash);
expect(heading.scrollIntoView).not.toHaveBeenCalled();
});
});
describe('wrapTables', () => {
// Making the table itself display:block; overflow-x:auto is not enough, its
// rows still lay out past the block box and push the page into horizontal
// scrolling on a phone. A wrapping element is what contains the overflow.
it('gives each table its own scroll container', () => {
const container = window.document.createElement('div');
container.innerHTML = '<table><tbody><tr><td>a</td></tr></tbody></table>';
wrapTables(container);
const wrapper = container.querySelector('[data-doc-table-scroll]');
expect(wrapper).not.toBeNull();
expect(wrapper?.className).toContain('overflow-x-auto');
expect(wrapper?.querySelector('table')).not.toBeNull();
});
it('does not wrap a table twice', () => {
const container = window.document.createElement('div');
container.innerHTML = '<table><tbody><tr><td>a</td></tr></tbody></table>';
wrapTables(container);
wrapTables(container);
expect(container.querySelectorAll('[data-doc-table-scroll]').length).toBe(1);
});
});
describe('stripLeadingTitle', () => {
it('removes the title the viewer promotes into the page header', () => {
expect(stripLeadingTitle('# Title\n\nBody text')).toBe('Body text');
});
it('leaves a level-one heading that is not the document title', () => {
const markdown = 'Intro paragraph\n\n# Later heading\n';
expect(stripLeadingTitle(markdown)).toBe(markdown);
});
it('leaves documents with no heading untouched', () => {
expect(stripLeadingTitle('Just body')).toBe('Just body');
});
});
describe('extractDocTitle', () => {
it('uses the first level-one heading', () => {
expect(extractDocTitle('# Installation Guide\n\nBody', 'fallback')).toBe('Installation Guide');
});
it('falls back when there is no heading', () => {
expect(extractDocTitle('Body only', 'INSTALL')).toBe('INSTALL');
});
it('does not treat a mid-document heading as the title', () => {
expect(extractDocTitle('Intro\n\n# Later heading', 'FAQ')).toBe('FAQ');
});
});
describe('documentation table column semantics', () => {
it('assigns column scope to every sanitized Markdown header without promoting data cells', () => {
const container = document.createElement('div');
container.innerHTML = renderDocMarkdown(
'| Feature | Community | Pro |\n| --- | --- | --- |\n| Metrics | Yes | Yes |',
'PULSE_PRO',
);
const headers = Array.from(container.querySelectorAll('thead th'));
expect(headers).toHaveLength(3);
expect(headers.map((header) => header.getAttribute('scope'))).toEqual(['col', 'col', 'col']);
expect(container.querySelectorAll('tbody [scope]')).toHaveLength(0);
expect(
container.querySelector('table')?.parentElement?.hasAttribute('data-doc-table-scroll'),
).toBe(true);
});
it('does not trust document-supplied roles or scope while assigning trusted column scope', () => {
const container = document.createElement('div');
container.innerHTML = renderDocMarkdown(
'<table><thead><tr><th role="presentation" scope="row" onclick="evil()">Heading</th></tr></thead><tbody><tr><th scope="col" class="fixed">Body label</th><td>Value</td></tr></tbody></table>',
'PULSE_PRO',
);
const header = container.querySelector('thead th');
expect(header?.getAttribute('scope')).toBe('col');
expect(container.querySelector('[role], [onclick], th[class]')).toBeNull();
expect(container.querySelector('tbody th')?.hasAttribute('scope')).toBe(false);
});
});