Scan Part of a Screen

If you want to test a specific component or feature for accessibility, you can run a targeted scan for that element or view rather than scanning the entire screen.

Use the run(onElement: ) Method

A single element or view can be scanned using the run(onElement: ) method. This method accepts any XCUIElement as a parameter. It can accept anything from an XCUIApplication (the entire app) to a specific element such as a button, label, text field, or any other UI element.

To find a specific element, use XCTest queries. Find more information in Apple's documentation:

• XCUIElementTypeQueryProvider docs
• XCUIElementQuery docs

We recommend validating that the element you are scanning for exists and is on screen prior to running a scan, to ensure that the framework is able to find the element and return the correct results. If the element is not found on screen at the time of the scan, an incomplete result may be posted instead.

Example

Below is an example test that looks for a button with the title "Menu", checks for its existence on screen, and runs a scan on it. This is an example of a basic query, though more complex ones involving children and descendants are possible.

var axe: AxeDevTools?
var app = XCUIApplication()

override func setUpWithError() throws {
    // log in to AxeDevTools
    axe = try? AxeDevTools.login(withAPIKey: "")

    // launch app and prevent tests from continuing if element is not found
    app.launch()
    continueAfterFailure = true
}

func testAccessibility() throws {
    // finds a button with the title or accessibilityIdentifier "Menu"
    // .firstMatch ensures that the test doesn't fail if multiple matching elements exist
    let buttonToTest = app.buttons["Menu"].firstMatch
    XCTAssert(buttonToTest.isHittable, "Button 'Menu' does not exist on the screen.")

    let result = try axe.run(onElement: buttonToTest)
    try axe.postResult(result)
}

Which Rules Can Run on Partial Screen Scans?

All rules will run on partial screen scans unless explicitly ignored by the user. However, the ScreenTitle and InScrollView rules may return NeedsReview if the partial screen scan does not include all the necessary information to pass or fail.