Testing Strategy (Vitest & Python Unittest)

Introduction

The testing strategy for the chemd project is designed as a multi-stage validation pipeline that mirrors the project's modular architecture. As a pnpm workspace and Turborepo monorepo, the project utilizes Vitest as its primary test runner for TypeScript-based packages and applications. The strategy focuses on ensuring the integrity of the semantic language layer, the resolution/template expansion layer, and the rendering adapters.

The scope of testing encompasses unit tests for individual block parsing logic, integration tests for the full compilation pipeline, and snapshot testing for complex outputs like HTML and SVG. While the provided source files primarily detail the TypeScript/Vitest environment, the architecture supports a multi-stage pipeline where diagnostics are attached at every stage—from source ingestion to final export.

Sources: AGENTS.md:10-15, chemd-v0.1-architecture.md:18.1-18.4

Testing Architecture & Workflow

The project follows a "validate changed scope first" approach. Developers are required to run filtered tests for specific packages before executing the full suite and type checks.

Test Execution Commands

The following commands are standard for the testing lifecycle:

Sources: AGENTS.md:20-25

Validation Pipeline

The testing process is integrated into the development workflow, requiring verification of plans before coding and validation after every step.

This diagram illustrates the mandatory verification steps required before a Pull Request can be submitted.
Sources: AGENTS.md:28-32

Unit and Integration Testing Tiers

Parser Validation

The packages/parser tests focus on the lexical and structural analysis of chemd documents. These tests verify the parser's ability to handle YAML frontmatter, detect semantic blocks (reaction, result, molecule), and tokenize inline chemistry syntax like :chem[...].

Key validation areas include:

• Token Spans: Tracking exact startLine, startColumn, endLine, and endColumn for references and inline tokens.
• Diagnostic Emission: Ensuring the parser emits correct warnings for unknown fields (W_UNKNOWN_FIELD), unterminated blocks (W_UNTERMINATED_BLOCK), or invalid date formats.
• Tolerance: Testing the parser's ability to keep parsing valid segments even after encountering invalid YAML or markdown lines.

Sources: packages/parser/tests/parser.test.ts:40-100, packages/parser/tests/parser.test.ts:250-265

Resolver and Template Testing

The packages/resolver tests ensure that the semantic links between document elements are correctly established. This includes the expansion of template and use blocks into semantic AST fragments.

The diagram shows the resolver's role in transforming a raw AST into a fully resolved document by interacting with an object index.
Sources: packages/resolver/tests/resolver.test.ts:15-30, chemd-v0.1-architecture.md:9

Renderer & Export Testing

Rendering tests verify the transformation of the resolved AST into final outputs. This tier uses Vitest to confirm that the renderer-html produces valid HTML structures with appropriate CSS classes and that the renderer-docx correctly prepares handoff payloads for external tools like Pandoc.

• HTML Rendering: Validates task items, nested lists, and table alignment semantics.
• DOCX Bridge: Tests the creation of a "bridge payload" containing the document AST and render metadata for downstream processing.
• Node.js Integration: Specific tests for Node-only environments verify the execution of Pandoc commands for DOCX generation, including timeout handling and binary path verification.

Sources: packages/renderer-html/tests/renderer-html.test.ts:80-100, packages/compiler/tests/compiler-node.test.ts:40-60

Testing Constraints and Requirements

The project maintains strict requirements for test coverage and accuracy:

1. Snapshot Testing: Used for stable fixtures to ensure that HTML and SVG outputs do not regress over time.
2. Golden File Tests: Employs fixture-driven tests for end-to-end compilation results.
3. No Arbitrary Logic: Tests for the template system ensure it remains "weak"—it must not execute arbitrary scripts, and tests must verify the prevention of circular expansion.
4. Diagnostic Accuracy: Every error condition (e.g., E_DUPLICATE_ID, E_TEMPLATE_CYCLE) must be backed by a test case ensuring the diagnostic is correctly attached to the AST.

Sources: chemd-v0.1-architecture.md:11.1-11.4, chemd-v0.1-architecture.md:18.1-18.4, packages/resolver/tests/resolver.test.ts:160-180

Summary

The chemd testing strategy relies on a robust suite of Vitest-powered unit and integration tests distributed across a monorepo. By isolating parsing, resolution, and rendering into distinct testing phases, the project ensures that semantic meaning is preserved even as rendering styles change. The strategy emphasizes diagnostic tracking and strict adherence to the v0.1 specification, providing a reliable foundation for the chemistry-focused markdown ecosystem.