Minor cleanup

README.md

@@ -108,6 +108,8 @@ If you encounter any issues with the installation process, try the following tro
 - Add github actions ✅
 - Maybe add some of the method in the Kif.framework?
 - UITest tap should have param to set shouldFail: true
+- Add example gif to readme
+- Write about things that are different when using this with SwiftUI
 
 ## License
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. The MIT License is a permissive open source license that allows you to use, copy, modify, and distribute the software for any purpose, as long as you include the original copyright and license notice.

Sources/UITestSugar/ui/element/debug/ElementDebugger.swift

@@ -26,13 +26,13 @@ public class ElementDebugger {
     * - Remark: There is also the native `debugDescription` property of `XCUIElement`.
     * - Parameters:
     *   - element: The element to debug.
-    *   - indentation: The number of spaces to indent the output for readability.
+    *   - indentation: The number of spaces to indent the output for readability
     * - Returns: A dictionary containing the element's accessibility properties, including:
-    *   - `id`: The `accessibilityIdentifier` property.
-    *   - `aLabel`: The `accessibilityLabel` property.
+    *   - `id`: The `accessibilityIdentifier` property
+    *   - `aLabel`: The `accessibilityLabel` property
     *   - `label`: The `label` property of the `XCUIElement`'s `button` object.
-    *   - `type`: The type of the `XCUIElement`.
-    *   - `title`: The `title` property of the `XCUIElement`.
+    *   - `type`: The type of the `XCUIElement`
+    *   - `title`: The `title` property of the `XCUIElement`
     * - Example: `Swift.print(debug(element: app))` prints the accessibility properties of the `app` element.
     */
    public static func debug(element: XCUIElement, indentation: String = "") -> String {
@@ -45,8 +45,7 @@ public class ElementDebugger {
       return str // Return the string
    }
    /**
-    * Debugs multiple elements by printing their information to the console.
-    * 
+    * Debugs multiple elements by printing their information to the console
     * ## Examples:
     * let ancestry = ElementParser.ancestry(root: (0, app), condition: { $0.label == "Edit list" })
     * let elements: [XCUIElement] = ancestry?.map { $0.1 }

Sources/UITestSugar/ui/element/extension/Element+Parsing.swift

@@ -3,9 +3,13 @@ import Foundation
 import XCTest
 
 extension XCUIElement {
-   // Define type aliases for element IDs and labels
+   /**
+    * Define type aliases for element IDs and labels
+    */
    public typealias IDType = (type: XCUIElementType, id: String?)
-   // Define a type alias for a tuple that represents an element type and an optional label
+   /**
+    * Define a type alias for a tuple that represents an element type and an optional label
+    */
    public typealias LabelType = (type: XCUIElementType, label: String?)
    /**
     * Returns an XCUIElement for map
@@ -29,7 +33,7 @@ extension XCUIElement {
    }
    /**
     * Returns the first descendant of the element that matches the specified query.
-    * The query parameter can be either an `IDType` or a `LabelType`.
+    * - Note: The query parameter can be either an `IDType` or a `LabelType`.
     * If the query is an `IDType`, the function calls the `firstDescendant(type:id:)` method to find the first descendant with the specified type and ID.
     * If the query is a `LabelType`, the function calls the `firstDescendant(label:type:)` method to find the first descendant with the specified label and type.
     * If the query is neither an `IDType` nor a `LabelType`, the function raises a fatal error.
@@ -53,8 +57,8 @@ extension XCUIElement {
    public typealias SearchType = (type: XCUIElement.ElementType, id: String?)
    /**
     * Returns the first descendant of the element that matches the specified query.
-    * The query is represented as an array of `SearchType` tuples, where each tuple contains the type and ID or label of the UI element being searched for.
-    * The function uses recursion to search for the element in a nested hierarchy of UI elements.
+    * - Note: The query is represented as an array of `SearchType` tuples, where each tuple contains the type and ID or label of the UI element being searched for.
+    * - Note: The function uses recursion to search for the element in a nested hierarchy of UI elements.
     * - Parameter map: The query to use when searching for the descendant.
     * - Returns: The first descendant of the element that matches the specified query.
     */
@@ -72,8 +76,9 @@ extension XCUIElement {
    }
    /**
     * Returns a query for all descendants of the element that match the specified query.
-    * The query is represented as an array of `SearchType` tuples, where each tuple contains the type and ID or label of the UI element being searched for.
-    * The function uses recursion to search for the element in a nested hierarchy of UI elements.
+    * - Note: The query is represented as an array of `SearchType` tuples, where each tuple contains the type and ID or label of the UI element being searched for.
+    * - Note: The function uses recursion to search for the element in a nested hierarchy of UI elements.
+    * - Fixme: ⚠️️ doc each line, use copilot
     * - Parameter map: The query to use when searching for the descendants.
     * - Returns: A query for all descendants of the element that match the specified query.
     */

Sources/UITestSugar/ui/element/extension/interaction/XCUIElement+Other.swift

@@ -17,7 +17,8 @@ extension XCUIElement {
    }
    /**
     * Checks if an item exists and is hittable. If it's not hittable, then the app is tapped so that the tooltip goes away.
-    * - Returns: The current XCUIElement instance.
+    * - Returns: The current XCUIElement instance
+    * - Fixme: ⚠️️ doc each line, use copilot
     */
    @discardableResult public func disregardToolTip() -> XCUIElement {
       let elementExists: Bool = self.waitForExistence(timeout: 10)

Sources/UITestSugar/ui/element/extension/interaction/XCUIElement+Tap.swift

@@ -58,6 +58,7 @@ extension XCUIElement {
    /**
     * Wait for existence then tap
     * - Remark: `waitForExistence` is a native call
+    * - Fixme: ⚠️️ doc each line, use copilot
     * ## Examples:
     * app.buttons.firstMatch.tap(waitForExistence: 0.2)
     * - Parameter waitForExistence: The maximum amount of time to wait for the element to exist before tapping it.

Sources/UITestSugar/ui/element/extension/interaction/XCUIElement+Text.swift

@@ -7,7 +7,7 @@ import XCTest
 extension XCUIElement {
    /**
     * Types the given `text` into the receiver and returns the receiver for chaining calls.
-    * This method is equivalent to `typeText`, but returns the receiver instead of `Void`.
+    * - Note: This method is equivalent to `typeText`, but returns the receiver instead of `Void`.
     * - Note: Same as typeText, but returns self for chaining calls
     * - Remark: We can't use `typeText` as it's a native call
     * - Parameter text: The text to type into the receiver.
@@ -80,11 +80,12 @@ extension XCUIElement {
    public func clearAndWriteText(text: String) {
       self.clear() // Clear the existing text in the element.
       self.typeText(text) // Enter the new text into the element.
-      // Note: You can add "\n" at the end of the text to submit the input.
+      // - Note: You can add "\n" at the end of the text to submit the input.
    }
    /**
     * Removes any current text in the field before typing in the new value and submitting
-    * Based on: https://stackoverflow.com/a/32894080 (The link provided is a reference to a Stack Overflow answer that provides a solution for selecting all text in a NSTextField or NSTextView on macOS. The solution involves using the selectAll(_:) method of the NSText class to select all the text in the field or view, and then using the writeSelection(to:) method to write the selected text to the pasteboard. This allows the selected text to be copied or replaced with new text. The code in the link is similar to the code in the previous message, but it's written in Objective-C and uses the NSTextField and NSTextView classes instead of the XCUIElement class.)
+    * - Note: Based on: https://stackoverflow.com/a/32894080 (The link provided is a reference to a Stack Overflow answer that provides a solution for selecting all text in a NSTextField or NSTextView on macOS. The solution involves using the selectAll(_:) method of the NSText class to select all the text in the field or view, and then using the writeSelection(to:) method to write the selected text to the pasteboard. This allows the selected text to be copied or replaced with new text. The code in the link is similar to the code in the previous message, but it's written in Objective-C and uses the NSTextField and NSTextView classes instead of the XCUIElement class.)
+    * - Fixme: ⚠️️ doc each line, use copilot
     */
    public func clear() {
       // Check if the current value is a string

Sources/UITestSugar/ui/element/modifier/ElementModifier+Scroll.swift

@@ -6,10 +6,10 @@ import XCTest
  */
 extension ElementModifier {
    /**
-    * Searches down a scroll view until `searchCondition` is met.
+    * Searches down a scroll view until `searchCondition` is met
     * - Parameters:
-    *   - element: The root element to search from.
-    *   - dir: The direction to scroll in.
+    *   - element: The root element to search from
+    *   - dir: The direction to scroll in
     *   - searchCondition: A closure that takes an `XCUIElement` and returns a `Bool`. The closure is used to check if an element being searched has a certain condition.
     * ## Example:
     * // Scroll down a list until the first item with a title of "Featured playlist" and an identifier of "Featured Playlists-View all" is found
@@ -37,6 +37,7 @@ extension ElementModifier {
     * Scrolls until `element` is visible.
     * - Remark: Try to set cells: `cell.accessibilityIdentifer = "cell \(indexPath.row)"`
     * - Remark: There is also a native function `firstScrollView.scrollToElement(element: seventhChild)` that can be used to scroll to an element.
+    * - Fixme: ⚠️️ doc each line, use copilot
     * - Parameters:
     *   - parent: The element to swipe.
     *   - element: The element to swipe to.

Sources/UITestSugar/ui/element/modifier/ElementModifier+Table.swift

@@ -16,7 +16,7 @@ extension ElementModifier {
       // Get the first cell in the table
       let firstCell: XCUIElement = tableElement.children(matching: .cell).firstMatch
       // Get the start coordinate of the pull-to-refresh gesture
-      // fix: use .zero here?
+      // - Fixme: ⚠️️ use .zero here?
       let start: XCUICoordinate = firstCell.coordinate(withNormalizedOffset: .init(dx: 0, dy: 0))
       // Get the end coordinate of the pull-to-refresh gesture
       let finish: XCUICoordinate = firstCell.coordinate(withNormalizedOffset: .init(dx: 0, dy: 6))

Sources/UITestSugar/ui/element/modifier/ElementModifier+Web.swift

@@ -6,14 +6,14 @@ import XCTest
  */
 extension ElementModifier {
    /**
-    * Returns a `WebView` item for a specified title.
-    * - Parameters:
-    *   - app: A reference to the app.
-    *   - title: The title of the link.
+    * Returns a `WebView` item for a specified title
+    * - Important: ⚠️️ This function may not work if the link title is not unique. Consider using a different solution if you encounter this issue.
     * - Remark: This function uses the `links` property of `XCUIApplication` to return a `WebView` item for the specified title.
     * - Remark: You can also use the `Accessibility Inspector.app` in macOS or enable the iOS Simulator's Accessibility Inspector to inspect elements in the app.
     * - Remark: You can also use the `staticTexts` property of `XCUIApplication` to return a `StaticText` item for the specified content.
-    * - Important: ⚠️️ This function may not work if the link title is not unique. Consider using a different solution if you encounter this issue.
+    * - Parameters:
+    *   - app: A reference to the app.
+    *   - title: The title of the link.
     * ## Examples:
     * let app = XCUIApplication()
     * let webView = ElementModifier.link(app: app, title: "Tweet this")

Sources/UITestSugar/ui/element/parser/ElementParser+Hierarchy.swift

@@ -9,11 +9,11 @@ extension ElementParser {
     * Returns an array of ancestral elements for a specified element.
     * - Fixme: ⚠️️ Refactor with `.map` or `.flatMap` on this method when u have time
     * - Fixme: ⚠️️ You can also use `elementAtIndex` and `element.count`
+    * - Remark: This function recursively searches the ancestors of the specified element to find the first element that satisfies the specified condition. It then returns an array of all ancestral elements from the specified element to the element that satisfies the condition.
+    * - Remark: If no element satisfies the condition, this function returns nil.
     * - Parameters:
     *   - root: The point to search from.
     *   - condition: A closure that evaluates to true or false.
-    * - Remark: This function recursively searches the ancestors of the specified element to find the first element that satisfies the specified condition. It then returns an array of all ancestral elements from the specified element to the element that satisfies the condition.
-    * - Remark: If no element satisfies the condition, this function returns nil.
     * ## Example:
     * let app = XCUIApplication()
     * let condition: ElementParser.MatchCondition = { element in let s = element.screenshot().image.size; Swift.print("s:  \(s)"); return s == size/*element == btn*/} // .screenshot().image.size == size
@@ -45,15 +45,15 @@ extension ElementParser {
    }
    /**
     * Returns an element in a hierarchy based on a `mapIndex`.
+    * - Remark: This function recursively searches the hierarchy of the specified root element to find the element at the specified index. It returns the element if it exists, or nil if it doesn't.
+    * - Remark: If the index is empty, this function returns the root element.
+    * - Remark: If the index is at its end point, this function cuts off the branch and returns the element at the specified index.
+    * - Remark: If the index is not at its end point, this function recursively calls itself on the child element at the specified index.
     * - Fixme: ⚠️️ Base it on query instead, because it's faster.
     * - Fixme: ⚠️️ You can also use `elementAtIndex` and `element.count`.
     * - Parameters:
     *   - root: The root element to search from.
     *   - index: An array of integers that represents the path to the desired element.
-    * - Remark: This function recursively searches the hierarchy of the specified root element to find the element at the specified index. It returns the element if it exists, or nil if it doesn't.
-    * - Remark: If the index is empty, this function returns the root element.
-    * - Remark: If the index is at its end point, this function cuts off the branch and returns the element at the specified index.
-    * - Remark: If the index is not at its end point, this function recursively calls itself on the child element at the specified index.
     * ## Example:
     * let app = XCUIApplication()
     * let element = ElementParser.element(root: app, index: [0, 1, 2])