docs: restructure pytest plugin documentation for enhanced Sphinx+MyST readability

Author: tony

docs/pytest-plugin/advanced-techniques.md

@@ -0,0 +1,168 @@
+---
+myst:
+  html_meta:
+    description: "Advanced techniques for testing with the libtmux pytest plugin"
+    keywords: "tmux, pytest, advanced testing, polling, temporary files"
+---
+
+(advanced-techniques)=
+
+# Advanced Techniques
+
+This page covers advanced testing techniques using the libtmux pytest plugin for more sophisticated testing scenarios.
+
+## Testing with Temporary Files
+
+### Creating Temporary Project Directories
+
+```{literalinclude} ../../tests/pytest_examples/test_temp_files.py
+:language: python
+:pyobject: temp_project_dir
+```
+
+### Working with Files in Temporary Directories
+
+```{literalinclude} ../../tests/pytest_examples/test_temp_files.py
+:language: python
+:pyobject: test_project_file_manipulation
+```
+
+## Command Polling
+
+### Implementing Robust Wait Functions
+
+```{literalinclude} ../../tests/pytest_examples/test_command_polling.py
+:language: python
+:pyobject: wait_for_output
+```
+
+### Testing with Command Polling
+
+```{literalinclude} ../../tests/pytest_examples/test_command_polling.py
+:language: python
+:pyobject: test_command_with_polling
+```
+
+### Error Handling with Polling
+
+```{literalinclude} ../../tests/pytest_examples/test_command_polling.py
+:language: python
+:pyobject: test_error_handling
+```
+
+## Setting Custom Home Directory
+
+### Temporary Home Directory Setup
+
+```{literalinclude} ../../tests/pytest_examples/test_home_directory.py
+:language: python
+:pyobject: set_home
+```
+
+## Testing Across tmux Server Restarts
+
+For testing functionality that needs to persist across server restarts:
+
+```python
+def test_persist_across_restart(session):
+    """Test functionality across server restarts."""
+    # Set up initial state
+    window = session.new_window(window_name="persist-test")
+    pane = window.active_pane
+    pane.send_keys("echo 'Data to persist' > /tmp/test-data.txt", enter=True)
+    time.sleep(0.5)
+    
+    # Get server info for reconnecting
+    socket_path = session.server.socket_path
+    session_id = session.id
+    
+    # Kill the server
+    session.server.kill_server()
+    
+    # Create a new server with the same socket
+    new_server = libtmux.Server(socket_path=socket_path)
+    new_server.new_session(session_name="restart-test")
+    
+    # Verify data persisted
+    new_session = new_server.get_by_id(session_id)
+    assert new_session is None  # Old session should not exist
+    
+    # But our file should still exist
+    new_pane = new_server.sessions[0].attached_window.active_pane
+    new_pane.send_keys("cat /tmp/test-data.txt", enter=True)
+    time.sleep(0.5)
+    
+    output = new_pane.capture_pane()
+    assert any("Data to persist" in line for line in output)
+    
+    # Clean up
+    new_pane.send_keys("rm /tmp/test-data.txt", enter=True)
+```
+
+## Testing with Complex Layouts
+
+Creating and testing more complex window layouts:
+
+```python
+def test_complex_layouts(session):
+    """Test creating and interacting with complex window layouts."""
+    # Create a window with multiple panes in a specific layout
+    window = session.new_window(window_name="complex-layout")
+    
+    # Start with a simple pane
+    main_pane = window.active_pane
+    
+    # Split into a left pane and right column
+    left_pane = main_pane
+    right_top = window.split(direction="right", percent=50)
+    
+    # Split the right column into top and bottom
+    right_bottom = right_top.split(direction="below", percent=50)
+    
+    # Apply a layout
+    window.select_layout("main-vertical")
+    
+    # Verify the layout was applied
+    assert window.get("window_layout") != None
+    
+    # Send unique commands to each pane for identification
+    left_pane.send_keys("echo 'Left Pane'", enter=True)
+    right_top.send_keys("echo 'Right Top'", enter=True)
+    right_bottom.send_keys("echo 'Right Bottom'", enter=True)
+    
+    time.sleep(0.5)
+    
+    # Verify each pane has the correct content
+    assert any("Left Pane" in line for line in left_pane.capture_pane())
+    assert any("Right Top" in line for line in right_top.capture_pane())
+    assert any("Right Bottom" in line for line in right_bottom.capture_pane())
+```
+
+## Best Practices
+
+### Test Structure
+
+1. **Arrange** - Set up your tmux environment and test data
+2. **Act** - Perform the actions you want to test
+3. **Assert** - Verify the expected outcome
+4. **Clean up** - Reset any state changes (usually handled by fixtures)
+
+### Tips for Reliable Tests
+
+1. **Use appropriate waits**: Terminal operations aren't instantaneous. Add sufficient wait times or use polling techniques.
+
+2. **Capture full pane contents**: Use `pane.capture_pane()` to get all output content for verification.
+
+3. **Isolate tests**: Don't rely on state from other tests. Each test should set up its own environment.
+
+4. **Use descriptive assertions**: When tests fail, the assertion message should clarify what went wrong.
+
+5. **Test error conditions**: Include tests for error handling to ensure your code behaves correctly in failure scenarios.
+
+6. **Keep tests fast**: Minimize wait times while keeping tests reliable.
+
+7. **Use parametrized tests**: For similar tests with different inputs, use pytest's parametrize feature.
+
+8. **Document test requirements**: If tests require specific tmux features, document this in comments.
+
+9. **Mind CI environments**: Tests should work consistently in both local and CI environments, which may have different tmux versions and capabilities.