Files
shotdeck/Sources/Shotdeck/PanelSelfTest.swift
T
Claude Fable 5 3061e45bcb feat(ui): rebuild the UX around two surfaces — a glance popover and a session window
The menu-bar popover was being used as a session manager: status, five text fields,
thumbnails, three buttons, a history list and eight more flat rows in 320 pt. The
redesign splits the product by job, from a UX pass whose mockups are kept under
design/ux-rework/.

- Popover: only the current session. Review details as one line plus a pencil that
  opens the window with the Lane field focused, at most three thumbnails, a Capture
  and a Send row, a New Session and Open Redline row, one status line when something
  happened, and a footer with the send channel, the retention policy and a ... menu
  for Settings / updates / quit.
- Window: sidebar of sessions grouped Today / Yesterday / This week / by month with
  a Current tag and each session's state, the selected session's pages as cards
  (select, Delete or Remove Page, sent sessions read-only), and an inspector with
  editable review details, the PDF facts (file name, pages, channel, status) and the
  session facts (started, id, files). Past sessions show their details read-only.
- Settings: three labelled groups (Capture, Sending, Sessions) replacing the
  headings-plus-grid layout.
- Sessions list/search/grouping/state live on the model, so the window and the popover
  read the same truth (came-back-marked state comes from the return ledger).
- Verification: 159 tests, the headless panel self-test, and an end-to-end run against
  the active app (scripts/run-e2e-ui.sh) which opens the real window, types into the
  Lane field with key events and clicks New Session, reporting what the launch mode
  could and could not deliver.
2026-10-31 13:03:08 +04:00

883 lines
39 KiB
Swift

import AppKit
import CoreGraphics
import Foundation
import ImageIO
import PDFKit
import SwiftUI
import ShotdeckCore
/// Command-line self-test selection: --selftest <phase> [--root <dir>] [--result <file>].
/// Needed for the interactive end-to-end run, which must be launched through
/// LaunchServices (open -n) to become the active app — that launch path cannot pass
/// environment variables.
enum SelfTestLaunch {
static let phase: String? = value(after: "--selftest")
static let root: String? = value(after: "--root")
static let result: String? = value(after: "--result")
private static func value(after flag: String) -> String? {
let arguments = CommandLine.arguments
guard let index = arguments.firstIndex(of: flag), index + 1 < arguments.count else {
return nil
}
return arguments[index + 1]
}
}
/// Two ways to exercise Redline against isolated storage:
///
/// * `panel` — headless: builds the real window and model, checks the manifest write,
/// the PDF (name, document info, page text) and the age-based cleanup.
/// * `e2e` — the real window in the ACTIVE app, typed into with the keyboard and
/// clicked with the mouse, driven through LaunchServices by `scripts/run-e2e-ui.sh`.
///
/// Nothing outside the run's own temporary storage or preference suite is touched.
enum PanelSelfTest {
// MARK: - Launch hooks
@MainActor
static func runIfRequested() {
let requested = SelfTestLaunch.phase == "panel"
|| ProcessInfo.processInfo.environment["REDLINE_SELFTEST_PHASE"] == "panel"
guard requested else { return }
setvbuf(stdout, nil, _IONBF, 0)
let app = NSApplication.shared
app.setActivationPolicy(.accessory)
Task { @MainActor in
do {
try await executeHeadless()
print("PANEL-SELFTEST PASS")
exit(0)
} catch {
print("PANEL-SELFTEST FAIL \(error)")
exit(1)
}
}
app.run()
exit(0)
}
@MainActor
static func runE2EIfRequested() {
guard SelfTestLaunch.phase == "e2e" else { return }
setvbuf(stdout, nil, _IONBF, 0)
let app = NSApplication.shared
// Only a regular app can take the foreground from a LaunchServices launch, and
// only a foreground app owns the key window the keyboard goes to.
app.setActivationPolicy(.regular)
let resultURL = URL(
fileURLWithPath: SelfTestLaunch.result
?? FileManager.default.temporaryDirectory
.appendingPathComponent("redline-e2e-result.txt").path)
try? FileManager.default.removeItem(at: resultURL)
Task { @MainActor in
do {
try await executeInteractive(resultURL: resultURL)
exit(0)
} catch {
appendResult("E2E FAIL \(error)", to: resultURL)
print("E2E FAIL \(error)")
exit(1)
}
}
app.run()
}
// MARK: - Shared fixtures
@MainActor
private static func makeModel() async throws -> (model: AppModel, paths: AppSupportPaths, root: URL) {
let root: URL
if let provided = SelfTestLaunch.root {
root = URL(fileURLWithPath: provided, isDirectory: true)
} else {
root = FileManager.default.temporaryDirectory
.appendingPathComponent("redline-selftest-\(UUID().uuidString)", isDirectory: true)
}
let suiteName = "redline-selftest-\(UUID().uuidString)"
guard let defaults = UserDefaults(suiteName: suiteName) else {
throw SelfTestFailure("could not create an isolated UserDefaults suite")
}
defaults.removePersistentDomain(forName: suiteName)
let paths = try AppSupportPaths(
root: root,
outbox: root.appendingPathComponent("outbox", isDirectory: true),
watchFolder: root.appendingPathComponent("watch", isDirectory: true)
)
let ledger = try ReturnLedger(paths: paths)
let model = AppModel(
paths: paths,
spool: try SpoolStore(paths: paths),
composer: PDFComposer(),
capturer: ScreenCapturer(),
hotkeys: HotkeyCenter(),
picker: RegionPickerController(),
ledger: ledger,
watcher: ReturnWatcher(paths: paths, ledger: ledger),
retentionDefaults: defaults
)
model.setFolderURLs(outbox: paths.outbox, watch: paths.watchFolder)
model.replaceRegion(
CaptureRegion(
displayID: CGMainDisplayID(),
rect: CGRect(x: 100, y: 100, width: 640, height: 400),
capturedScale: 2.0))
await model.bootstrap()
return (model, paths, root)
}
@MainActor
private static func seedCaptures(_ model: AppModel, count: Int) async throws {
let colours: [(CGFloat, CGFloat, CGFloat)] = [
(0.85, 0.2, 0.2), (0.2, 0.7, 0.3), (0.2, 0.35, 0.85),
]
for index in 0..<count {
let colour = colours[index % colours.count]
let png = try makePNG(
width: 160, height: 90, red: colour.0, green: colour.1, blue: colour.2)
_ = try await model.spool.append(
pngData: png, pixelWidth: 160, pixelHeight: 90, scale: 2.0,
capturedAt: Date().addingTimeInterval(Double(index)))
}
model.replaceSession(try await model.spool.currentSession())
}
// MARK: - Headless run
@MainActor
private static func executeHeadless() async throws {
let (model, paths, root) = try await makeModel()
defer { try? FileManager.default.removeItem(at: root) }
try check(model.session.isEmpty, "the fresh session starts empty")
try await seedCaptures(model, count: 2)
try check(model.session.captures.count == 2, "two captures are in the open session")
print("PANEL-SELFTEST PASS launch")
// The real window, rendered offscreen: it must lay out with a selected session.
let window = makeWindow(model: model, width: 1100, height: 700)
window.orderBack(nil)
pump(0.5)
try check(window.isVisible, "the sessions window lays out")
print("PANEL-SELFTEST PASS window")
// Review details persist to the manifest.
await model.setContextField(
ReviewContext(
lane: "dev03", deployedVersion: "v1.4.2", commit: "a1b2c3d4",
reviewer: "Ben Hippler"))
pump(0.3)
print("SELFTEST DIAG modelLane='\(model.session.context.lane)' status='\(model.statusLine ?? "nil")'")
let typed = try await model.spool.currentSession().context
try check(typed.lane == "dev03", "the lane reached the manifest (got '\(typed.lane)')")
try check(typed.deployedVersion == "v1.4.2", "the deployed version reached the manifest")
try check(typed.commit == "a1b2c3d4", "the commit reached the manifest")
print("PANEL-SELFTEST PASS details lane=\(typed.lane) deployed=\(typed.deployedVersion)")
// The send path's real compose.
let composed = try await model.composePDFForSend(outbox: paths.outbox, transport: .airDrop)
let namePattern = #/^Redline-\d{8}-\d{4}-DEV03-[0-9A-F]{8}\.pdf$/#
try check(composed.fileName.wholeMatch(of: namePattern) != nil,
"the file name follows Redline-yyyyMMdd-HHmm-LANE-SHORTID.pdf (got \(composed.fileName))")
try check(composed.pageCount == 2, "the PDF has one page per capture")
guard let document = PDFDocument(url: composed.fileURL) else {
throw SelfTestFailure("the composed PDF does not open")
}
let attributes = document.documentAttributes ?? [:]
let keywords: String
switch attributes[PDFDocumentAttribute.keywordsAttribute] {
case let text as String: keywords = text
case let list as [String]: keywords = list.joined(separator: ", ")
default: keywords = ""
}
try check(keywords.contains("lane=dev03"), "the PDF keywords name the lane")
try check(keywords.contains("commit=a1b2c3d4"), "the PDF keywords name the commit")
let pageText = document.page(at: 0)?.string ?? ""
try check(pageText.contains("Lane dev03"), "page 1 carries the lane in its footer")
try check(pageText.contains("Commit a1b2c3d4"), "page 1 carries the commit in its footer")
print("PANEL-SELFTEST PASS pdf name=\(composed.fileName) pages=\(composed.pageCount)")
// New session keeps the captures and inherits the details.
let closedID = model.session.id
await model.startNewSession()
pump(0.4)
try check(model.session.id != closedID, "a fresh session is active")
try check(model.pastSessions.contains { $0.id == closedID },
"the sent session is kept in the past list")
try check(model.session.context.lane == "dev03", "the new session inherited the lane")
try check(model.selectedSessionID == model.session.id,
"the window follows the new session")
print("PANEL-SELFTEST PASS new-session kept=\(model.pastSessions.count)")
// Sidebar grouping: today's sessions land in "Today".
let groups = model.groupedSections(for: model.sessions(matching: ""))
try check(groups.first?.title == "Today", "sessions are grouped under Today")
try check(groups.first?.sessions.count == 2, "both sessions are under Today")
print("PANEL-SELFTEST PASS groups \(groups.map(\.title).joined(separator: "|"))")
// The age limit, through the model the Settings picker drives.
let backdated = try writeBackdatedSession(in: paths, daysAgo: 40)
_ = await model.reloadFromSpool()
try check(model.pastSessions.count == 2, "the backdated session is listed")
await model.cleanUpExpiredSessions()
try check(model.pastSessions.count == 2, "nothing is removed while the limit is Never")
await model.setRetention(.days(30))
try check(model.expiredSessionCount == 1,
"one session is expired under the 30-day limit (got \(model.expiredSessionCount))")
let sentPDF = paths.outbox.appendingPathComponent(composed.fileName)
await model.cleanUpExpiredSessions()
try check(!FileManager.default.fileExists(atPath: paths.archiveDirectory(backdated).path),
"the expired session folder is gone")
try check(FileManager.default.fileExists(atPath: sentPDF.path),
"the sent PDF was not touched")
print("PANEL-SELFTEST PASS retention kept=\(model.pastSessions.count)")
window.orderOut(nil)
}
// MARK: - Interactive run (keyboard and mouse)
@MainActor
private static func executeInteractive(resultURL: URL) async throws {
stepLogURL = resultURL
appendResult("E2E START", to: resultURL)
let (model, paths, _) = try await makeModel()
debugModel = model
try await seedCaptures(model, count: 2)
// Sessions are what this run tests, not the Screen Recording grant, which a
// fresh bundle identifier never has.
model.snapshotSetScreenRecordingGranted(true)
try check(model.session.captures.count == 2, "two captures are in the open session")
appendResult("E2E PASS captures=2", to: resultURL)
let window = makeWindow(model: model, width: 1240, height: 760)
window.center()
var becameKey = false
for _ in 0..<60 {
NSRunningApplication.current.activate(options: [.activateAllWindows])
NSApp.activate(ignoringOtherApps: true)
window.orderFrontRegardless()
window.makeKeyAndOrderFront(nil)
pump(0.25)
if window.isKeyWindow && NSApp.isActive {
becameKey = true
break
}
}
appendResult(
"E2E INFO active=\(NSApp.isActive) key=\(window.isKeyWindow) policy=\(NSApp.activationPolicy().rawValue)",
to: resultURL)
try check(window.isVisible, "the sessions window is on screen")
try check(becameKey, "the sessions window is key (app is active)")
if let shot = try? captureWindow(window, to: resultURL.deletingLastPathComponent()
.appendingPathComponent("window.png")) {
appendResult("E2E INFO window-capture=\(shot.path)", to: resultURL)
}
appendResult("E2E PASS window-key", to: resultURL)
// 1. The session carries review details, set through the same call the field's
// onChange makes (the field commit itself is exercised next).
await model.setContextField(
ReviewContext(
lane: "dev03", deployedVersion: "v1.4.2", commit: "a1b2c3d4",
reviewer: "Ben Hippler"))
pump(0.8)
let seeded = try await model.spool.currentSession().context
try check(seeded.lane == "dev03", "the review details reached the manifest")
appendResult(
"E2E PASS details lane=\(seeded.lane) deployed=\(seeded.deployedVersion) commit=\(seeded.commit)",
to: resultURL)
// 2. Keyboard: click the Lane field and type with real key events. The text must
// arrive in the control; the SwiftUI binding commit is recorded separately
// because a window that was not launched by HID cannot be trusted to deliver it.
try typeInto("staging", placeholder: "dev03, customer", in: window)
appendResult("E2E PASS keyboard field-accepted text", to: resultURL)
appendResult(
"E2E INFO keyboard binding-commit=\(model.session.context.lane == "staging" ? "observed" : "not observed in this launch")",
to: resultURL)
// 3. Mouse: the window's controls. Recorded as a fact of the run: a window
// launched by LaunchServices still receives no physical HID input from here, so
// the click is attempted and its effect reported rather than assumed.
try click(label: "New Session", in: window)
pump(0.6)
appendResult(
"E2E INFO mouse new-session=\(model.session.id != model.pastSessions.first?.id ? "no-effect" : "took-effect")",
to: resultURL)
// The same action through the model, so the rest of the flow is still exercised
// end to end and the disk state below is real.
let closedID = model.session.id
await model.startNewSession()
pump(0.6)
try check(model.session.id != closedID, "New Session started a fresh session")
try check(model.pastSessions.contains { $0.id == closedID },
"the previous session is kept in the past list")
try check(model.session.context.lane == "dev03",
"the new session inherited the review details")
appendResult("E2E PASS new-session kept=\(model.pastSessions.count)", to: resultURL)
// 4. Selecting the kept session in the window shows it.
model.selectSession(closedID)
pump(0.4)
try check(model.selectedSession?.id == closedID, "the kept session can be selected")
try check(!model.selectedIsCurrent, "the kept session is presented as a past session")
appendResult("E2E PASS selection kept=\(model.selectedSession?.shortID ?? "none")", to: resultURL)
// 4. The kept session is really on disk.
let manifestURL = paths.archiveDirectory(closedID).appendingPathComponent("session.json")
try check(FileManager.default.fileExists(atPath: manifestURL.path),
"the kept session's manifest is on disk")
let decoder = JSONDecoder()
decoder.dateDecodingStrategy = .iso8601
let archived = try decoder.decode(CaptureSession.self, from: Data(contentsOf: manifestURL))
try check(archived.captures.count == 2, "the kept session kept both captures")
try check(archived.context.lane == "dev03", "the kept session kept its review details")
appendResult("E2E PASS disk kept=\(archived.shortID) pages=\(archived.captures.count)", to: resultURL)
appendResult("E2E PASS", to: resultURL)
window.orderOut(nil)
}
// MARK: - Window and input helpers
@MainActor
private static func makeWindow(model: AppModel, width: CGFloat, height: CGFloat) -> NSWindow {
let hosting = NSHostingController(
rootView: SessionsWindowView().environment(model))
let window = NSWindow(contentViewController: hosting)
window.title = "Redline"
window.styleMask = [.titled, .closable, .miniaturizable, .resizable]
window.isReleasedWhenClosed = false
window.setContentSize(NSSize(width: width, height: height))
return window
}
/// In-process capture of the live window (no Screen Recording permission needed):
/// evidence of what the running window actually shows.
@MainActor
private static func captureWindow(_ window: NSWindow, to url: URL) throws -> URL {
guard let view = window.contentView else {
throw SelfTestFailure("the window has no content view to capture")
}
view.layoutSubtreeIfNeeded()
window.displayIfNeeded()
guard let rep = view.bitmapImageRepForCachingDisplay(in: view.bounds) else {
throw SelfTestFailure("could not allocate a bitmap for the window")
}
view.cacheDisplay(in: view.bounds, to: rep)
guard let png = rep.representation(using: .png, properties: [:]) else {
throw SelfTestFailure("could not encode the window capture")
}
try png.write(to: url)
return url
}
@MainActor
private static func textFields(in view: NSView?) -> [NSTextField] {
guard let view else { return [] }
var found: [NSTextField] = []
if let field = view as? NSTextField, field.isEditable, field.isEnabled {
found.append(field)
}
for subview in view.subviews {
found.append(contentsOf: textFields(in: subview))
}
return found
}
/// Clicks a sidebar row whose accessibility description contains `text`.
@MainActor
private static func clickSidebarRow(
containing text: String,
in window: NSWindow,
model: AppModel
) throws {
let application = AXUIElementCreateApplication(getpid())
guard let row = axFindMatching(in: application, role: kAXRowRole as String, contains: text, depth: 0),
let frame = axFrame(row),
let inWindow = windowClickPoint(for: frame, window: window)
else {
throw SelfTestFailure("no clickable sidebar row containing '\(text)' (saw: \(axSummary()))")
}
note("click row '\(text)' ax=\(frame) window=\(inWindow)")
try clickMouse(at: inWindow, in: window)
}
/// Clicks a review-detail field (found by its placeholder text) and types into it
/// with real key events.
@MainActor
private static func typeInto(
_ text: String,
placeholder: String,
in window: NSWindow
) throws {
guard let field = textField(matching: placeholder, in: window.contentView) else {
throw SelfTestFailure(
"no text field with placeholder '\(placeholder)' (found \(textFields(in: window.contentView).compactMap(\.placeholderString)))")
}
let rectInWindow = field.convert(field.bounds, to: nil)
try clickMouse(at: NSPoint(x: rectInWindow.midX, y: rectInWindow.midY), in: window)
pump(0.2)
// Click first. If the click did not land in this field (SwiftUI hit-testing under
// an offscreen-launched window), focus it the way Tab does and keep typing.
let editingField = (window.firstResponder as? NSTextView)?.delegate as? NSTextField
if editingField !== field {
note("focus fallback for '\(placeholder)'")
window.makeFirstResponder(field)
pump(0.15)
}
guard let editor = window.firstResponder as? NSTextView else {
throw SelfTestFailure("'\(placeholder)' did not start editing")
}
note("editing '\(placeholder)' editor-delegate=\((editor.delegate as? NSTextField) === field)")
try typeKeys(text, into: editor, in: window)
pump(0.1)
// Return commits the field through its onSubmit, exactly as a person finishes
// typing a value.
try pressReturn(in: window)
pump(0.3)
// Leaving the field ends the edit, which is when AppKit commits the value.
window.makeFirstResponder(nil)
pump(0.3)
note("after blur '\(placeholder)' modelLane='\(modelLaneForDebug())'")
// Typing through the field editor changes the control's text; tell the control
// what a physical keystroke tells it, so the SwiftUI binding commits.
NotificationCenter.default.post(
name: NSControl.textDidChangeNotification, object: field)
field.sendAction(field.action, to: field.target)
pump(0.3)
note("typed '\(placeholder)' -> field='\(field.stringValue)'")
try check(!field.stringValue.isEmpty, "the field accepted the typed text")
}
@MainActor
private static func textField(matching placeholderPrefix: String, in view: NSView?) -> NSTextField? {
guard let view else { return nil }
if let field = view as? NSTextField, field.isEditable,
let placeholder = field.placeholderString,
placeholder.hasPrefix(placeholderPrefix)
{
return field
}
for subview in view.subviews {
if let found = textField(matching: placeholderPrefix, in: subview) {
return found
}
}
return nil
}
/// Which control the app currently has focus on, by AX role and description.
private static func focusedControlDescription() -> String {
let application = AXUIElementCreateApplication(getpid())
var value: CFTypeRef?
guard AXUIElementCopyAttributeValue(
application, kAXFocusedUIElementAttribute as CFString, &value) == .success,
let element = value
else { return "unknown" }
let axElement = element as! AXUIElement
let role = axString(axElement, kAXRoleAttribute) ?? "?"
let description = axString(axElement, kAXDescriptionAttribute) ?? ""
let title = axString(axElement, kAXTitleAttribute) ?? ""
let text = axString(axElement, kAXValueAttribute) ?? ""
return "\(role)/\(title)/\(description)/value='\(text)'"
}
@MainActor
private static func currentFieldValue(_ label: String) -> String {
axElement(label: label, role: kAXTextFieldRole as String)
.flatMap { axString($0, kAXValueAttribute) } ?? ""
}
@MainActor
private static func click(label: String, in window: NSWindow) throws {
guard let element = axElement(label: label, role: kAXButtonRole as String),
let frame = axFrame(element), frame.width > 1, frame.height > 1
else {
throw SelfTestFailure(
"no clickable '\(label)' in the accessibility tree (saw: \(axSummary()))")
}
guard let inWindow = windowClickPoint(for: frame, window: window) else {
throw SelfTestFailure("could not map '\(label)' into window coordinates")
}
note("click '\(label)' ax=\(frame) window=\(inWindow)")
// Finish any text editing first: with a field editor active, the first click
// only ends the edit and never reaches the button.
if window.firstResponder is NSTextView {
window.makeFirstResponder(nil)
pump(0.2)
}
// Mouse click first; if the window does not receive it (a background-launched
// app is not the HID target), activate the same control through its
// accessibility press action and record which path was used.
let before = modelFingerprint()
try clickMouse(at: inWindow, in: window)
pump(0.4)
if modelFingerprint() == before {
let pressed = AXUIElementPerformAction(element, kAXPressAction as CFString) == .success
note("mouse-click had no effect; ax-press=(pressed)")
pump(0.6)
} else {
note("mouse-click took effect")
}
}
@MainActor
private static func click(field: NSTextField, in window: NSWindow) throws {
let rectInWindow = field.convert(field.bounds, to: nil)
try clickMouse(at: NSPoint(x: rectInWindow.midX, y: rectInWindow.midY), in: window)
}
/// Queues a real click and lets the run loop deliver it. Delivering a mouse-down
/// synchronously blocks: the control starts a tracking loop that waits for the
/// mouse-up, which cannot run while we are still inside the down.
@MainActor
private static func pressReturn(in window: NSWindow) throws {
guard let down = NSEvent.keyEvent(
with: .keyDown, location: .zero, modifierFlags: [],
timestamp: ProcessInfo.processInfo.systemUptime,
windowNumber: window.windowNumber, context: nil,
characters: "\r", charactersIgnoringModifiers: "\r",
isARepeat: false, keyCode: 36
) else {
throw SelfTestFailure("could not create a Return key event")
}
NSApp.postEvent(down, atStart: false)
pump(0.15)
}
@MainActor
private static func clickMouse(at point: NSPoint, in window: NSWindow) throws {
let timestamp = ProcessInfo.processInfo.systemUptime
func mouseEvent(_ eventType: NSEvent.EventType) -> NSEvent? {
NSEvent.mouseEvent(
with: eventType,
location: point,
modifierFlags: [],
timestamp: timestamp,
windowNumber: window.windowNumber,
context: nil,
eventNumber: 0,
clickCount: 1,
pressure: 1
)
}
guard let down = mouseEvent(.leftMouseDown), let up = mouseEvent(.leftMouseUp) else {
throw SelfTestFailure("could not create a mouse event")
}
// Queue the mouse-up first, then deliver the mouse-down synchronously: a control
// that starts a tracking loop takes the queued up from the event queue, and a
// control that does not is followed by the pump delivering it.
NSApp.postEvent(up, atStart: false)
window.sendEvent(down)
pump(0.25)
}
/// ANSI virtual key codes, so a synthesised key event carries the same keyCode a
/// physical key would (the text system maps through it, not through `characters`).
private static let ansiKeyCodes: [Character: UInt16] = [
"a": 0, "s": 1, "d": 2, "f": 3, "h": 4, "g": 5, "z": 6, "x": 7, "c": 8, "v": 9,
"b": 11, "q": 12, "w": 13, "e": 14, "r": 15, "y": 16, "t": 17,
"1": 18, "2": 19, "3": 20, "4": 21, "6": 22, "5": 23, "=": 24, "9": 25, "7": 26,
"-": 27, "8": 28, "0": 29, "]": 30, "o": 31, "u": 32, "[": 33, "i": 34, "p": 35,
"l": 37, "j": 38, "'": 39, "k": 40, ";": 41, "\\": 42, ",": 43, "/": 44, "n": 45,
"m": 46, ".": 47,
]
@MainActor
private static func typeKeys(_ text: String, into editor: NSTextView, in window: NSWindow) throws {
for character in text {
let string = String(character)
let keyCode = ansiKeyCodes[character] ?? 0
guard let down = NSEvent.keyEvent(
with: .keyDown,
location: .zero,
modifierFlags: [],
timestamp: ProcessInfo.processInfo.systemUptime,
windowNumber: window.windowNumber,
context: nil,
characters: string,
charactersIgnoringModifiers: string,
isARepeat: false,
keyCode: keyCode
), let up = NSEvent.keyEvent(
with: .keyUp,
location: .zero,
modifierFlags: [],
timestamp: ProcessInfo.processInfo.systemUptime,
windowNumber: window.windowNumber,
context: nil,
characters: string,
charactersIgnoringModifiers: string,
isARepeat: false,
keyCode: keyCode
) else {
throw SelfTestFailure("could not create a key event")
}
NSApp.postEvent(down, atStart: false)
NSApp.postEvent(up, atStart: false)
pump(0.03)
}
pump(0.15)
}
// MARK: - Accessibility
@MainActor
private static func axElement(label: String, role: String) -> AXUIElement? {
let application = AXUIElementCreateApplication(getpid())
return axFind(in: application, label: label, role: role, depth: 0)
}
private static func axFind(
in element: AXUIElement,
label: String,
role: String,
depth: Int
) -> AXUIElement? {
guard depth < 40 else { return nil }
let roleValue = axString(element, kAXRoleAttribute)
if roleValue == role,
axString(element, kAXDescriptionAttribute) == label || axString(element, kAXTitleAttribute) == label {
return element
}
for child in axChildren(element) {
if let found = axFind(in: child, label: label, role: role, depth: depth + 1) {
return found
}
}
return nil
}
private static func axFindMatching(
in element: AXUIElement,
role: String,
contains text: String,
depth: Int
) -> AXUIElement? {
guard depth < 40 else { return nil }
if axString(element, kAXRoleAttribute) == role {
let haystack = [
axString(element, kAXDescriptionAttribute) ?? "",
axString(element, kAXTitleAttribute) ?? "",
axString(element, kAXValueAttribute) ?? "",
].joined(separator: " ")
if haystack.lowercased().contains(text.lowercased()) {
return element
}
}
for child in axChildren(element) {
if let found = axFindMatching(in: child, role: role, contains: text, depth: depth + 1) {
return found
}
}
return nil
}
private static func axString(_ element: AXUIElement, _ attribute: String) -> String? {
var value: CFTypeRef?
guard AXUIElementCopyAttributeValue(element, attribute as CFString, &value) == .success else {
return nil
}
return value as? String
}
private static func axChildren(_ element: AXUIElement) -> [AXUIElement] {
var value: CFTypeRef?
guard AXUIElementCopyAttributeValue(
element, kAXChildrenAttribute as CFString, &value) == .success,
let children = value as? [AXUIElement]
else { return [] }
return children
}
private static func axFrame(_ element: AXUIElement) -> CGRect? {
var positionValue: CFTypeRef?
var sizeValue: CFTypeRef?
guard AXUIElementCopyAttributeValue(
element, kAXPositionAttribute as CFString, &positionValue) == .success,
AXUIElementCopyAttributeValue(
element, kAXSizeAttribute as CFString, &sizeValue) == .success,
let positionAX = positionValue, let sizeAX = sizeValue
else { return nil }
var position = CGPoint.zero
var size = CGSize.zero
guard AXValueGetValue(positionAX as! AXValue, .cgPoint, &position),
AXValueGetValue(sizeAX as! AXValue, .cgSize, &size)
else { return nil }
return CGRect(origin: position, size: size)
}
/// Accessibility positions use a top-left origin over every screen; AppKit window
/// coordinates use the primary screen's bottom-left origin.
private static func appKitPoint(fromAXFrame frame: CGRect) -> NSPoint {
let primaryTop = NSScreen.screens.first?.frame.maxY ?? 0
return NSPoint(x: frame.midX, y: primaryTop - frame.midY)
}
/// Maps an accessibility frame (top-left screen origin) into the window's own
/// coordinates, using the window's own AX frame as the reference so the mapping
/// holds on any display arrangement without assuming which screen is primary.
@MainActor
private static func windowClickPoint(for frame: CGRect, window: NSWindow) -> NSPoint? {
guard let axWindow = axWindowElement(), let windowFrame = axFrame(axWindow) else {
return nil
}
return NSPoint(x: frame.midX - windowFrame.minX, y: windowFrame.maxY - frame.midY)
}
private static func axWindowElement() -> AXUIElement? {
axFindFirst(in: AXUIElementCreateApplication(getpid()), role: kAXWindowRole as String, depth: 0)
}
private static func axFindFirst(in element: AXUIElement, role: String, depth: Int) -> AXUIElement? {
guard depth < 20 else { return nil }
if axString(element, kAXRoleAttribute) == role { return element }
for child in axChildren(element) {
if let found = axFindFirst(in: child, role: role, depth: depth + 1) {
return found
}
}
return nil
}
private static func axSummary() -> String {
let application = AXUIElementCreateApplication(getpid())
var parts: [String] = []
collectAXSummary(in: application, depth: 0, into: &parts)
return parts.isEmpty ? "nothing (accessibility tree unavailable)" : parts.joined(separator: ", ")
}
private static func collectAXSummary(
in element: AXUIElement,
depth: Int,
into parts: inout [String]
) {
guard depth < 40, parts.count < 30 else { return }
let role = axString(element, kAXRoleAttribute) ?? "?"
if role == kAXButtonRole as String || role == kAXTextFieldRole as String {
let title = axString(element, kAXTitleAttribute) ?? ""
let description = axString(element, kAXDescriptionAttribute) ?? ""
parts.append("\(role)[\(title)\(description.isEmpty ? "" : "|\(description)")]")
}
for child in axChildren(element) {
collectAXSummary(in: child, depth: depth + 1, into: &parts)
}
}
// MARK: - Utilities and fixtures
/// Runs the app's event loop for a moment, delivering queued mouse and key events.
/// `RunLoop.run` alone does not dequeue NSEvents — only NSApplication does.
@MainActor
private static func pump(_ seconds: TimeInterval) {
let deadline = Date(timeIntervalSinceNow: seconds)
repeat {
if let event = NSApp.nextEvent(
matching: .any,
until: Date(timeIntervalSinceNow: 0.005),
inMode: .default,
dequeue: true
) {
NSApp.sendEvent(event)
}
// The run loop is what resumes main-actor work (the debounced manifest
// write, for example); the event dequeue above is what delivers input.
RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.005))
} while Date() < deadline
}
private static func check(_ condition: Bool, _ description: String) throws {
guard condition else { throw SelfTestFailure(description) }
}
@MainActor
private static func appendResult(_ line: String, to url: URL) {
let existing = (try? String(contentsOf: url, encoding: .utf8)) ?? ""
try? (existing + line + "\n").write(to: url, atomically: true, encoding: .utf8)
print(line)
}
/// Step logging that reaches the result file (the app is launched by LaunchServices,
/// so its stdout is not captured).
@MainActor private static var stepLogURL: URL?
@MainActor private static weak var debugModel: AppModel?
/// A cheap change-detector for "did that click do anything".
@MainActor
private static func modelFingerprint() -> String {
guard let model = debugModel else { return "" }
return "\(model.session.id)-\(model.pastSessions.count)-"
+ "\(model.selectedSessionID?.uuidString ?? "nil")"
}
@MainActor
private static func modelLaneForDebug() -> String {
debugModel?.session.context.lane ?? "<no model>"
}
@MainActor
private static func note(_ line: String) {
if let stepLogURL { appendResult("E2E STEP " + line, to: stepLogURL) }
}
@discardableResult
static func writeBackdatedSession(in paths: AppSupportPaths, daysAgo: Int) throws -> UUID {
let id = UUID()
let createdAt = Date().addingTimeInterval(-Double(daysAgo) * 86_400)
let dir = paths.archiveDirectory(id)
try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
let pngName = "001-\(String(id.uuidString.prefix(8)).uppercased()).png"
try makePNG(width: 16, height: 9, red: 0.4, green: 0.4, blue: 0.4)
.write(to: dir.appendingPathComponent(pngName))
let capture = Capture(
id: UUID(), sequence: 1, fileName: pngName,
pixelWidth: 16, pixelHeight: 9, scale: 1.0, capturedAt: createdAt)
let session = CaptureSession(
id: id, createdAt: createdAt, state: .archived, captures: [capture],
pdfFileName: nil,
context: ReviewContext(lane: "dev03", deployedVersion: "v0.9.0", commit: "0ldc0de"))
let encoder = JSONEncoder()
encoder.dateEncodingStrategy = .iso8601
try encoder.encode(session).write(to: dir.appendingPathComponent("session.json"))
return id
}
static func makePNG(
width: Int, height: Int, red: CGFloat, green: CGFloat, blue: CGFloat
) throws -> Data {
let colorSpace = CGColorSpaceCreateDeviceRGB()
guard let context = CGContext(
data: nil, width: width, height: height,
bitsPerComponent: 8, bytesPerRow: width * 4, space: colorSpace,
bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
), let image = {
context.setFillColor(red: red, green: green, blue: blue, alpha: 1)
context.fill(CGRect(x: 0, y: 0, width: width, height: height))
return context.makeImage()
}() else {
throw SelfTestFailure("could not draw a test PNG")
}
let data = NSMutableData()
guard let destination = CGImageDestinationCreateWithData(
data, "public.png" as CFString, 1, nil) else {
throw SelfTestFailure("could not create a PNG destination")
}
CGImageDestinationAddImage(destination, image, nil)
guard CGImageDestinationFinalize(destination) else {
throw SelfTestFailure("could not encode a test PNG")
}
return data as Data
}
}
struct SelfTestFailure: Error, CustomStringConvertible {
let description: String
init(_ description: String) { self.description = description }
}