Imported Upstream version 5.4.0.167

Former-commit-id: 5624ac747d633e885131e8349322922b6a59baaa

external/corefx/Documentation/project-docs/developer-guide.md

@@ -226,7 +226,11 @@ msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx
 
 The tests can also be filtered based on xunit trait attributes defined in [`xunit.netcore.extensions`](https://github.com/dotnet/buildtools/tree/master/src/xunit.netcore.extensions). These attributes are specified above the test method's definition. The available attributes are:
 
-_**`OuterLoop`:**_
+#### OuterloopAttribute
+
+```cs
+[OuterLoop()]
+```
 Tests marked as `Outerloop` are for scenarios that don't need to run every build. They may take longer than normal tests, cover seldom hit code paths, or require special setup or resources to execute. These tests are excluded by default when testing through msbuild but can be enabled manually by adding the  `Outerloop` property e.g.
 
 ```cmd
@@ -238,25 +242,136 @@ To run <b>only</b> the Outerloop tests, use the following command:
 msbuild <csproj_file> /t:BuildAndTest /p:WithCategories=OuterLoop
 ```
 
-_**`PlatformSpecific(TestPlatforms platforms)`:**_
+#### PlatformSpecificAttribute
+
+```cs
+[PlatformSpecific(TestPlatforms platforms)]
+```
 Use this attribute on test methods to specify that this test may only be run on the specified platforms. This attribute returns the following categories based on platform
 - `nonwindowstests` for tests that don't run on Windows
 - `nonlinuxtests` for tests that don't run on Linux
 - `nonosxtests` for tests that don't run on OS X
 
+**[Available Test Platforms](https://github.com/dotnet/buildtools/blob/master/src/xunit.netcore.extensions/TestPlatforms.cs#L10)**
+
 When running tests by building a test project, tests that don't apply to the `OSGroup` are not run. For example, to run Linux-specific tests on a Linux box, use the following command line:
 ```sh
 <repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=Linux
 ```
-
-_**`ActiveIssue(int issue, TestPlatforms platforms)`:**_
-Use this attribute over test methods to skip failing tests only on the specific platforms; if no platforms are specified, then the test is skipped on all platforms. This attribute returns the 'failing' category, which is disabled by default.
-
 To run all Linux-compatible tests that are failing:
 ```sh
 <repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing
 ```
 
+#### ActiveIssueAttribute
+This attribute is intended to be used when there is an active issue tracking the test failure and it is needed to be fixed. This is a temporary attribute to skip the test while the issue is fixed. It is important that you limit the scope of the attribute to just the platforms and target monikers where the issue applies.
+
+This attribute can be applied either to a test class (will disable all the tests in that class) or to a test method. It allows multiple usages on the same member.
+
+This attribute returns the 'failing' category, which is disabled by default.
+
+**Disable for all platforms and all target frameworks:**
+```cs
+[ActiveIssue(int issue)]
+[ActiveIssue(string issue)]
+```
+**Disable for specific platform:**
+```cs
+[ActiveIssue(int issue, TestPlatforms platforms)]
+[ActiveIssue(string issue, TestPlatforms platforms)]
+```
+**Disable for specific target frameworks:**
+```cs
+[ActiveIssue(int issue, TargetFrameworkMonikers frameworks)]
+[ActiveIssue(string issue, TargetFrameworkMonikers frameworks)]
+```
+**Disable for specific test platforms and target frameworks:**
+```cs
+[ActiveIssue(int issue, TestPlatforms platforms, TargetFrameworkMonikers frameworks)]
+[ActiveIssue(string issue, TestPlatforms platforms, TargetFrameworkMonikers frameworks)]
+```
+Use this attribute over test methods to skip failing tests only on the specific platforms and the specific target frameworks.
+
+#### SkipOnTargetFrameworkAttribute
+This attribute is intended to disable a test permanently on a framework where an API is not available or there is an intentional difference in behavior in between the tested framework and the skipped framework.
+
+This attribute can be applied either to a test class (will disable all the tests in that class) or to a test method. It allows multiple usages on the same member.
+
+```cs
+[SkipOnTargetFramework(TargetFrameworkMonikers frameworks, string reason)]
+```
+Use this attribute over test methods to skip tests only on the specific target frameworks. The reason parameter doesn't affect the traits but we rather always use it so that when we see this attribute we know why it is being skipped on that framework. 
+
+If it needs to be skipped in multiple frameworks and the reasons are different please use two attributes on the same test so that you can specify different reasons for each framework.
+
+**Currently this are the [Framework Monikers](https://github.com/dotnet/buildtools/blob/master/src/xunit.netcore.extensions/TargetFrameworkMonikers.cs#L23-L26) that we support through our test execution infrastructure**
+
+#### ConditionalFactAttribute
+Use this attribute to run the test only when a condition is `true`. This attribute is used when `ActiveIssueAttribute` or `SkipOnTargetFrameworkAttribute` are not flexible enough due to needing to run a custom logic at test time. This test behaves as a `[Fact]` test that has no test data passed in as a parameter.
+
+```cs
+[ConditionalFact(params string[] conditionMemberNames)]
+```
+
+The conditional method needs to be a static method or property on this or any ancestor type, of any visibility, accepting zero arguments, and having a return type of Boolean.
+
+**Example:**
+```cs
+public class TestClass
+{
+    public static bool ConditionProperty => true;
+
+    [ConditionalFact(nameof(ConditionProperty))]
+    public static void TestMethod()
+    {
+        Assert.True(true);
+    }
+}
+```
+
+#### ConditionalTheoryAttribute
+Use this attribute to run the test only when a condition is `true`. This attribute is used when `ActiveIssueAttribute` or `SkipOnTargetFrameworkAttribute` are not flexible enough due to needing to run a custom logic at test time. This test behaves as a `[Theory]` test that has no test data passed in as a parameter.
+
+```cs
+[ConditionalTheory(params string[] conditionMemberNames)]
+```
+
+This attribute must have `[MemberData(string member)]` or a `[ClassData(Type class)]` attribute, which represents an `IEnumerable<object>` containing the data that will be passed as a parameter to the test. Another option is to add multiple or one `[InlineData(object params[] parameters)]` attribute.
+
+The conditional method needs to be a static method or property on this or any ancestor type, of any visibility, accepting zero arguments, and having a return type of Boolean.
+
+**Example:**
+```cs
+public class TestClass
+{
+    public static bool ConditionProperty => true;
+
+    public static IEnumerable<object[]> Subtract_TestData()
+    {
+        yield return new object[] { new IntPtr(42), 6, (long)36 };
+        yield return new object[] { new IntPtr(40), 0, (long)40 };
+        yield return new object[] { new IntPtr(38), -2, (long)40 };
+    }
+
+    [ConditionalTheory(nameof(ConditionProperty))]
+    [MemberData(nameof(Equals_TestData))]
+    public static void Subtract(IntPtr ptr, int offset, long expected)
+    {
+        IntPtr p1 = IntPtr.Subtract(ptr, offset);
+        VerifyPointer(p1, expected);
+
+        IntPtr p2 = ptr - offset;
+        VerifyPointer(p2, expected);
+
+        IntPtr p3 = ptr;
+        p3 -= offset;
+        VerifyPointer(p3, expected);
+    }
+}
+```
+
+**Note that all of the attributes above must include an issue number/link and/or have a comment next to them briefly justifying the reason. ActiveIssueAttribute and SkipOnTargetFrameworkAttribute should use their constructor parameters to do this**
+
 _**A few common examples with the above attributes:**_
 
 - Run all tests acceptable on Windows that are not failing: