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 61665536e1c35..8e3ebf3785c0d 100644 --- a/docs/core/testing/unit-testing-mstest-writing-tests-assertions.md +++ b/docs/core/testing/unit-testing-mstest-writing-tests-assertions.md @@ -12,12 +12,45 @@ Use the `Assert` classes of the <xref:Microsoft.VisualStudio.TestTools.UnitTesti ## The `Assert` class -In your test method, you can call any methods of the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert?displayProperty=fullName> class, such as <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.AreEqual%2A?displayProperty=nameWithType>. The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> class has many methods to choose from, and many of the methods have several overloads. +Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> class to verify that the code under test behaves as expected. Available APIs are: + +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.AreEqual*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.AreNotEqual*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.AreNotSame*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.AreSame*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.Fail*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.Inconclusive*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsFalse*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsInstanceOfType*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsNotInstanceOfType*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsNotNull*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsNull*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.IsTrue*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.ThrowsException*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert.ThrowsExceptionAsync*?displayProperty=nameWithType> ## The `StringAssert` class -Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert> class to compare and examine strings. This class contains a variety of useful methods, such as <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.Contains%2A?displayProperty=nameWithType>, <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.Matches%2A?displayProperty=nameWithType>, and <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.StartsWith%2A?displayProperty=nameWithType>. +Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert> class to compare and examine strings. Available APIs are: + +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.Contains*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.DoesNotMatch*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.EndsWith*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.Matches*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.StringAssert.StartsWith*?displayProperty=nameWithType> ## The `CollectionAssert` class -Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert> class to compare collections of objects, or to verify the state of a collection. +Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert> class to compare collections of objects, or to verify the state of a collection. Available APIs are: + +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.AllItemsAreInstancesOfType*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.AllItemsAreNotNull*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.AllItemsAreUnique*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.AreEqual*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.AreEquivalent*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.AreNotEqual*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.AreNotEquivalent*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.Contains*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.DoesNotContain*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.IsNotSubsetOf*?displayProperty=nameWithType> +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.CollectionAssert.IsSubsetOf*?displayProperty=nameWithType> diff --git a/docs/core/testing/unit-testing-mstest-writing-tests-attributes.md b/docs/core/testing/unit-testing-mstest-writing-tests-attributes.md index ff95a240e6225..de97619d95378 100644 --- a/docs/core/testing/unit-testing-mstest-writing-tests-attributes.md +++ b/docs/core/testing/unit-testing-mstest-writing-tests-attributes.md @@ -29,7 +29,7 @@ Every test class must have the `TestClass` attribute, and every test method must ### `TestClassAttribute` -The [TestClass](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestClassAttribute>) attribute marks a class that contains tests and, optionally, initialize or cleanup methods. +The [TestClass](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestClassAttribute) attribute marks a class that contains tests and, optionally, initialize or cleanup methods. This attribute can be extended to change or extend the default behavior. @@ -44,11 +44,11 @@ public class MyTestClass ### `TestMethodAttribute` -The [TestMethod](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute>) attribute is used inside a `TestClass` to define the actual test method to run. +The [TestMethod](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute) attribute is used inside a `TestClass` to define the actual test method to run. The method should be an instance `public` method defined as `void`, `Task`, or `ValueTask` (starting with MSTest v3.3). It can optionally be `async` but should not be `async void`. -The method should have zero parameters, unless it's used with `[DataRow]`, `[DynamicData]` or similar attribute that provides test case data to the test method. +The method should have zero parameters, unless it's marked with the [DataRow](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute) attribute, the [DynamicData](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DynamicDataAttribute) attribute, or a similar attribute that provides test case data to the test method. Consider the following example test class: @@ -74,9 +74,9 @@ Use the following elements to set up data-driven tests. For more information, se ### `DataRowAttribute` -The `DataRowAttribute` allows you to run the same test method with multiple different inputs. It can appear one or multiple times on a test method. It should be combined with `TestMethodAttribute`. +The [DataRow](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute) attribute allows you to run the same test method with multiple different inputs. It can appear one or multiple times on a test method. It should be combined with the [TestMethod](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute) attribute. -The number and types of arguments must exactly match the test method signature. Consider the following example of a valid test class demonstrating the `DataRow` attribute usage with inline arguments that align to test method parameters: +The number and types of arguments must exactly match the test method signature. Consider the following example of a valid test class demonstrating the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute> usage with inline arguments that align to test method parameters: ```csharp [TestClass] @@ -113,7 +113,7 @@ public class TestClass ``` > [!NOTE] -> You can also use the `params` feature to capture multiple inputs of the `DataRow`. +> You can also use the `params` feature to capture multiple inputs of the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute>. ```csharp [TestClass] @@ -152,7 +152,7 @@ public class TestClass > _Staring with v3:_ > `[DataRow(new string[] { "a" }, new string[] { "b" })]` -You can modify the display name used in Visual Studio and loggers for each instance of `DataRowAttribute` by setting the `DisplayName` property. +You can modify the display name used in Visual Studio and loggers for each instance of <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute> by setting the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute.DisplayName> property. ```csharp [TestClass] @@ -164,7 +164,7 @@ public class TestClass } ``` -You can also create your own specialized data row attribute by inheriting the `DataRowAttribute`. +You can also create your own specialized `DataRow` attribute by inheriting the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute>. ```csharp [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] @@ -187,9 +187,9 @@ Setup and cleanup that is common to multiple tests can be extracted to a separat ### Assembly level -[AssemblyInitialize](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyInitializeAttribute>) is called right after your assembly is loaded and [AssemblyCleanup](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyCleanupAttribute>) is called right before your assembly is unloaded. +The [AssemblyInitialize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyInitializeAttribute) attribute is called right after your assembly is loaded and the [AssemblyCleanup](xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyCleanupAttribute) attribute is called right before your assembly is unloaded. -The methods marked with these attributes should be defined as `static void`, `static Task` or `static ValueTask` (starting with MSTest v3.3), in a `TestClass`, and appear only once. The initialize part requires one parameter of type [TestContext](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext) and the cleanup either no parameters, or starting with MSTest 3.8 can have one parameter of type [TestContext](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext). +The methods marked with these attributes should be defined as `static void`, `static Task` or `static ValueTask` (starting with MSTest v3.3), in a class marked with <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestClassAttribute>, and appear only once. The initialize part requires one parameter of type <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> and the cleanup either no parameters, or starting with MSTest 3.8 can have one parameter of type <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext>. ```csharp [TestClass] @@ -207,31 +207,16 @@ public class MyTestClass } ``` -```csharp -[TestClass] -public class MyOtherTestClass -{ - [AssemblyInitialize] - public static async Task AssemblyInitialize(TestContext testContext) - { - } - - [AssemblyCleanup] - public static async Task AssemblyCleanup() // Starting with MSTest 3.8, it can be AssemblyCleanup(TestContext testContext) - { - } -} -``` - ### Class level -[ClassInitialize](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassInitializeAttribute>) is called right before your class is loaded (but after static constructor) and [ClassCleanup](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassCleanupAttribute>) is called right after your class is unloaded. +The [ClassInitialize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassInitializeAttribute) attribute is called right before your class is loaded (but after the static constructor) and the [ClassCleanup](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassCleanupAttribute) is called right after your class is unloaded. -It's possible to control the inheritance behavior: only for current class using `InheritanceBehavior.None` or for all derived classes using `InheritanceBehavior.BeforeEachDerivedClass`. +> [!IMPORTANT] +> By default, <xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassCleanupAttribute> will be triggered after the last test of the assembly (similarly to <xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyCleanupAttribute>). You can change this behavior by setting the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassCleanupAttribute.CleanupBehavior> on the attribute. Alternatively, you can set this behavior globally for the assembly using the assembly attribute <xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassCleanupExecutionAttribute>. -It's also possible to configure whether the class cleanup should be run at the end of the class or at the end of the assembly. +It's also possible to control the inheritance behavior: only for current class using <xref:Microsoft.VisualStudio.TestTools.UnitTesting.InheritanceBehavior.None?displayProperty=nameWithType>, or for all derived classes using <xref:Microsoft.VisualStudio.TestTools.UnitTesting.InheritanceBehavior.BeforeEachDerivedClass?displayProperty=nameWithType>. -The methods marked with these attributes should be defined as `static void`, `static Task` or `static ValueTask` (starting with MSTest v3.3), in a `TestClass`, and appear only once. The initialize part requires one parameter of type [TestContext](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext) and the cleanup either no parameters, or starting with MSTest 3.8 can have one parameter of type [TestContext](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext). +The methods marked with these attributes should be defined as `static void`, `static Task` or `static ValueTask` (starting with MSTest v3.3), in a `TestClass`, and appear only once. The initialize part requires one parameter of type <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> and the cleanup either no parameters, or starting with MSTest 3.8 can have one parameter of type <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext>. ```csharp [TestClass] @@ -249,29 +234,13 @@ public class MyTestClass } ``` -```csharp -[TestClass] -public class MyOtherTestClass -{ - [ClassInitialize] - public static async Task ClassInitialize(TestContext testContext) - { - } - - [ClassCleanup] - public static async Task ClassCleanup() // Starting with MSTest 3.8, it can be ClassCleanup(TestContext testContext) - { - } -} -``` - ### Test level -[TestInitialize](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestInitializeAttribute>) is called right before your test is started and [TestCleanup](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestCleanupAttribute>) is called right after your test is finished. +The [TestInitialize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestInitializeAttribute) attribute is called right before your test is started and the [TestCleanup](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestCleanupAttribute) is called right after your test is finished. -The `TestInitialize` is similar to the class constructor but is usually more suitable for long or async initializations. The `TestInitialize` is always called after the constructor and called for each test (including each data row of data-driven tests). +The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestInitializeAttribute> is similar to the class constructor but is usually more suitable for long or async initializations. The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestInitializeAttribute> is always called after the constructor and called for each test (including each entry of [data-driven tests](#attributes-used-for-data-driven-testing)). -The `TestCleanup` is similar to the class `Dispose` (or `DisposeAsync`) but is usually more suitable for long or async cleanups. The `TestCleanup` is always called just before the `DisposeAsync`/`Dispose` and called for each test (including each data row of data-driven tests). +The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestCleanupAttribute> is similar to the class `Dispose` (or `DisposeAsync`) but is usually more suitable for long or async cleanups. The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestCleanupAttribute> is always called just before the `DisposeAsync`/`Dispose` and called for each test (including each entry of [data-driven tests](#attributes-used-for-data-driven-testing)). The methods marked with these attributes should be defined as `void`, `Task` or `ValueTask` (starting with MSTest v3.3), in a `TestClass`, be parameterless, and appear one or multiple times. @@ -291,56 +260,40 @@ public class MyTestClass } ``` -```csharp -[TestClass] -public class MyOtherTestClass -{ - [TestInitialize] - public async Task TestInitialize() - { - } - - [TestCleanup] - public async Task TestCleanup() - { - } -} -``` - ## Attributes used to control test execution The following attributes can be used to modify the way tests are executed. ### `TimeoutAttribute` -The [Timeout](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute>) attribute can be used to specify the maximum time in milliseconds that a test method is allowed to run. If the test method runs longer than the specified time, the test will be aborted and marked as failed. +The [Timeout](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute) attribute can be used to specify the maximum time in milliseconds that a test method is allowed to run. If the test method runs longer than the specified time, the test will be aborted and marked as failed. This attribute can be applied to any test method or any fixture method (initialization and cleanup methods). It is also possible to specify the timeout globally for either all test methods or all test fixture methods by using the [timeout properties of the runsettings file](./unit-testing-mstest-configure.md#mstest-element). > [!NOTE] -> The timeout is not guaranteed to be precise. The test will be aborted after the specified time has passed, but it may take a few milliseconds longer. +> The timeout is not guaranteed to be precise. The test will be aborted after the specified time has passed, but it may take longer before the step is cancelled. When using the timeout feature, a separate thread/task is created to run the test method. The main thread/task is responsible for monitoring the timeout and unobserving the method thread/task if the timeout is reached. -Starting with MSTest 3.6, it is possible to specify `CooperativeCancellation` property on the attribute (or globally through runsettings) to enable cooperative cancellation. In this mode, the method is responsible for checking the cancellation token and aborting the test if it is signaled as you would do in a typical `async` method. This mode is more performant and allows for more precise control over the cancellation process. This mode can be applied to both async and sync methods. +Starting with MSTest 3.6, it is possible to specify <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TimeoutAttribute.CooperativeCancellation*> property on the attribute (or globally through runsettings) to enable cooperative cancellation. In this mode, the method is responsible for checking the cancellation token and aborting the test if it is signaled as you would do in a typical `async` method. This mode is more performant and allows for more precise control over the cancellation process. This mode can be applied to both async and sync methods. ### `STATestClassAttribute` -When applied to a test class, the `[STATestClass]` attribute indicates that all test methods (and the `[ClassInitialize]` and `[ClassCleanup]` methods) in the class should be run in a single-threaded apartment (STA). This attribute is useful when the test methods interact with COM objects that require STA. +When applied to a test class, the [STATestClass](xref:Microsoft.VisualStudio.TestTools.UnitTesting.STATestClassAttribute) attribute indicates that all test methods (and the `[ClassInitialize]` and `[ClassCleanup]` methods) in the class should be run in a single-threaded apartment (STA). This attribute is useful when the test methods interact with COM objects that require STA. > [!NOTE] > This is only supported on Windows and in version 3.6 and later. ### `STATestMethodAttribute` -When applied to a test method, the `[STATestMethod]` attribute indicates that the test method should be run in a single-threaded apartment (STA). This attribute is useful when the test method interacts with COM objects that require STA. +When applied to a test method, the [STATestMethod](xref:Microsoft.VisualStudio.TestTools.UnitTesting.STATestMethodAttribute) attribute indicates that the test method should be run in a single-threaded apartment (STA). This attribute is useful when the test method interacts with COM objects that require STA. > [!NOTE] > This is only supported on Windows and in version 3.6 and later. ### `ParallelizeAttribute` -By default, MSTest runs tests in a sequential order. The [Parallelize](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.ParallelizeAttribute>) attribute can be used to run tests in parallel. This is an assembly level attribute. You can specify if the parallelism should be at **class level** (multiple classes can be run in parallel but tests in a given class are run sequentially) or at **method level**. +By default, MSTest runs tests in a sequential order. The assembly level attribute [Parallelize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ParallelizeAttribute) attribute can be used to run tests in parallel. You can specify if the parallelism should be at [class level](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ExecutionScope.ClassLevel) (multiple classes can be run in parallel but tests in a given class are run sequentially) or at [method level](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ExecutionScope.MethodLevel). It's also possible to specify the maximum number of threads to use for parallel execution. A value of `0` (default value) means that the number of threads is equal to the number of logical processors on the machine. @@ -348,16 +301,16 @@ It is also possible to specify the parallelism through the [parallelization prop ### `DoNotParallelizeAttribute` -The [DoNotParallelize](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.DoNotParallelizeAttribute>) attribute can be used to prevent parallel execution of tests in a given assembly. This attribute can be applied at the assembly level, class level or method level. +The [DoNotParallelize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DoNotParallelizeAttribute) attribute can be used to prevent parallel execution of tests in a given assembly. This attribute can be applied at the assembly level, class level or method level. > [!NOTE] -> By default, MSTest runs tests in sequential order so you only need to use this attribute if you have applied the `[Parallelize]` attribute at the assembly level. +> By default, MSTest runs tests in sequential order so you only need to use this attribute if you have applied the assembly level [Parallelize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ParallelizeAttribute) attribute. ### `RetryAttribute` -The `RetryAttribute` was introduced in MSTest 3.8. This attribute causes the test method to be retried when it fails or timeouts. It allows you to specify the maximum number of retry attempts, the time delay between retries, and a delay backoff type, which is either constant or exponential. +The `Retry` attribute was introduced in MSTest 3.8. This attribute causes the test method to be retried when it fails or timeouts. It allows you to specify the maximum number of retry attempts, the time delay between retries, and a delay backoff type, which is either constant or exponential. -Only one `RetryAttribute` is expected to be present on a test method, and `RetryAttribute` cannot be used on methods that are not marked with `TestMethodAttribute`. +Only one `RetryAttribute` is expected to be present on a test method, and `RetryAttribute` cannot be used on methods that are not marked with [TestMethod](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute). > [!NOTE] > `RetryAttribute` derives from an abstract `RetryBaseAttribute`. You can also create your own retry implementations if the built-in `RetryAttribute` doesn't suite your needs. @@ -366,13 +319,13 @@ Only one `RetryAttribute` is expected to be present on a test method, and `Retry ### `DeploymentItemAttribute` -The MSTest framework introduced <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DeploymentItemAttribute> for copying files or folders specified as deployment items to the deployment directory (without adding a custom output path the copied files will be in TestResults folder inside the project folder). The deployment directory is where all the deployment items are present along with test project DLL. +The [DeploymentItem](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DeploymentItemAttribute) attribute is used for copying files or folders specified as deployment items to the deployment directory (without adding a custom output path the copied files will be in `TestResults` folder inside the project folder). The deployment directory is where all the deployment items are present along with test project DLL. -It can be used either on test classes (classes marked with `TestClass` attribute) or on test methods (methods marked with `TestMethod` attribute). +It can be used either on test classes (classes marked with the [TestClass](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestClassAttribute) attribute) or on test methods (methods marked with [TestMethod](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute) attribute). Users can have multiple instances of the attribute to specify more than one item. -And here you can see its [constructors](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.DeploymentItemAttribute>). +And here you can see its [constructors](<xref:Microsoft.VisualStudio.TestTools.UnitTesting.DeploymentItemAttribute#constructors>). **Example** @@ -396,7 +349,7 @@ public class UnitTest1 ### `ExpectedExceptionAttribute` -The MSTest framework introduced <xref:Microsoft.VisualStudio.TestTools.UnitTesting.ExpectedExceptionAttribute> for marking a test method to expect an exception of a specific type. The test will pass if the expected exception is thrown and the exception message matches the expected message. +The [ExpectedException](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ExpectedExceptionAttribute) attribute defines the exception that the test method is expected to throw. The test passes if the expected exception is thrown and the exception message matches the expected message. > [!WARNING] > This attribute exists for backward compatibility and is not recommended for new tests. Instead, use the `Assert.ThrowsException` (or `Assert.ThrowsExactly` if using MSTest 3.8 and later) method. 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 d4d2c818f9ac6..10f92957d2e24 100644 --- a/docs/core/testing/unit-testing-mstest-writing-tests-testcontext.md +++ b/docs/core/testing/unit-testing-mstest-writing-tests-testcontext.md @@ -14,7 +14,8 @@ The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> class gives The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> object is available in the following contexts: -- As a parameter to `[AssemblyInitialize]` and `[ClassInitialize]` methods. In this context, the properties related to the test run are not available. +- As a parameter to [AssemblyInitialize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyInitializeAttribute), the [ClassInitialize](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassInitializeAttribute) methods. In this context, the properties related to the test run are not available. +- Starting with 3.6, optionally, as a parameter to [AssemblyCleanup](xref:Microsoft.VisualStudio.TestTools.UnitTesting.AssemblyCleanupAttribute), the [ClassCleanup](xref:Microsoft.VisualStudio.TestTools.UnitTesting.ClassCleanupAttribute) methods. In this context, the properties related to the test run are not available. - As a property of a test class. In this context, the properties related to the test run are available. - As a constructor parameter of a test class (starting with v3.6). This way is recommended over using the property, because it gives access to the object in the constructor. While the property is only available after the constructor has run. This way also helps to ensure immutability of the object and allows the compiler to enforce that the object is not null. @@ -26,32 +27,32 @@ Or with MSTest 3.6+: ## The `TestContext` members -The `TestContext` class provides properties about the test run along with methods to manipulate the test environment. This section covers the most commonly used properties and methods. +The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> class provides properties about the test run along with methods to manipulate the test environment. This section covers the most commonly used properties and methods. ### Test run information -The `TestContext` provides information about the test run, such as: +The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> provides information about the test run, such as: -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestName> – the name of the currently executing test. -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.CurrentTestOutcome> - the result of the current test. -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.FullyQualifiedTestClassName> - the full name of the test class. -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestRunDirectory> - the directory where the test run is executed. -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.DeploymentDirectory> - the directory where the deployment items are located. -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.ResultsDirectory> - the directory where the test results are stored. Typically a subdirectory of the `TestRunDirectory`. -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestRunResultsDirectory> - the directory where the test results are stored. Typically a subdirectory of the `ResultsDirectory`. -- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestResultsDirectory> - the directory where the test results are stored. Typically a subdirectory of the `ResultsDirectory`. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestName?displayProperty=nameWithType> – the name of the currently executing test. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.CurrentTestOutcome?displayProperty=nameWithType> - the result of the current test. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.FullyQualifiedTestClassName?displayProperty=nameWithType> - the full name of the test class. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestRunDirectory?displayProperty=nameWithType> - the directory where the test run is executed. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.DeploymentDirectory?displayProperty=nameWithType> - the directory where the deployment items are located. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.ResultsDirectory?displayProperty=nameWithType> - the directory where the test results are stored. Typically a subdirectory of the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestRunDirectory?displayProperty=nameWithType>. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestRunResultsDirectory?displayProperty=nameWithType> - the directory where the test results are stored. Typically a subdirectory of the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.ResultsDirectory?displayProperty=nameWithType>. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestResultsDirectory?displayProperty=nameWithType> - the directory where the test results are stored. Typically a subdirectory of the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.ResultsDirectory?displayProperty=nameWithType>. -In MSTest 3.7 and later, the `TestContext` class also provides new properties helpful for `TestInitialize` and `TestCleanup` methods: +In MSTest 3.7 and later, the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> class also provides new properties helpful for `TestInitialize` and `TestCleanup` methods: -- `TestContext.TestData` - the data that will be provided to the parameterized test method or `null` if the test is not parameterized. -- `TestContext.TestDisplayName` - the display name of the test method. -- `TestContext.TestException` - the exception thrown by either the test method or test initialize, or `null` if the test method did not throw an exception. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestData?displayProperty=nameWithType> - the data that will be provided to the parameterized test method, or `null` if the test is not parameterized. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestDisplayName?displayProperty=nameWithType> - the display name of the test method. +- <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestException?displayProperty=nameWithType> - the exception thrown by either the test method or test initialize, or `null` if the test method did not throw an exception. ### Data-driven tests -In MSTest 3.7 and later, the property `TestData` can be used to access the data for the current test during `TestInitialize` and `TestCleanup` methods. +In MSTest 3.7 and later, the property <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.TestData?displayProperty=nameWithType> can be used to access the data for the current test during `TestInitialize` and `TestCleanup` methods. -When targeting .NET framework, the `TestContext` enables you to retrieve and set data for each iteration in a data-driven test, using properties like `DataRow` and `DataConnection` (for [DataSource](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataSourceAttribute)-based tests). +When targeting .NET framework, the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> enables you to retrieve and set data for each iteration in a data-driven test, using properties like `DataRow` and `DataConnection` (for [DataSource](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataSourceAttribute)-based tests). Consider the following CSV file `TestData.csv`: @@ -81,4 +82,4 @@ The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.AddResultFile :::code language="csharp" source="snippets/testcontext/csharp/AddResultFile.cs"::: -You can also use `TestContext.Write` or `TestContext.WriteLine` methods to write custom messages directly to the test output. This is especially useful for debugging purposes, as it provides real-time logging information within your test execution context. +You can also use <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.Write*?displayProperty=nameWithType> or <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.WriteLine*?displayProperty=nameWithType> methods to write custom messages directly to the test output. This is especially useful for debugging purposes, as it provides real-time logging information within your test execution context.