Document Assert.That custom assertions and de-emphasize StringAssert/CollectionAssert by Evangelink · Pull Request #54185 · dotnet/docs

Evangelink · 2026-06-04T13:04:37Z

Summary

Updates the MSTest assertions article to:

Document the Assert.That, StringAssert.That, and CollectionAssert.That extensibility hook (the singleton property used as a target for user-authored extension methods, per testfx RFC 002).
Strengthen the guidance that StringAssert and CollectionAssert are not recommended for new code and are likely to be deprecated. The main reason is discoverability: splitting assertions across three types means you can't see all available checks in a single IntelliSense list.

Contributes to microsoft/testfx#8818

Changes

New section Create custom assertions with Assert.That with:
- A C# extension method example (IsPrime) that targets the Assert instance type.
- A call-site example showing Assert.That.IsPrime(result).
- A subsection acknowledging StringAssert.That and CollectionAssert.That exist for the same pattern, but recommending Assert.That for new code.
- A disambiguation NOTE clarifying the singleton property (Assert.That.MyAssertion(...)) is distinct from the MSTest 3.8 expression-tree method (Assert.That(() => condition)).
Strengthened deprecation messaging on StringAssert and CollectionAssert (NOTE → WARNING), and updated the top-of-doc callout from TIP → IMPORTANT explaining the discoverability problem.
New best-practice bullet recommending custom assertions extend Assert.That (not StringAssert.That/CollectionAssert.That).
Added ai-usage: ai-assisted and bumped ms.date.

Verification

npx markdownlint-cli2 passes with 0 errors.
All three new <xref:...> API IDs (Assert.That, StringAssert.That, CollectionAssert.That) resolve against the Microsoft Learn API browser.

Content source

API surface and extensibility pattern: verified against microsoft/testfx sources (Assert.cs, StringAssert.cs, CollectionAssert.cs, Assert.That.cs) and RFC 002 — Framework Extensibility for Custom Assertions.
"Likely to be deprecated" wording reflects @Evangelink's guidance in the issue prompt; no formal [Obsolete] attribute is shipped yet.

Internal previews

📄 File	🔗 Preview link
docs/core/testing/unit-testing-mstest-writing-tests-assertions.md	MSTest assertions

…lectionAssert guidance - Add 'Create custom assertions with Assert.That' section explaining the singleton extensibility hook with a worked extension method example. - Note that StringAssert.That and CollectionAssert.That exist for the same pattern but recommend Assert.That for new code. - Disambiguate the singleton property from the MSTest 3.8 Assert.That(() => condition) expression-tree method. - Strengthen messaging that StringAssert and CollectionAssert are likely to be deprecated and aren't recommended due to discoverability issues. - Add ai-usage: ai-assisted and bump ms.date. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Updates the MSTest assertions documentation to explain the *.That extensibility hook for custom assertions and to steer new code away from StringAssert/CollectionAssert due to discoverability and likely future deprecation.

Changes:

Replaces the top callout with stronger guidance to prefer Assert and warns about likely deprecation of StringAssert/CollectionAssert.
Adds a new section documenting custom assertions via Assert.That (and mentions StringAssert.That/CollectionAssert.That).
Updates best-practices guidance to recommend extending Assert.That, and adds ai-usage plus an updated ms.date.

Show a summary per file

File	Description
docs/core/testing/unit-testing-mstest-writing-tests-assertions.md	Adds `Assert.That` extensibility documentation and strengthens guidance away from `StringAssert`/`CollectionAssert`.

Copilot's findings

Files reviewed: 1/1 changed files
Comments generated: 2

…e disambiguation NOTE Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Evangelink · 2026-06-05T15:22:47Z

@meaghanlewis @gewarren could you please review?

gewarren · 2026-06-05T15:43:20Z

+### `Assert.That` property versus `Assert.That(...)` method
+
+> [!NOTE]
+> Don't confuse the `Assert.That` singleton *property*—used as an extensibility hook—with the `Assert.That(() => condition)` *method* added in MSTest 3.8. The latter accepts a boolean expression and produces detailed failure messages by analyzing the expression tree (for example, `Assert.That(() => order.Total > 0)`). The two APIs share a name but serve different purposes.


Suggested change

> Don't confuse the `Assert.That` singleton *property*—used as an extensibility hook—with the `Assert.That(() => condition)` *method* added in MSTest 3.8. The latter accepts a boolean expression and produces detailed failure messages by analyzing the expression tree (for example, `Assert.That(() => order.Total > 0)`). The two APIs share a name but serve different purposes.

> Don't confuse the `Assert.That` singleton *property*—used as an extensibility hook—with the `Assert.That(() => condition)` *method* added in MSTest 3.8. The latter accepts a Boolean expression and produces detailed failure messages by analyzing the expression tree (for example, `Assert.That(() => order.Total > 0)`). The two APIs share a name but serve different purposes.

Applied the suggested wording in da34c0b.

gewarren · 2026-06-05T15:44:06Z

 1. **Use `Throws`/`ThrowsExactly` for exceptions**: In MSTest v3.8+, prefer `Assert.Throws`, `Assert.ThrowsExactly`, and their async counterparts (`ThrowsAsync`, `ThrowsExactlyAsync`) over the `ExpectedException` attribute.

-1. **Prefer `Assert` over `StringAssert`/`CollectionAssert`**: When functionality exists in both classes, use the `Assert` class for better discoverability and consistency.
+1. **Prefer `Assert` over `StringAssert`/`CollectionAssert`**: For better discoverability and consistency, use the `Assert` class. The `StringAssert` and `CollectionAssert` classes are likely to be deprecated in a future release.


This should be an unordered (bullet) list.

Changed the best practices section to an unordered list in da34c0b.

gewarren · 2026-06-05T15:44:20Z

-> [!TIP]
-> When functionality exists in both `Assert` and `StringAssert`/`CollectionAssert`, prefer the `Assert` class. The `Assert` class provides better discoverability and is the recommended choice for new code. `StringAssert` and `CollectionAssert` are maintained for backward compatibility.
+> [!IMPORTANT]
+> For new code, always use the `Assert` class. The `StringAssert` and `CollectionAssert` classes are likely to be deprecated in a future release. They're maintained primarily for backward compatibility, but they're not recommended because splitting assertions across three types hurts discoverability—you can't see all available checks in a single IntelliSense list.


Suggested change

> For new code, always use the `Assert` class. The `StringAssert` and `CollectionAssert` classes are likely to be deprecated in a future release. They're maintained primarily for backward compatibility, but they're not recommended because splitting assertions across three types hurts discoverability—you can't see all available checks in a single IntelliSense list.

> For new code, always use the `Assert` class. The `StringAssert` and `CollectionAssert` classes are likely to be deprecated in a future release. They're maintained primarily for backward compatibility, but they're not recommended because splitting assertions across three types hurts discoverability.

I don't think we need to say more than that it hurts discoverability.

Trimmed the guidance to just the discoverability concern in da34c0b.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Evangelink requested review from meaghanlewis and nohwnd as code owners June 4, 2026 13:04

Copilot AI review requested due to automatic review settings June 4, 2026 13:04

dotnetrepoman Bot added this to the June 2026 milestone Jun 4, 2026

Copilot started reviewing on behalf of Evangelink June 4, 2026 13:04 View session

dotnet-policy-service Bot added the dotnet-fundamentals/svc label Jun 4, 2026

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Comment thread docs/core/testing/unit-testing-mstest-writing-tests-assertions.md

Comment thread docs/core/testing/unit-testing-mstest-writing-tests-assertions.md Outdated

Evangelink commented Jun 4, 2026

View reviewed changes

Comment thread docs/core/testing/unit-testing-mstest-writing-tests-assertions.md

Address review: fix IsPrime imports, clarify Assert.That wording, mov…

7ef869c

…e disambiguation NOTE Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Evangelink mentioned this pull request Jun 4, 2026

Improve That property XML docs: fix broken link, add inline examples (fixes #8818) microsoft/testfx#8822

Merged

Evangelink enabled auto-merge (squash) June 5, 2026 15:22

gewarren approved these changes Jun 5, 2026

View reviewed changes

Address MSTest assertions review feedback

da34c0b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document Assert.That custom assertions and de-emphasize StringAssert/CollectionAssert#54185

Document Assert.That custom assertions and de-emphasize StringAssert/CollectionAssert#54185
Evangelink wants to merge 3 commits into
mainfrom
dev/amauryleve/mstest-assert-that-custom-assertions

Evangelink commented Jun 4, 2026 •

edited by github-actions Bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Evangelink commented Jun 5, 2026

Uh oh!

gewarren Jun 5, 2026

Uh oh!

Evangelink Jun 7, 2026

Uh oh!

gewarren Jun 5, 2026

Uh oh!

Evangelink Jun 7, 2026

Uh oh!

gewarren Jun 5, 2026

Uh oh!

gewarren Jun 5, 2026

Uh oh!

Evangelink Jun 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	> Don't confuse the `Assert.That` singleton property—used as an extensibility hook—with the `Assert.That(() => condition)` method added in MSTest 3.8. The latter accepts a boolean expression and produces detailed failure messages by analyzing the expression tree (for example, `Assert.That(() => order.Total > 0)`). The two APIs share a name but serve different purposes.
	> Don't confuse the `Assert.That` singleton property—used as an extensibility hook—with the `Assert.That(() => condition)` method added in MSTest 3.8. The latter accepts a Boolean expression and produces detailed failure messages by analyzing the expression tree (for example, `Assert.That(() => order.Total > 0)`). The two APIs share a name but serve different purposes.

	> For new code, always use the `Assert` class. The `StringAssert` and `CollectionAssert` classes are likely to be deprecated in a future release. They're maintained primarily for backward compatibility, but they're not recommended because splitting assertions across three types hurts discoverability—you can't see all available checks in a single IntelliSense list.
	> For new code, always use the `Assert` class. The `StringAssert` and `CollectionAssert` classes are likely to be deprecated in a future release. They're maintained primarily for backward compatibility, but they're not recommended because splitting assertions across three types hurts discoverability.

Conversation

Evangelink commented Jun 4, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Verification

Content source

Internal previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Evangelink commented Jun 5, 2026

Uh oh!

gewarren Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Evangelink Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Evangelink Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Evangelink Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Evangelink commented Jun 4, 2026 •

edited by github-actions Bot

Loading