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

---
title: "Testing"
linkTitle: "Testing"
weight: 30
description: >
  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:

```bash
task test:quick
```

This runs:

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

### Full Test Suite

Before creating a pull request:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```markdown
Some text

​```bash
command here
​```

More text
```

### Markdown: MD032 - Blank lines around lists

**Problem:** Missing blank line before/after list

**Solution:** Add blank lines:

```markdown
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](../cicd/).