website-and-documentation/content/en/docs-old/documentation/testing.md

title	linkTitle	weight	description
Testing	Testing	30	Quality assurance processes for documentation.

Testing Philosophy

Quality documentation requires testing. Our testing process validates:

• Build integrity - Hugo can generate the site
• Content quality - Markdown follows best practices
• HTML validity - Generated HTML is well-formed
• Link integrity - No broken internal or external links

Testing Capabilities

{{< likec4-view view="testingCapabilities" project="documentation-platform" >}}

Local Testing

Before committing changes, run tests locally:

Quick Tests

For rapid feedback during development:

task test:quick

This runs:

• task test:build - Hugo build validation
• task test:markdown - Markdown linting

Full Test Suite

Before creating a pull request:

task test

This runs all tests including:

• task test:build - Build validation
• task test:markdown - Markdown linting
• task test:html - HTML validation
• task test:links - Link checking

Individual Tests

You can run individual tests:

Build Test

Validates that Hugo can build the site:

task test:build

This runs: hugo --gc --minify --logLevel info

What it checks:

• Hugo configuration is valid
• Content files have correct frontmatter
• Templates render without errors
• No circular dependencies in content structure

Markdown Lint

Checks Markdown syntax and style:

task test:markdown

This uses markdownlint with custom rules in .markdownlint.json.

What it checks:

• Consistent heading hierarchy
• Proper list formatting
• Code blocks have language tags
• No trailing whitespace
• Consistent line length (where applicable)

Common issues:

• Missing blank lines around code blocks
• Inconsistent list markers
• Heading levels skipped

HTML Validation

Validates generated HTML:

task test:html

This uses htmlvalidate with rules in .htmlvalidate.json.

What it checks:

• Well-formed HTML5
• Proper nesting of elements
• Valid attributes
• Accessible markup

Link Checking

Verifies all links are valid:

task test:links

This uses htmltest configured in .htmltest.yml.

What it checks:

• Internal links point to existing pages
• External links are reachable
• Anchor links target existing elements
• No redirects (301/302)

Note: This test can be slow for large sites with many external links.

CI Testing

All tests run automatically on:

• Push to main - Full test suite
• Pull requests - Full test suite

View the GitHub Actions workflow: .github/workflows/test.yml

CI Test Results

If tests fail in CI:

1. Check the GitHub Actions logs
2. Look for specific test failures
3. Run the same test locally: task test:<name>
4. Fix the issue
5. Commit and push

Artifacts

CI uploads test artifacts:

• htmltest-report/ - Link checking results

Download these from the GitHub Actions run to investigate failures.

Test Configuration Files

File	Purpose
.markdownlint.json	Markdown linting rules
.htmlvalidate.json	HTML validation rules
.htmltest.yml	Link checker configuration

Best Practices

1. Test early, test often - Run task test:quick frequently
2. Fix issues immediately - Don't accumulate technical debt
3. Understand failures - Read error messages carefully
4. Update tests - If rules change, update config files
5. Document exceptions - If you need to ignore a rule, document why

Common Issues and Solutions

Markdown: MD031 - Blank lines around fences

Problem: Missing blank line before/after code block

Solution: Add blank lines:

Some text

​```bash
command here
​```

More text

Markdown: MD032 - Blank lines around lists

Problem: Missing blank line before/after list

Solution: Add blank lines:

Text before

- List item 1
- List item 2

Text after

HTML: Invalid nesting

Problem: Elements improperly nested

Solution: Check template files and shortcodes

Link Check: 404 Not Found

Problem: Link points to non-existent page

Solution:

• Fix the link
• Create the missing page
• Remove the link if no longer relevant

Next Steps

Learn about the automated CI/CD pipeline.