xctest-extensions

Useful XCTest utilities and extensions for test targets.

Overview

Currently, the library provides a small but useful set of XCTest related methods.

Wait for Expression

Two wait methods are implemented which may be useful in asynchronous testing scenarios where using XCTest expectations is not possible.

These methods allow for the continuous evaluation of an autoclosure expression with a timeout period in seconds. If the wait times out, it triggers a test fail. The evaluation is done every 10 milliseconds by default, but the interfal can be overridden with a custom polling period.

// wait for expression:
// useful for non-equatability tests or tests where the test value
// is not required to be logged in failure log messages
// (akin to XCTAssertTrue)
wait(for: x > 10, timeout: 1.5)
wait(for: x > 10, timeout: 1.5, "Description of waiter")

// closures can also be used for more complex expressions
wait(for: {
    let x = a + b
    let y = check ? 5 : 10
    return x == y
}, timeout: 1.5)

// wait for equality:
// useful where the test value is required to be logged in failure log messages
// (akin to XCTAssertEqual)
wait(for: x, equals: 10, timeout: 1.5)
wait(for: x, equals: 10, timeout: 1.5, "Description of waiter")

// closures can also be used for more complex expressions
wait(for: {
    let x = a + b
    return x > 10
}, equals: {
    #if os(macOS)
        10
    #else
        15
    #endif
}, timeout: 1.5)

General Wait

A generic non-blocking wait method is also provided:

wait(sec: 1.5) // seconds

UI Testing

A small assortment of throwing wrappers for XCUIElement methods are implemented.

waitForExistence(timeout:) -> Bool wrapped in a throwing method:

let okButton = try await app
    .buttons["OK"]
    .waitForExistence(throwingTimeout: 2.0)

await okButton.click()

waitForNonExistence(timeout:) -> Bool wrapped in a throwing method:

let okButton = await app.buttons["OK"].firstMatch
try await okButton.waitForNonExistence(throwingTimeout: 2.0)

wait(for:toEqual:timeout:) -> Bool wrapped in a throwing method:

let okButton = await app.staticTexts["Idle"].firstMatch
try await okButton.wait(for: \.label, toEqual: "Active", throwingTimeout: 2.0)

Installation

Swift Package Manager (SPM)

To add this package to an Xcode app project, use:

https://github.com/orchetect/xctest-extensions as the URL.

To add this package to a Swift package, add the dependency to your package and target in Package.swift:

let package = Package(
    dependencies: [
        .package(url: "https://github.com/orchetect/xctest-extensions", from: "2.0.0")
    ],
    targets: [
        .target(
            dependencies: [
                .product(name: "XCTestExtensions", package: "xctest-extensions")
            ]
        )
    ]
)

Usage

Import the module in test target files where needed.

import XCTest
import XCTestExtensions

Documentation

This README serves as basic documentation.

All methods have inline help explaining their purpose and basic usage examples.

Requirements

Minimum system requirements for testing: Xcode 15 or higher on macOS 11.3 or higher

Author

Coded by a bunch of 🐹 hamsters in a trenchcoat that calls itself @orchetect.

License

Licensed under the MIT license. See LICENSE for details.

Community & Support

Please do not email maintainers for technical support. Several options are available for issues and questions:

• Questions and feature ideas can be posted to Discussions.
• If an issue is a verifiable bug with reproducible steps it may be posted in Issues.

Contributions

Contributions are welcome. Posting in Discussions first prior to new submitting PRs for features or modifications is encouraged.

Legacy

This repository was formerly known as XCTestUtils.