feat(pytest-plugin): Add executable test examples

- Create a new pytest_examples directory with test files for all examples
- Update the examples.md file to use sphinx literalinclude for including test code
- Enhance pytest-plugin index.md with better explanations and references
- Ensure all examples are properly linted and match project code standards
- Add sections for advanced testing techniques like multi-pane, custom configs, and command polling
- Make examples directly runnable and testable via pytest

Author: tony

docs/pytest-plugin/examples.md

@@ -3,7 +3,7 @@
 # tmux `pytest` plugin
 
 libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an
-independent tmux server.
+independent tmux server, making it easy to test tmux-related functionality with complete isolation.
 
 ```{seealso} Using the pytest plugin?
 
@@ -26,14 +26,24 @@ Install `libtmux` via the python package manager of your choosing, e.g.
 $ pip install libtmux
 ```
 
-The pytest plugin will be automatically detected via pytest, and the fixtures will be added.
+The pytest plugin will be automatically detected via pytest, and the fixtures will be added to your test environment.
+
+### Key Benefits
+
+- **Isolated Testing Environment**: Each test gets a fresh tmux server that won't interfere with other tests
+- **Automatic Cleanup**: Servers, sessions, and other resources are automatically cleaned up after tests
+- **Simplified Setup**: Common fixtures for server, session, window, and pane management
+- **Reliable Testing**: Consistent environment for reproducible test results
+- **Custom Configuration**: Easily test with different tmux configurations and settings
 
 ### Real world usage
 
 View libtmux's own [tests/](https://github.com/tmux-python/libtmux/tree/master/tests) as well as
-tmuxp's [tests/](https://github.com/tmux-python/tmuxp/tree/master/tests).
+tmuxp's [tests/](https://github.com/tmux-python/tmuxp/tree/master/tests) for real-world examples.
 
-libtmux's tests `autouse` the {ref}`recommended-fixtures` above to ensure stable test execution, assertions and
+For more detailed examples with code snippets, see the {ref}`pytest_plugin_examples` page.
+
+libtmux's tests `autouse` the {ref}`recommended-fixtures` below to ensure stable test execution, assertions and
 object lookups in the test grid.
 
 ## pytest-tmux
@@ -137,6 +147,18 @@ def set_home(
     monkeypatch.setenv("HOME", str(user_path))
 ```
 
+## Advanced Testing Techniques
+
+For more sophisticated testing scenarios, see our detailed examples:
+
+1. **Testing with Multiple Panes**: Learn how to test applications that require interaction between multiple panes
+2. **Testing with Custom Configurations**: Set up tests with specific tmux configuration settings
+3. **Managing Temporary Files**: Work with temporary files and directories in your tests
+4. **Advanced Command Polling**: Implement robust waiting for command completion
+5. **Parametrized Testing**: Run the same test with different inputs
+
+See the {ref}`pytest_plugin_examples` page for detailed code examples of these techniques.
+
 ## Fixtures
 
 ```{eval-rst}
@@ -152,5 +174,4 @@ def set_home(
 
 ```{toctree}
 
-examples
-```
+examples

docs/pytest-plugin/index.md

@@ -0,0 +1,4 @@
+"""Example tests for the libtmux pytest plugin.
+
+These examples are used in the documentation and tests.
+"""

tests/pytest_examples/__init__.py

@@ -0,0 +1,65 @@
+"""Basic usage examples for the libtmux pytest plugin."""
+
+from __future__ import annotations
+
+import time
+
+
+def test_basic_server(server, session) -> None:
+    """Test basic server connection.
+
+    Note: We need a session fixture to ensure there's an active session.
+    """
+    # Verify the server has sessions by checking for the session provided by the fixture
+    sessions = server.list_sessions()
+    assert sessions, "Server should have at least one session"
+
+    # Check if the server is responding to commands
+    assert server.cmd("list-sessions").stdout is not None
+
+
+def test_basic_session(session) -> None:
+    """Test basic session functionality."""
+    # Session should be created by the fixture
+    assert session is not None
+
+    # Session should have a name
+    assert session.session_name
+
+    # Get session info
+    session_info = session.cmd("display-message", "-p", "#{session_name}").stdout
+    assert len(session_info) > 0
+
+
+def test_basic_window(session) -> None:
+    """Test basic window creation."""
+    # Create a new window
+    window = session.new_window(window_name="test-window")
+
+    # Verify window was created with the correct name
+    assert window.window_name == "test-window"
+
+    # Get the number of panes in the window
+    assert len(window.panes) == 1
+
+    # Rename the window
+    window.rename_window("renamed-window")
+    assert window.window_name == "renamed-window"
+
+
+def test_basic_pane(session) -> None:
+    """Test basic pane functionality."""
+    window = session.new_window(window_name="pane-test")
+    pane = window.active_pane
+
+    # Send a command to the pane
+    pane.send_keys("echo 'Hello, tmux!'", enter=True)
+
+    # Give the command time to execute
+    time.sleep(0.5)
+
+    # Capture the pane output
+    output = pane.capture_pane()
+
+    # Verify the output contains our message
+    assert any("Hello, tmux!" in line for line in output)

tests/pytest_examples/test_basic_usage.py

@@ -0,0 +1,76 @@
+"""Examples for command polling in tmux tests."""
+
+from __future__ import annotations
+
+import time
+
+
+def test_command_with_polling(session) -> None:
+    """Test running a command and polling for completion."""
+    # Create a window for testing
+    window = session.new_window(window_name="polling-test")
+    pane = window.active_pane
+
+    # Clear the pane
+    pane.send_keys("clear", enter=True)
+    time.sleep(0.3)
+
+    # Run a command that takes some time (using sleep)
+    pane.send_keys("echo 'Starting task'; sleep 2; echo 'Task complete'", enter=True)
+
+    # Poll for completion by checking for the completion message
+    max_polls = 10
+    poll_interval = 0.5
+    completion_found = False
+
+    for _ in range(max_polls):
+        output = pane.capture_pane()
+        if any("Task complete" in line for line in output):
+            completion_found = True
+            break
+        time.sleep(poll_interval)
+
+    # Verify the task completed
+    assert completion_found, "Task did not complete within the expected time"
+
+    # Additional verification that both messages are in the output
+    final_output = pane.capture_pane()
+    assert any("Starting task" in line for line in final_output)
+    assert any("Task complete" in line for line in final_output)
+
+
+def test_error_handling(session) -> None:
+    """Test error handling during command execution."""
+    # Create a window for testing
+    window = session.new_window(window_name="error-test")
+    pane = window.active_pane
+
+    # Clear the pane
+    pane.send_keys("clear", enter=True)
+    time.sleep(0.3)
+
+    # Run a command that will produce an error
+    pane.send_keys(
+        "echo 'Running command with error'; "
+        "ls /nonexistent_directory; "
+        "echo 'Command finished'",
+        enter=True,
+    )
+    time.sleep(1)  # Wait for command to complete
+
+    # Capture the output
+    output = pane.capture_pane()
+
+    # Verify error message and completion message
+    assert any("Running command with error" in line for line in output), (
+        "Start message not found"
+    )
+    assert any("Command finished" in line for line in output), (
+        "Completion message not found"
+    )
+
+    # Verify error message is in the output
+    has_error = any("No such file or directory" in line for line in output) or any(
+        "cannot access" in line for line in output
+    )
+    assert has_error, "Error message not found in output"

tests/pytest_examples/test_command_polling.py

@@ -0,0 +1,34 @@
+"""Examples for working with custom tmux configurations."""
+
+from __future__ import annotations
+
+import time
+
+
+def test_with_custom_config(TestServer, tmp_path) -> None:
+    """Test using a custom tmux configuration."""
+    # Create a custom tmux configuration file
+    config_file = tmp_path / "tmux.conf"
+    # Simply test with a history-limit change which is more reliable
+    config_file.write_text("set -g history-limit 5000")
+
+    # Create a server with the custom configuration
+    server = TestServer(config_file=str(config_file))
+
+    # Create a session to ensure the server is active
+    session = server.new_session("custom-config-test")
+
+    # Verify server has our session
+    assert server.has_session("custom-config-test")
+
+    # Test that we can run commands in the session, which proves the config is working
+    window = session.active_window
+    pane = window.active_pane
+
+    # Send a command
+    pane.send_keys("echo 'Testing custom config'", enter=True)
+    time.sleep(0.5)
+
+    # Verify the command was executed
+    output = pane.capture_pane()
+    assert any("Testing custom config" in line for line in output)

tests/pytest_examples/test_custom_config.py

@@ -0,0 +1,112 @@
+"""Examples for working with custom environment in tmux tests."""
+
+from __future__ import annotations
+
+import os
+import time
+
+
+def test_environment_variables(session) -> None:
+    """Test setting and using environment variables."""
+    # Create a window for testing
+    window = session.new_window(window_name="env-test")
+    pane = window.active_pane
+
+    # Set environment variables for the pane
+    test_env = {
+        "TEST_VAR1": "value1",
+        "TEST_VAR2": "value2",
+        "TEST_PATH": "/custom/path:/another/path",
+    }
+
+    # Clear the pane first
+    pane.send_keys("clear", enter=True)
+    time.sleep(0.3)
+
+    # Set environment variables
+    for key, value in test_env.items():
+        pane.send_keys(f"export {key}='{value}'", enter=True)
+
+    time.sleep(0.5)
+
+    # Verify environment variables were set
+    pane.send_keys("echo $TEST_VAR1", enter=True)
+    time.sleep(0.5)
+    output = pane.capture_pane()
+    assert any("value1" in line for line in output)
+
+    # Test with a script that uses the variables
+    pane.send_keys('echo "Combined: $TEST_VAR1 and $TEST_VAR2"', enter=True)
+    time.sleep(0.5)
+    output = pane.capture_pane()
+    assert any("Combined: value1 and value2" in line for line in output)
+
+
+def test_directory_navigation(session, tmp_path) -> None:
+    """Test navigating directories in tmux."""
+    # Create a window for testing
+    window = session.new_window(window_name="dir-test")
+    pane = window.active_pane
+
+    # Clear the pane
+    pane.send_keys("clear", enter=True)
+    time.sleep(0.3)
+
+    # Get and save the initial directory to tmp_path
+    initial_dir_file = tmp_path / "initial_dir.txt"
+    pane.send_keys(f"pwd > {initial_dir_file}", enter=True)
+    time.sleep(0.5)
+
+    # Navigate to /tmp directory
+    pane.send_keys("cd /tmp", enter=True)
+    time.sleep(0.5)
+
+    # Verify we changed directory
+    pane.send_keys("pwd", enter=True)
+    time.sleep(0.5)
+    output = pane.capture_pane()
+    assert any("/tmp" in line for line in output)
+
+    # Create a test directory and navigate to it
+    test_dir = f"tmux_test_{os.getpid()}"
+    pane.send_keys(f"mkdir -p {test_dir}", enter=True)
+    pane.send_keys(f"cd {test_dir}", enter=True)
+    time.sleep(0.5)
+
+    # Verify we're in the test directory
+    pane.send_keys("pwd", enter=True)
+    time.sleep(0.5)
+    output = pane.capture_pane()
+    assert any(f"/tmp/{test_dir}" in line for line in output)
+
+    # Clean up
+    pane.send_keys("cd ..", enter=True)
+    pane.send_keys(f"rm -r {test_dir}", enter=True)
+
+
+def test_custom_session(TestServer) -> None:
+    """Test creating a session with custom parameters."""
+    # Create a new server instance
+    server = TestServer()
+
+    # Create a session with custom parameters
+    session_params = {
+        "session_name": "custom-session",
+        "x": 800,
+        "y": 600,
+        "start_directory": "/tmp",
+    }
+
+    session = server.new_session(**session_params)
+
+    # Verify session was created with the right name
+    assert session.session_name == "custom-session"
+
+    # Verify working directory was set correctly
+    window = session.active_window
+    pane = window.active_pane
+
+    pane.send_keys("pwd", enter=True)
+    time.sleep(0.5)
+    output = pane.capture_pane()
+    assert any("/tmp" in line for line in output)