Add documentation about the TestContext (#43420)

Author: Evangelink

docs/core/testing/snippets/testcontext/csharp/AddResultFile.cs

@@ -0,0 +1,22 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class TestClassResultFile
+{
+    public TestContext TestContext { get; set; }
+
+    [TestMethod]
+    public void TestMethodWithResultFile()
+    {
+        // Simulate creating a log file for this test
+        string logFilePath = Path.Combine(TestContext.TestRunDirectory, "TestLog.txt");
+        File.WriteAllText(logFilePath, "This is a sample log entry for the test.");
+
+        // Add the log file to the test result
+        TestContext.AddResultFile(logFilePath);
+
+        // Perform some assertions (example only)
+        Assert.IsTrue(File.Exists(logFilePath), "The log file was not created.");
+        Assert.IsTrue(new FileInfo(logFilePath).Length > 0, "The log file is empty.");
+    }
+}

docs/core/testing/snippets/testcontext/csharp/CsvDataSource.cs

@@ -0,0 +1,30 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using System;
+
+namespace YourNamespace
+{
+    [TestClass]
+    public class CsvDataDrivenTest
+    {
+        public TestContext TestContext { get; set; }
+
+        [TestMethod]
+        [DataSource(
+            "Microsoft.VisualStudio.TestTools.DataSource.CSV",
+            "|DataDirectory|\\TestData.csv",
+            "TestData#csv",
+            DataAccessMethod.Sequential)]
+        public void TestWithCsvDataSource()
+        {
+            // Access data from the current row
+            int number = Convert.ToInt32(TestContext.DataRow["Number"]);
+            string name = TestContext.DataRow["Name"].ToString();
+
+            Console.WriteLine($"Number: {number}, Name: {name}");
+
+            // Example assertions or logic
+            Assert.IsTrue(number > 0);
+            Assert.IsFalse(string.IsNullOrEmpty(name));
+        }
+    }
+}

docs/core/testing/snippets/testcontext/csharp/TestContext.cs

@@ -0,0 +1,25 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class MyTestClassTestContext
+{
+    public TestContext TestContext { get; set; }
+
+    [AssemblyInitialize]
+    public static void AssemblyInitialize(TestContext context)
+    {
+        // Access TestContext properties and methods here. The properties related to the test run are not available.
+    }
+
+    [ClassInitialize]
+    public static void ClassInitialize(TestContext context)
+    {
+        // Access TestContext properties and methods here. The properties related to the test run are not available.
+    }
+
+    [TestMethod]
+    public void MyTestMethod()
+    {
+        // Access TestContext properties and methods here
+    }
+}

docs/core/testing/snippets/testcontext/csharp/TestContextCtor.cs

@@ -0,0 +1,30 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+[TestClass]
+public class MyTestClassTestContextThroughCtor
+{
+    private readonly TestContext _testContext;
+
+    public MyTestClassTestContextThroughCtor(TestContext testContext)
+    {
+        _testContext = testContext;
+    }
+
+    [AssemblyInitialize]
+    public static void AssemblyInitialize(TestContext context)
+    {
+        // Access TestContext properties and methods here. The properties related to the test run are not available.
+    }
+
+    [ClassInitialize]
+    public static void ClassInitialize(TestContext context)
+    {
+        // Access TestContext properties and methods here. The properties related to the test run are not available.
+    }
+
+    [TestMethod]
+    public void MyTestMethod()
+    {
+        // Access TestContext properties and methods here
+    }
+}

docs/core/testing/snippets/testcontext/csharp/project.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net481</TargetFramework>
+    <LangVersion>latest</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="MSTest" Version="3.6.3" />
+  </ItemGroup>
+
+</Project>

docs/core/testing/unit-testing-mstest-writing-tests-testcontext.md

@@ -0,0 +1,84 @@
+---
+title: MSTest TestContext
+description: Learn about the TestContext class of MSTest.
+author: Evangelink
+ms.author: amauryleve
+ms.date: 11/12/2024
+---
+
+# The `TestContext` class
+
+The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> class gives useful information and tools to help manage test execution. It lets you access details about the test run and adjust the test environment. This class is part of the <xref:Microsoft.VisualStudio.TestTools.UnitTesting> namespace.
+
+## Accessing the `TestContext` object
+
+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 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.
+
+:::code language="csharp" source="snippets/testcontext/csharp/TestContext.cs":::
+
+Or with MSTest 3.6+:
+
+:::code language="csharp" source="snippets/testcontext/csharp/TestContextCtor.cs":::
+
+## 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.
+
+### Test run information
+
+The `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`.
+
+In MSTest 3.7 and later, the `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.
+
+### 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.
+
+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).
+
+Consider the following CSV file `TestData.csv`:
+
+```csv
+Number,Name
+1,TestValue1
+2,TestValue2
+3,TestValue3
+```
+
+You can use the `DataSource` attribute to read the data from the CSV file:
+
+:::code language="csharp" source="snippets/testcontext/csharp/CsvDataSource.cs":::
+
+### Store and retrieve runtime data
+
+You can use <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.Properties?displayProperty=nameWithType> to store custom key-value pairs that can be accessed across different methods in the same test session.
+
+```csharp
+TestContext.Properties["MyKey"] = "MyValue";
+string value = TestContext.Properties["MyKey"]?.ToString();
+```
+
+### Associate data to a test
+
+The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.AddResultFile(System.String)?displayProperty=nameWithType> method allows you to add a file to the test results, making it available for review in the test output. This can be useful if you generate files during your test (for example, log files, screenshots, or data files) that you want to attach to the test results.
+
+:::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.

docs/core/testing/unit-testing-mstest-writing-tests.md

@@ -47,6 +47,12 @@ MSTest assertions are divided into the following classes:
 - [The `StringAssert` class](./unit-testing-mstest-writing-tests-assertions.md#the-stringassert-class)
 - [The `CollectionAssert` class](./unit-testing-mstest-writing-tests-assertions.md#the-collectionassert-class)
 
+## The `TestContext` class
+
+The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> class provides contextual information and support for test execution, making it easier to retrieve information about the test run and manipulate aspects of the environment. It's defined in the <xref:Microsoft.VisualStudio.TestTools.UnitTesting> namespace and is available when using the MSTest Framework.
+
+For more information, see [Accessing the `TestContext` object](./unit-testing-mstest-writing-tests-testcontext.md#accessing-the-testcontext-object) or [The `TestContext` members](./unit-testing-mstest-writing-tests-testcontext.md#the-testcontext-members).
+
 ## Testing private members
 
 You can generate a test for a private method. This generation creates a private accessor class, which instantiates an object of the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.PrivateObject> class. The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.PrivateObject> class is a wrapper class that uses reflection as part of the private accessor process. The <xref:Microsoft.VisualStudio.TestTools.UnitTesting.PrivateType> class is similar, but is used for calling private static methods instead of calling private instance methods.

docs/navigate/devops-testing/toc.yml

@@ -87,6 +87,8 @@ items:
                 href: ../../core/testing/unit-testing-mstest-writing-tests-attributes.md
               - name: Assertions
                 href: ../../core/testing/unit-testing-mstest-writing-tests-assertions.md
+              - name: TestContext
+                href: ../../core/testing/unit-testing-mstest-writing-tests-testcontext.md
           - name: Running tests
             items:
               - name: Overview