tests — docs

Module: tests-docs Cohesion: 0.80 Members: 0

tests — docs

This document provides an overview and detailed explanation of the tests/docs/renderers.test.ts module. This module is crucial for ensuring the correctness and reliability of the documentation rendering pipeline, specifically for the MultiFormatRenderer and HtmlThemeEngine components.

Introduction

The renderers.test.ts module contains unit tests for the core logic responsible for transforming structured documentation input into various output formats (Markdown, JSON, HTML, Wiki). It validates the functionality of MultiFormatRenderer and HtmlThemeEngine, ensuring that documentation is consistently and accurately generated across different targets.

Developers contributing to the documentation generation process, adding new output formats, or modifying existing rendering logic should refer to these tests to understand expected behavior and ensure new changes do not introduce regressions.

Core Components Under Test

This test module primarily focuses on two key classes:

MultiFormatRenderer: This class is responsible for orchestrating the generation of documentation in multiple formats from a common RenderInput structure. It handles tasks like slug generation, section extraction, and delegating to format-specific rendering methods.
HtmlThemeEngine: This class provides the foundational capabilities for converting Markdown content into HTML, applying styling, and handling HTML-specific utilities like escaping. It's a dependency for MultiFormatRenderer when generating HTML-based outputs.

The relationship between these components can be visualized as follows:

graph TD
    A[MultiFormatRenderer] --> B[HtmlThemeEngine]
    A --> C{Output Formats}
    C --> D[Markdown]
    C --> E[JSON]
    C --> F[HTML]
    C --> G[Wiki (HTML, JSON)]

Test Fixtures

To facilitate consistent testing, the module defines two helper functions for creating mock RenderInput data:

makeInput(overrides?: Partial): RenderInput: Creates a standard RenderInput object representing a single module's documentation. It includes common fields like moduleId, title, markdown, members, cohesion, filePaths, and generatedAt. This function allows for easy customization of specific fields for individual test cases.
makeModules(): RenderInput[]: Returns an array of RenderInput objects, typically used when testing features that involve multiple modules, such as sidebar navigation or index page generation.

Detailed Test Coverage

The tests are organized by the methods they validate, providing clear examples of expected inputs and outputs.

`MultiFormatRenderer.slug`

This suite tests the utility method for converting arbitrary strings into a URL-friendly, lowercase kebab-case slug.

Converts to lowercase kebab-case: Ensures basic conversion, e.g., AgentExecutor -> agentexecutor.
Replaces non-alphanumeric with hyphens: Handles special characters and spaces, e.g., agent/executor_v2 -> agent-executor-v2.
Trims leading and trailing hyphens: Cleans up slugs, e.g., --hello--world-- -> hello-world.
Collapses multiple special chars into single hyphen: Prevents excessive hyphens, e.g., a...b___c -> a-b-c.
Handles empty string: Ensures robustness for edge cases.

`MultiFormatRenderer.extractSections`

This suite validates the logic for parsing Markdown content and extracting sections based on H2 headings.

Splits by H2 headings: Verifies that content under H2 headings is correctly identified and stored under a slugified key.
Captures intro content before first H2: Ensures any content preceding the first H2 is captured under the special _intro key.
Strips YAML frontmatter before extracting: Confirms that YAML frontmatter is removed before section parsing.
Handles markdown with no H2 headings: Ensures all content is placed in _intro if no H2s are present.
Handles empty markdown: Verifies graceful handling of empty input.

`MultiFormatRenderer.toMarkdown`

This suite tests the generation of Markdown output, including the addition of YAML frontmatter.

Adds YAML frontmatter: Checks for the presence and correct formatting of metadata like title, module, cohesion, members, and generated.
Preserves original markdown after frontmatter: Ensures the original Markdown content is untouched after the frontmatter.
Escapes double quotes in title: Verifies proper escaping for YAML compatibility.
Reports correct size in bytes: Confirms the sizeBytes property accurately reflects the content's byte length.

`MultiFormatRenderer.toJson`

This suite validates the generation of JSON output, ensuring a structured representation of the module's documentation.

Produces valid JSON with correct structure: Checks for the presence of top-level fields like id, title, cohesion, and members.
Extracts sections correctly into JSON: Verifies that Markdown sections are parsed and included in the sections object within the JSON output.
Includes filePaths and generatedAt: Ensures these metadata fields are present.

`MultiFormatRenderer.toHtml`

This suite tests the generation of a self-contained HTML page for a single module, including navigation and theme features.

Produces self-contained HTML: Checks for standard HTML document structure, including