TeraAccessibilityAudit.swift (18159B)
1 import XCTest 2 3 @MainActor 4 final class TeraAccessibilityAudit { 5 private let test: XCTestCase 6 private var findings: [String] = [] 7 8 init(test: XCTestCase) { 9 self.test = test 10 } 11 12 static func assertNoFindings(_ findings: [String], file: StaticString = #filePath, line: UInt = #line) { 13 XCTAssertTrue(findings.isEmpty, "Unresolved accessibility findings:\n" + findings.joined(separator: "\n"), 14 file: file, line: line) 15 } 16 17 static func retainFinding(_ description: String, elementLabel: String?, in findings: inout [String]) -> Bool { 18 findings.append("\(description): \(elementLabel ?? "unidentified")") 19 // Continuing a native scan does not waive the mandatory caller assertion. 20 return true 21 } 22 23 static func contrastDisposition(label: String?, isEnabled: Bool, cameraIsDisabled: Bool, 24 isRequestedTarget: Bool, 25 isPartlyOccluded: Bool) -> TeraAccessibilityContrastDisposition 26 { 27 guard let label else { return .retain } 28 if label == "Camera", !isEnabled, cameraIsDisabled { 29 return .disabledCamera 30 } 31 return !isRequestedTarget && isPartlyOccluded ? .recheck : .retain 32 } 33 34 static func failContrastRechecks(file: StaticString = #filePath, line: UInt = #line) { 35 XCTFail("Not all partially obscured contrast findings passed an unobscured recheck", file: file, line: line) 36 } 37 38 func run(_ app: XCUIApplication, dynamicType: Bool = false, includeContrast: Bool = true) throws -> [String] { 39 // Native scans can move focus and scroll position. Audit clipping before 40 // those scans and retain every finding, including unidentified ones. 41 var types: XCUIAccessibilityAuditType = [.elementDetection, .hitRegion, 42 .sufficientElementDescription, .trait] 43 if dynamicType { 44 types.insert(.dynamicType) 45 } 46 let before = XCTAttachment(string: app.debugDescription) 47 before.name = "Accessibility tree before audit" 48 before.lifetime = .keepAlways 49 test.add(before) 50 let screenshot = XCTAttachment(screenshot: app.screenshot()) 51 screenshot.name = "Screen before audit" 52 screenshot.lifetime = .keepAlways 53 test.add(screenshot) 54 try scan(app, types: .textClipped) 55 if includeContrast { 56 try auditContrast(app) 57 } 58 try scan(app, types: types) 59 return findings 60 } 61 62 private func scan(_ app: XCUIApplication, types: XCUIAccessibilityAuditType) throws { 63 try app.performAccessibilityAudit(for: types) { issue in 64 let detail = XCTAttachment(string: "Audit type: \(issue.auditType.rawValue)\nAudit: \(issue.detailedDescription)\nElement: \(issue.element?.debugDescription ?? "unidentified")") 65 detail.lifetime = .keepAlways 66 self.test.add(detail) 67 let tree = XCTAttachment(string: app.debugDescription) 68 tree.name = "Audit finding accessibility tree" 69 tree.lifetime = .keepAlways 70 self.test.add(tree) 71 let screen = XCTAttachment(screenshot: app.screenshot()) 72 screen.name = "Audit finding screen" 73 screen.lifetime = .keepAlways 74 self.test.add(screen) 75 if let element = issue.element { 76 let fresh = TeraAuditTarget(element, app: app).resolve(in: app) 77 let geometry = XCTAttachment(string: "Current target: \(fresh.debugDescription)") 78 geometry.lifetime = .keepAlways 79 self.test.add(geometry) 80 } 81 return self.retainFinding(issue) 82 } 83 } 84 } 85 86 @MainActor 87 enum TeraAccessibilityNavigation { 88 static func qualifySupportSettings(_ app: XCUIApplication, test: XCTestCase) throws -> [String] { 89 var findings: [String] = [] 90 for identifier in ["tera.settings.diagnostics.contents", "tera.settings.diagnostics.exclusions", 91 "tera.settings.support.contact", "tera.settings.support.review", 92 "tera.settings.support.local_removal", "tera.settings.support.remote_copies"] 93 { 94 let target = app.descendants(matching: .any) 95 .matching(NSPredicate(format: "identifier == %@", identifier)).firstMatch 96 scroll(app, to: target, requiresHit: identifier == "tera.settings.support.contact", test: test) 97 XCTAssertTrue(target.exists) 98 if identifier == "tera.settings.support.contact" { 99 XCTAssertTrue(target.isHittable) 100 XCTAssertGreaterThanOrEqual(target.frame.height, 44) 101 } 102 findings += try TeraAccessibilityAudit(test: test).run(app) 103 } 104 return findings 105 } 106 107 static func viewport(_ app: XCUIApplication) -> (top: CGFloat, bottom: CGFloat) { 108 let navigation = app.navigationBars.firstMatch 109 let tabs = app.tabBars.firstMatch 110 // A presented account/import sheet covers the underlying tab bar. Its 111 // foreground content must use the sheet viewport, not the covered tabs. 112 let top = navigation.exists ? navigation.frame.maxY : 64 113 let bottom = tabs.exists && tabs.isHittable ? tabs.frame.minY : app.frame.maxY - 40 114 return (top, bottom) 115 } 116 117 static func scroll(_ app: XCUIApplication, to element: XCUIElement, up: Bool = true, 118 requiresHit: Bool = true, test: XCTestCase) 119 { 120 var forward = up 121 var previousViewport: [String] = [] 122 var stationaryDrags = 0 123 for _ in 0 ..< 28 { 124 let position = scrollPosition(app) 125 let frame = element.exists ? String(describing: element.frame) : "not instantiated" 126 XCTContext.runActivity(named: "Accessibility scroll: position \(position ?? "unknown"), target \(frame)") { _ in } 127 if isVisible(element, app: app, requiresHit: requiresHit) { 128 return 129 } 130 // Lazy forms revise their estimated content height while revealing rows. 131 // A repeated percentage is not an edge. Reverse only after actual 132 // visible content has stopped moving across two completed drags. 133 let viewport = visibleContent(app) 134 stationaryDrags = !viewport.isEmpty && viewport == previousViewport ? stationaryDrags + 1 : 0 135 if stationaryDrags == 2 { 136 forward.toggle() 137 stationaryDrags = 0 138 } 139 previousViewport = viewport 140 if element.exists, element.frame.width > 0, element.frame.height > 0 { 141 let (top, bottom) = TeraAccessibilityNavigation.viewport(app) 142 let frame = element.frame 143 let distance = bottom - top - 40 144 let delta = max(-distance, min(distance, frame.midY - (top + bottom) / 2)) 145 if abs(delta) > 8 { 146 drag(app, amount: -delta, top: top, bottom: bottom) 147 continue 148 } 149 } 150 // Audit scans can leave a lazy form on either side of the target. 151 // Reverse only when scrolling has stopped making progress, so a long 152 // maximum-text form can use the whole bound to reach the opposite end. 153 let (top, bottom) = TeraAccessibilityNavigation.viewport(app) 154 let delta = (bottom - top - 40) * (forward ? -0.7 : 0.7) 155 drag(app, amount: delta, top: top, bottom: bottom) 156 } 157 // The final drag can expose a lazy element. Check its settled frame before 158 // declaring the bounded search unsuccessful. 159 if isVisible(element, app: app, requiresHit: requiresHit) { 160 return 161 } 162 let screenshot = XCTAttachment(screenshot: app.screenshot()) 163 screenshot.lifetime = .keepAlways 164 test.add(screenshot) 165 let (top, bottom) = TeraAccessibilityNavigation.viewport(app) 166 let exists = element.exists 167 let frame = exists ? element.frame : .zero 168 let detail = exists ? element.debugDescription : "Target is not instantiated" 169 let geometry = String(format: "minY=%.17g maxY=%.17g top=%.17g bottom=%.17g", frame.minY, frame.maxY, top, bottom) 170 XCTFail("Required accessibility element is unreachable: exists=\(exists) hittable=\(exists && element.isHittable) \(geometry). \(detail).\n\(app.debugDescription)") 171 } 172 173 private static func isVisible(_ element: XCUIElement, app: XCUIApplication, requiresHit: Bool) -> Bool { 174 guard element.exists, !requiresHit || element.isHittable else { return false } 175 let (top, bottom) = TeraAccessibilityNavigation.viewport(app) 176 let frame = element.frame 177 return contains(frame, top: top, bottom: bottom) 178 } 179 180 static func contains(_ frame: CGRect, top: CGFloat, bottom: CGFloat) -> Bool { 181 // UIKit's scaled geometry can differ by a few floating-point units at the 182 // same boundary (observed 189 versus 189.00000000000011). Eight ulps are 183 // far below a screen pixel; actual clipping still fails the native audits. 184 frame.width > 0 && frame.height > 0 185 && frame.minY >= top - top.ulp * 8 186 && frame.maxY <= bottom + bottom.ulp * 8 187 } 188 189 private static func scrollPosition(_ app: XCUIApplication) -> String? { 190 // Text editors have their own scrollbars. Progress belongs to the outer 191 // form, whose visible scrollbar is farther right than those nested editors. 192 let bars = app.otherElements.matching(NSPredicate(format: "label BEGINSWITH %@", "Vertical scroll bar")) 193 .allElementsBoundByIndex.filter { $0.frame.height > 0 && $0.frame.intersects(app.frame) } 194 let outer = bars.max { lhs, rhs in 195 lhs.frame.maxX == rhs.frame.maxX ? lhs.frame.height < rhs.frame.height : lhs.frame.maxX < rhs.frame.maxX 196 } 197 return outer?.value as? String 198 } 199 200 private static func visibleContent(_ app: XCUIApplication) -> [String] { 201 let (top, bottom) = TeraAccessibilityNavigation.viewport(app) 202 return app.staticTexts.allElementsBoundByIndex.compactMap { text in 203 let frame = text.frame 204 guard frame.height > 0, frame.maxY > top, frame.minY < bottom else { return nil } 205 return "\(text.identifier):\(text.label):\(frame.minY.rounded()):\(frame.maxY.rounded())" 206 } 207 } 208 209 private static func drag(_ app: XCUIApplication, amount: CGFloat, top: CGFloat, bottom: CGFloat) { 210 // Application coordinates can resolve to a zero-width origin. The actual 211 // window gives a stable point in the form margin, outside nested editors. 212 let window = app.windows.firstMatch 213 let origin = window.coordinate(withNormalizedOffset: .zero) 214 // Start and end in the middle half of the scrollable area. The system 215 // bars can intercept gestures near the nominal safe-area boundaries. 216 let span = bottom - top 217 let delta = max(-span / 2, min(span / 2, amount)) 218 let startY = (delta < 0 ? bottom - span / 4 : top + span / 4) - window.frame.minY 219 let start = origin.withOffset(CGVector(dx: 20, dy: startY)) 220 // A second withOffset replaces the previous offset. Calculate both ends 221 // from the same origin so the destination stays inside the viewport. 222 let finish = origin.withOffset(CGVector(dx: 20, dy: startY + delta)) 223 // Hold at the destination to stop momentum before reading the next frame. 224 start.press(forDuration: 0.05, thenDragTo: finish, 225 withVelocity: .slow, thenHoldForDuration: 0.3) 226 } 227 } 228 229 /// Contrast sampling under translucent navigation/tab bars can report a 230 /// partially occluded element. Every such finding must pass a new contrast 231 /// audit with its entire frame exposed. Unidentified findings remain fatal. 232 private extension TeraAccessibilityAudit { 233 func auditContrast(_ app: XCUIApplication) throws { 234 var pending: [String: TeraAuditTarget] = [:] 235 var verified = Set<String>() 236 var requested: TeraAuditTarget? 237 for _ in 0 ..< 20 { 238 let target = requested?.resolve(in: app) 239 let targetKey = requested?.key 240 if let target { 241 // A menu's static label has no separate tap action. It still must be 242 // fully exposed and pass the actual native contrast re-audit below. 243 TeraAccessibilityNavigation.scroll(app, to: target, up: requested?.scrollUp ?? true, 244 requiresHit: requested?.type != .staticText, test: test) 245 } 246 let findingsBefore = findings.count 247 try app.performAccessibilityAudit(for: .contrast) { issue in 248 let observation = XCTAttachment(string: "Contrast observation: \(issue.detailedDescription)\n\(issue.element?.debugDescription ?? "unidentified")") 249 observation.lifetime = .keepAlways 250 self.test.add(observation) 251 guard let element = issue.element else { return self.retainFinding(issue) } 252 // SC 1.4.3 exempts inactive controls. Keep this bound to the actual 253 // disabled camera control; no active text or clipping finding is exempt. 254 let key = self.contrastKey(element) 255 let camera = app.buttons["Camera"] 256 let disposition = Self.contrastDisposition(label: element.label, isEnabled: element.isEnabled, 257 cameraIsDisabled: camera.exists && !camera.isEnabled, 258 isRequestedTarget: key == targetKey, 259 isPartlyOccluded: self.isPartlyOccluded(element, app: app)) 260 switch disposition { 261 case .disabledCamera: return true 262 case .retain: return self.retainFinding(issue) 263 case .recheck: break 264 } 265 if !verified.contains(key) { 266 pending[key] = TeraAuditTarget(element, app: app) 267 } 268 let evidence = XCTAttachment(string: "Contrast requires unobscured recheck: \(element.debugDescription)") 269 evidence.lifetime = .keepAlways 270 self.test.add(evidence) 271 return true 272 } 273 if let target, let targetKey { 274 let (top, bottom) = TeraAccessibilityNavigation.viewport(app) 275 XCTAssertTrue((requested?.type == .staticText || target.isHittable) 276 && TeraAccessibilityNavigation.contains(target.frame, top: top, bottom: bottom), 277 "Contrast recheck moved outside the viewport") 278 if findings.count == findingsBefore { 279 verified.insert(targetKey) 280 } 281 } 282 guard let next = pending.keys.sorted().first else { return } 283 requested = pending.removeValue(forKey: next) 284 } 285 Self.failContrastRechecks() 286 } 287 288 func retainFinding(_ issue: XCUIAccessibilityAuditIssue) -> Bool { 289 Self.retainFinding(issue.compactDescription, elementLabel: issue.element?.label, in: &findings) 290 } 291 292 func contrastKey(_ element: XCUIElement) -> String { 293 "\(element.elementType.rawValue):\(element.identifier):\(element.label)" 294 } 295 296 func isPartlyOccluded(_ element: XCUIElement, app: XCUIApplication) -> Bool { 297 let frame = element.frame 298 let (top, bottom) = TeraAccessibilityNavigation.viewport(app) 299 guard frame.height > 0, frame.height < bottom - top - 16, 300 frame.minX >= app.frame.minX, frame.maxX <= app.frame.maxX else { return false } 301 return frame.minY < app.frame.maxY && frame.maxY > app.frame.minY 302 && !TeraAccessibilityNavigation.contains(frame, top: top, bottom: bottom) 303 } 304 } 305 306 enum TeraAccessibilityContrastDisposition: Equatable { 307 case retain, recheck, disabledCamera 308 } 309 310 private struct TeraAuditTarget { 311 let type: XCUIElement.ElementType 312 let identifier: String 313 let label: String 314 let scrollUp: Bool 315 316 var key: String { 317 "\(type.rawValue):\(identifier):\(label)" 318 } 319 320 @MainActor init(_ element: XCUIElement, app: XCUIApplication) { 321 type = element.elementType 322 identifier = element.identifier 323 label = element.label 324 scrollUp = element.frame.midY > app.frame.midY 325 } 326 327 @MainActor func resolve(in app: XCUIApplication) -> XCUIElement { 328 let predicate = identifier.isEmpty ? NSPredicate(format: "label == %@", label) 329 : NSPredicate(format: "identifier == %@ AND label == %@", identifier, label) 330 // UIKit-backed SwiftUI section headings expose different legacy and modern 331 // automation types. Match the stable identity and label across both trees. 332 return app.descendants(matching: .any).matching(predicate).firstMatch 333 } 334 } 335 336 @MainActor 337 enum TeraAccessibilitySettings { 338 static func setSystemReduceMotion(_ enabled: Bool, restoring test: XCTestCase? = nil) -> Bool { 339 let settings = XCUIApplication(bundleIdentifier: "com.apple.Preferences") 340 // This helper operates Settings, not the app under qualification. Keep 341 // its navigation stable while Tera uses the real maximum system size. 342 settings.launchArguments = ["-UIPreferredContentSizeCategoryName", "UICTContentSizeCategoryL"] 343 settings.launch() 344 if settings.navigationBars["Settings"].exists { 345 for _ in 0 ..< 3 { 346 settings.swipeDown() 347 } 348 } 349 for _ in 0 ..< 8 { 350 if settings.switches["Reduce Motion"].exists { 351 break 352 } 353 let motion = settings.buttons["Motion"].exists ? settings.buttons["Motion"] : settings.cells["Motion"] 354 let accessibility = settings.buttons["Accessibility"].exists ? settings.buttons["Accessibility"] : settings.cells["Accessibility"] 355 if motion.exists, motion.isHittable { 356 motion.tap() 357 } else if accessibility.exists, accessibility.isHittable { 358 accessibility.tap() 359 } else if settings.navigationBars.buttons.firstMatch.exists { 360 settings.navigationBars.buttons.firstMatch.tap() 361 } else { 362 settings.swipeUp() 363 } 364 } 365 let toggle = settings.switches["Reduce Motion"] 366 XCTAssertTrue(toggle.waitForExistence(timeout: 5), settings.debugDescription) 367 let original = toggle.value as? String == "1" 368 // Register restoration before changing the setting, including on failure. 369 if let test { 370 let originalSetting = XCTAttachment(string: "Original system Reduce Motion: \(original)") 371 originalSetting.lifetime = .keepAlways 372 test.add(originalSetting) 373 test.addTeardownBlock { 374 await MainActor.run { 375 _ = setSystemReduceMotion(original) 376 } 377 } 378 } 379 if original != enabled { 380 // Settings exposes the entire row as the switch accessibility element; 381 // its label does not toggle the visual control on this OS version. 382 toggle.coordinate(withNormalizedOffset: CGVector(dx: 0.9, dy: 0.5)).tap() 383 } 384 let settled = XCTNSPredicateExpectation(predicate: NSPredicate(format: "value == %@", enabled ? "1" : "0"), object: toggle) 385 XCTAssertEqual(XCTWaiter.wait(for: [settled], timeout: 5), .completed, settings.debugDescription) 386 settings.terminate() 387 return original 388 } 389 }