[DevOps] Expand doc link tests to all documentation folders#2029
[DevOps] Expand doc link tests to all documentation folders#2029
Conversation
- Refactor DocsLinks.Tests.ps1 with reusable helpers and add validation for docs/ (Jekyll), docs-wiki/ (wiki page links, repo-relative links), and root markdown files - Add -Docs parameter to Test-PowerShell.ps1 for running doc tests - Fix broken links in changelog.md (wrong PowerShell command paths) - Fix broken wiki link [[unit tests]] -> [[unit tests|Build and test]] - Delete unused draft docs/_docs/services/compute/vritual-machines.md - Add version-gated known-issue skip for configure-recommendations.md Co-Authored-By: Claude <noreply@anthropic.com>
microsoft-github-policy-service
bot
added
the
Needs: Review 👀
There was a problem hiding this comment.
Pull request overview
This PR expands the existing documentation link validation tests to cover all documentation folders in the repository (docs/, docs-wiki/, and root markdown files) instead of just docs-mslearn/. The changes include refactoring helpers for better reusability, adding new test contexts for each documentation location, implementing a known-issues mechanism for version-gated links, and fixing several broken links discovered by the expanded tests.
Changes:
- Refactored
DocsLinks.Tests.ps1with reusable helper functions and added comprehensive test coverage for docs/ (Jekyll), docs-wiki/ (GitHub Wiki), and root markdown files - Added
-Docsparameter toTest-PowerShell.ps1for independent execution of documentation link tests - Fixed broken links in changelog.md and Home.md, and removed unused draft file with typo in filename
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| src/scripts/Test-PowerShell.ps1 | Adds -Docs switch parameter to enable running documentation link tests independently |
| src/powershell/Tests/Unit/DocsLinks.Tests.ps1 | Major refactor expanding test coverage from docs-mslearn to all doc folders with reusable helpers, version-gated known issues, and new validation contexts |
| docs/_docs/services/compute/vritual-machines.md | Deletes unused draft file with typo in filename (vritual instead of virtual) |
| docs-wiki/Home.md | Fixes wiki link syntax from [[unit tests]] to [[unit tests|Build and test]] to reference correct page |
| docs-mslearn/toolkit/changelog.md | Corrects broken PowerShell command documentation paths from cost-management/ to cost/ |
| $toolkitVersion = (Get-Content (Join-Path $repoRoot 'package.json') | ConvertFrom-Json).version | ||
| $knownIssues = @( | ||
| # configure-recommendations.md will be created as part of 14.0 | ||
| @{ MaxVersion = '14.0'; PathPattern = 'toolkit/hubs/data-processing.md'; LinkPattern = 'configure-recommendations.md' } | ||
| ) | ||
|
|
||
| # Helper: Check if a link should be skipped as a known issue | ||
| function Test-KnownIssue([string]$sourceRel, [string]$linkTarget) | ||
| { | ||
| foreach ($issue in $knownIssues) | ||
| { | ||
| if ([version]$toolkitVersion -lt [version]$issue.MaxVersion -and |
There was a problem hiding this comment.
The version parsing logic may fail if package.json contains a version with a pre-release suffix like "13.0.0-dev". The [version] type cast in PowerShell doesn't support semantic versioning pre-release identifiers. Consider stripping any suffix before comparison, or wrapping the version cast in a try-catch block to handle potential parsing errors gracefully.
For example, you could add: $toolkitVersion = $toolkitVersion -replace '-.*$', '' before the version comparison to remove any pre-release suffix.
🛠️ Description
Expands the existing
DocsLinks.Tests.ps1to validate markdown links across all documentation folders, not justdocs-mslearn/. Also fixes broken links uncovered by the new tests.Fixes #1690
Changes
Test expansion (
DocsLinks.Tests.ps1):BeforeDiscoverywith reusable helpers (Get-MarkdownFiles,Get-InternalMdLinks,Get-MarkdownUrls)docs/(Jekyll) internal link + anchor validation — excludes_automation/(parked files pending migration)docs-wiki/wiki page link validation ([[Page]]syntax, case-insensitive)docs-wiki/repo-relative link validation (../tree/dev/links)docs-wiki/internal relative link validationdocs-mslearn:prefixconfigure-recommendations.md(expected in 14.0)New
-Docsparameter (Test-PowerShell.ps1):-Docsswitch to run doc link tests independentlyBroken link fixes:
changelog.md: Fixedpowershell/cost-management/→powershell/cost/pathsHome.md: Fixed[[unit tests]]→[[unit tests|Build and test]]docs/_docs/services/compute/vritual-machines.md(typo filename, all links broken)📋 Checklist
🔬 How did you test this change?
🙋♀️ Do any of the following that apply?
📑 Did you update
docs/changelog.md?📖 Did you update documentation?
🤖 Generated with Claude Code