docs(pytest-plugin): Expand examples with advanced testing techniques

- Add comprehensive examples for testing with multiple panes
- Add section on testing complex tmux configurations with custom settings
- Add examples for working with temporary files and directories in tests
- Add advanced polling techniques for more robust command execution tests
- Improve debugging section with more detailed diagnostics

Author: tony

docs/pytest-plugin/examples.md

@@ -9,6 +9,8 @@ The libtmux pytest plugin provides powerful fixtures for testing tmux-related fu
 Testing a simple server connection:
 
 ```python
+import libtmux
+
 def test_server_connection(server):
     """Test that we can connect to a tmux server."""
     assert server is not None
@@ -20,6 +22,8 @@ def test_server_connection(server):
 Testing session creation and properties:
 
 ```python
+import libtmux
+
 def test_new_session(session):
     """Test that the session fixture provides a working session."""
     assert session is not None
@@ -38,6 +42,9 @@ def test_new_session(session):
 Testing window creation and manipulation:
 
 ```python
+import libtmux
+from libtmux.constants import PaneDirection
+
 def test_window_operations(session):
     """Test window creation and properties."""
     # Create a new window
@@ -49,7 +56,7 @@ def test_window_operations(session):
     assert window.window_name == "renamed_window"
 
     # Split the window
-    pane = window.split_window()
+    pane = window.split(direction=PaneDirection.Right)
     assert len(window.panes) == 2
 
     # Send keys to pane
@@ -67,6 +74,9 @@ def test_window_operations(session):
 Testing pane creation and interaction:
 
 ```python
+import libtmux
+from libtmux.constants import PaneDirection
+
 def test_pane_operations(pane):
     """Test operations on a pane fixture."""
     # Send a command
@@ -81,7 +91,7 @@ def test_pane_operations(pane):
     assert any("Testing pane operations" in line for line in output)
 
     # Split the pane
-    new_pane = pane.split_window()
+    new_pane = pane.split(direction=PaneDirection.Below)
     assert new_pane is not None
 
     # Verify we have two panes now
@@ -94,6 +104,8 @@ def test_pane_operations(pane):
 Setting up a specific environment for tests:
 
 ```python
+import libtmux
+
 def test_with_custom_environment(server):
     """Test with a customized environment setup."""
     # Create a session with specific options
@@ -116,7 +128,7 @@ def test_with_custom_environment(server):
 
     # Test window switching
     custom_session.switch_window(1)
-    current = custom_session.attached_window
+    current = custom_session.active_window
     assert current.window_name == "window2"
 
     # Clean up
@@ -132,6 +144,8 @@ def test_with_custom_environment(server):
 Handling commands that take time to execute:
 
 ```python
+import libtmux
+
 def test_long_running_command(pane):
     """Test interaction with long-running commands."""
     # Start a command that will run for a few seconds
@@ -158,6 +172,8 @@ def test_long_running_command(pane):
 Testing integration with other terminal programs:
 
 ```python
+import libtmux
+
 def test_program_integration(pane):
     """Test interaction with another terminal program."""
     # Start a text editor (nano is simple and widely available)
@@ -195,6 +211,8 @@ def test_program_integration(pane):
 Testing error handling:
 
 ```python
+import libtmux
+
 def test_error_handling(pane):
     """Test handling of command errors."""
     # Send a command that will fail
@@ -217,6 +235,7 @@ Using pytest parametrization with tmux fixtures:
 
 ```python
 import pytest
+import libtmux
 
 @pytest.mark.parametrize("window_name", ["test1", "test2", "test3"])
 def test_multiple_windows(session, window_name):
@@ -225,7 +244,7 @@ def test_multiple_windows(session, window_name):
     assert window.window_name == window_name
 
     # Do something with each window
-    pane = window.attached_pane
+    pane = window.active_pane
     pane.send_keys(f"echo 'Testing window {window_name}'", enter=True)
 
     # Verify output
@@ -248,6 +267,8 @@ def test_multiple_windows(session, window_name):
 If you're having trouble with your tmux tests, try these techniques:
 
 ```python
+import libtmux
+
 def test_with_debugging(pane):
     """Example showing debugging techniques."""
     # Capture initial state
@@ -279,3 +300,241 @@ def test_with_debugging(pane):
         print(f"Failed to find '{expected_text}' in output: {output}")
     assert any(expected_text in line for line in output)
 ```
+
+## Testing with Multiple Panes
+
+Testing applications that require multiple panes and interaction between them:
+
+```python
+import pytest
+import libtmux
+from libtmux.constants import PaneDirection
+import time
+
+def test_multi_pane_interaction(server, session):
+    """Test interaction between multiple panes."""
+    # Create a window with multiple panes for testing
+    window = session.new_window(window_name="multi-pane-test")
+    
+    # First pane (already exists as the active pane)
+    main_pane = window.active_pane
+    
+    # Create a second pane for output
+    output_pane = window.split(direction=PaneDirection.Right)
+    
+    # Create a third pane for monitoring
+    monitor_pane = main_pane.split(direction=PaneDirection.Below)
+    
+    # Wait for panes to be ready
+    time.sleep(0.5)
+    
+    # Set up the panes with specific content
+    main_pane.send_keys("echo 'This is the main pane'", enter=True)
+    output_pane.send_keys("echo 'This is the output pane'", enter=True)
+    monitor_pane.send_keys("echo 'This is the monitor pane'", enter=True)
+    
+    # Create a temporary file in one pane
+    main_pane.send_keys("echo 'Shared data' > shared_file.txt", enter=True)
+    time.sleep(0.5)
+    
+    # Read it from another pane
+    output_pane.send_keys("cat shared_file.txt", enter=True)
+    time.sleep(0.5)
+    
+    # Verify the content was shared
+    output_content = output_pane.capture_pane()
+    assert any("Shared data" in line for line in output_content)
+    
+    # Use the monitor pane to check the file exists
+    monitor_pane.send_keys("ls -la shared_file.txt", enter=True)
+    time.sleep(0.5)
+    
+    monitor_content = monitor_pane.capture_pane()
+    assert any("shared_file.txt" in line for line in monitor_content)
+    
+    # Clean up
+    main_pane.send_keys("rm shared_file.txt", enter=True)
+```
+
+## Testing Complex Tmux Configurations
+
+Testing with a custom tmux configuration:
+
+```python
+import pytest
+import libtmux
+import pathlib
+import tempfile
+
+@pytest.fixture
+def custom_config():
+    """Create a temporary tmux configuration file."""
+    with tempfile.NamedTemporaryFile(mode='w+', suffix='.conf') as f:
+        # Write custom tmux configuration
+        f.write("# Custom tmux configuration for testing\n")
+        f.write("set -g base-index 1\n")
+        f.write("set -g pane-base-index 1\n")
+        f.write("set -g status-left '[#S] '\n")
+        f.write("set -g status-style bg=green,fg=black\n")
+        f.write("set -g history-limit 5000\n")
+        f.flush()
+        yield pathlib.Path(f.name)
+
+@pytest.fixture
+def custom_server(custom_config, TestServer):
+    """Create a server with custom configuration."""
+    Server = TestServer()
+    server = Server(config_file=str(custom_config))
+    yield server
+    server.kill_server()
+
+def test_with_custom_config(custom_server):
+    """Test tmux with a custom configuration."""
+    session = custom_server.new_session(session_name="custom-config-test")
+    
+    # Verify custom configuration was applied
+    options = custom_server.show_options("g")
+    
+    # Check that history limit was set correctly
+    history_limit = options.get("history-limit", "")
+    assert history_limit == "5000"
+    
+    # Create a window to test base-index
+    window = session.new_window(window_name="test-window")
+    
+    # In our custom config, the first window should be index 1
+    window_index = window.get("window_index")
+    assert int(window_index) > 0, "Custom base-index wasn't applied"
+```
+
+## Testing with Temporary Files and Directories
+
+Managing temporary files in tests:
+
+```python
+import pytest
+import libtmux
+import pathlib
+import tempfile
+import time
+
+@pytest.fixture
+def temp_project_dir():
+    """Create a temporary project directory for testing."""
+    with tempfile.TemporaryDirectory() as tmpdirname:
+        project_dir = pathlib.Path(tmpdirname)
+        
+        # Create some sample files
+        (project_dir / "main.py").write_text("print('Hello, world!')")
+        (project_dir / "README.md").write_text("# Test Project\n\nThis is a test project.")
+        (project_dir / "config.ini").write_text("[settings]\nverbose = true")
+        
+        yield project_dir
+
+def test_project_file_manipulation(session, temp_project_dir):
+    """Test working with files in a temporary project directory."""
+    window = session.new_window(window_name="file-test")
+    pane = window.active_pane
+    
+    # Navigate to the project directory
+    pane.send_keys(f"cd {temp_project_dir}", enter=True)
+    time.sleep(0.5)
+    
+    # List files
+    pane.send_keys("ls -la", enter=True)
+    time.sleep(0.5)
+    
+    # Verify files are visible
+    output = pane.capture_pane()
+    assert any("main.py" in line for line in output)
+    assert any("README.md" in line for line in output)
+    
+    # Run a Python file
+    pane.send_keys("python main.py", enter=True)
+    time.sleep(0.5)
+    
+    # Verify output
+    output = pane.capture_pane()
+    assert any("Hello, world!" in line for line in output)
+    
+    # Create a new file through tmux
+    pane.send_keys("echo 'print(\"Testing is fun\")' > test.py", enter=True)
+    time.sleep(0.5)
+    
+    # Run the new file
+    pane.send_keys("python test.py", enter=True)
+    time.sleep(0.5)
+    
+    # Verify output from new file
+    output = pane.capture_pane()
+    assert any("Testing is fun" in line for line in output)
+```
+
+## Advanced Polling for Command Completion
+
+More robust way to wait for command completion:
+
+```python
+import pytest
+import libtmux
+import time
+import re
+
+def wait_for_output(pane, expected_pattern, timeout=5, interval=0.1):
+    """
+    Wait for a specific pattern to appear in the pane output.
+    
+    Args:
+        pane: The tmux pane to check
+        expected_pattern: Regex pattern to look for
+        timeout: Maximum time to wait in seconds
+        interval: Time between checks in seconds
+        
+    Returns:
+        The matching line if found, None if timeout occurs
+    """
+    pattern = re.compile(expected_pattern)
+    start_time = time.time()
+    
+    while time.time() - start_time < timeout:
+        output = pane.capture_pane()
+        
+        for line in output:
+            if pattern.search(line):
+                return line
+                
+        time.sleep(interval)
+    
+    return None  # Timeout occurred
+
+def test_command_with_polling(session):
+    """Test robust command polling."""
+    window = session.new_window(window_name="polling-test")
+    pane = window.active_pane
+    
+    # Start a command that takes time
+    pane.send_keys("echo 'Starting'; sleep 2; echo 'Finished!'", enter=True)
+    
+    # Wait for command to complete
+    result = wait_for_output(pane, r"Finished!")
+    
+    # Verify command completed successfully
+    assert result is not None, "Command did not finish within timeout"
+    
+    # Run a sequence of commands
+    pane.send_keys("echo 'Processing step 1'", enter=True)
+    assert wait_for_output(pane, r"Processing step 1")
+    
+    pane.send_keys("echo 'Processing step 2'", enter=True)
+    assert wait_for_output(pane, r"Processing step 2")
+    
+    pane.send_keys("echo 'Processing step 3'", enter=True)
+    assert wait_for_output(pane, r"Processing step 3")
+    
+    # Verify order of operations
+    output = pane.capture_pane()
+    step1_line = next((i for i, line in enumerate(output) if "Processing step 1" in line), -1)
+    step2_line = next((i for i, line in enumerate(output) if "Processing step 2" in line), -1)
+    step3_line = next((i for i, line in enumerate(output) if "Processing step 3" in line), -1)
+    
+    assert step1_line < step2_line < step3_line, "Commands did not execute in the correct order"