From fec3fcb5a05fdfdcd86521b8006157ca5579b29c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Amaury=20Lev=C3=A9?= Date: Mon, 22 Jun 2026 20:02:18 +0200 Subject: [PATCH 1/3] Document Assert.Scope() soft assertions and related behaviors (#54409) * Document Assert.Scope() soft assertions and related behaviors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review: code-format .editorconfig, soften suppression wording, unspaced em dashes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix xref-not-found: use inline code for experimental Assert.Scope() API Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Evangelink Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...testing-mstest-writing-tests-assertions.md | 68 ++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/docs/core/testing/unit-testing-mstest-writing-tests-assertions.md b/docs/core/testing/unit-testing-mstest-writing-tests-assertions.md index 8e5a690d88834..19588b26fc6b6 100644 --- a/docs/core/testing/unit-testing-mstest-writing-tests-assertions.md +++ b/docs/core/testing/unit-testing-mstest-writing-tests-assertions.md @@ -3,7 +3,7 @@ title: MSTest assertions description: Learn about MSTest assertions including Assert, StringAssert, and CollectionAssert classes for validating test results. author: Evangelink ms.author: amauryleve -ms.date: 06/04/2026 +ms.date: 06/16/2026 ai-usage: ai-assisted --- @@ -104,6 +104,72 @@ public async Task AssertExamples() - - +### Soft assertions with `Assert.Scope()` + +> [!IMPORTANT] +> `Assert.Scope()` is an experimental API. Using it produces the `MSTESTEXP` diagnostic, which you suppress (for example, with `#pragma warning disable MSTESTEXP` or in your project's `.editorconfig` file) to acknowledge that the shape and behavior of the API can change in future releases. + +By default, every assertion throws an as soon as it fails, which ends the test immediately. `Assert.Scope()` introduces *soft assertions*: while a scope is active, assertion failures are collected instead of thrown, so execution continues and you can see every failure in the scope at once. When the scope is disposed, the collected failures are reported together: + +```csharp +[TestMethod] +public void ValidatePerson() +{ + using (Assert.Scope()) + { + Assert.AreEqual("Jane", person.FirstName); // failure collected, execution continues + Assert.AreEqual("Doe", person.LastName); // failure collected, execution continues + Assert.IsTrue(person.IsActive); // failure collected, execution continues + } + // On Dispose, all collected failures are reported together. +} +``` + +When the scope is disposed: + +- If exactly one failure was collected, the original `AssertFailedException` is thrown. +- If multiple failures were collected, a single `AssertFailedException` is thrown that wraps all of them in an `AggregateException`. + +#### Postconditions aren't enforced inside a scope + +Because a failing assertion no longer throws inside a scope, code that runs after it can't rely on the assertion having succeeded. This applies to *every* postcondition, including nullability and type narrowing: + +```csharp +using (Assert.Scope()) +{ + Assert.IsNotNull(item); + // 'item' might still be null here: the failure was collected, not thrown. + Assert.AreEqual("expected", item.Value); + // 'item.Value' might not equal "expected" either. +} +``` + +If a failed assertion would lead to a `NullReferenceException` (or any other exception) on a later line within the scope, that secondary exception is a symptom of the already-collected failure, not a separate bug. The original assertion failure is still reported when the scope is disposed. + +#### Value-returning assertions return `null`/`default` on failure inside a scope + +Some assertions return a value on success—for example, and return the caught exception, and returns the matched element. When one of these assertions *fails* inside a scope, the failure is collected and the method returns `null`/`default` instead of throwing: + +```csharp +using (Assert.Scope()) +{ + // No exception is thrown by the lambda, so the assertion fails. The failure is + // collected and 'ex' is null. Accessing 'ex' below throws NullReferenceException. + InvalidOperationException ex = Assert.Throws(() => { }); + _ = ex.Message; // NullReferenceException—don't use the return value in a scope +} +``` + +Don't rely on the value returned by a soft assertion inside a scope. If you need the returned value (such as the caught exception), call the assertion *outside* the scope, or restructure the test so nothing depends on the return value until after the scope is disposed. + +#### `Assert.Fail` and `Assert.Inconclusive` always throw + + and are never soft. They always throw immediately, even inside a scope, because they express an unconditional test outcome. Use one of them when a condition is critical and the rest of the test can't meaningfully continue without it. + +#### Nested scopes aren't supported + +You can't nest `Assert.Scope()` calls. Only one assertion scope can be active at a time. + ## The `StringAssert` class Use the class to compare and examine strings. From a595c972c8ccce64827744f6fda48f0ffbaae6f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Amaury=20Lev=C3=A9?= Date: Mon, 22 Jun 2026 20:13:12 +0200 Subject: [PATCH 2/3] Add MSTest DeploymentItem sub-page (#54210) * Add MSTest DeploymentItem sub-page Adds a new `Write tests` sub-page that documents `DeploymentItemAttribute` end to end: how it resolves relative paths against the build output directory, the two constructor overloads, how to stage source files via `CopyToOutputDirectory` or post-build events, `TestContext.DeploymentDirectory`, `DeploymentEnabled`, legacy mode caveats, and best practices. Cross-links the new page from the main Write tests page (description table + attribute quick reference) and the TestContext page, and wires the entry into devops-testing/toc.yml. Related to microsoft/testfx#8960 (the matching XML doc comment fix on the attribute is microsoft/testfx#8968). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix DeploymentItem snippet compile issues and rename heading - Add missing 'using System.IO;' to the two snippets that use File/Path. - Drop trailing backslash from verbatim folder paths (@"TestFiles\" and @"Resources\") since C# verbatim string literals can't end with a single backslash. - Rename 'Use a post-build event' section to 'Use a post-build target' to match the MSBuild example. Addresses review comments on PR #54210. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...g-mstest-writing-tests-deployment-items.md | 172 ++++++++++++++++++ ...esting-mstest-writing-tests-testcontext.md | 2 +- .../unit-testing-mstest-writing-tests.md | 2 + docs/navigate/devops-testing/toc.yml | 2 + 4 files changed, 177 insertions(+), 1 deletion(-) create mode 100644 docs/core/testing/unit-testing-mstest-writing-tests-deployment-items.md diff --git a/docs/core/testing/unit-testing-mstest-writing-tests-deployment-items.md b/docs/core/testing/unit-testing-mstest-writing-tests-deployment-items.md new file mode 100644 index 0000000000000..b102ebc3d9c3d --- /dev/null +++ b/docs/core/testing/unit-testing-mstest-writing-tests-deployment-items.md @@ -0,0 +1,172 @@ +--- +title: Deploy files alongside MSTest tests +description: Learn how to use the DeploymentItemAttribute in MSTest to copy files and folders alongside test assemblies for use during test execution. +author: Evangelink +ms.author: amauryleve +ms.date: 06/09/2026 +ai-usage: ai-assisted +--- + +# Deploy files alongside MSTest tests + +Some tests need extra files at runtime, such as test data, configuration files, golden masters, or native dependencies. Use the to declare files and folders that should be available next to your test assembly when each test runs. + +## Overview + +When you apply `[DeploymentItem]` to a test class or a test method, MSTest copies the specified files or folders into the directory exposed by before any test in that scope runs. The deployment directory is also the current working directory for the test, so your test code can open the files by their copied names. + +The attribute accepts a relative or absolute path: + +- **Relative paths** are resolved against the build output directory (the folder that contains the test assembly, for example `bin\Debug\net10.0\`). +- **Absolute paths** are used as-is. + +> [!IMPORTANT] +> In MSTest 3.x, deployment items are copied per test run. To make a file available at deployment time, the file must already exist in (or be copied to) the build output directory. + +## Apply `[DeploymentItem]` + +The attribute can be applied to a test method, a test class, or both. Multiple instances are allowed and combine: + +```csharp +using System.IO; +using Microsoft.VisualStudio.TestTools.UnitTesting; + +[TestClass] +[DeploymentItem(@"TestFiles\shared-config.json")] +public class ConfigurationTests +{ + [TestMethod] + [DeploymentItem(@"TestFiles\customers.csv")] + public void LoadCustomers_FromCsv_ReturnsAllRows() + { + // Both shared-config.json (from the class) and customers.csv (from + // the method) are available in the deployment directory. + Assert.IsTrue(File.Exists("shared-config.json")); + Assert.IsTrue(File.Exists("customers.csv")); + } +} +``` + +> [!NOTE] +> When you apply `[DeploymentItem]` to a test class, the class must contain at least one test method. Applying it to a class that only has `AssemblyInitialize` or `ClassInitialize` methods has no effect. Analyzer [MSTEST0035](mstest-analyzers/mstest0035.md) flags such misuse. + +## Constructor overloads + +`DeploymentItemAttribute` has two constructors: [`DeploymentItemAttribute(string path)`](#deploymentitemattributestring-path) and [`DeploymentItemAttribute(string path, string outputDirectory)`](#deploymentitemattributestring-path-string-outputdirectory). + +### `DeploymentItemAttribute(string path)` + +Copies the file or folder identified by `path` into the root of the deployment directory. + +```csharp +// Copy a single file from the build output directory. +[DeploymentItem("settings.json")] + +// Copy a file that lives in a subfolder of the build output directory. +// The file is copied to the root of the deployment directory (the +// "Resources" folder is not preserved). +[DeploymentItem(@"Resources\test-data.xml")] + +// Copy the entire TestFiles folder (and all of its subfolders) into the +// deployment directory. +[DeploymentItem("TestFiles")] +``` + +### `DeploymentItemAttribute(string path, string outputDirectory)` + +Copies the items into a subdirectory of the deployment directory, given by `outputDirectory`. + +```csharp +// Creates a "Data" subfolder under the deployment directory, then copies +// test-data.xml into it. The file is reached at "Data\test-data.xml". +[DeploymentItem("test-data.xml", "Data")] + +// Copies the contents of the Resources folder into a "Resources" +// subfolder of the deployment directory. +[DeploymentItem("Resources", "Resources")] +``` + +The `outputDirectory` argument must be a folder path. It can't be used to rename the file. To deploy a file with a different name, rename it in the source folder (or use a post-build step). + +## Ensure source files reach the build output directory + +Because relative paths are resolved against the build output directory, the source file or folder must already be there. There are two common ways to achieve this. + +### Use `` or `` with `CopyToOutputDirectory` + +Add the files to your test project and mark them to copy to the build output directory: + +```xml + + + PreserveNewest + + +``` + +After a build, the `TestFiles` folder is replicated in `bin\\\TestFiles\`, and `[DeploymentItem("TestFiles")]` resolves correctly. + +### Use a post-build target + +For files that live outside the test project, copy them into the build output directory as part of the build: + +```xml + + + +``` + +## Inspect the deployment directory at runtime + +If you need the absolute path of the deployment directory—for example, to pass it to a process you spawn or to log it for diagnostics—use : + +```csharp +using System.IO; + +[TestMethod] +[DeploymentItem(@"TestFiles\input.json")] +public void ProcessInput_FromDeployedFile_Succeeds() +{ + string fullPath = Path.Combine(TestContext.DeploymentDirectory, "input.json"); + string contents = File.ReadAllText(fullPath); + // ... +} +``` + +For more on `TestContext`, see [The `TestContext` class](unit-testing-mstest-writing-tests-testcontext.md). + +## When deployment doesn't happen + +By default, MSTest creates a per-run deployment directory and copies items into it. You can disable deployment in a `.runsettings` file so tests run directly out of the build output directory: + +```xml + + + False + + +``` + +When deployment is disabled, `[DeploymentItem]` attributes have no effect, and the test runs in the build output directory itself. For more configuration options, see [Configure MSTest](unit-testing-mstest-configure.md). + +## Legacy mode and `.testsettings` + +When MSTest runs in legacy mode (a `.testsettings` file is used, or `RunSettings/MSTest/ForcedLegacyMode` is set to `true` in a `.runsettings` file), relative paths might be resolved against the solution root directory instead of the build output directory. Avoid legacy mode for new projects—the modern `.runsettings`-based configuration is the recommended approach. + +## Best practices + +- **Prefer `CopyToOutputDirectory` over deep relative paths.** Don't reach into source folders with `..\..\` style paths—they tie your tests to a specific repository layout. Stage the files in the build output directory first. +- **Keep deployment items small.** Each item is copied for every test run; large files slow down test execution. +- **Use folders to deploy related assets together.** `[DeploymentItem("TestFiles")]` is easier to maintain than dozens of per-file attributes. +- **Prefer embedded resources or in-memory data for small fixtures.** Embedded resources eliminate the need for deployment and avoid I/O at test time. +- **Don't rely on the working directory being the project directory.** During test execution, the working directory is the deployment directory, not the test project folder. + +## See also + +- +- +- [The `TestContext` class](unit-testing-mstest-writing-tests-testcontext.md) +- [MSTEST0035: `[DeploymentItem]` can be specified only on test class or test method](mstest-analyzers/mstest0035.md) +- [Configure MSTest](unit-testing-mstest-configure.md) +- [Write tests with MSTest](unit-testing-mstest-writing-tests.md) diff --git a/docs/core/testing/unit-testing-mstest-writing-tests-testcontext.md b/docs/core/testing/unit-testing-mstest-writing-tests-testcontext.md index 7c42a6dd7457f..eb3f4f1f2bef0 100644 --- a/docs/core/testing/unit-testing-mstest-writing-tests-testcontext.md +++ b/docs/core/testing/unit-testing-mstest-writing-tests-testcontext.md @@ -37,7 +37,7 @@ The provides inf - - the result of the current test. - - the full name of the test class. - - the directory where the test run is executed. -- - the directory where the deployment items are located. +- - the directory where the deployment items are located. To populate this directory, use [`DeploymentItemAttribute`](unit-testing-mstest-writing-tests-deployment-items.md). - - the directory where the test results are stored. Typically a subdirectory of the . - - the directory where the test results are stored. Typically a subdirectory of the . - - the directory where the test results are stored. Typically a subdirectory of the . diff --git a/docs/core/testing/unit-testing-mstest-writing-tests.md b/docs/core/testing/unit-testing-mstest-writing-tests.md index de89b5842aa8e..9b6ae842dea14 100644 --- a/docs/core/testing/unit-testing-mstest-writing-tests.md +++ b/docs/core/testing/unit-testing-mstest-writing-tests.md @@ -119,6 +119,7 @@ MSTest documentation is organized by topic: | [Execution control](unit-testing-mstest-writing-tests-controlling-execution.md) | Threading, parallelization, timeouts, retries, and conditional execution | | [Test organization](unit-testing-mstest-writing-tests-organizing.md) | Categories, priorities, owners, and metadata | | [TestContext](unit-testing-mstest-writing-tests-testcontext.md) | Access test runtime information | +| [Deployment items](unit-testing-mstest-writing-tests-deployment-items.md) | Copy files and folders alongside test assemblies | ## Attribute quick reference @@ -133,6 +134,7 @@ MSTest documentation is organized by topic: | Conditional | `Ignore`, `OSCondition`, `CICondition` | [Execution control](unit-testing-mstest-writing-tests-controlling-execution.md) | | Metadata | `TestCategory`, `TestProperty`, `Owner`, `Priority` | [Test organization](unit-testing-mstest-writing-tests-organizing.md) | | Work tracking | `WorkItem`, `GitHubWorkItem` | [Test organization](unit-testing-mstest-writing-tests-organizing.md) | +| Test resources | `DeploymentItem` | [Deployment items](unit-testing-mstest-writing-tests-deployment-items.md) | ## Assertions diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml index a37a24b53360b..e5e58f5987990 100644 --- a/docs/navigate/devops-testing/toc.yml +++ b/docs/navigate/devops-testing/toc.yml @@ -70,6 +70,8 @@ items: href: ../../core/testing/unit-testing-mstest-writing-tests-controlling-execution.md - name: Test organization href: ../../core/testing/unit-testing-mstest-writing-tests-organizing.md + - name: Deployment items + href: ../../core/testing/unit-testing-mstest-writing-tests-deployment-items.md - name: Running tests items: - name: Overview From 85e686f2d1f925b8f0bf98edc228e7f650b7a376 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 23 Jun 2026 07:37:07 -0700 Subject: [PATCH 3/3] Add empty lines for code block rendering (#54493) --- docs/fsharp/language-reference/verbose-syntax.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/fsharp/language-reference/verbose-syntax.md b/docs/fsharp/language-reference/verbose-syntax.md index 781bff52102b3..beecf89934126 100644 --- a/docs/fsharp/language-reference/verbose-syntax.md +++ b/docs/fsharp/language-reference/verbose-syntax.md @@ -83,7 +83,9 @@ end + `for...do` + ```fsharp @@ -102,7 +104,9 @@ done + `while...do` + ```fsharp @@ -121,7 +125,9 @@ done + `for...in` + ```fsharp @@ -140,7 +146,9 @@ done + `do` + ```fsharp