Document that timeouts notice test thread interrupt status

[dkfellows]

Please at least document that a test annotated with @Timeout must not complete in the interrupted state (preferably in the documentation for the annotation). That will at least then save someone else a few days of work trying to find out why things were blowing up despite apparently working.

---

The problem was I had a test case that effectively did this:

@Test
@Timeout(1)
void myTestCase() {
    Thread.currentThread().interrupt();
}

and JUnit 5 was saying that the test was failing... much later on in the test suite. This was intensely confusing! Once I knew what the problem was, clearing the interrupt status was trivially easy (I could ensure this would only happen in a way that was successful).

(The real test was a lot more complex which is why it was so much harder to spot.)

Better yet, the decision about whether a test timed out shouldn't be based on whether the interrupted flag is set on that thread, but if that's how it has to be then let us know so that we can at least ensure that our test code doesn't trigger spurious failures. Hence the simple documentation enhancement request for the annotation.

[sbrannen]

Hi @dkfellows,

Congratulations on creating your first issue for JUnit 5! 👍

We'll see how we can improve the documentation in 5.11.

Thanks

[marcphilipp]

I could not reproduce this issue. Since #1688 which was released in 5.4, the interrupted flag is reset after test execution. If you enable logging, you should see an entry similar to the following in case the test did not timeout:

DEBUG org.junit.platform.engine.support.hierarchical.NodeTestTask - Execution of TestDescriptor with display name [myTestCase()] and unique ID [[engine:junit-jupiter]/[class:org.junit.jupiter.TimeoutTests]/[method:myTestCase()]] failed to clear the 'interrupted status' flag for the current thread. JUnit has cleared the flag, but you may wish to investigate why the flag was not cleared by user code.

If the test did time out, the flag is cleared earlier and no entry is being logged.

@dkfellows Which version of JUnit are you using? Could you please provide a more complete reproducer?

[github-actions]

If you would like us to be able to process this issue, please provide the requested information. If the information is not provided within the next 3 weeks, we will be unable to proceed and this issue will be closed.

[github-actions]

Closing due to lack of requested feedback. If you would like to proceed with your contribution, please provide the requested information and we will re-open this issue.