Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document MSTestAnalysisMode property #44632

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document MSTestAnalysisMode property #44632

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64e13b2
Document MSTestAnalysisMode property
Youssef1313 Jan 31, 2025
cabddeb
Address review comments
Youssef1313 Jan 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/core/testing/mstest-analyzers/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,42 @@ ms.date: 12/20/2023

The rules are organized into categories such as performance usage...

Starting with MSTest.TestFramework 3.7, the MSTest.Analyzers NuGet package is a dependency of the framework. For earlier versions, you need to use `MSTest` metapackage or add a package reference for `MSTest.Analyzers` explicitly.

## MSTestAnalysisMode

Starting with MSTest 3.8, an MSBuild property named `MSTestAnalysisMode` is available to determine which analyzers are enabled at which severity.

The available values are:

### `None`

This sets all analyzers to `none` severity, making all of them disabled. You can then enable individual analyzers using `.editorconfig` or `.globalconfig` files.

### `Default`

This follows the default documented behavior for each rule.

- Rules that are enabled by default will use their default severity.
- Rules that are disabled by default will use `none` severity.

### `Recommended`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be a bit too boring to maintain the doc but it would probably be awesome if we could list here the rules enabled by this mode.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's easy that it gets outdated, esp when changes happen between releases. I'm not sure how to best handle this. Maybe the generated globalconfigs we produce should be part of version control with CI check that ensures the file is up-to-date? In that case we can instruct users to go to the relevant release branch and look into the globalconfig exactly for the specific release. Alternatively, we can tell them that they can look into the NuGet package contents with NuGet Package Explorer and find the globalconfig there (it's less convenient though 😕)

I'm not really sure what's best.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we could generate a markdown per version and we would include it here.
@IEvangelist is this something that is common?


This mode is more aggressive than `Default`. Rules that are enabled by default with Info (`suggestion`) severity are escalated to be warnings. Moreover, certain rules may decide that they are escalated to be errors in both `Recommended` and `All` modes. For example, [MSTEST0003: Test methods should have valid layout](mstest0003.md) is escalated to error in `Recommended` and `All` modes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first sentence could feel a little scary to users. I would instead say that in Default we are ensuring to not have rules that would cause warning or error and that don't result in runtime error. Recommended is what we think most dev should use but this means that a minor update of the package could cause new warnings.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recommended is what we think most dev should use but this means that a minor update of the package could cause new warnings.

But a minor update can cause new warnings for "Default" as well?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only for cases where there is an execution error. Otherwise we mark the new rules as info


### `All`

This mode is more aggressive than `All`. All rules are enabled as warnings. As mentioned for `Recommended` mode, certain rules may decide that they are escalated to be errors in both `Recommended` and `All` modes. For example, [MSTEST0003: Test methods should have valid layout](./mstest0003.md) is escalated to error in `Recommended` and `All` modes.

> [!NOTE]
> The following rules are completely opt-in and are not enabled in `Default`, `Recommended`, or `All` modes:
>
> - [MSTEST0015: Test method should not be ignored](mstest0015.md)
> - [MSTEST0019: Prefer TestInitialize methods over constructors](mstest0019.md)
> - [MSTEST0020: Prefer constructors over TestInitialize methods](mstest0020.md)
> - [MSTEST0021: Prefer Dispose over TestCleanup methods](mstest0021.md)
> - [MSTEST0022: Prefer TestCleanup over Dispose methods](mstest0022.md)
Comment on lines +48 to +55
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure where to best document this. Options:

  1. In this page only as I did in this PR
  2. In doc page of the specific analyzer, with only a note here mentioning "some rules" may have this behavior
  3. Both as I did here plus in the specific analyzer page.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably 3 but the specific analyzer page update can be done on a follow-up PR IMO.


## Categories

### Design rules
Expand Down