|
| 1 | +// |
| 2 | +// This source file is part of the Swift.org open source project |
| 3 | +// |
| 4 | +// Copyright (c) 2023–2025 Apple Inc. and the Swift project authors |
| 5 | +// Licensed under Apache License v2.0 with Runtime Library Exception |
| 6 | +// |
| 7 | +// See https://swift.org/LICENSE.txt for license information |
| 8 | +// See https://swift.org/CONTRIBUTORS.txt for Swift project authors |
| 9 | +// |
| 10 | + |
| 11 | +#if !SWT_NO_EXIT_TESTS |
| 12 | +@_spi(Experimental) @_spi(ForToolsIntegrationOnly) |
| 13 | +extension ExitTest { |
| 14 | + /// A type representing a value captured by an exit test's body. |
| 15 | + /// |
| 16 | + /// An instance of this type may represent the actual value that was captured |
| 17 | + /// when the exit test was invoked. In the child process created by the |
| 18 | + /// current exit test handler, instances will initially only have the type of |
| 19 | + /// the value, but not the value itself. |
| 20 | + /// |
| 21 | + /// Instances of this type are created automatically by the testing library |
| 22 | + /// for all elements in an exit test body's capture list and are stored in the |
| 23 | + /// exit test's ``capturedValues`` property. For example, given the following |
| 24 | + /// exit test: |
| 25 | + /// |
| 26 | + /// ```swift |
| 27 | + /// await #expect(exitsWith: .failure) { [a = a as T, b = b as U, c = c as V] in |
| 28 | + /// ... |
| 29 | + /// } |
| 30 | + /// ``` |
| 31 | + /// |
| 32 | + /// There are three captured values in its ``capturedValues`` property. These |
| 33 | + /// values are captured at the time the exit test is called, as they would be |
| 34 | + /// if the closure were called locally. |
| 35 | + /// |
| 36 | + /// The current exit test handler is responsible for encoding and decoding |
| 37 | + /// instances of this type. When the handler is called, it is passed an |
| 38 | + /// instance of ``ExitTest``. The handler encodes the values in that |
| 39 | + /// instance's ``capturedValues`` property, then passes the encoded forms of |
| 40 | + /// those values to the child process. The encoding format and message-passing |
| 41 | + /// interface are implementation details of the exit test handler. |
| 42 | + /// |
| 43 | + /// When the child process calls ``ExitTest/find(identifiedBy:)``, it receives |
| 44 | + /// an instance of ``ExitTest`` whose ``capturedValues`` property contains |
| 45 | + /// type information but no values. The child process decodes the values it |
| 46 | + /// encoded in the parent process and then updates the ``wrappedValue`` |
| 47 | + /// property of each element in the array before calling the exit test's body. |
| 48 | + public struct CapturedValue: Sendable { |
| 49 | + /// An enumeration of the different states a captured value can have. |
| 50 | + private enum _Kind: Sendable { |
| 51 | + /// The runtime value of the captured value is known. |
| 52 | + case wrappedValue(any Codable & Sendable) |
| 53 | + |
| 54 | + /// Only the type of the captured value is known. |
| 55 | + case typeOnly(any (Codable & Sendable).Type) |
| 56 | + } |
| 57 | + |
| 58 | + /// The current state of this instance. |
| 59 | + private var _kind: _Kind |
| 60 | + |
| 61 | + init(wrappedValue: some Codable & Sendable) { |
| 62 | + _kind = .wrappedValue(wrappedValue) |
| 63 | + } |
| 64 | + |
| 65 | + init(typeOnly type: (some Codable & Sendable).Type) { |
| 66 | + _kind = .typeOnly(type) |
| 67 | + } |
| 68 | + |
| 69 | + /// The underlying value captured by this instance at runtime. |
| 70 | + /// |
| 71 | + /// In a child process created by the current exit test handler, the value |
| 72 | + /// of this property is `nil` until the entry point sets it. |
| 73 | + public var wrappedValue: (any Codable & Sendable)? { |
| 74 | + get { |
| 75 | + if case let .wrappedValue(wrappedValue) = _kind { |
| 76 | + return wrappedValue |
| 77 | + } |
| 78 | + return nil |
| 79 | + } |
| 80 | + |
| 81 | + set { |
| 82 | + let type = typeOfWrappedValue |
| 83 | + |
| 84 | + func validate<T, U>(_ newValue: T, is expectedType: U.Type) { |
| 85 | + assert(newValue is U, "Attempted to set a captured value to an instance of '\(String(describingForTest: T.self))', but an instance of '\(String(describingForTest: U.self))' was expected.") |
| 86 | + } |
| 87 | + validate(newValue, is: type) |
| 88 | + |
| 89 | + if let newValue { |
| 90 | + _kind = .wrappedValue(newValue) |
| 91 | + } else { |
| 92 | + _kind = .typeOnly(type) |
| 93 | + } |
| 94 | + } |
| 95 | + } |
| 96 | + |
| 97 | + /// The type of the underlying value captured by this instance. |
| 98 | + /// |
| 99 | + /// This type is known at compile time and is always available, even before |
| 100 | + /// this instance's ``wrappedValue`` property is set. |
| 101 | + public var typeOfWrappedValue: any (Codable & Sendable).Type { |
| 102 | + switch _kind { |
| 103 | + case let .wrappedValue(wrappedValue): |
| 104 | + type(of: wrappedValue) |
| 105 | + case let .typeOnly(type): |
| 106 | + type |
| 107 | + } |
| 108 | + } |
| 109 | + } |
| 110 | +} |
| 111 | + |
| 112 | +// MARK: - Collection conveniences |
| 113 | + |
| 114 | +extension Array where Element == ExitTest.CapturedValue { |
| 115 | + init<each T>(_ wrappedValues: repeat each T) where repeat each T: Codable & Sendable { |
| 116 | + self.init() |
| 117 | + repeat self.append(ExitTest.CapturedValue(wrappedValue: each wrappedValues)) |
| 118 | + } |
| 119 | + |
| 120 | + init<each T>(_ typesOfWrappedValues: repeat (each T).Type) where repeat each T: Codable & Sendable { |
| 121 | + self.init() |
| 122 | + repeat self.append(ExitTest.CapturedValue(typeOnly: (each typesOfWrappedValues).self)) |
| 123 | + } |
| 124 | +} |
| 125 | + |
| 126 | +extension Collection where Element == ExitTest.CapturedValue { |
| 127 | + /// Cast the elements in this collection to a tuple of their wrapped values. |
| 128 | + /// |
| 129 | + /// - Returns: A tuple containing the wrapped values of the elements in this |
| 130 | + /// collection. |
| 131 | + /// |
| 132 | + /// - Throws: If an expected value could not be found or was not of the |
| 133 | + /// type the caller expected. |
| 134 | + /// |
| 135 | + /// This function assumes that the entry point function has already set the |
| 136 | + /// ``wrappedValue`` property of each element in this collection. |
| 137 | + func takeCapturedValues<each T>() throws -> (repeat each T) { |
| 138 | + func nextValue<U>( |
| 139 | + as type: U.Type, |
| 140 | + from capturedValues: inout SubSequence |
| 141 | + ) throws -> U { |
| 142 | + // Get the next captured value in the collection. If we run out of values |
| 143 | + // before running out of parameter pack elements, then something in the |
| 144 | + // exit test handler or entry point is likely broken. |
| 145 | + guard let wrappedValue = capturedValues.first?.wrappedValue else { |
| 146 | + let actualCount = self.count |
| 147 | + let expectedCount = parameterPackCount(repeat (each T).self) |
| 148 | + fatalError("Found fewer captured values (\(actualCount)) than expected (\(expectedCount)) when passing them to the current exit test.") |
| 149 | + } |
| 150 | + |
| 151 | + // Next loop, get the next element. (We're mutating a subsequence, not |
| 152 | + // self, so this is generally an O(1) operation.) |
| 153 | + capturedValues = capturedValues.dropFirst() |
| 154 | + |
| 155 | + // Make sure the value is of the correct type. If it's not, that's also |
| 156 | + // probably a problem with the exit test handler or entry point. |
| 157 | + guard let wrappedValue = wrappedValue as? U else { |
| 158 | + fatalError("Expected captured value at index \(capturedValues.startIndex) with type '\(String(describingForTest: U.self))', but found an instance of '\(String(describingForTest: Swift.type(of: wrappedValue)))' instead.") |
| 159 | + } |
| 160 | + |
| 161 | + return wrappedValue |
| 162 | + } |
| 163 | + |
| 164 | + var capturedValues = self[...] |
| 165 | + return (repeat try nextValue(as: (each T).self, from: &capturedValues)) |
| 166 | + } |
| 167 | +} |
| 168 | +#endif |
0 commit comments