DEV Community

Cover image for XCUITest Screenshots: Capturing, Attaching, and Managing iOS Test Evidence
QAPulse by SK
QAPulse by SK

Posted on Originally published at skakarh.com

XCUITest Screenshots: Capturing, Attaching, and Managing iOS Test Evidence

#iostestevidence #iosuitesting #mobileregressiontest #sdet

XCUITest screenshots provide visual evidence of an iOS application’s UI state during automated testing. They help SDETs diagnose failures, verify expected screens, document test execution, and preserve evidence inside Xcode test results. Apple’s UI automation APIs allow screenshots to be captured from the device screen, application, or individual UI elements and attached to tests or activities through XCTest. (Apple Developer)

Definition

XCUITest screenshots are captured visual representations of an iOS screen, application window, or UI element during XCUITest execution.

They can be used as:

  • Failure evidence
  • Debugging artifacts
  • Test execution evidence
  • Visual verification
  • Regression documentation
  • CI diagnostic artifacts

Apple provides XCUIScreenshot for captured UI state and XCTAttachment for storing screenshots and other test output with tests, activities, or issues. (Apple Developer)

Key Points

  • Capture screenshots at important test states.
  • Attach screenshots to XCTest results.
  • Keep failure evidence automatically.
  • Capture full-screen or element-level UI.
  • Give attachments meaningful names.
  • Use .keepAlways when evidence must survive successful tests.
  • Avoid unnecessary screenshots in every test step.
  • Combine screenshots with assertions and logs.
  • Use screenshots for CI failure diagnosis.
  • Protect sensitive information in captured evidence.

Why XCUITest Screenshots Matter

A failed assertion tells you what failed.

A screenshot can show what the application actually looked like when it failed.

Consider:

XCTAssertTrue(
    app.buttons["Checkout"].exists
)
Enter fullscreen mode Exit fullscreen mode

If the assertion fails, the test result may tell you that the element was not found.

A screenshot can reveal that the application instead displayed:

Loading...
Network Error
Login Required
Unexpected Alert
Empty State
Incorrect Screen
Enter fullscreen mode Exit fullscreen mode

This makes visual evidence particularly valuable for UI automation.

What Can XCUITest Capture?

XCUITest supports screenshots from several automation objects.

Apple documents XCUIScreenshotProviding as the protocol that provides the screenshot() operation, with XCUIScreen, XCUIApplication, and XCUIElement among the conforming types. (Apple Developer)

Device Screen 

let screenshot = XCUIScreen.main.screenshot()
Enter fullscreen mode Exit fullscreen mode

This captures the current main screen.

Apple also provides access to active screens through XCUIScreen.screens. (Apple Developer)

Application 

let screenshot = app.screenshot()
Enter fullscreen mode Exit fullscreen mode

This captures the application’s current visual state.

UI Element 

let screenshot = app.buttons["Checkout"].screenshot()
Enter fullscreen mode Exit fullscreen mode

This is useful when you want evidence for a specific component rather than the entire application.

Capturing a Basic Screenshot

A simple XCUITest can capture the application state like this:

import XCTest

final class ScreenshotTests: XCTestCase {

    func testCaptureApplicationScreenshot() {

        let app = XCUIApplication()
        app.launch()

        let screenshot = app.screenshot()

        let attachment = XCTAttachment(
            screenshot: screenshot
        )

        add(attachment)
    }
}
Enter fullscreen mode Exit fullscreen mode

XCTAttachment supports screenshot-based attachments, which can then appear in Xcode’s test results for later analysis. (Apple Developer)

Naming Screenshot Attachments

Unnamed evidence becomes difficult to understand in a large test suite.

Prefer descriptive names:

let attachment = XCTAttachment(
    screenshot: screenshot
)

attachment.name = "Checkout Screen"
add(attachment)
Enter fullscreen mode Exit fullscreen mode

For failure-oriented evidence:

attachment.name = "Login Failure State"
Enter fullscreen mode Exit fullscreen mode

Meaningful names help engineers quickly understand what the artifact represents.

Keeping Screenshot Attachments

XCTest attachments have a lifetime policy.

By default, attachments from successful tests can be discarded. Apple documents XCTAttachment.Lifetime.keepAlways when an attachment should remain available even after a successful test. (Apple Developer)

Use:

attachment.lifetime = .keepAlways
Enter fullscreen mode Exit fullscreen mode

Example:

let screenshot = app.screenshot()

let attachment = XCTAttachment(
    screenshot: screenshot
)

attachment.name = "Successful Login"
attachment.lifetime = .keepAlways

add(attachment)
Enter fullscreen mode Exit fullscreen mode

This is useful when screenshots are required as permanent test evidence.

Failure-Only Screenshot Capture

Capturing screenshots after every action can produce excessive test artifacts.

A better strategy is to capture screenshots at important checkpoints or when a test fails.

For example:

func attachScreenshot(
    named name: String,
    from app: XCUIApplication
) {

    let screenshot = app.screenshot()

    let attachment = XCTAttachment(
        screenshot: screenshot
    )

    attachment.name = name
    attachment.lifetime = .keepAlways

    add(attachment)
}
Enter fullscreen mode Exit fullscreen mode

Then:

attachScreenshot(
    named: "Before Checkout",
    from: app
)
Enter fullscreen mode Exit fullscreen mode

This keeps screenshot handling reusable.

Screenshot Checkpoints

👉 Continue reading the full article on skakarh.com →

Originally published at skakarh.com/xcuitest-screenshots.
Subscribe to QA Pulse by SK —
weekly signal for QA, Test Automation and AI in Software Engineering.

Top comments (0)