<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "XCTest",
  "identifier" : "/documentation/XCTest/XCTestCase",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "XCTest"
    ],
    "preciseIdentifier" : "c:objc(cs)XCTestCase"
  },
  "title" : "XCTestCase"
}
-->

# XCTestCase

The primary class for defining test cases, test methods, and performance tests.

```
class XCTestCase
```

## Overview

A test case is a group of related test methods, with optional setup and teardown before and after tests run. See [Defining Test Cases and Test Methods](/documentation/XCTest/defining-test-cases-and-test-methods) for more information.

`XCTestCase` conforms to [`XCTActivity`](/documentation/XCTest/XCTActivity), so you can simplify complex tests by organizing them into activities, and attach output to tests for later analysis. For more information, see [Activities and Attachments](/documentation/XCTest/activities-and-attachments).

Create tests for asynchronous operations using expectations. For more information, see `Testing Asynchronous Operations with Expectations`. If your app uses Swift <doc://com.apple.documentation/documentation/Swift/concurrency>, annotate test methods with `async` or `async throws` instead to test asynchronous operations, and use standard Swift concurrency patterns in your tests.

Create tests to measure performance for specific blocks of code using the methods in the Measuring Performance section below. Build performance tests as part of a continuous improvement cycle for performance in your app. For more information, see <doc://com.apple.documentation/documentation/Xcode/improving-your-app-s-performance>.

## Topics

### Customizing Test Setup and Teardown

[Set Up and Tear Down State in Your Tests](/documentation/XCTest/set-up-and-tear-down-state-in-your-tests)

Prepare initial state before tests run, and clean up resources after tests complete.

[`setUp()`](/documentation/XCTest/XCTestCase/setUp())

Provides an opportunity to customize initial state before a test case begins.

[`addTeardownBlock(_:)`](/documentation/XCTest/XCTestCase/addTeardownBlock(_:)-2guon)

Registers a block of teardown code to run after the current test method ends.

[`addTeardownBlock(_:)`](/documentation/XCTest/XCTestCase/addTeardownBlock(_:)-5zw6c)

Registers a block of teardown code to run after the current test method ends.

[`addAsyncTeardownBlock:`](/documentation/XCTest/XCTestCase/addAsyncTeardownBlock:)

Registers a block of asynchronous teardown code to run after the current test method ends.

[`addTeardownBlock:`](/documentation/XCTest/XCTestCase/addTeardownBlock:)

Registers a block of teardown code to run after the current test method ends.

[`tearDown()`](/documentation/XCTest/XCTestCase/tearDown())

Provides an opportunity to perform cleanup after a test case ends.

### Managing Test Case Execution

[`runsForEachTargetApplicationUIConfiguration`](/documentation/XCTest/XCTestCase/runsForEachTargetApplicationUIConfiguration)

A Boolean value that indicates whether your UI tests run once for each possible combination of orientation, localization, and other appearance settings your app supports.

[`continueAfterFailure`](/documentation/XCTest/XCTestCase/continueAfterFailure)

A Boolean value that indicates whether a test method should continue running after a failure occurs.

[`executionTimeAllowance`](/documentation/XCTest/XCTestCase/executionTimeAllowance)

The number of seconds, rounded up to the nearest minute, for a test to run before it fails with a timeout error.

### Measuring Performance

[`measure(_:)`](/documentation/XCTest/XCTestCase/measure(_:))

Measures the performance of a block of code.

[`measureMetrics(_:automaticallyStartMeasuring:for:)`](/documentation/XCTest/XCTestCase/measureMetrics(_:automaticallyStartMeasuring:for:))

Measures the performance of a block of code, optionally deferring the starting point for measurement.

[`measure(metrics:block:)`](/documentation/XCTest/XCTestCase/measure(metrics:block:))

Records the selected metrics for a block of code.

[`measure(metrics:options:block:)`](/documentation/XCTest/XCTestCase/measure(metrics:options:block:))

Records the selected metrics, using the specified measurement options, for a block of code.

[`measure(options:block:)`](/documentation/XCTest/XCTestCase/measure(options:block:))

Records the performance, using the specified measurement options, for a block of code.

[`startMeasuring()`](/documentation/XCTest/XCTestCase/startMeasuring())

Starts recording performance metrics within a block of code.

[`stopMeasuring()`](/documentation/XCTest/XCTestCase/stopMeasuring())

Ends recording performance metrics within a block of code.

[`defaultPerformanceMetrics`](/documentation/XCTest/XCTestCase/defaultPerformanceMetrics)

An array of default performance metrics the test records.

[`defaultMetrics`](/documentation/XCTest/XCTestCase/defaultMetrics)

An array of default metrics the test uses to record performance.

[`defaultMeasureOptions`](/documentation/XCTest/XCTestCase/defaultMeasureOptions)

The default measurement options the test uses to record performance.

[`XCTPerformanceMetric`](/documentation/XCTest/XCTPerformanceMetric)

Performance metrics that the test records.

### Creating Asynchronous Test Expectations

To create asynchronous test expectations, use the convenience methods below, or create instances of the test expectation class and its subclasses manually.

[`expectation(description:)`](/documentation/XCTest/XCTestCase/expectation(description:))

Creates a new expectation with an associated description.

[`expectation(for:evaluatedWith:handler:)`](/documentation/XCTest/XCTestCase/expectation(for:evaluatedWith:handler:))

Creates an expectation that the test fulfills by evaluating the predicate with the specified object.

[`expectation(forNotification:object:handler:)`](/documentation/XCTest/XCTestCase/expectation(forNotification:object:handler:))

Creates an expectation that the test fulfills when it receives a specific notification for a specified object.

[`expectation(forNotification:object:notificationCenter:handler:)`](/documentation/XCTest/XCTestCase/expectation(forNotification:object:notificationCenter:handler:))

Creates an expectation that the test fulfills when it receives a specific notification from a specific notification center for a specified object.

[`keyValueObservingExpectation(for:keyPath:expectedValue:)`](/documentation/XCTest/XCTestCase/keyValueObservingExpectation(for:keyPath:expectedValue:))

Creates an expectation that uses Key-Value Observing to observe a value until it matches an expected value.

[`expectation(that:on:options:willEqual:)`](/documentation/XCTest/XCTestCase/expectation(that:on:options:willEqual:))

Creates an expectation using key-value observing the test fulfills when the value of an observed property changes to an expected value.

[`keyValueObservingExpectation(for:keyPath:handler:)`](/documentation/XCTest/XCTestCase/keyValueObservingExpectation(for:keyPath:handler:))

Creates an expectation that uses Key-Value Observing to observe a value and respond to changes in that value by calling a provided handler.

[`expectation(that:on:options:willSatisfy:)`](/documentation/XCTest/XCTestCase/expectation(that:on:options:willSatisfy:)-6itb)

Creates an expectation using key-value observing the test fulfills when the value of an observed property changes and satisfies the conditions of a predicate’s evaluation.

[`expectation(that:on:options:willSatisfy:)`](/documentation/XCTest/XCTestCase/expectation(that:on:options:willSatisfy:)-292oj)

Creates an expectation using key-value observing to monitor changes to a given key path on a given object.

[`expectation(that:on:options:willSatisfy:)`](/documentation/XCTest/XCTestCase/expectation(that:on:options:willSatisfy:)-85or0)

Creates an expectation using key-value observing to monitor changes to a given key path on a given object.

### Waiting for Expectations

To wait for the test to fulfill asynchronous test expectations, create a waiter object directly or by using the convenience methods.

[`fulfillment(of:timeout:enforceOrder:)`](/documentation/XCTest/XCTestCase/fulfillment(of:timeout:enforceOrder:))

Waits on a group of expectations for up to the specified timeout, optionally enforcing their order of fulfillment.

[`wait(for:)`](/documentation/XCTest/XCTestCase/wait(for:))

Waits on a group of expectations.

[`wait(for:enforceOrder:)`](/documentation/XCTest/XCTestCase/wait(for:enforceOrder:))

Waits on a group of expectations optionally enforcing their order of fulfillment.

[`wait(for:timeout:)`](/documentation/XCTest/XCTestCase/wait(for:timeout:))

Waits for the test to fulfill a set of expectations within a specified time.

[`wait(for:timeout:enforceOrder:)`](/documentation/XCTest/XCTestCase/wait(for:timeout:enforceOrder:))

Waits for the test to satisfy an array of expectations and specifies whether they must occur in the array’s order.

[`waitForExpectations(timeout:handler:)`](/documentation/XCTest/XCTestCase/waitForExpectations(timeout:handler:))

Waits until the test fulfills all expectations or until it times out.

[`XCWaitCompletionHandler`](/documentation/XCTest/XCWaitCompletionHandler)

A block the test runner calls when the test fulfills a waiter’s expectations, or when it times out.

[`XCTestError`](/documentation/XCTest/XCTestError)

A type of error that can occur while the test waits to fulfill expectations.

[`XCTestError.Code`](/documentation/XCTest/XCTestError/Code)

Error codes for errors that can occur while the test is waiting to fulfill expectations.

[`XCTestErrorDomain`](/documentation/XCTest/XCTestErrorDomain)

The error domain for errors that can occur while the test is waiting to fulfill expectations.

### Monitoring UI Interruptions

[Handling UI Interruptions](/documentation/XCTest/handling-ui-interruptions)

Improve your UI test’s stability by handling interface changes that block the UI elements under test.

[`addUIInterruptionMonitor(withDescription:handler:)`](/documentation/XCTest/XCTestCase/addUIInterruptionMonitor(withDescription:handler:))

Adds a handler to the current context.

[`removeUIInterruptionMonitor(_:)`](/documentation/XCTest/XCTestCase/removeUIInterruptionMonitor(_:))

Removes a handler using the token from when you added the handler.

### Creating Tests Programmatically

The test runner automatically detects methods you define in your test case subclasses. Use the symbols below if you need more customization for test case creation, such as to define test cases dynamically at run time.

[`init(invocation:)`](/documentation/XCTest/XCTestCase/init(invocation:))

Initializes a test case with an invocation.

[`testCaseWithInvocation:`](/documentation/XCTest/XCTestCase/testCaseWithInvocation:)

Creates a test case with an invocation.

[`init(selector:)`](/documentation/XCTest/XCTestCase/init(selector:))

Initializes a test case with a selector.

[`testCaseWithSelector:`](/documentation/XCTest/XCTestCase/testCaseWithSelector:)

Creates a test case with a selector.

[`testInvocations`](/documentation/XCTest/XCTestCase/testInvocations)

An array of invocations that represents each test method in the test case.

[`invocation`](/documentation/XCTest/XCTestCase/invocation)

The invocation for running the test.

[`invokeTest()`](/documentation/XCTest/XCTestCase/invokeTest())

Invokes the test.

[`record(_:)`](/documentation/XCTest/XCTestCase/record(_:))

Records an issue during test execution.

[`recordFailure(withDescription:inFile:atLine:expected:)`](/documentation/XCTest/XCTestCase/recordFailure(withDescription:inFile:atLine:expected:))

Records a failure during text execution.

[`defaultTestSuite`](/documentation/XCTest/XCTestCase/defaultTestSuite)

A test suite that contains test cases for all of the tests in the class.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)