docs(examples): Add comprehensive examples for waiter utility

- Move example tests to tests/examples/test/test_waiter.py
- Add examples for all wait functions including the fluent API
- Ensure proper typing and None checks throughout examples
- Demonstrate wait_for_any_content and wait_for_all_content with different patterns
- Show fluent API chaining with configuration options

Author: tony

tests/examples/test/waiter/test_waiter.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python
+"""
+Examples of using the libtmux waiter API for testing.
+
+This file demonstrates various ways to use the waiter utility
+for waiting on pane content in tmux sessions.
+"""
+
+from __future__ import annotations
+
+import re
+import typing as t
+
+import libtmux
+from libtmux.test.waiter import (
+    ContentMatchType,
+    WaitResult,
+    expect,
+    wait_for_all_content,
+    wait_for_any_content,
+    wait_for_pane_content,
+    wait_until_pane_ready,
+)
+
+if t.TYPE_CHECKING:
+    from libtmux.pane import Pane
+
+
+def run_basic_example(server: libtmux.Server) -> None:
+    """Demonstrate basic waiting for pane content."""
+    session = server.new_session("waiter-example")
+    window = session.active_window
+    pane: Pane = window.active_pane  # type: ignore
+
+    # Run a command
+    pane.send_keys("echo 'Hello, world!'", enter=True)
+
+    # Wait for the output to appear
+    wait_for_pane_content(pane, "Hello, world!")
+
+    # Wait for shell prompt
+    wait_until_pane_ready(pane)
+
+
+def run_fluent_api_example(server: libtmux.Server) -> None:
+    """Demonstrate the fluent API for waiting on pane content."""
+    session = server.new_session("waiter-fluent-example")
+    pane: Pane = t.cast("Pane", session.active_window.active_pane)
+
+    # Run a command
+    pane.send_keys("for i in {1..5}; do echo $i; sleep 0.1; done", enter=True)
+
+    # Use the fluent API for better readability
+    (
+        expect(pane)
+        .with_timeout(2.0)
+        .wait_for_regex(r"\b[35]\b")  # Wait for either 3 or 5 to appear
+    )
+
+    # Wait for completion without raising an exception
+    pane.send_keys("sleep 1 && echo 'Completed'", enter=True)
+    result2: WaitResult = (
+        expect(pane)
+        .without_raising()
+        .with_timeout(0.5)  # Short timeout to demo timeout handling
+        .wait_for_text("Completed")
+    )
+
+    if result2.success:
+        pass
+
+    # Wait again with longer timeout
+    expect(pane).with_timeout(2.0).wait_for_text("Completed")
+
+
+def run_any_content_example(server: libtmux.Server) -> None:
+    """Demonstrate waiting for any of multiple patterns."""
+    session = server.new_session("waiter-any-example")
+    window = session.active_window
+    pane: Pane = window.active_pane  # type: ignore
+
+    # Run a command that will produce one of several outputs
+    pane.send_keys("echo 'Error: Connection failed'", enter=True)
+
+    # Wait for any of multiple patterns
+    result: WaitResult = wait_for_any_content(
+        pane,
+        ["Success", "Error:", "timeout"],
+        ContentMatchType.CONTAINS,
+    )
+
+    if (
+        result.success
+        and result.matched_content is not None
+        and "Error" in str(result.matched_content)
+    ):
+        pass
+
+
+def run_all_content_example(server: libtmux.Server) -> None:
+    """Demonstrate waiting for all patterns to appear."""
+    session = server.new_session("waiter-all-example")
+    window = session.active_window
+    pane: Pane = window.active_pane  # type: ignore
+
+    # Run commands that will produce multiple outputs
+    pane.send_keys("echo 'Database connected'; echo 'Server started'", enter=True)
+
+    # Wait for all patterns to appear
+    result: WaitResult = wait_for_all_content(
+        pane,
+        ["Database connected", "Server started"],
+        ContentMatchType.CONTAINS,
+    )
+
+    if result.success:
+        pass
+
+
+def run_mixed_type_example(server: libtmux.Server) -> None:
+    """Demonstrate using different match types together."""
+    session = server.new_session("waiter-mixed-example")
+    window = session.active_window
+    pane: Pane = window.active_pane  # type: ignore
+
+    # Run a command
+    pane.send_keys("echo '10 items found in database'", enter=True)
+
+    # Wait with mixed pattern types
+    wait_for_any_content(
+        pane,
+        [
+            "exact match",  # Will not match
+            "items found",  # Will match as substring
+            re.compile(r"\d+ items"),  # Will match as regex
+            lambda lines: len(lines) > 0,  # Will match as predicate
+        ],
+        [
+            ContentMatchType.EXACT,
+            ContentMatchType.CONTAINS,
+            ContentMatchType.REGEX,
+            ContentMatchType.PREDICATE,
+        ],
+    )
+
+
+def clean_up(server: libtmux.Server) -> None:
+    """Clean up test sessions."""
+    for prefix in [
+        "waiter-example",
+        "waiter-fluent-example",
+        "waiter-any-example",
+        "waiter-all-example",
+        "waiter-mixed-example",
+    ]:
+        for session in server.sessions:
+            if session.name is not None and session.name.startswith(prefix):
+                session.kill()
+
+
+def main() -> None:
+    """Run all examples."""
+    server = libtmux.Server()
+
+    try:
+        run_basic_example(server)
+
+        run_fluent_api_example(server)
+
+        run_any_content_example(server)
+
+        run_all_content_example(server)
+
+        run_mixed_type_example(server)
+
+    finally:
+        # Make sure to clean up
+        clean_up(server)
+
+
+if __name__ == "__main__":
+    main()