Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
4.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Unit tests for the inline-code linkifiers.
 *
 * Run: pnpm -F @astryxdesign/docsite test
 */

import {describe, it, expect} from 'vitest';
import {linkifyCode} from '../components/codeLinkifiers';
import {docTopics, docsTreeRoutes} from '../generated/docsRegistry';
import {components} from '../generated/componentRegistry';

describe('doc topic linkifier', () => {
  it.each([
    ['astryx docs tokens', '/docs/tokens'],
    ['astryx docs styling-libraries', '/docs/styling-libraries'],
    ['npx astryx docs icons', '/docs/icons'],
    ['npx @astryxdesign/cli docs icons', '/docs/icons'],
    ['npx @astryxdesign/[email protected] docs global', '/docs/global'],
    ['  astryx docs theme  ', '/docs/theme'],
    // The docs index, for a bare command.
    ['astryx docs', '/docs'],
    // A section argument and CLI-only flags still belong to the topic page.
    ['astryx docs tokens spacing', '/docs/tokens'],
    ['astryx docs styling --dense', '/docs/styling'],
    ['astryx docs styling --zh', '/docs/styling'],
  ])('links %s', (code, href) => {
    expect(linkifyCode(code)).toBe(href);
  });

  it('links every topic the site serves', () => {
    for (const {topic} of docTopics) {
      expect(linkifyCode(`astryx docs ${topic}`)).toBe(`/docs/${topic}`);
    }
  });

  it.each([
    // A renamed topic degrades to plain code rather than a 404.
    ['astryx docs nonexistent-topic'],
    // Other commands have no one-to-one page.
    ['astryx component Button'],
    ['astryx theme build'],
    ['astryx upgrade --apply'],
    // Ordinary backticked prose and identifiers.
    ['xstyle'],
    ['--color-text-primary'],
    ['See astryx docs tokens for the full reference'],
    ['other-cli docs tokens'],
    [''],
  ])('leaves %s as plain code', code => {
    expect(linkifyCode(code)).toBeNull();
  });
});

describe('component name linkifier', () => {
  it.each([
    ['Button', '/components/Button'],
    [
      'InternationalizationProvider',
      '/components/InternationalizationProvider',
    ],
    [
      '<InternationalizationProvider>',
      '/components/InternationalizationProvider',
    ],
    ['<Button/>', '/components/Button'],
    ['<Button />', '/components/Button'],
    ['  <Popover>  ', '/components/Popover'],
    // XDS-prefixed aliases map to the unprefixed page, like the changelog's
    // prose linkifier.
    ['XDSButton', '/components/Button'],
    ['<XDSButton>', '/components/Button'],
  ])('links %s', (code, href) => {
    expect(linkifyCode(code)).toBe(href);
  });

  it('links every documented component and hook name', () => {
    for (const {name} of Object.values(components).flat()) {
      expect(linkifyCode(name)).toBe(`/components/${name}`);
    }
  });

  it.each([
    // Case matters: `button` is the HTML element, `Button` the component.
    ['button'],
    ['<dialog>'],
    // A name with anything attached is a snippet, not a reference.
    ['Popover API'],
    ['<Button open>'],
    ['Button.props'],
    ['Crimson Text'],
    ['NotARealComponent'],
    ['<NotARealComponent>'],
    ['XDSNotARealComponent'],
  ])('leaves %s as plain code', code => {
    expect(linkifyCode(code)).toBeNull();
  });
});

/** Every backticked `astryx docs ...` reference in a chunk of authored data. */
function docReferences(json: string): string[] {
  const found = [...json.matchAll(/`((?:npx )?astryx docs[^`]*)`/g)];
  return [...new Set(found.map(m => m[1]))];
}

/**
 * Guards the failure mode the linkifier cannot catch at runtime: if a topic is
 * renamed, an unresolvable reference degrades to plain code instead of 404ing,
 * so nobody notices the cross-reference went stale.
 *
 * Scanning the serialized registries rather than walking their shapes keeps
 * this short and covers every authored field, not just the ones rendered
 * today.
 */
describe('doc references in shipped content', () => {
  const corpora = {
    'doc topics': JSON.stringify(docTopics),
    'component docs': JSON.stringify(components),
  };

  it.each(Object.entries(corpora))('scans %s', (_name, json) => {
    expect(docReferences(json).length).toBeGreaterThan(0);
  });

  it('links every reference to a page the site serves', () => {
    // A docs-tree route the site has no page for yet (a namespace, a command
    // or API doc) stays plain code, and still opens in `astryx docs`; any
    // other unlinked reference is stale.
    const treeRoutes = new Set(docsTreeRoutes);
    const inTree = (ref: string) =>
      treeRoutes.has(ref.replace(/^(?:npx )?astryx docs /, '').split(' ')[0]);
    const all = Object.values(corpora).flatMap(docReferences);
    expect(all.filter(ref => linkifyCode(ref) == null && !inTree(ref))).toEqual(
      [],
    );
    expect(treeRoutes.has('cli/commands/upgrade')).toBe(true);
  });
});