Repository: tmux-python/libtmux (language: python)

Issue:
pytest plugin examples
```
"""
>>> source = ''.join([example.source for example in request._pyfuncitem.dtest.examples])

# >>> test_mod = pytester.makepyfile(whatever=inspect.getsource(test_func))
>>> pytester.makepyfile(**{'whatever.py': source})
PosixPath(...)

# PosixPath('...libtmux.pytest_plugin.py')

>>> result = pytester.runpytest('-p', 'pytester', '--disable-warnings', 'whatever.py')
===...

>>> result.assert_outcomes(errors=0)

"""

```


Discussion / hints:

Fix patch:
diff --git a/CHANGES b/CHANGES
index b29eb230f..de94a41ee 100644
--- a/CHANGES
+++ b/CHANGES
@@ -12,6 +12,12 @@ $ pip install --user --upgrade --pre libtmux
 
 - _Insert changes/features/fixes for next release here_
 
+## libtmux 0.15.3 (unreleased)
+
+### Tests / docs
+
+- Examples for pytest plugin (#439)
+
 ## libtmux 0.15.2 (2022-09-17)
 
 **Maintenance release, no features or fixes**
diff --git a/docs/__init__.py b/docs/__init__.py
new file mode 100644
index 000000000..e69de29bb


Test patch:
diff --git a/conftest.py b/conftest.py
new file mode 100644
index 000000000..c6481d5f7
--- /dev/null
+++ b/conftest.py
@@ -0,0 +1,1 @@
+pytest_plugins = ["pytester"]
diff --git a/src/libtmux/conftest.py b/src/libtmux/conftest.py
index c99992127..cd01c8ad4 100644
--- a/src/libtmux/conftest.py
+++ b/src/libtmux/conftest.py
@@ -24,6 +24,7 @@ def add_doctest_fixtures(
         doctest_namespace["session"] = session
         doctest_namespace["window"] = session.attached_window
         doctest_namespace["pane"] = session.attached_pane
+        doctest_namespace["request"] = request
 
 
 @pytest.fixture(autouse=True, scope="function")
diff --git a/src/libtmux/pytest_plugin.py b/src/libtmux/pytest_plugin.py
index 863e9e44f..186f41092 100644
--- a/src/libtmux/pytest_plugin.py
+++ b/src/libtmux/pytest_plugin.py
@@ -108,7 +108,31 @@ def server(
     monkeypatch: pytest.MonkeyPatch,
     config_file: pathlib.Path,
 ) -> Server:
-    """Returns a new, temporary :class:`libtmux.Server`"""
+    """Returns a new, temporary :class:`libtmux.Server`
+
+    >>> from libtmux.server import Server
+
+    >>> def test_example(server: Server) -> None:
+    ...     assert isinstance(server, Server)
+    ...     session = server.new_session('my session')
+    ...     assert len(server.sessions) == 1
+    ...     assert [session.name.startswith('my') for session in server.sessions]
+
+    .. ::
+        >>> locals().keys()
+        dict_keys(...)
+
+        >>> source = ''.join([e.source for e in request._pyfuncitem.dtest.examples][:3])
+        >>> pytester = request.getfixturevalue('pytester')
+
+        >>> pytester.makepyfile(**{'whatever.py': source})
+        PosixPath(...)
+
+        >>> result = pytester.runpytest('whatever.py', '--disable-warnings')
+        ===...
+
+        >>> result.assert_outcomes(passed=1)
+    """
     t = Server()
     t.socket_name = "libtmux_test%s" % next(namer)
 
@@ -122,7 +146,31 @@ def fin() -> None:
 
 @pytest.fixture(scope="function")
 def session(request: pytest.FixtureRequest, server: Server) -> "Session":
-    """Returns a new, temporary :class:`libtmux.Session`"""
+    """Returns a new, temporary :class:`libtmux.Session`
+
+    >>> from libtmux.session import Session
+
+    >>> def test_example(session: "Session") -> None:
+    ...     assert isinstance(session.name, str)
+    ...     assert session.name.startswith('libtmux_')
+    ...     window = session.new_window(window_name='new one')
+    ...     assert window.name == 'new one'
+
+    .. ::
+        >>> locals().keys()
+        dict_keys(...)
+
+        >>> source = ''.join([e.source for e in request._pyfuncitem.dtest.examples][:3])
+        >>> pytester = request.getfixturevalue('pytester')
+
+        >>> pytester.makepyfile(**{'whatever.py': source})
+        PosixPath(...)
+
+        >>> result = pytester.runpytest('whatever.py', '--disable-warnings')
+        ===...
+
+        >>> result.assert_outcomes(passed=1)
+    """
     session_name = "tmuxp"
 
     if not server.has_session(session_name):