@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/SwiftUI/Runtime/Replay.swift

@@ -0,0 +1,382 @@
+// Headless event scripts (SB_EVENTS, Examples/*/__snapshots__/events.txt).
+//
+// An event names its target by element id (`tap:12`) or by a selector
+// resolved against what is on screen when the event is replayed:
+//
+//   tap:"Add Samples 2"         the tappable element showing that text
+//   tap:"Edit"#2                the second of several matches
+//   tap:@save                   `.accessibilityIdentifier("save")`
+//   select:[tabview]:"Settings" an element of that kind (here by a tab title)
+//   text:"Name":Paul            a field by its placeholder
+//   back, dismiss               the visible screen's back button, the top sheet or alert
+//
+// A selector that matches nothing, or several elements without `#n`, stops
+// the replay with an error op, so a script never taps the wrong element.
+
+/// A replay target written as a selector.
+struct _Selector: CustomStringConvertible {
+    var kind: String?
+    var text: String?
+    var identifier: String?
+    /// 1-based, from `#n`.
+    var index: Int?
+
+    var description: String {
+        var out = ""
+        if let kind { out += "[\(kind)]" }
+        if let text { out += _quoted(text) }
+        if let identifier { out += "@\(identifier)" }
+        if let index { out += "#\(index)" }
+        return out
+    }
+}
+
+enum _ScriptTarget {
+    case id(Int)
+    case selector(_Selector)
+}
+
+/// One event of a script, parsed but not yet resolved.
+struct _ScriptEvent {
+    var type: String
+    var target: _ScriptTarget?
+    /// What follows the target (`Paul` in `text:"Name":Paul`), unquoted.
+    var value: String?
+    /// Whether `value` was written in quotes (`select:"Sort":"Title"` names an option).
+    var valueQuoted = false
+    var raw: String
+}
+
+struct _ScriptError: Error {
+    let message: String
+}
+
+private func _quoted(_ text: String) -> String {
+    "\"" + text.replacingAll("\\", with: "\\\\").replacingAll("\"", with: "\\\"") + "\""
+}
+
+extension String {
+    func trimmingSpaces() -> String {
+        String(drop(while: { $0 == " " }).reversed().drop(while: { $0 == " " }).reversed())
+    }
+
+    fileprivate func replacingAll(_ target: Character, with replacement: String) -> String {
+        var out = ""
+        for character in self {
+            if character == target { out += replacement } else { out.append(character) }
+        }
+        return out
+    }
+}
+
+/// The event types whose first field is a target.
+private let _targetedEvents: Set<String> = [
+    "tap", "text", "toggle", "select", "step", "slide", "date", "geometry",
+    "drag", "longpress", "delete", "refresh",
+]
+
+/// The element kinds a selector picks for each event type, unless it names
+/// a kind itself (`[navscreen]`). A selector resolves to the nearest element
+/// at or above a match that has a handler and is one of these, as a tap on
+/// a button's text reaches the button.
+private let _targetKinds: [String: Set<String>] = [
+    "tap": ["button", "navlink", "listrow", "tapgesture"],
+    "longpress": ["gesture"],
+    "drag": ["gesture"],
+    "delete": ["listrow"],
+    "text": ["textfield", "searchfield", "texteditor"],
+    "toggle": ["toggle"],
+    "select": ["picker", "tabview"],
+    "step": ["stepper"],
+    "slide": ["slider"],
+    "date": ["datepicker"],
+    "geometry": ["geometry"],
+]
+
+enum _EventScript {
+    /// Splits a script into events at commas and line breaks outside quotes.
+    /// A line whose first non-blank character is `#` is a comment.
+    static func split(_ script: String) -> [String] {
+        var events: [String] = []
+        var current = ""
+        var inQuotes = false
+        var escaped = false
+        var inComment = false
+        func flush() {
+            let trimmed = current.trimmingSpaces()
+            if !trimmed.isEmpty { events.append(trimmed) }
+            current = ""
+        }
+        for character in script {
+            if inComment {
+                if character == "\n" { inComment = false }
+                continue
+            }
+            if inQuotes {
+                current.append(character)
+                if escaped {
+                    escaped = false
+                } else if character == "\\" {
+                    escaped = true
+                } else if character == "\"" {
+                    inQuotes = false
+                }
+                continue
+            }
+            switch character {
+            case "\"":
+                inQuotes = true
+                current.append(character)
+            case ",", "\n", "\r":
+                flush()
+            case "#" where current.trimmingSpaces().isEmpty:
+                inComment = true
+            default:
+                current.append(character)
+            }
+        }
+        flush()
+        return events
+    }
+
+    static func parse(_ raw: String) throws(_ScriptError) -> _ScriptEvent {
+        var scanner = _Scanner(raw)
+        let type = scanner.read(until: ":").trimmingSpaces()
+        var event = _ScriptEvent(type: type, raw: raw)
+        guard scanner.skip(":") else { return event }
+        if _targetedEvents.contains(type) {
+            event.target = try scanner.readTarget(in: raw)
+            guard scanner.skip(":") else {
+                guard scanner.atEnd else { throw _ScriptError(message: "unexpected text after the target in \(raw)") }
+                return event
+            }
+        }
+        if scanner.peek == "\"" {
+            event.value = try scanner.readQuoted(in: raw)
+            event.valueQuoted = true
+            guard scanner.atEnd else { throw _ScriptError(message: "unexpected text after the value in \(raw)") }
+        } else {
+            event.value = scanner.rest.trimmingSpaces()
+        }
+        return event
+    }
+}
+
+private struct _Scanner {
+    let characters: [Character]
+    var position = 0
+
+    init(_ text: String) { characters = Array(text) }
+
+    var atEnd: Bool { position >= characters.count }
+    var peek: Character? { atEnd ? nil : characters[position] }
+    var rest: String { String(characters[position...]) }
+
+    mutating func skip(_ character: Character) -> Bool {
+        guard peek == character else { return false }
+        position += 1
+        return true
+    }
+
+    mutating func read(until stop: Character) -> String {
+        var out = ""
+        while let next = peek, next != stop {
+            out.append(next)
+            position += 1
+        }
+        return out
+    }
+
+    mutating func skipSpaces() {
+        while peek == " " { position += 1 }
+    }
+
+    mutating func readQuoted(in raw: String) throws(_ScriptError) -> String {
+        guard skip("\"") else { throw _ScriptError(message: "expected a quoted string in \(raw)") }
+        var out = ""
+        while let next = peek {
+            position += 1
+            if next == "\"" { return out }
+            if next == "\\", let escaped = peek {
+                position += 1
+                out.append(escaped)
+            } else {
+                out.append(next)
+            }
+        }
+        throw _ScriptError(message: "unterminated string in \(raw)")
+    }
+
+    /// An element id, or a selector: `[kind]`, then `"text"` or `@identifier`, then `#n`.
+    mutating func readTarget(in raw: String) throws(_ScriptError) -> _ScriptTarget {
+        skipSpaces()
+        if let first = peek, first.isNumber || first == "-" {
+            let text = read(until: ":").trimmingSpaces()
+            guard let id = Int(text) else { throw _ScriptError(message: "bad element id \(text) in \(raw)") }
+            return .id(id)
+        }
+        var selector = _Selector()
+        if skip("[") {
+            selector.kind = read(until: "]")
+            guard skip("]"), !(selector.kind ?? "").isEmpty else {
+                throw _ScriptError(message: "expected [kind] in \(raw)")
+            }
+        }
+        if peek == "\"" {
+            selector.text = try readQuoted(in: raw)
+        } else if skip("@") {
+            var identifier = ""
+            while let next = peek, next != ":", next != "#" {
+                identifier.append(next)
+                position += 1
+            }
+            selector.identifier = identifier.trimmingSpaces()
+            guard !(selector.identifier ?? "").isEmpty else { throw _ScriptError(message: "expected an identifier after @ in \(raw)") }
+        }
+        if skip("#") {
+            let digits = read(until: ":").trimmingSpaces()
+            guard let index = Int(digits), index > 0 else { throw _ScriptError(message: "bad match number #\(digits) in \(raw)") }
+            selector.index = index
+        }
+        skipSpaces()
+        guard selector.kind != nil || selector.text != nil || selector.identifier != nil else {
+            throw _ScriptError(message: "expected an element id or a selector in \(raw)")
+        }
+        return .selector(selector)
+    }
+}
+
+// MARK: - Resolving selectors
+
+extension _Reconciler.Rendered {
+    func string(_ key: String) -> String? {
+        if case .object(let fields) = props, case .string(let value)? = fields[key] { return value }
+        return nil
+    }
+
+    func number(_ key: String) -> Double? {
+        if case .object(let fields) = props, case .number(let value)? = fields[key] { return value }
+        return nil
+    }
+
+    /// Whether `text` is what this element shows or is labelled with: a
+    /// `text`, an image's name, a screen title, a control's label or
+    /// placeholder, or its `accessibilityLabel`.
+    func shows(_ text: String) -> Bool {
+        if accessibility?.label == text { return true }
+        switch kind {
+        case "text": return string("text") == text
+        case "image": return string("systemName") == text || string("name") == text
+        default:
+            return string("title") == text || string("label") == text || string("placeholder") == text
+        }
+    }
+}
+
+@MainActor
+extension _Reconciler {
+    /// The elements on screen: the top sheet or alert if one is presented,
+    /// else everything, without the screens a stack has pushed over and
+    /// the unselected tabs.
+    private var visibleRoots: [Rendered] {
+        if let modal = roots.last(where: { $0.kind == "sheet" || $0.kind == "alert" }) { return [modal] }
+        return roots
+    }
+
+    private func visibleChildren(of element: Rendered) -> [Rendered] {
+        switch element.kind {
+        case "navstack":
+            guard let top = element.children.lastIndex(where: { $0.kind == "navscreen" }) else { return element.children }
+            return element.children.enumerated().filter { index, child in
+                child.kind != "navscreen" || index == top
+            }.map(\.1)
+        case "tabview":
+            guard let selected = element.number("selected").map(Int.init),
+                  element.children.indices.contains(selected) else { return element.children }
+            return [element.children[selected]]
+        default:
+            return element.children
+        }
+    }
+
+    /// The element a selector names for an event of this type.
+    func resolve(_ selector: _Selector, for type: String) throws(_ScriptError) -> Rendered {
+        let kinds = selector.kind.map { Set([$0]) } ?? _targetKinds[type]
+        func isTarget(_ element: Rendered) -> Bool {
+            handlers[element.id] != nil && (kinds?.contains(element.kind) ?? true)
+        }
+        func isMatch(_ element: Rendered) -> Bool {
+            if let identifier = selector.identifier { return element.accessibility?.identifier == identifier }
+            if let text = selector.text { return element.shows(text) }
+            return element.kind == selector.kind
+        }
+
+        var found: [Rendered] = []
+        func visit(_ element: Rendered, path: inout [Rendered]) {
+            path.append(element)
+            if isMatch(element), let target = path.last(where: isTarget), !found.contains(where: { $0.id == target.id }) {
+                found.append(target)
+            }
+            for child in visibleChildren(of: element) { visit(child, path: &path) }
+            path.removeLast()
+        }
+        var path: [Rendered] = []
+        for root in visibleRoots { visit(root, path: &path) }
+
+        let event = "\(type):\(selector)"
+        guard !found.isEmpty else { throw _ScriptError(message: "\(event) matches nothing on screen") }
+        if let index = selector.index {
+            guard index <= found.count else {
+                throw _ScriptError(message: "\(event): only \(found.count) element\(found.count == 1 ? "" : "s") match")
+            }
+            return found[index - 1]
+        }
+        guard found.count == 1 else {
+            let ids = found.map { "\($0.kind) \($0.id)" }.joined(separator: ", ")
+            throw _ScriptError(message: "\(event) matches \(found.count) elements (\(ids)); pick one with #1…#\(found.count)")
+        }
+        return found[0]
+    }
+
+    /// The rendered element with this id, if it is on the tree.
+    func element(id: Int) -> Rendered? {
+        func find(in elements: [Rendered]) -> Rendered? {
+            for element in elements {
+                if element.id == id { return element }
+                if let found = find(in: element.children) { return found }
+            }
+            return nil
+        }
+        return find(in: roots)
+    }
+
+    /// `back`: the visible screen's back button.
+    func backTarget() throws(_ScriptError) -> Rendered {
+        try resolve(_Selector(kind: "navscreen"), for: "tap")
+    }
+
+    /// `dismiss`: the top sheet or alert.
+    func dismissTarget() throws(_ScriptError) -> Rendered {
+        guard let modal = roots.last(where: { $0.kind == "sheet" || $0.kind == "alert" }), handlers[modal.id] != nil else {
+            throw _ScriptError(message: "dismiss: no sheet or alert is presented")
+        }
+        return modal
+    }
+
+    /// The index `select:…:"Option"` names: a picker option or a tab title.
+    func optionIndex(_ option: String, of element: Rendered) throws(_ScriptError) -> Int {
+        let names: [String?]
+        if element.kind == "tabview" {
+            names = element.children.map { $0.string("title") }
+        } else if case .object(let fields) = element.props, case .array(let options)? = fields["options"] {
+            names = options.map { if case .string(let name) = $0 { name } else { nil } }
+        } else {
+            names = []
+        }
+        guard let index = names.firstIndex(of: option) else {
+            let known = names.compactMap { $0 }.map(_quoted).joined(separator: ", ")
+            throw _ScriptError(message: "\(element.kind) \(element.id) has no option \(_quoted(option)) (options: \(known))")
+        }
+        return index
+    }
+}