Skip to content

Commit b8265c7

Browse files
committed
Avoid the word 'exit' in documentation, add more details about exit conditions
1 parent eb884a5 commit b8265c7

File tree

1 file changed

+38
-27
lines changed

1 file changed

+38
-27
lines changed

Sources/Testing/Testing.docc/exit-testing.md

Lines changed: 38 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@ See https://swift.org/LICENSE.txt for license information
1010
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
1111
-->
1212

13-
Use exit tests to test functionality that may cause a test process to terminate.
13+
Use exit tests to test functionality that may cause a test process to exit.
1414

1515
## Overview
1616

1717
Your code may contain calls to [`precondition()`](https://developer.apple.com/documentation/swift/precondition(_:_:file:line:)),
1818
[`fatalError()`](https://developer.apple.com/documentation/swift/fatalerror(_:file:line:)),
19-
or other functions that may cause the current process to terminate. For example:
19+
or other functions that may cause the current process to exit. For example:
2020

2121
```swift
2222
extension Customer {
@@ -29,17 +29,14 @@ extension Customer {
2929
```
3030

3131
In this function, if `food.isDelicious` or `food.isNutritious` is `false`, the
32-
precondition will fail and Swift will terminate the process. You can write an
33-
exit test to validate preconditions like the ones above and to make sure that
32+
precondition will fail and Swift will force the process to exit. You can write
33+
an exit test to validate preconditions like the ones above and to make sure that
3434
your functions correctly catch invalid inputs.
3535

3636
## Create an exit test
3737

3838
To create an exit test, call either the ``expect(exitsWith:observing:_:sourceLocation:performing:)``
39-
or the ``require(exitsWith:observing:_:sourceLocation:performing:)`` macro and
40-
pass a closure containing the code that may terminate the process along with the
41-
expected result of calling that code (success, failure, or a specific exit code
42-
or signal):
39+
or the ``require(exitsWith:observing:_:sourceLocation:performing:)`` macro:
4340

4441
```swift
4542
@Test func `Customer won't eat food unless it's delicious`() async {
@@ -51,25 +48,39 @@ or signal):
5148
}
5249
```
5350

54-
When an exit test is performed at runtime, the testing library starts a new
55-
process with the same executable as the current process. The current task is
56-
then suspended (as with `await`) and waits for the child process to terminate.
57-
`expression` is not called in the parent process.
58-
59-
Meanwhile, in the child process, the closure you passed to ``expect(exitsWith:observing:_:sourceLocation:performing:)``
60-
or to ``require(exitsWith:observing:_:sourceLocation:performing:)`` is called
61-
directly. To ensure a clean environment for execution, the closure is not called
62-
within the context of the original test. Instead, it is treated as if it were
63-
the `main()` function of the child process.
64-
65-
If the closure returns before the child process terminates, it is terminated
66-
automatically (as if the main function of the child process were allowed to
67-
return naturally.) If an error is thrown from the closure, it is handed as if
68-
the error were thrown from `main()` and the process is terminated.
69-
70-
Once the child process terminates, the parent process resumes and compares its
71-
exit status against the expected exit condition you passed. If they match, the
72-
exit test has passed; otherwise, it has failed and an issue is recorded.
51+
The closure or function reference you pass to these macros is the body of the
52+
exit test. When an exit test is performed at runtime, the testing library starts
53+
a new process with the same executable as the current process. The current task
54+
is then suspended (as with `await`) and waits for the child process to
55+
exit. The exit test's body is not called in the parent process.
56+
57+
Meanwhile, in the child process, the body is called directly. To ensure a clean
58+
environment for execution, the body is not called within the context of the
59+
original test. Instead, it is treated as if it were the `main()` function of the
60+
child process.
61+
62+
If the body returns before the child process exits, it is allowed to return and
63+
the process exits naturally. If an error is thrown from the body, it is handled
64+
as if the error were thrown from `main()` and the process is forced to exit.
65+
66+
## Specify an exit condition
67+
68+
When you create an exit test, you must specify how you expect the child process
69+
will exit by passing an instance of ``ExitTest/Condition``:
70+
71+
- If the exit test's body should run to completion or exit normally (for
72+
example, by calling `exit(EXIT_SUCCESS)` from the C standard library), pass
73+
``ExitTest/Condition/success``.
74+
- If the body will cause the child process to exit with some failure, but the
75+
exact status reported by the system is not important, pass
76+
``ExitTest/Condition/failure``.
77+
- If you need to check for a specific exit code or signal, pass
78+
``ExitTest/Condition/exitCode(_:)`` or ``ExitTest/Condition/signal(_:)``.
79+
80+
When the child process exits, the parent process resumes and compares the exit
81+
status of the child process against the expected exit condition you passed. If
82+
they match, the exit test has passed; otherwise, it has failed and the testing
83+
library records an issue.
7384

7485
## Gather output from the child process
7586

0 commit comments

Comments
 (0)