Skip to content

Commit d507481

Browse files
EvangelinkEvangelink
authored
Add new analyzers docs (#47564)
* Add new analyzers docs * Address review feedback
1 parent 229140b commit d507481

File tree

8 files changed

+282
-28
lines changed

8 files changed

+282
-28
lines changed

‎docs/core/testing/mstest-analyzers/design-rules.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,5 @@ Identifier | Name | Description
2323
[MSTEST0025](mstest0025.md) | PreferAssertFailOverAlwaysFalseConditionsAnalyzer | Use 'Assert.Fail' instead of an always-failing assert
2424
[MSTEST0029](mstest0029.md) | PublicMethodShouldBeTestMethod | A `public` method of a class marked with `[TestClass]` should be a test method (marked with `[TestMethod]`). The rule ignores methods that are marked with `[TestInitialize]`, or `[TestCleanup]` attributes.
2525
[MSTEST0036](mstest0036.md) | DoNotUseShadowingAnalyzer | Shadowing test members could cause testing issues (such as NRE).
26+
[MSTEST0044](mstest0044.md) | PreferTestMethodOverDataTestMethodAnalyzer | A method or type uses <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataTestMethodAttribute> or inherits from it.
27+
[MSTEST0045](mstest0045.md) | UseCooperativeCancellationForTimeoutAnalyzer | A test method uses <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute> without setting the `CooperativeCancellation` property to `true`.

‎docs/core/testing/mstest-analyzers/mstest0044.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: "MSTEST0044: Prefer TestMethod over DataTestMethod"
3+
description: "Learn about code analysis rule MSTEST0044: Prefer TestMethod over DataTestMethod"
4+
ms.date: 07/24/2025
5+
f1_keywords:
6+
- MSTEST0044
7+
- PreferTestMethodOverDataTestMethodAnalyzer
8+
helpviewer_keywords:
9+
- PreferTestMethodOverDataTestMethodAnalyzer
10+
- MSTEST0044
11+
author: Evangelink
12+
ms.author: amauryleve
13+
---
14+
# MSTEST0044: Prefer TestMethod over DataTestMethod
15+
16+
| Property | Value |
17+
|-------------------------------------|------------------------------------------------------------------------------------------|
18+
| **Rule ID** | MSTEST0044 |
19+
| **Title** | Prefer TestMethod over DataTestMethod |
20+
| **Category** | Design |
21+
| **Fix is breaking or non-breaking** | Non-breaking |
22+
| **Enabled by default** | Yes |
23+
| **Default severity** | Warning |
24+
| **Introduced in version** | 3.10.0 |
25+
| **Is there a code fix** | Yes |
26+
27+
## Cause
28+
29+
A method or type uses <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataTestMethodAttribute> or inherits from it.
30+
31+
## Rule description
32+
33+
<xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataTestMethodAttribute> provides no additional value over <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute> and will be removed in a future version. Use <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute> instead for all test methods, including those that use data source attributes like <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute>.
34+
35+
## How to fix violations
36+
37+
Use the provided code fixer to automatically replace <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataTestMethodAttribute> with <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute>. You can also manually replace the attribute if needed. If you have a custom attribute that inherits from <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataTestMethodAttribute>, change it to inherit from <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute> instead.
38+
39+
## When to suppress warnings
40+
41+
Don't suppress warnings from this rule. <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataTestMethodAttribute> will be removed in a future version, so you should migrate to <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute>.

‎docs/core/testing/mstest-analyzers/mstest0045.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "MSTEST0045: Use cooperative cancellation for timeout"
3+
description: "Learn about code analysis rule MSTEST0045: Use cooperative cancellation for timeout"
4+
ms.date: 07/24/2025
5+
f1_keywords:
6+
- MSTEST0045
7+
- UseCooperativeCancellationForTimeoutAnalyzer
8+
helpviewer_keywords:
9+
- UseCooperativeCancellationForTimeoutAnalyzer
10+
- MSTEST0045
11+
author: Evangelink
12+
ms.author: amauryleve
13+
---
14+
# MSTEST0045: Use cooperative cancellation for timeout
15+
16+
| Property | Value |
17+
|-------------------------------------|------------------------------------------------------------------------------------------|
18+
| **Rule ID** | MSTEST0045 |
19+
| **Title** | Use cooperative cancellation for timeout |
20+
| **Category** | Design |
21+
| **Fix is breaking or non-breaking** | Non-breaking |
22+
| **Enabled by default** | Yes |
23+
| **Default severity** | Info |
24+
| **Introduced in version** | 3.10.0 |
25+
| **Is there a code fix** | Yes |
26+
27+
## Cause
28+
29+
A test method uses <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute> without setting the `CooperativeCancellation` property to `true`.
30+
31+
## Rule description
32+
33+
When using <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute>, you should set `CooperativeCancellation` to `true` to enable cooperative cancellation. Without cooperative cancellation, the test framework stops observing the test execution when the timeout is reached, but the test continues running in the background. This can lead to problems for other tests or cleanup steps, as the original test is still executing and might interfere with subsequent operations.
34+
35+
When using cooperative cancellation mode, MSTest only triggers cancellation of the token and you're responsible for flowing and utilizing the test context token in your test code. This mode aligns with the default behavior of cancellation in .NET.
36+
37+
## How to fix violations
38+
39+
Use the provided code fixer to automatically set the `CooperativeCancellation` property to `true` on the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute>. You can also manually add the property if needed.
40+
41+
Alternatively, you can configure cooperative cancellation globally in your [runsettings](/dotnet/core/testing/unit-testing-mstest-configure#mstest-element) or [testconfig.json](/dotnet/core/testing/unit-testing-mstest-configure#timeout-settings) file to apply this setting to all timeout attributes in your test project.
42+
43+
## When to suppress warnings
44+
45+
Suppress this warning if you specifically need the test to be terminated abruptly when the timeout is reached, rather than using cooperative cancellation.

‎docs/core/testing/mstest-analyzers/mstest0046.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: "MSTEST0046: Use Assert instead of StringAssert"
3+
description: "Learn about code analysis rule MSTEST0046: Use Assert instead of StringAssert"
4+
ms.date: 07/24/2025
5+
f1_keywords:
6+
- MSTEST0046
7+
- StringAssertToAssertAnalyzer
8+
helpviewer_keywords:
9+
- StringAssertToAssertAnalyzer
10+
- MSTEST0046
11+
author: Evangelink
12+
ms.author: amauryleve
13+
---
14+
# MSTEST0046: Use Assert instead of StringAssert
15+
16+
| Property | Value |
17+
|-------------------------------------|------------------------------------------------------------------------------------------|
18+
| **Rule ID** | MSTEST0046 |
19+
| **Title** | Use Assert instead of StringAssert |
20+
| **Category** | Usage |
21+
| **Fix is breaking or non-breaking** | Non-breaking |
22+
| **Enabled by default** | Yes |
23+
| **Default severity** | Info |
24+
| **Introduced in version** | 3.10.0 |
25+
| **Is there a code fix** | Yes |
26+
27+
## Cause
28+
29+
A test method uses <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert> methods instead of equivalent <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods.
30+
31+
## Rule description
32+
33+
<xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert> methods have equivalent counterparts in <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> that provide the same functionality. Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods for consistency, better readability, improved discoverability, and alignment with behavior across all test frameworks.
34+
35+
The following <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert> methods have equivalent <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods:
36+
37+
- `StringAssert.Contains(value, substring)` → `Assert.Contains(substring, value)`
38+
- `StringAssert.StartsWith(value, substring)` → `Assert.StartsWith(substring, value)`
39+
- `StringAssert.EndsWith(value, substring)` → `Assert.EndsWith(substring, value)`
40+
- `StringAssert.Matches(value, pattern)` → `Assert.MatchesRegex(pattern, value)`
41+
- `StringAssert.DoesNotMatch(value, pattern)` → `Assert.DoesNotMatchRegex(pattern, value)`
42+
43+
> [!WARNING]
44+
> When migrating from <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert> to <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods, be careful about the change in parameter order. In <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods, the expected value is always the first parameter.
45+
46+
## How to fix violations
47+
48+
Use the provided code fixer to automatically replace <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert> method calls with their equivalent <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods. You can also manually replace the method calls if needed.
49+
50+
## When to suppress warnings
51+
52+
Don't suppress warnings from this rule. The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> methods provide the same functionality with better consistency.

‎docs/core/testing/mstest-analyzers/mstest0048.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: "MSTEST0048: Avoid TestContext properties in fixture methods"
3+
description: "Learn about code analysis rule MSTEST0048: Avoid TestContext properties in fixture methods"
4+
ms.date: 07/24/2025
5+
f1_keywords:
6+
- MSTEST0048
7+
- TestContextPropertyUsageAnalyzer
8+
helpviewer_keywords:
9+
- TestContextPropertyUsageAnalyzer
10+
- MSTEST0048
11+
author: Evangelink
12+
ms.author: amauryleve
13+
---
14+
# MSTEST0048: Avoid TestContext properties in fixture methods
15+
16+
| Property | Value |
17+
|-------------------------------------|------------------------------------------------------------------------------------------|
18+
| **Rule ID** | MSTEST0048 |
19+
| **Title** | Avoid TestContext properties in fixture methods |
20+
| **Category** | Usage |
21+
| **Fix is breaking or non-breaking** | Non-breaking |
22+
| **Enabled by default** | Yes |
23+
| **Default severity** | Warning |
24+
| **Introduced in version** | 3.10.0 |
25+
| **Is there a code fix** | No |
26+
27+
## Cause
28+
29+
A fixture method (methods with <xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyInitializeAttribute>, <xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyCleanupAttribute>, <xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassInitializeAttribute>, or <xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassCleanupAttribute>) accesses restricted <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> properties.
30+
31+
## Rule description
32+
33+
Certain <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> properties aren't available in fixture methods because they're specific to individual test execution:
34+
35+
Properties unavailable in class and assembly fixture methods:
36+
37+
- `TestData`
38+
- `TestDisplayName`
39+
- `DataRow`
40+
- `DataConnection`
41+
- `TestName`
42+
- `ManagedMethod`
43+
44+
Properties unavailable in assembly-level fixture methods:
45+
46+
- `FullyQualifiedTestClassName`
47+
- `ManagedType`
48+
49+
## How to fix violations
50+
51+
Remove the usage of restricted <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> properties from fixture methods. Consider using alternative approaches for class/assembly initialization and cleanup that don't rely on test-specific context information.
52+
53+
## When to suppress warnings
54+
55+
Don't suppress warnings from this rule. Accessing these properties in fixture methods can result in unexpected behavior or runtime errors.

‎docs/core/testing/mstest-analyzers/mstest0049.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "MSTEST0049: Flow TestContext cancellation token"
3+
description: "Learn about code analysis rule MSTEST0049: Flow TestContext cancellation token"
4+
ms.date: 07/24/2025
5+
f1_keywords:
6+
- MSTEST0049
7+
- FlowTestContextCancellationTokenAnalyzer
8+
helpviewer_keywords:
9+
- FlowTestContextCancellationTokenAnalyzer
10+
- MSTEST0049
11+
author: Evangelink
12+
ms.author: amauryleve
13+
---
14+
# MSTEST0049: Flow TestContext cancellation token
15+
16+
| Property | Value |
17+
|-------------------------------------|------------------------------------------------------------------------------------------|
18+
| **Rule ID** | MSTEST0049 |
19+
| **Title** | Flow TestContext cancellation token |
20+
| **Category** | Usage |
21+
| **Fix is breaking or non-breaking** | Non-breaking |
22+
| **Enabled by default** | Yes |
23+
| **Default severity** | Info |
24+
| **Introduced in version** | 3.10.0 |
25+
| **Is there a code fix** | Yes |
26+
27+
## Cause
28+
29+
A method call within a test context doesn't use the <xref:System.Threading.CancellationToken> available from <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> when the called method has a parameter or overload that accepts a <xref:System.Threading.CancellationToken>.
30+
31+
## Rule description
32+
33+
When <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> is available in your test methods, you should flow its <xref:System.Threading.CancellationToken> to async operations. This enables cooperative cancellation when timeouts occur and ensures proper resource cleanup. The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> cancellation token is especially important when using cooperative cancellation with timeout attributes.
34+
35+
This rule triggers when:
36+
37+
- A method call has an optional <xref:System.Threading.CancellationToken> parameter that isn't explicitly provided.
38+
- A method call has an overload that accepts a <xref:System.Threading.CancellationToken> but the non-cancellable overload is used instead.
39+
40+
## How to fix violations
41+
42+
Use the provided code fixer to automatically pass the <xref:System.Threading.CancellationToken> from <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> to method calls that support cancellation. You can also manually update method calls to include `TestContext.CancellationToken` as a parameter.
43+
44+
## When to suppress warnings
45+
46+
Suppress this warning if you intentionally don't want to support cancellation for specific operations, or if the operation should continue even when the test is cancelled.

0 commit comments

Comments
 (0)