Defining test functions

Define a test function to validate that code is working correctly.

Overview

Defining a test function for a Swift package or project is straightforward.

Import the testing library

To import the testing library, add the following to the Swift source file that contains the test:

import Testing

Declare a test function

To declare a test function, write a Swift function declaration that doesn’t take any arguments, then prefix its name with the @Test attribute:

@Test func foodTruckExists() {
  // Test logic goes here.
}

This test function can be present at file scope or within a type. A type containing test functions is automatically a test suite and can be optionally annotated with the @Suite attribute. For more information about suites, see Organizing test functions with suite types.

Note that, while this function is a valid test function, it doesn’t actually perform any action or test any code. To check for expected values and outcomes in test functions, add Expectations and confirmations to the test function.

Customize a test’s name

To customize a test function’s name as presented in an IDE or at the command line, supply a string literal as an argument to the @Test attribute:

@Test("Food truck exists") func foodTruckExists() { ... }

To further customize the appearance and behavior of a test function, use Traits such as tags(_:).

Write concurrent or throwing tests

As with other Swift functions, test functions can be marked async and throws to annotate them as concurrent or throwing, respectively. If a test is only safe to run in the main actor’s execution context (that is, from the main thread of the process), it can be annotated @MainActor:

@Test @MainActor func foodTruckExists() async throws { ... }

Limit the availability of a test

If a test function can only run on newer versions of an operating system or of the Swift language, use the @available attribute when declaring it. Use the message argument of the @available attribute to specify a message to log if a test is unable to run due to limited availability:

@available(macOS 11.0, *)
@available(swift, introduced: 8.0, message: "Requires Swift 8.0 features to run")
@Test func foodTruckExists() { ... }