Expand the 'Known Issues' documentation article #823
Conversation
Resolves rdar://137961874
stmontgomery
added
documentation
stmontgomery
requested review from
grynspan,
dennisweissmann,
briancroom,
SeanROlszewski and
suzannaratcliff
as code owners
|
@swift-ci please test |
| @@ -10,13 +10,135 @@ See https://swift.org/LICENSE.txt for license information | |||
| See https://swift.org/CONTRIBUTORS.txt for Swift project authors | |||
| --> | |||
|
|
|||
| Highlight known issues when running tests. | |||
There was a problem hiding this comment.
I think this specific phrasing came from our DevPubs friends? So you might want to ask them to look too.
|
|
||
| ### Mark a thrown error as known | ||
|
|
||
| If an `Error` is caught by the closure passed to `withKnownIssue()`, the issue |
There was a problem hiding this comment.
Might be good to explain the difference from #expect(throws:)?
| } | ||
| ``` | ||
|
|
||
| If the underlying problem is truly nondeterministic, you may acknowledge this |
There was a problem hiding this comment.
How about:
If the underlying problem is unpredictable and causes your test to fail at random, you can pass
isIntermittent: trueto let the testing library know that your test will not always record an issue:
|
|
||
| If `withKnownIssue()` sometimes succeeds but other times records an issue | ||
| indicating there were no known issues, this may indicate a nondeterministic | ||
| failure or a "flaky" test. |
There was a problem hiding this comment.
Might want a paragraph here emphasizing "fix your tests first". We get a fair amount of feedback asking "why even have XFAIL semantics?"
| #expect(foodTruck.grill.isHeating) | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Do you want to add one more example showing all of the knobs and doodads in a single call?
This expands the Known issues DocC article to give examples and describe several different ways it can be used.
Checklist:
Resolves rdar://137961874