field_ios

In-the-field app for Radroots on iOS
git clone https://radroots.dev/git/field_ios.git
Log | Files | Refs | README | LICENSE

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 }