Merge pull request #8564 from Evangelink/mstest-data-driven

Jak-MS · web-flow · commit ecb3a6e0ac95 · 2022-10-17T13:41:52.000-07:00
Update doc for MSTest data-driven tests
diff --git a/docs/test/how-to-create-a-data-driven-unit-test.md b/docs/test/how-to-create-a-data-driven-unit-test.md
@@ -2,7 +2,7 @@
 title: Create Data-Driven Unit Tests
 description: Learn how to use the Microsoft unit test framework for managed code to set up a unit test method to retrieve values from a data source.
 ms.custom: SEO-VS-2020
-ms.date: 05/08/2019
+ms.date: 10/17/2012
 ms.topic: how-to
 f1_keywords: 
   - vs.test.testresults.unittest.datadriven
@@ -22,17 +22,13 @@ author: mikejo5000
 
  [!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)]
 
-You can use the Microsoft unit test framework for managed code to set up a unit test method to retrieve values from a data source. The method is run successively for each row in the data source, which makes it easy to test a variety of input by using a single method.
+You can use the Microsoft unit test framework (MSTest) for managed code to set up a unit test method to retrieve values from a data source. The method is run successively for each row in the data source, which makes it easy to test a variety of input by using a single method.
 
-Creating a data-driven unit test involves the following steps:
+A data-driven unit test can use any of the following kind:
 
-1. Create a data source that contains the values that you use in the test method. The data source can be any type that is registered on the machine that runs the test.
-
-2. Add a private <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> field and a public `TestContext` property to the test class.
-
-3. Create a unit test method and add a <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataSourceAttribute> attribute to it.
-
-4. Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.DataRow%2A> indexer property to retrieve the values that you use in a test.
+- inline data using the `DataRow` attribute
+- member data using the `DynamicData` attribute
+- from some well-known source provider using the `DataSource` attribute
 
 ## The method under test
 
@@ -54,15 +50,94 @@ We'll test a method in `Maths` that adds two integers using a loop:
 public int AddIntegers(int first, int second)
 {
     int sum = first;
-    for( int i = 0; i < second; i++)
+    for (int i = 0; i < second; i++)
     {
         sum += 1;
     }
+
     return sum;
 }
 ```
 
-## Create a data source
+## Test test method
+
+### Inline data-driven test
+
+For inline tests, MSTest uses `DataRow` to specify values used by the data-driven test. The test in this example runs successively for each data row.
+
+```csharp
+[DataTestMethod]
+[DataRow(1, 1, 2)]
+[DataRow(2, 2, 4)]
+[DataRow(3, 3, 6)]
+[DataRow(0, 0, 1)] // The test run with this row fails
+public void AddIntegers_FromDataRowTest(int x, int y, int expected)
+{
+    var target = new Maths();
+    int actual = target.AddIntegers(x, y);
+    Assert.AreEqual(expected, actual,
+        "x:<{0}> y:<{1}>",
+        new object[] {x, y});
+}
+```
+
+### Member data-driven test
+
+MSTest uses `DynamicData` attribute to specify the name, kind (property, the default, or method) and defining type (by default current type is used) of the member that will provide the data used by the data-driven test.
+
+```csharp
+public static IEnumerable<object[]> AdditionData
+{
+    get
+    {
+        return new[]
+        { 
+            new object[] { 1, 1, 2 },
+            new object[] { 2, 2, 4 },
+            new object[] { 3, 3, 6 },
+            new object[] { 0, 0, 1 }, // The test run with this row fails
+        };
+    }
+}
+
+[TestMethod]
+[DynamicData(nameof(ReusableTestDataProperty))]
+public void AddIntegers_FromDynamicDataTest(int x, int y, int expected)
+{
+    var target = new Maths();
+    int actual = target.AddIntegers(x, y);
+    Assert.AreEqual(expected, actual,
+        "x:<{0}> y:<{1}>",
+        new object[] {x, y});
+}
+```
+
+It is also possible to override the default generated display name, using the `DynamicDataDisplayName` property of the `DynamicData` attribute. The display name method signature must be `publc static string` and accept two parameters, the first of type `MethodInfo` and the second of type `object[]`.
+
+```csharp
+public static string GetCustomDynamicDataDisplayName(MethodInfo methodInfo, object[] data)
+{
+    return string.Format("DynamicDataTestMethod {0} with {1} parameters", methodInfo.Name, data.Length);
+}
+
+[DynamicData(nameof(AdditionData), DynamicDataDisplayName = nameof(GetCustomDynamicDataDisplayName))]
+```
+
+### Source provider data-driven test
+
+Creating a data source driven unit test involves the following steps:
+
+1. Create a data source that contains the values that you use in the test method. The data source can be any type that is registered on the machine that runs the test.
+
+2. Add a public `TestContext` property of type <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> to the test class.
+
+3. Create a unit test method
+
+4. Add a <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataSourceAttribute> attribute to it.
+
+5. Use the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext.DataRow%2A> indexer property to retrieve the values that you use in a test.
+
+#### Create a data source
 
 To test the `AddIntegers` method, create a data source that specifies a range of values for the parameters and the sum that you expect to be returned. In this example, we'll create a Sql Compact database named `MathsData` and a table named `AddIntegersData` that contains the following column names and values
 
@@ -72,31 +147,26 @@ To test the `AddIntegers` method, create a data source that specifies a range of
 |1|1|2|
 |2|-3|-1|
 
-## Add a TestContext to the test class
+#### Add a TestContext to the test class
 
 The unit test framework creates a `TestContext` object to store the data source information for a data-driven test. The framework then sets this object as the value of the `TestContext` property that you create.
 
 ```csharp
-private TestContext testContextInstance;
-public TestContext TestContext
-{
-    get { return testContextInstance; }
-    set { testContextInstance = value; }
-}
+public TestContext TestContext { get; set; }
 ```
 
 In your test method, you access the data through the `DataRow` indexer property of the `TestContext`.
 
 > [!NOTE]
-> .NET Core does not support the [DataSource](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataSourceAttribute) attribute. If you try to access test data in this way in a .NET Core or UWP unit test project, you'll see an error similar to **"'TestContext' does not contain a definition for 'DataRow' and no accessible extension method 'DataRow' accepting a first argument of type 'TestContext' could be found (are you missing a using directive or an assembly reference?)"**.
+> .NET Core does not support the [DataSource](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataSourceAttribute) attribute. If you try to access test data in this way in a .NET Core, UWP or WinUI unit test project, you will see an error similar to **"'TestContext' does not contain a definition for 'DataRow' and no accessible extension method 'DataRow' accepting a first argument of type 'TestContext' could be found (are you missing a using directive or an assembly reference?)"**.
 
-## Write the test method
+#### Write the test method
 
 The test method for `AddIntegers` is fairly simple. For each row in the data source, call `AddIntegers` with the **FirstNumber** and **SecondNumber** column values as parameters, and verify the return value against **Sum** column value:
 
 ```csharp
+[TestMethod]
 [DataSource(@"Provider=Microsoft.SqlServerCe.Client.4.0; Data Source=C:\Data\MathsData.sdf;", "Numbers")]
-[TestMethod()]
 public void AddIntegers_FromDataSourceTest()
 {
     var target = new Maths();
@@ -105,16 +175,14 @@ public void AddIntegers_FromDataSourceTest()
     int x = Convert.ToInt32(TestContext.DataRow["FirstNumber"]);
     int y = Convert.ToInt32(TestContext.DataRow["SecondNumber"]);
     int expected = Convert.ToInt32(TestContext.DataRow["Sum"]);
-    int actual = target.IntegerMethod(x, y);
+    int actual = target.AddIntegers(x, y);
     Assert.AreEqual(expected, actual,
         "x:<{0}> y:<{1}>",
         new object[] {x, y});
 }
 ```
 
-The `Assert` method includes a message that displays the `x` and `y` values of a failed iteration. By default, the asserted values - `expected` and `actual` - are already included in failed test details.
-
-### Specify the DataSourceAttribute
+#### Specify the DataSourceAttribute
 
 The `DataSource` attribute specifies the connection string for the data source and the name of the table that you use in the test method. The exact information in the connection string differs, depending on what kind of data source you are using. In this example, we used a SqlServerCe database.
 
@@ -149,7 +217,7 @@ The connection strings depend on the type of the type of data source, but it sho
     )]
 ```
 
-### Use TestContext.DataRow to access the data
+#### Use TestContext.DataRow to access the data
 
 To access the data in the `AddIntegersData` table, use the `TestContext.DataRow` indexer. `DataRow` is a <xref:System.Data.DataRow> object, so retrieve column values by index or column names. Because the values are returned as objects, convert them to the appropriate type:
 
@@ -166,26 +234,10 @@ The test results bar at the top of **Test Explorer** is animated as your test ru
 > [!NOTE]
 > There's a result for each row of data and also one summary result. If the test passed on each row of data, the summary run shows as **Passed**. If the test failed on any data row, the summary run shows as **Failed**.
 
-If you ran the `AddIntegers_FromDataSourceTest` method in our example, the results bar turns red and the test method is moved to the **Failed Tests**. A data-driven test fails if any of the iterated methods from the data source fails. When you choose a failed data-driven test in the **Test Explorer** window, the details pane displays the results of each iteration that is identified by the data row index. In our example, it appears that the `AddIntegers` algorithm does not handle negative values correctly.
+If you ran any of the `AddIntegers_FromDataRowTest`, `AddIntegers_FromDynamicDataTest` or `AddIntegers_FromDataSourceTest` method in our example, the results bar turns red and the test method is moved to the **Failed Tests**. A data-driven test fails if any of the iterated methods from the data source fails. When you choose a failed data-driven test in the **Test Explorer** window, the details pane displays the results of each iteration that is identified by the data row index. In our example, it appears that the `AddIntegers` algorithm does not handle negative values correctly.
 
 When the method under test is corrected and the test rerun, the results bar turns green and the test method is moved to the **Passed Test** group.
 
-## Run an inline data-driven test
-
-For inline tests, MSTest uses `DataRow` to retrieve values from a data source. The test in this example runs successively for each data row.
-
-```csharp
-[DataTestMethod]
-[DataRow(1, 1, 2)]
-[DataRow(2, 2, 4)]
-[DataRow(3, 3, 6)]
-[DataRow(0, 0, 1)] // The test run with this row fails
-public void AddTests(int x, int y, int expected)
-{
-  Assert.AreEqual(expected, x + y);
-}
-```
-
 ## See also
 
 - <xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataSourceAttribute?displayProperty=fullName>
diff --git a/docs/test/unit-test-basics.md b/docs/test/unit-test-basics.md
@@ -1,7 +1,7 @@
 ---
 title: Unit testing fundamentals
 description: Learn how Visual Studio Test Explorer provides a flexible and efficient way to run your unit tests and view their results. 
-ms.date: 12/28/2021
+ms.date: 10/17/2021
 ms.topic: conceptual
 f1_keywords:
 - vs.UnitTest.CreateUnitTest
@@ -298,33 +298,9 @@ Learn more details about [debugging unit tests](../debugger/debugger-feature-tou
 
 **Q: Can I create unit tests that take multiple sets of data as input to run the test?**
 
-**A:** Yes. *Data-driven test methods* let you test a range of values with a single unit test method. Use a `DataSource` attribute for the test method that specifies the data source and table that contains the variable values that you want to test.  In the method body, you assign the row values to variables using the `TestContext.DataRow[`*ColumnName*`]` indexer.
+**A:** Yes. *Data-driven test methods* let you test a range of values with a single unit test method. Use a `DataRow`, `DynamicData` or `DataSource` attribute for the test method that specifies the data source that contains the variable values that you want to test.
 
-> [!NOTE]
-> These procedures apply only to test methods that you write by using the Microsoft unit test framework for managed code. If you're using a different framework, consult the framework documentation for equivalent functionality.
-
-For example, assume we add an unnecessary method to the `CheckingAccount` class that is named `AddIntegerHelper`. `AddIntegerHelper` adds two integers.
-
-To create a data-driven test for the `AddIntegerHelper` method, we first create an Access database named *AccountsTest.accdb* and a table named `AddIntegerHelperData`. The `AddIntegerHelperData` table defines columns to specify the first and second operands of the addition and a column to specify the expected result. We fill a number of rows with appropriate values.
-
-```csharp
-[DataSource(
-    @"Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\Projects\MyBank\TestData\AccountsTest.accdb",
-    "AddIntegerHelperData"
-)]
-[TestMethod()]
-public void AddIntegerHelper_DataDrivenValues_AllShouldPass()
-{
-    var target = new CheckingAccount();
-    int x = Convert.ToInt32(TestContext.DataRow["FirstNumber"]);
-    int y = Convert.ToInt32(TestContext.DataRow["SecondNumber"]);
-    int expected = Convert.ToInt32(TestContext.DataRow["Sum"]);
-    int actual = target.AddIntegerHelper(x, y);
-    Assert.AreEqual(expected, actual);
-}
-```
-
-The attributed method runs once for each row in the table. **Test Explorer** reports a test failure for the method if any of the iterations fail. The test results detail pane for the method shows you the pass/fail status method for each row of data.
+The attributed method runs once for each row in the data source. **Test Explorer** reports a test failure for the method if any of the iterations fail. The test results detail pane for the method shows you the pass/fail status method for each row of data.
 
 Learn more about [data-driven unit tests](../test/how-to-create-a-data-driven-unit-test.md).
 
