Actionable UI Test Assertions

When writing your XCUITest UI test, it is important to provide enough data when an assertion fails so that someone looking at a test run report can most easily see what failed and begin to figure out the “why”. The context for this post is for tests run either within Xcode or through Xcode’s Bots tool. That way, you have the graphical report to examine.


The most basic thing I look for is that the assertion message is included with an assertion statement.

You could syntactically be okay with something like this :

XCTAssertTrue( loginButton.exists )

However, that assertion will only show up as a failure in a report with no context other than a line number. An improved message looks like this :

XCTAssertTrue( loginButton.exists, "The login button does not exist" )


A useful piece of data to have is to show the tree of elements present when a failure occurs. You can easily log this information as in :

print ( XCUIApplication().debugDescription )

When a test report is created in Xcode, you can attach things like screenshots, text documents and other things to the report. I use it for including a debug description of the last screen used when an assertion fails. This can help with analysis of the test failure. This is in addition to the screen shots included with the Bot report by default.

An example block of code to include in your tearDown() method for a test case :

XCTContext.runActivity(named: "Create Debug Description") { _ in
    let elementsTree = app.debugDescription
    let attachment = XCTAttachment(string: elementsTree) = "Final Screen Debug Description"

Example showing what a Bot report looks like when the UI Test cannot find an element.

Here is the Final Screen Debug Description element tree attachment looks like from above example.

While you can have a suite of UI Tests that take detailed actions and numerous assertions, they are most effective when someone can interpret the results and get a head start on understanding the root cause of a test failure.

When working with a team, it is best to get the test results recorded plus notifying team members about the failure so that it can be acted on right away.