Skip to content

Commit 4c0d958

Browse files
grynspangrynspan
committed
Create an Exit Testing DocC article
1 parent c947c4b commit 4c0d958

File tree

2 files changed

+1
-142
lines changed

2 files changed

+1
-142
lines changed

‎Sources/Testing/Expectations/Expectation+Macro.swift

-142
Original file line numberDiff line numberDiff line change
@@ -511,78 +511,6 @@ public macro require<R>(
511511
/// }
512512
/// ```
513513
///
514-
/// - Note: A call to this expectation macro is called an "exit test."
515-
///
516-
/// ## How exit tests are run
517-
///
518-
/// When an exit test is performed at runtime, the testing library starts a new
519-
/// process with the same executable as the current process. The current task is
520-
/// then suspended (as with `await`) and waits for the child process to
521-
/// terminate. `expression` is not called in the parent process.
522-
///
523-
/// Meanwhile, in the child process, `expression` is called directly. To ensure
524-
/// a clean environment for execution, it is not called within the context of
525-
/// the original test. If `expression` does not terminate the child process, the
526-
/// process is terminated automatically as if the main function of the child
527-
/// process were allowed to return naturally. If an error is thrown from
528-
/// `expression`, it is handed as if the error were thrown from `main()` and the
529-
/// process is terminated.
530-
///
531-
/// Once the child process terminates, the parent process resumes and compares
532-
/// its exit status against `expectedExitCondition`. If they match, the exit
533-
/// test has passed; otherwise, it has failed and an issue is recorded.
534-
///
535-
/// ## Child process output
536-
///
537-
/// By default, the child process is configured without a standard output or
538-
/// standard error stream. If your test needs to review the content of either of
539-
/// these streams, you can pass its key path in the `observedValues` argument:
540-
///
541-
/// ```swift
542-
/// let result = await #expect(
543-
/// exitsWith: .failure,
544-
/// observing: [\.standardOutputContent]
545-
/// ) {
546-
/// print("Goodbye, world!")
547-
/// fatalError()
548-
/// }
549-
/// if let result {
550-
/// #expect(result.standardOutputContent.contains(UInt8(ascii: "G")))
551-
/// }
552-
/// ```
553-
///
554-
/// - Note: The content of the standard output and standard error streams may
555-
/// contain any arbitrary sequence of bytes, including sequences that are not
556-
/// valid UTF-8 and cannot be decoded by [`String.init(cString:)`](https://developer.apple.com/documentation/swift/string/init(cstring:)-6kr8s).
557-
/// These streams are globally accessible within the child process, and any
558-
/// code running in an exit test may write to it including the operating
559-
/// system and any third-party dependencies you have declared in your package.
560-
///
561-
/// The actual exit condition of the child process is always reported by the
562-
/// testing library even if you do not specify it in `observedValues`.
563-
///
564-
/// ## Runtime constraints
565-
///
566-
/// Exit tests cannot capture any state originating in the parent process or
567-
/// from the enclosing lexical context. For example, the following exit test
568-
/// will fail to compile because it captures an argument to the enclosing
569-
/// parameterized test:
570-
///
571-
/// ```swift
572-
/// @Test(arguments: 100 ..< 200)
573-
/// func sellIceCreamCones(count: Int) async {
574-
/// await #expect(exitsWith: .failure) {
575-
/// precondition(
576-
/// count < 10, // ERROR: A C function pointer cannot be formed from a
577-
/// // closure that captures context
578-
/// "Too many ice cream cones"
579-
/// )
580-
/// }
581-
/// }
582-
/// ```
583-
///
584-
/// An exit test cannot run within another exit test.
585-
///
586514
/// @Metadata {
587515
/// @Available(Swift, introduced: 6.2)
588516
/// }
@@ -628,76 +556,6 @@ public macro require<R>(
628556
/// }
629557
/// ```
630558
///
631-
/// - Note: A call to this expectation macro is called an "exit test."
632-
///
633-
/// ## How exit tests are run
634-
///
635-
/// When an exit test is performed at runtime, the testing library starts a new
636-
/// process with the same executable as the current process. The current task is
637-
/// then suspended (as with `await`) and waits for the child process to
638-
/// terminate. `expression` is not called in the parent process.
639-
///
640-
/// Meanwhile, in the child process, `expression` is called directly. To ensure
641-
/// a clean environment for execution, it is not called within the context of
642-
/// the original test. If `expression` does not terminate the child process, the
643-
/// process is terminated automatically as if the main function of the child
644-
/// process were allowed to return naturally. If an error is thrown from
645-
/// `expression`, it is handed as if the error were thrown from `main()` and the
646-
/// process is terminated.
647-
///
648-
/// Once the child process terminates, the parent process resumes and compares
649-
/// its exit status against `expectedExitCondition`. If they match, the exit
650-
/// test has passed; otherwise, it has failed and an issue is recorded.
651-
///
652-
/// ## Child process output
653-
///
654-
/// By default, the child process is configured without a standard output or
655-
/// standard error stream. If your test needs to review the content of either of
656-
/// these streams, you can pass its key path in the `observedValues` argument:
657-
///
658-
/// ```swift
659-
/// let result = try await #require(
660-
/// exitsWith: .failure,
661-
/// observing: [\.standardOutputContent]
662-
/// ) {
663-
/// print("Goodbye, world!")
664-
/// fatalError()
665-
/// }
666-
/// #expect(result.standardOutputContent.contains(UInt8(ascii: "G")))
667-
/// ```
668-
///
669-
/// - Note: The content of the standard output and standard error streams may
670-
/// contain any arbitrary sequence of bytes, including sequences that are not
671-
/// valid UTF-8 and cannot be decoded by [`String.init(cString:)`](https://developer.apple.com/documentation/swift/string/init(cstring:)-6kr8s).
672-
/// These streams are globally accessible within the child process, and any
673-
/// code running in an exit test may write to it including the operating
674-
/// system and any third-party dependencies you have declared in your package.
675-
///
676-
/// The actual exit condition of the child process is always reported by the
677-
/// testing library even if you do not specify it in `observedValues`.
678-
///
679-
/// ## Runtime constraints
680-
///
681-
/// Exit tests cannot capture any state originating in the parent process or
682-
/// from the enclosing lexical context. For example, the following exit test
683-
/// will fail to compile because it captures an argument to the enclosing
684-
/// parameterized test:
685-
///
686-
/// ```swift
687-
/// @Test(arguments: 100 ..< 200)
688-
/// func sellIceCreamCones(count: Int) async throws {
689-
/// try await #require(exitsWith: .failure) {
690-
/// precondition(
691-
/// count < 10, // ERROR: A C function pointer cannot be formed from a
692-
/// // closure that captures context
693-
/// "Too many ice cream cones"
694-
/// )
695-
/// }
696-
/// }
697-
/// ```
698-
///
699-
/// An exit test cannot run within another exit test.
700-
///
701559
/// @Metadata {
702560
/// @Available(Swift, introduced: 6.2)
703561
/// }

‎Sources/Testing/Testing.docc/Expectations.md

+1
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ the test when the code doesn't satisfy a requirement, use
7474

7575
### Checking how processes exit
7676

77+
- <doc:exit-testing>
7778
- ``expect(exitsWith:observing:_:sourceLocation:performing:)``
7879
- ``require(exitsWith:observing:_:sourceLocation:performing:)``
7980
- ``ExitTest``

0 commit comments

Comments
 (0)