docs-ssot

Appearance

Testing ​

Testing ​

This document describes the testing strategy for docs-ssot.

Overview ​

The project includes tests for the documentation generator, include resolver, and pipeline processing.

Testing ensures that documentation generation is deterministic, correct, and safe from issues such as missing includes or circular references.

What We Test ​

The following components should be tested:

Include Resolver ​

  • Include directive parsing
  • File loading
  • Recursive includes
  • Circular include detection
  • Missing file errors

Template Processing ​

  • Template loading
  • Include expansion inside templates
  • Final document assembly

Pipeline ​

  • End-to-end document generation
  • README generation
  • AGENTS.md, CLAUDE.md generation
  • Multiple template builds

Test Types ​

Unit Tests ​

Unit tests should cover:

  • Include parsing
  • Path resolution
  • Circular include detection
  • File loading logic
  • Markdown merging

Integration Tests ​

Integration tests should:

  • Run the generator on a test docs directory
  • Generate README.md
  • Compare output with expected files

Example flow:

testdata/
docs/
template/
expected/

Test steps:

  1. Run generator
  2. Generate README.md
  3. Compare with expected/README.md
  4. Test should fail if output differs

Example Test Cases ​

Include Resolver ​

  • Include single file
  • Include nested files
  • Include multiple files
  • Missing file error
  • Circular include error

Generator ​

  • Generate README from template
  • Generate CLAUDE from template
  • Multiple includes in template
  • Nested includes
  • Empty include file

Deterministic Output ​

Generated documents must always be deterministic:

  • Same input → same output
  • No timestamps in generated files
  • No random ordering
  • Stable include order

This is important for Git diffs and CI.

CI Testing ​

Tests should run in CI on every pull request.

Typical CI steps:

sh
go test ./...
docs-ssot build
git diff --exit-code README.md

This ensures that generated files are always up to date.

sh
make test

Example Makefile:

makefile
test:
	go test ./...

test-e2e:
	docs-ssot build
	git diff --exit-code