Add a sample on how to get the cancellation token for TimeoutAttribute with CooperativeCancellation

[wizgob]

Type of issue

Missing information

Description

There is no indication on how the cancellation token should be passed.

The obvious guess did not work for me with MsTest 3.6.4 and sicne it's not documented, I've no idea of what I'm doing wrong

Page URL

https://learn.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.testtools.unittesting.timeoutattribute.cooperativecancellation?view=mstest-net-3.8

Content source URL

https://github.com/MicrosoftDocs/visualstudio-docs-dotnet-api-pr/blob/live/visualstudiosdk/Microsoft.VisualStudio.TestTools.UnitTesting/TimeoutAttribute.xml

[nohwnd]

namespace TestProject22
{
    [TestClass]
    public sealed class Test1
    {
        internal TestContext TestContext { get; set; }

        [TestMethod]
        [Timeout(1000, 
            // This tells the framework that we want to handle cancellation ourselves,
            // The framework will not abandon the work to background or skip awaiting the test case.
            CooperativeCancellation = true)]
        public void TestMethod1()
        {
            // Sleep longer than the timeout of 1 second above.
            Thread.Sleep(3_000);

            // Return when we were cancelled.
            if (TestContext.CancellationTokenSource.IsCancellationRequested)
            {
                return;
            }

            // Continue working if we were not cancelled.
            Thread.Sleep(3_000);
        }
    }
}

Does this look good enough? Or too simple?

[Evangelink]

We should throw and not return otherwise the test will be green (at least I think):

[TestMethod]
        [Timeout(1000, 
            // This tells the framework that we want to handle cancellation ourselves,
            // The framework will not abandon the work to background or skip awaiting the test case.
            CooperativeCancellation = true)]
        public void TestMethod1()
        {
            // Sleep longer than the timeout of 1 second above.
            Thread.Sleep(3_000);

            TestContext.CancellationTokenSource.Token.ThrowIfCancellationRequested();

            // Continue working if we were not cancelled.
            Thread.Sleep(3_000);
        }

[nohwnd]

namespace TestProject22
{
    [TestClass]
    public sealed class Test1
    {
        public TestContext TestContext { get; set; }

        [TestMethod]
        [Timeout(1000, 
            // This tells the framework that we want to handle cancellation ourselves,
            // The framework will not abandon the work to background or skip awaiting the test case.
            CooperativeCancellation = true)]
        public void TestMethod1()
        {
            // Sleep longer than the timeout of 1 second above.
            Thread.Sleep(3_000);

            TestContext.CancellationTokenSource.Token.ThrowIfCancellationRequested();
            
            // Continue working if we were not cancelled.
            Thread.Sleep(3_000);
        }
    }
}

Fixed the public on test context as well.

Nitpicks:

Imho succeeding the test when cancelled is a bug, and should be fixed to always fail even if user returns.

In my opinion we should show both the built in cancellation message in the error report, and the reported exception.

When I throw via the token:

When I throw an exception when cancelling the test:

In the second case I don't have any info about the test being cancelled. In the first case it is hard for me to understand that there was 1s timeout, but the cancellation did not happen until 3s.

[Evangelink]

What's tricky with the return (and why I didn't do it) is that when you are back to the framework and the token was cancelled you have no way to tell apart cancellation that happened during the test or right after:
test finishes, token cancelled, reach framework end of invoke vs test starts, token cancelled, test exits because of token, reach test framework.

[nohwnd]

no way to tell apart cancellation that happened during the test or right after

Understandable, but it also seems like a quite narrow race condition where I would err on the side of caution, and if the test asked for cooperative cancellation, and the cancellation token is already cancelled when the test returns, it must mean that the test did not complete soon enough and was cancelled, and it should fail. That return error I did seems to be too easy to make.

It also seems similar to the case where we would have Debug.Assert being triggered in tests, we would translate that to exception but also let framework know that this test is failing no matter of the result (e.g. when the assert exception gets handled).