| // This source file is part of the Swift.org open source project |
| // |
| // Copyright (c) 2016 Apple Inc. and the Swift project authors |
| // Licensed under Apache License v2.0 with Runtime Library Exception |
| // |
| // See http://swift.org/LICENSE.txt for license information |
| // See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors |
| // |
| // |
| // XCTestCase+Asynchronous.swift |
| // Methods on XCTestCase for testing asynchronous operations |
| // |
| |
| public extension XCTestCase { |
| |
| /// Creates and returns an expectation associated with the test case. |
| /// |
| /// - Parameter description: This string will be displayed in the test log |
| /// to help diagnose failures. |
| /// - Parameter file: The file name to use in the error message if |
| /// this expectation is not waited for. Default is the file |
| /// containing the call to this method. It is rare to provide this |
| /// parameter when calling this method. |
| /// - Parameter line: The line number to use in the error message if the |
| /// this expectation is not waited for. Default is the line |
| /// number of the call to this method in the calling file. It is rare to |
| /// provide this parameter when calling this method. |
| /// |
| /// - Note: Whereas Objective-C XCTest determines the file and line |
| /// number of expectations that are created by using symbolication, this |
| /// implementation opts to take `file` and `line` as parameters instead. |
| /// As a result, the interface to these methods are not exactly identical |
| /// between these environments. To ensure compatibility of tests between |
| /// swift-corelibs-xctest and Apple XCTest, it is not recommended to pass |
| /// explicit values for `file` and `line`. |
| @discardableResult func expectation(description: String, file: StaticString = #file, line: Int = #line) -> XCTestExpectation { |
| let expectation = XCTestExpectation( |
| description: description, |
| file: file, |
| line: line, |
| testCase: self) |
| _allExpectations.append(expectation) |
| return expectation |
| } |
| |
| /// Creates a point of synchronization in the flow of a test. Only one |
| /// "wait" can be active at any given time, but multiple discrete sequences |
| /// of { expectations -> wait } can be chained together. |
| /// |
| /// - Parameter timeout: The amount of time within which all expectation |
| /// must be fulfilled. |
| /// - Parameter file: The file name to use in the error message if |
| /// expectations are not met before the given timeout. Default is the file |
| /// containing the call to this method. It is rare to provide this |
| /// parameter when calling this method. |
| /// - Parameter line: The line number to use in the error message if the |
| /// expectations are not met before the given timeout. Default is the line |
| /// number of the call to this method in the calling file. It is rare to |
| /// provide this parameter when calling this method. |
| /// - Parameter handler: If provided, the handler will be invoked both on |
| /// timeout or fulfillment of all expectations. Timeout is always treated |
| /// as a test failure. |
| /// |
| /// - Note: Whereas Objective-C XCTest determines the file and line |
| /// number of the "wait" call using symbolication, this implementation |
| /// opts to take `file` and `line` as parameters instead. As a result, |
| /// the interface to these methods are not exactly identical between |
| /// these environments. To ensure compatibility of tests between |
| /// swift-corelibs-xctest and Apple XCTest, it is not recommended to pass |
| /// explicit values for `file` and `line`. |
| func waitForExpectations(timeout: TimeInterval, file: StaticString = #file, line: Int = #line, handler: XCWaitCompletionHandler? = nil) { |
| // Mirror Objective-C XCTest behavior; display an unexpected test |
| // failure when users wait without having first set expectations. |
| // FIXME: Objective-C XCTest raises an exception for most "API |
| // violation" failures, including this one. Normally this causes |
| // the test to stop cold. swift-corelibs-xctest does not stop, |
| // and executes the rest of the test. This discrepancy should be |
| // fixed. |
| if _allExpectations.count == 0 { |
| recordFailure( |
| withDescription: "API violation - call made to wait without any expectations having been set.", |
| inFile: String(describing: file), |
| atLine: line, |
| expected: false) |
| return |
| } |
| |
| // Objective-C XCTest outputs the descriptions of every unfulfilled |
| // expectation. We gather them into this array, which is also used |
| // to determine failure--a non-empty array meets expectations weren't |
| // met. |
| var unfulfilledDescriptions = [String]() |
| |
| // We continue checking whether expectations have been fulfilled until |
| // the specified timeout has been reached. |
| // FIXME: Instead of polling the expectations to check whether they've |
| // been fulfilled, it would be more efficient to use a runloop |
| // source that can be signaled to wake up when an expectation is |
| // fulfilled. |
| let runLoop = RunLoop.current |
| let timeoutDate = Date(timeIntervalSinceNow: timeout) |
| repeat { |
| unfulfilledDescriptions = [] |
| for expectation in _allExpectations { |
| if !expectation.isFulfilled { |
| unfulfilledDescriptions.append(expectation.description) |
| } |
| } |
| |
| // If we've met all expectations, then break out of the specified |
| // timeout loop early. |
| if unfulfilledDescriptions.count == 0 { |
| break |
| } |
| |
| // Otherwise, wait another fraction of a second. |
| runLoop.run(until: Date(timeIntervalSinceNow: 0.01)) |
| } while Date().compare(timeoutDate) == ComparisonResult.orderedAscending |
| |
| if unfulfilledDescriptions.count > 0 { |
| // Not all expectations were fulfilled. Append a failure |
| // to the array of expectation-based failures. |
| let descriptions = unfulfilledDescriptions.joined(separator: ", ") |
| recordFailure( |
| withDescription: "Asynchronous wait failed - Exceeded timeout of \(timeout) seconds, with unfulfilled expectations: \(descriptions)", |
| inFile: String(describing: file), |
| atLine: line, |
| expected: true) |
| } |
| |
| // We've recorded all the failures; clear the expectations that |
| // were set for this test case. |
| _allExpectations = [] |
| |
| // The handler is invoked regardless of whether the test passed. |
| if let completionHandler = handler { |
| var error: NSError? = nil |
| if unfulfilledDescriptions.count > 0 { |
| // If the test failed, send an error object. |
| error = NSError( |
| domain: XCTestErrorDomain, |
| code: XCTestError.Code.timeoutWhileWaiting.rawValue, |
| userInfo: [:]) |
| } |
| completionHandler(error) |
| } |
| } |
| } |
| |
| internal extension XCTestCase { |
| /// It is an API violation to create expectations but not wait for them to |
| /// be completed. Notify the user of a mistake via a test failure. |
| func failIfExpectationsNotWaitedFor(_ expectations: [XCTestExpectation]) { |
| if expectations.count > 0 { |
| recordFailure( |
| withDescription: "Failed due to unwaited expectations.", |
| inFile: String(describing: expectations.last!.file), |
| atLine: expectations.last!.line, |
| expected: false) |
| } |
| } |
| } |
