docs(pytest plugin) Examples

Author: tony

docs/pytest-plugin/examples.md

@@ -0,0 +1,281 @@
+(pytest_plugin_examples)=
+
+# Examples
+
+The libtmux pytest plugin provides powerful fixtures for testing tmux-related functionality. Here are examples demonstrating how to use the plugin effectively in your test suite.
+
+## Basic Test with Server Fixture
+
+Testing a simple server connection:
+
+```python
+def test_server_connection(server):
+    """Test that we can connect to a tmux server."""
+    assert server is not None
+    assert server.cmd('list-sessions').stderr == []
+```
+
+## Session-based Tests
+
+Testing session creation and properties:
+
+```python
+def test_new_session(session):
+    """Test that the session fixture provides a working session."""
+    assert session is not None
+    assert session.session_name is not None
+    
+    # Verify we can execute tmux commands in this session
+    session.cmd('display-message', '-p', 'test message')
+    
+    # Get information about the session
+    session_info = session.cmd('display-message', '-p', '#{session_name}').stdout
+    assert len(session_info) > 0
+```
+
+## Window Management Tests
+
+Testing window creation and manipulation:
+
+```python
+def test_window_operations(session):
+    """Test window creation and properties."""
+    # Create a new window
+    window = session.new_window(window_name="test_window")
+    assert window.window_name == "test_window"
+    
+    # Rename the window
+    window.rename_window("renamed_window")
+    assert window.window_name == "renamed_window"
+    
+    # Split the window
+    pane = window.split_window()
+    assert len(window.panes) == 2
+    
+    # Send keys to pane
+    pane.send_keys("echo 'Hello from test'", enter=True)
+    
+    # Verify the output (need to give time for command to execute)
+    import time
+    time.sleep(0.5)
+    output = pane.capture_pane()
+    assert any("Hello from test" in line for line in output)
+```
+
+## Pane Management Tests
+
+Testing pane creation and interaction:
+
+```python
+def test_pane_operations(pane):
+    """Test operations on a pane fixture."""
+    # Send a command
+    pane.send_keys("echo 'Testing pane operations'", enter=True)
+    
+    # Wait for command to complete
+    import time
+    time.sleep(0.5)
+    
+    # Capture output
+    output = pane.capture_pane()
+    assert any("Testing pane operations" in line for line in output)
+    
+    # Split the pane
+    new_pane = pane.split_window()
+    assert new_pane is not None
+    
+    # Verify we have two panes now
+    window = pane.window
+    assert len(window.panes) == 2
+```
+
+## Testing with Custom Environment
+
+Setting up a specific environment for tests:
+
+```python
+def test_with_custom_environment(server):
+    """Test with a customized environment setup."""
+    # Create a session with specific options
+    custom_session = server.new_session(
+        session_name="custom-test",
+        kill_session=True,
+        attach=False
+    )
+    
+    # Set session options
+    custom_session.set_option("mouse", "on")
+    custom_session.set_option("history-limit", "5000")
+    
+    # Create multiple windows
+    windows = [
+        custom_session.new_window(window_name="window1"),
+        custom_session.new_window(window_name="window2"),
+        custom_session.new_window(window_name="window3")
+    ]
+    
+    # Test window switching
+    custom_session.switch_window(1)
+    current = custom_session.attached_window
+    assert current.window_name == "window2"
+    
+    # Clean up
+    custom_session.kill_session()
+    
+    # Verify the session was killed
+    sessions = server.list_sessions()
+    assert not any(s.session_name == "custom-test" for s in sessions)
+```
+
+## Testing Long-Running Commands
+
+Handling commands that take time to execute:
+
+```python
+def test_long_running_command(pane):
+    """Test interaction with long-running commands."""
+    # Start a command that will run for a few seconds
+    pane.send_keys("sleep 3 && echo 'Command completed'", enter=True)
+    
+    # Verify command is running
+    import time
+    time.sleep(0.5)  # Give time for the command to start
+    
+    # Check immediate output (should not see completion message yet)
+    output = pane.capture_pane()
+    assert not any("Command completed" in line for line in output)
+    
+    # Wait for command to complete
+    time.sleep(3)
+    
+    # Verify command completed
+    output = pane.capture_pane()
+    assert any("Command completed" in line for line in output)
+```
+
+## Integration Testing with External Programs
+
+Testing integration with other terminal programs:
+
+```python
+def test_program_integration(pane):
+    """Test interaction with another terminal program."""
+    # Start a text editor (nano is simple and widely available)
+    pane.send_keys("nano", enter=True)
+    
+    # Wait for nano to start
+    import time
+    time.sleep(1)
+    
+    # Type some text
+    pane.send_keys("This is a test file created by libtmux")
+    
+    # Save the file (Ctrl+O)
+    pane.send_keys("^O")  # Ctrl+O
+    time.sleep(0.5)
+    pane.send_keys("test_file.txt", enter=True)
+    
+    # Exit nano (Ctrl+X)
+    pane.send_keys("^X")  # Ctrl+X
+    time.sleep(0.5)
+    
+    # Verify the file was created
+    pane.send_keys("cat test_file.txt", enter=True)
+    time.sleep(0.5)
+    
+    output = pane.capture_pane()
+    assert any("This is a test file created by libtmux" in line for line in output)
+    
+    # Clean up
+    pane.send_keys("rm test_file.txt", enter=True)
+```
+
+## Testing Error Conditions
+
+Testing error handling:
+
+```python
+def test_error_handling(pane):
+    """Test handling of command errors."""
+    # Send a command that will fail
+    pane.send_keys("command_that_does_not_exist", enter=True)
+    
+    # Wait for the error to appear
+    import time
+    time.sleep(0.5)
+    
+    # Capture the output
+    output = pane.capture_pane()
+    
+    # Verify error message appears
+    assert any("command not found" in line.lower() for line in output)
+```
+
+## Parametrized Tests
+
+Using pytest parametrization with tmux fixtures:
+
+```python
+import pytest
+
+@pytest.mark.parametrize("window_name", ["test1", "test2", "test3"])
+def test_multiple_windows(session, window_name):
+    """Test creating windows with different names."""
+    window = session.new_window(window_name=window_name)
+    assert window.window_name == window_name
+    
+    # Do something with each window
+    pane = window.attached_pane
+    pane.send_keys(f"echo 'Testing window {window_name}'", enter=True)
+    
+    # Verify output
+    import time
+    time.sleep(0.5)
+    output = pane.capture_pane()
+    assert any(f"Testing window {window_name}" in line for line in output)
+```
+
+## Best Practices for Testing with libtmux
+
+1. **Keep tests isolated**: Each test should run in its own tmux environment to prevent interference
+2. **Add sufficient wait times**: Terminal commands take time to execute; add appropriate delays
+3. **Clean up after tests**: Kill sessions you create if not using the automatic fixtures
+4. **Use assertions effectively**: Verify both the state of tmux objects and the visible output
+5. **Handle slow commands**: For commands that may take variable time, implement polling rather than fixed waits
+
+## Debugging Tests
+
+If you're having trouble with your tmux tests, try these techniques:
+
+```python
+def test_with_debugging(pane):
+    """Example showing debugging techniques."""
+    # Capture initial state
+    initial_state = pane.capture_pane()
+    print(f"Initial pane state: {initial_state}")
+    
+    # Send a command
+    pane.send_keys("echo 'Debug test'", enter=True)
+    
+    # Wait with diagnostic output
+    import time
+    for i in range(5):
+        time.sleep(0.1)
+        output = pane.capture_pane()
+        print(f"Output after {i+1} wait cycle: {output}")
+    
+    # Get tmux server information for debugging
+    server_info = pane.server.cmd("info").stdout
+    print(f"Server info: {server_info}")
+    
+    # Get detailed window information
+    window_info = pane.window.cmd("display-message", "-p", "#{window_id} #{window_name}").stdout
+    print(f"Window info: {window_info}")
+    
+    # Assert with detailed error
+    expected_text = "Debug test"
+    output = pane.capture_pane()
+    if not any(expected_text in line for line in output):
+        print(f"Failed to find '{expected_text}' in output: {output}")
+    assert any(expected_text in line for line in output)
+```

docs/pytest-plugin/index.md

@@ -147,3 +147,10 @@ def set_home(
     :show-inheritance:
     :member-order: bysource
 ```
+
+## More
+
+```{toctree}
+
+examples
+```