Create and run unit tests, performance tests, and UI tests for your Xcode project.


The XCTest framework enables you to write unit tests for your Xcode projects that integrate seamlessly with the Xcode testing workflow, as described in Testing with Xcode.

Tests assert that certain conditions are satisfied during test execution, and record test failures (with optional messages) if those conditions are not satisfied. Tests can also measure the performance of blocks of code to check for performance regressions, and can interact with an application's UI to validate user interaction flows.

To add tests to your project, create a new subclass of XCTestCase, and add one or more test methods to the test case, as shown in Listing 1. Test methods are instance methods that take no parameters, do not return a value, and have a name that begins with "test". Each test method you add becomes an individual test in your Xcode project.

Listing 1

Creating a test case

class TableValidationTests: XCTestCase {
    /// Tests that a new table instance has zero rows and columns.
    func testEmptyTableRowAndColumnCount() {
        let table = Table()
        XCTAssertEqual(table.rowCount, 0, "Row count was not zero.")
        XCTAssertEqual(table.columnCount, 0, "Column count was not zero.")

This example defines an XCTestCase subclass, TableValidationTests, with a single test method, testEmptyTableRowAndColumnCount. This test method creates a new instance of a class called Table, and checks that its rowCount and columnCount properties are both equal to 0.

Asserting Test Conditions

You can check (or assert) conditions inside test methods to make sure that your code is behaving as expected. Use the XCTAssert family of functions to check for boolean conditions, nil or non-nil values, expected values, and thrown errors.

For example, Listing 1 above uses the XCTAssertEqual(_:_:_:file:line:) function to assert that two integers have the same value.


Defining Test Cases


A subclass of XCTest that provides an override point for defining custom tests.


An abstract base class for testing.

Asynchronous Test Expectations


An expected outcome in an asynchronous test.

Asserting Failure

func XCTFail(String, file: StaticString, line: UInt)

Generates a failure immediately and unconditionally.

Testing User Interface Elements


A user interface element in an application.


The different types of UI element that can be located.


Describes the attributes exposed by UI elements.


A query for locating UI elements.


A protocol adopted by classes that provide ready-made queries for descendant elements of specific types.


A proxy for an application that can be launched and terminated.


A location on screen relative to some UI element.


Simulates events involving physical buttons and device state for an iOS device.


A physical button on an iOS device.


Simulates interaction with a physical remote control.


A button on a physical remote control.


Describes the available user interface size classes.


Flags for keyboard modifiers such as shift, control, option, and command.

XCUIKeyboardKey Constants

Constants for use with typeKey(_:modifierFlags:) to represent keys that have no textual equivalent.

Collecting Information About Test Runs


A base class for collecting information about a specific execution of an XCTest.


Collects information about a specific execution of an XCTestCase.


Collects information about a specific execution of an XCTestSuite.

Observing Test Progress


The XCTestObservation protocol defines methods that are called in response to significant events in the progress of test runs.


Provides information about the progress of test runs to registered observers.

Defining Custom Test Suites


A collection (or suite) of test cases.

See Also

Related Documentation