Improve analyzers docs #51209
Open
Improve analyzers docs #51209
+500
−81
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request improves the MSTest analyzers documentation by reorganizing the content for better browsability. The changes add category-based and concept-based organization to help developers find relevant analyzer rules more easily.
Changes:
- Restructured TOC to make category overview pages directly accessible (removed redundant "Overview" nesting)
- Enhanced category overview pages (design, performance, suppression, usage) with comprehensive tables and scenario-based guidance
- Added "Rules by concept" section to overview.md organizing rules by common testing scenarios
- Added "All rules (quick reference)" table in overview.md for easy lookup
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/navigate/devops-testing/toc.yml | Improved navigation structure by linking category pages directly and removing nested "Overview" items |
| docs/core/testing/mstest-analyzers/usage-rules.md | Added comprehensive rule table, organized rules by common scenarios (test structure, lifecycle, data-driven testing, assertions, TestContext, async, configuration) |
| docs/core/testing/mstest-analyzers/suppression-rules.md | Added detailed explanations of suppression rules with examples showing why each rule suppresses specific diagnostics |
| docs/core/testing/mstest-analyzers/performance-rules.md | Expanded with detailed guidance on test parallelization including when to enable/disable parallelization |
| docs/core/testing/mstest-analyzers/design-rules.md | Organized design rules by scenarios (structuring classes, initialization/cleanup patterns, assertions, test quality) |
| docs/core/testing/mstest-analyzers/overview.md | Added "Rules by concept" section and comprehensive "All rules" quick reference table |
Comments suppressed due to low confidence (5)
docs/core/testing/mstest-analyzers/performance-rules.md:40
- According to the Markdown Writing Style Instructions, write complete sentences in lists with proper punctuation. The bullet points should be complete sentences. For example, change "Tests have dependencies on shared resources" to "Tests have dependencies on shared resources." (add period) or rephrase as complete sentences.
- Tests have dependencies on shared resources
- Tests modify global state
- Tests require specific execution order
- You're debugging test failures
docs/core/testing/mstest-analyzers/usage-rules.md:66
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Validating test structure" to a noun-based title, such as "Test structure validation" or use an imperative like "Validate test structure".
### Validating test structure
docs/core/testing/mstest-analyzers/design-rules.md:33
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Structuring test classes" to a noun-based title, such as "Test class structure" or use an imperative like "Structure test classes".
### Structuring test classes
docs/core/testing/mstest-analyzers/design-rules.md:41
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Choosing initialization patterns" to a noun-based title, such as "Initialization patterns" or "Initialization pattern selection".
### Choosing initialization patterns
docs/core/testing/mstest-analyzers/design-rules.md:55
- According to the Markdown Writing Style Instructions, never use gerunds in titles. Change "Writing better assertions" to a noun-based title, such as "Better assertions" or "Assertion best practices".
### Writing better assertions
Youssef1313
reviewed
Jan 20, 2026
Youssef1313
reviewed
Jan 20, 2026
gewarren
approved these changes
Jan 22, 2026
adegeo
reviewed
Jan 23, 2026
| [MSTEST0045](mstest0045.md) | UseCooperativeCancellationForTimeoutAnalyzer | A test method uses <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute> without setting the `CooperativeCancellation` property to `true`. | ||
| Design rules help you create and maintain test suites that adhere to proper design and good practices. These rules focus on test structure, best practices, and common patterns that lead to maintainable test code. | ||
|
|
||
| ## Rules in this category |
Contributor
There was a problem hiding this comment.
In all of the articles, tables and lists are missing periods.
Contributor
|
@Evangelink I've opened a new pull request, #51301, to work on those changes. Once the pull request is ready, I'll request review from you. |
…ion (#51301) * Initial plan * Add missing periods to tables and lists in analyzer rules documentation Co-authored-by: Evangelink <11340282+Evangelink@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Evangelink <11340282+Evangelink@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Make it easier to browse all rules, rules by category and also allows people browsing the docs to understand the rules that could be interesting by concepts (avoiding the hassle to browse all rules).
Internal previews