maniramezan/swifttestcommons
Shared test helpers for Swift packages and tools.
Installation
Add the package, then depend on the products each target needs:
dependencies: [
.package(url: "https://github.com/maniramezan/SwiftTestCommons", .upToNextMinor(from: "0.3.0")),
],
targets: [
.testTarget(
name: "AppTests",
dependencies: [.product(name: "TestCommons", package: "SwiftTestCommons")]
),
.testTarget(
name: "AppUITests",
dependencies: [.product(name: "TestCommonsXCUI", package: "SwiftTestCommons")]
),
]Use the latest release. Before 1.0, a minor release can contain breaking changes, so pin with .upToNextMinor(from:) rather than from:. Tags are bare SemVer (0.3.0), never v0.3.0.
Reading order and frame geometry
ReadingOrder is pure frame geometry, so one implementation backs XCUITest, hosted-view tests, and device drivers:
ReadingOrder.follows(second, first, in: .rightToLeft)Rows are compared by vertical center, with an exclusive tolerance (default: one point). Empty or nonfinite frames and nonpositive or nonfinite tolerances never match. Horizontal order compares centers; it does not require frames to be disjoint. firstAdjacentPair(in:successor:rowTolerance:) checks keys in ascending order, skipping missing successors, row breaks, invalid frames, and successors that do not advance the key.
In a UI test, pass rowTolerance: to use the same tolerance as the geometry helper:
XCTAssertReadingOrder(first: dayOne.frame, second: dayTwo.frame, direction: .rightToLeft, "Persian")FrameGeometry checks containment, overlap, horizontal gaps, and horizontal alignment using valid frames in one coordinate space. ReadingOrder uses the same validity checks.
Dependency spies
CallRecorder<Value: Sendable> records arguments to asynchronous dependencies:
let recorder = CallRecorder<String>()
await recorder.record("request")
let arguments = await recorder.values()
let lastArgument = await recorder.lastValue()Await the operation under test before reading the recorder. Calls from concurrent tasks are ordered by arrival at the actor.
TestValueBox<Value: Sendable> supports synchronous callbacks with get(), set(:), and atomic withValue(:) updates:
let calls = TestValueBox(0)
let callback: @Sendable () -> Void = {
calls.withValue { $0 += 1 }
}
callback()The mutation closure must not call back into the same box. A thrown error releases the lock; mutations made before the error remain. TestError() supplies a payload-free, equatable error for failure-path tests.
Test doubles
ScriptedResponder<Request, Response> records requests and answers call n with scripted outcome n. hold(call:) suspends one call so in-flight state can be asserted; running out of outcomes throws ScriptedResponder.Exhausted, never a scripted error.
let responder = ScriptedResponder<String, Int>([.failure(TestError()), .success(42)])
let fetch: @Sendable (String) async throws -> Int = { try await responder.respond(to: $0) }StubbedURLSession answers one session's requests in process, from a handler or a list of StubResponses, and records them with bodies. Sessions are isolated, so parallel tests can stub independently, on Apple platforms and Linux. Keep the stub alive while its session is in use, and invalidate it when the test finishes:
let stub = try StubbedURLSession(responses: [.json(#"{"id":1}"#), .text("busy", statusCode: 503)])
defer { stub.invalidate() }
let client = APIClient(session: stub.session)ManualClock is a Clock whose sleeps resume only when a test calls advance(by:) or advance(to:). Wait with waitForSleepers(_:) before advancing.
ScriptedValues supplies deterministic sequences of dates, UUIDs, or any other sendable fixtures, with fail, repeat-last, and fallback exhaustion policies. Running out throws ScriptedValues.Exhausted, never TestError. Own mutable scripts in an actor or a TestValueBox when sharing them.
Async coordination
AsyncGate is a cancellation-aware one-shot signal with multiple waiters. Use waiterCount to establish that work has suspended before opening it.
waitUntil uses a monotonic deadline and throws ObservationTimeout carrying the last observation. Observation closures must return promptly and cooperate with cancellation.
let count = try await waitUntil(timeout: .seconds(2)) { await model.count } matching: { $0 >= 3 }observeStream consumes any sendable AsyncSequence, with both a time budget and an event budget. It returns collected events with a matched, finished, limit-reached, or timed-out outcome. Source errors and caller cancellation propagate. A count limit alone cannot prevent a stalled stream from hanging.
Isolated storage and fixtures
Each temporary resource has a unique name so parallel tests cannot share state:
let directory = try TemporaryDirectory(prefix: "ImportTests")
defer { try? directory.remove() }
let file = try directory.write(Data("{}".utf8), named: "fixtures/empty.json")
let preferences = try TemporaryUserDefaults()
defer { preferences.remove() }
preferences.defaults.set(true, forKey: "enabled")Cleanup is explicit and repeatable. The preferences helper clears its own suite only; pass preferences.defaults to the code under test. preferences.suiteName lets another instance reopen the same suite for persistence tests.
FixtureDirectory reads UTF-8 text or data from an explicit root or owning bundle. Relative paths escaping their resource root are rejected. jsonRoundTrip accepts caller-owned coders, and fixtureEnvironment builds independent dictionaries without mutating process-global environment variables.
Snapshot references
SnapshotReferenceDirectory finds an existing Snapshots/<test filename>/ directory beside the source file, then in explicitly supplied resource directories. This supports test runners whose compiled source paths no longer exist:
let references = SnapshotReferenceDirectory.resolve(
for: #filePath,
resourceDirectories: [testBundle.resourceURL].compactMap { $0 }
)Pass references?.path to your snapshot library's directory argument. A missing directory returns nil, so the snapshot library can apply its default recording location. Supply the owning test bundle instead of scanning all bundles to avoid filename collisions. Resource directories are searched in the supplied order; directoryName: customizes Snapshots. This helper does not depend on a snapshot library or choose recording/toolchain policy.
Rendering SwiftUI views
TestCommonsUI.ViewRendering.pngData(rendering:size:scale:) renders SwiftUI content offscreen, with no window or host application, at a fixed scale (default 1) so bytes match across devices:
let png = ViewRendering.pngData(rendering: Text("Ready"), size: CGSize(width: 200, height: 100))HostedView owns a real platform window for platform-backed controls and lazy containers. It renders PNG bytes, waits for stable frames, and compares against a caller-supplied blank reference:
let hosted = HostedView(Text("Ready"), size: CGSize(width: 200, height: 100), scale: 2)
defer { hosted.close() }
_ = hosted.waitForStableRender(timeout: .seconds(2))
let png = hosted.renderPNG()On iOS, hosted rendering needs a test target with a host app; in hostless package tests it returns nil instead of blank bytes. Stable pixels do not establish content arrival. Serialize suites that pump the main run loop.
UI tests
TestCommonsXCUI waits for existence, enabled state, hittability, absence, labels, and values. Call them from the main actor and pass your test's timeout:
TestCommonsXCUI.waitForEnabled(submitButton, timeout: 5)
TestCommonsXCUI.waitForValue("ready", on: statusElement, timeout: 5, named: "Status")Each reports an XCTest failure at the caller with the element's debug description and returns a discardable success flag. State waits require the element to exist as well as match the requested state, within one timeout budget. Label waits observe labels; value waits observe values. Qualify the helper with TestCommonsXCUI when a test target still has a local helper with the same name.
container.scrollUpUntilHittable(child, maxAttempts:) and scrollDownUntilHittable perform bounded swipes and return whether the child exists and is hittable. They check after the final swipe and make no swipes for nonpositive budgets. Assert the returned flag when revealing the child is required for the next interaction.
attachDiagnostics captures a screenshot and accessibility hierarchy with caller-chosen attachment lifetime. configureLocale replaces prior Apple language/locale arguments while preserving app flags. uniqueHittableElement reports ambiguous visible queries. replaceText supports plain fields exposing their actual string contents, an explicit trailing caret coordinate, and final value verification. Secure or placeholder-only fields need a caller-owned interaction strategy.
Documentation
Each product has a DocC catalog with API references and usage guides:
- TestCommons: geometry, dependency spies,
test doubles, async observation, isolated storage, and snapshot reference resolution.
- TestCommonsUI: hosted rendering and
frame observation.
- TestCommonsXCUI: element waits,
bounded scrolling, layout assertions, and adapters that preserve failure locations.
With Xcode selected and its iOS Simulator SDK installed, build and validate all archives:
python3 Scripts/build-documentation.pyThe check treats DocC warnings as errors, requires documentation and Topics curation for every declared public API, checks parameter and return coverage, and type-checks each Swift guide example. Compiler-synthesized and inherited members are excluded from the declared-API coverage count. CI runs the same check.
Open a generated archive in Xcode:
open .build/documentation/Build/Products/Debug-iphonesimulator/TestCommons.doccarchive
open .build/documentation/Build/Products/Debug-iphonesimulator/TestCommonsUI.doccarchive
open .build/documentation/Build/Products/Debug-iphonesimulator/TestCommonsXCUI.doccarchive.spi.yml configures hosted documentation on the Swift Package Index.
Contributing
Work on a feature branch and merge through a pull request; run git config --local core.hooksPath .githooks once per checkout to block direct pushes to main. Run these before opening a pull request (CI runs the same checks):
swift build
swift test --enable-code-coverage
python3 Scripts/check-coverage.py --diff-base origin/main
swift format lint --strict --recursive Package.swift Sources Tests
python3 Scripts/build-documentation.py- Each product keeps a line-coverage floor (
TARGET_THRESHOLDSin the script). Floors only go up. - At least 90% of executable lines changed since the merge base must be covered. In GitHub
Actions, each uncovered changed line is annotated on the pull request.
TestCommonsXCUIis exempt from the changed-line check because itsXCUIElementwaits need a
UI-test host. Keep its floor rising by moving pure logic into internal functions with unit tests.
Conventional Commits drive automated tagging and GitHub Releases (see .github/workflows/release.yml). There is no CHANGELOG.md; release notes live on the GitHub Release. See AGENTS.md for code conventions.
License
MIT.
Package Metadata
Repository: maniramezan/swifttestcommons
Default branch: main
README: README.md