docs(pytest-plugin) Examples to test files

Author: tony

docs/pytest-plugin/index.md

@@ -86,19 +86,16 @@ You could also read the code and override {func}`server fixture <libtmux.pytest_
 You can override `session_params` to customize the `session` fixture. The
 dictionary will directly pass into {meth}`Server.new_session` keyword arguments.
 
-```python
-import pytest
-
-@pytest.fixture
-def session_params():
-    return {
-        'x': 800,
-        'y': 600
-    }
+```{literalinclude} ../../tests/pytest_examples/test_session_params.py
+:language: python
+:pyobject: session_params
+```
 
+Simple test using the custom session parameters:
 
-def test_something(session):
-    assert session
+```{literalinclude} ../../tests/pytest_examples/test_session_params.py
+:language: python
+:pyobject: test_custom_session_dimensions
 ```
 
 The above will assure the libtmux session launches with `-x 800 -y 600`.
@@ -109,24 +106,16 @@ The above will assure the libtmux session launches with `-x 800 -y 600`.
 
 If you need multiple independent tmux servers in your tests, the {func}`TestServer fixture <libtmux.pytest_plugin.TestServer>` provides a factory that creates servers with unique socket names. Each server is automatically cleaned up when the test completes.
 
-```python
-def test_something(TestServer):
-    Server = TestServer()  # Get unique partial'd Server
-    server = Server()      # Create server instance
-    
-    session = server.new_session()
-    assert server.is_alive()
+```{literalinclude} ../../tests/pytest_examples/test_multiple_servers.py
+:language: python
+:pyobject: test_basic_test_server
 ```
 
 You can also use it with custom configurations, similar to the {ref}`server fixture <Setting a tmux configuration>`:
 
-```python
-def test_with_config(TestServer, tmp_path):
-    config_file = tmp_path / "tmux.conf"
-    config_file.write_text("set -g status off")
-    
-    Server = TestServer()
-    server = Server(config_file=str(config_file))
+```{literalinclude} ../../tests/pytest_examples/test_multiple_servers.py
+:language: python
+:pyobject: test_with_config
 ```
 
 This is particularly useful when testing interactions between multiple tmux servers or when you need to verify behavior across server restarts.
@@ -135,16 +124,9 @@ This is particularly useful when testing interactions between multiple tmux serv
 
 ### Setting a temporary home directory
 
-```python
-import pathlib
-import pytest
-
-@pytest.fixture(autouse=True, scope="function")
-def set_home(
-    monkeypatch: pytest.MonkeyPatch,
-    user_path: pathlib.Path,
-):
-    monkeypatch.setenv("HOME", str(user_path))
+```{literalinclude} ../../tests/pytest_examples/test_home_directory.py
+:language: python
+:pyobject: set_home
 ```
 
 ## Advanced Testing Techniques

tests/pytest_examples/test_home_directory.py

@@ -0,0 +1,75 @@
+"""Examples for setting up a temporary home directory for tests.
+
+This file demonstrates how to set up and use a temporary home directory
+for tests, which is useful for isolating configuration files.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    import pathlib
+
+
+@pytest.fixture(autouse=True)
+def set_home(
+    monkeypatch: pytest.MonkeyPatch,
+    user_path: pathlib.Path,
+) -> None:
+    """Set the HOME environment variable to a temporary directory."""
+    monkeypatch.setenv("HOME", str(user_path))
+
+
+def test_home_directory_set(session) -> None:
+    """Test that the HOME environment variable is set correctly."""
+    # Get the active pane to run commands
+    pane = session.active_window.active_pane
+
+    # Execute a command to print the HOME directory
+    pane.send_keys("echo $HOME", enter=True)
+
+    # Wait for the command to execute
+    time.sleep(1)
+
+    # Capture the output
+    output = pane.capture_pane()
+
+    # Get what we expect the HOME to be
+    expected_home = os.environ.get("HOME")
+    assert expected_home, "HOME environment variable not set"
+
+    # The output should include the HOME path somewhere
+    found_home = False
+    for line in output:
+        if expected_home in line:
+            found_home = True
+            break
+
+    assert found_home, f"Expected to find {expected_home} in output: {output}"
+
+
+def test_create_config_in_home(session, user_path) -> None:
+    """Test creating and using configuration in the temporary home directory."""
+    # Create a simple configuration file in the home directory
+    config_file = user_path / ".my-test-config"
+    config_file.write_text("test-config-value")
+
+    # Get the active pane to run commands
+    pane = session.active_window.active_pane
+
+    # Execute a command to check the config file exists
+    pane.send_keys(f"cat {config_file}", enter=True)
+
+    # Wait a moment for the command to execute
+    time.sleep(1)
+
+    # Capture and verify the output
+    output = pane.capture_pane()
+    assert any("test-config-value" in line for line in output), (
+        "Config file content not found"
+    )

tests/pytest_examples/test_multiple_servers.py

@@ -0,0 +1,69 @@
+"""Examples for working with multiple tmux servers.
+
+This file contains examples of using the TestServer fixture to create
+and manage multiple independent tmux server instances.
+"""
+
+from __future__ import annotations
+
+
+def test_basic_test_server(TestServer) -> None:
+    """Test creating and using a server via TestServer fixture."""
+    # TestServer returns a partial Server class that we can instantiate
+    ServerClass = TestServer()  # Get uniquely configured Server class
+    server = ServerClass  # This is already an instance, not a class
+
+    server.new_session()
+    assert server.is_alive()
+
+    # Clean up is automatic at the end of the test
+
+
+def test_with_config(TestServer, tmp_path) -> None:
+    """Test creating a server with custom configuration."""
+    # Create a custom tmux configuration in the temporary directory
+    config_file = tmp_path / "tmux.conf"
+    config_file.write_text("set -g status off")
+
+    # Create a server using this configuration
+    ServerClass = TestServer()
+    # Override the server with a new one that uses our config
+    server = type(ServerClass)(config_file=str(config_file))
+
+    # Verify the server is running
+    assert server.is_alive()
+
+    # Create a session to work with
+    server.new_session()
+
+    # Optional: Verify the configuration was applied
+    # This would require specific tests for the status being off
+
+    # Clean up is automatic at the end of the test
+
+
+def test_multiple_independent_servers(TestServer) -> None:
+    """Test running multiple independent tmux servers simultaneously."""
+    # Create first server
+    ServerClass1 = TestServer()
+    server1 = ServerClass1  # This is already an instance
+    session1 = server1.new_session(session_name="session1")
+
+    # Create second server (completely independent)
+    ServerClass2 = TestServer()
+    server2 = ServerClass2  # This is already an instance
+    session2 = server2.new_session(session_name="session2")
+
+    # Verify both servers are running
+    assert server1.is_alive()
+    assert server2.is_alive()
+
+    # Verify sessions exist on their respective servers only
+    assert session1.server is server1
+    assert session2.server is server2
+
+    # Verify session names are independent
+    assert session1.name == "session1"
+    assert session2.name == "session2"
+
+    # Clean up is automatic at the end of the test

tests/pytest_examples/test_session_params.py

@@ -0,0 +1,23 @@
+"""Example test demonstrating custom session parameters.
+
+This example shows how to customize the session fixture parameters.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture
+def session_params():
+    """Override session_params to specify custom session dimensions."""
+    return {"x": 800, "y": 600}
+
+
+def test_custom_session_dimensions(session) -> None:
+    """Test that session is created with custom dimensions."""
+    assert session
+
+    # Optional: Additional assertions about session dimensions
+    # These would require accessing tmux directly to verify the dimensions
+    # but we include the example for documentation completeness