@@ -10,13 +10,13 @@ See https://swift.org/LICENSE.txt for license information
10
10
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
11
11
-->
12
12
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 .
14
14
15
15
## Overview
16
16
17
17
Your code may contain calls to [ ` precondition() ` ] ( https://developer.apple.com/documentation/swift/precondition(_:_:file:line:) ) ,
18
18
[ ` 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:
20
20
21
21
``` swift
22
22
extension Customer {
@@ -29,17 +29,14 @@ extension Customer {
29
29
```
30
30
31
31
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
34
34
your functions correctly catch invalid inputs.
35
35
36
36
## Create an exit test
37
37
38
38
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:
43
40
44
41
``` swift
45
42
@Test func `Customer won't eat food unless it's delicious`() async {
@@ -51,25 +48,39 @@ or signal):
51
48
}
52
49
```
53
50
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.
73
84
74
85
## Gather output from the child process
75
86
0 commit comments