docs,tests: Improve test utility fixtures (#437)

Author: tony

docs/index.md

@@ -19,7 +19,7 @@ quickstart
 about
 topics/index
 reference/index
-pytest-plugin
+pytest-plugin/index
 ```
 
 ```{toctree}

docs/internals/index.md

@@ -8,11 +8,6 @@ These APIs are internal and not covered by versioning policy.
 
 :::
 
-```{toctree}
-
-test
-```
-
 ## Environmental variables
 
 (LIBTMUX_TMUX_FORMAT_SEPARATOR)=

docs/pytest-plugin.md renamed to docs/pytest-plugin/index.md

@@ -28,7 +28,15 @@ $ pip install libtmux
 
 The pytest plugin will be automatically detected via pytest, and the fixtures will be added.
 
-## Fixtures
+### 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).
+
+libtmux's tests `autouse` the {ref}`recommended-fixtures` above to ensure stable, assertions and
+object lookups in the test grid.
+
+## pytest-tmux
 
 `pytest-tmux` works through providing {ref}`pytest fixtures <pytest:fixtures-api>` - so read up on
 those!
@@ -77,15 +85,7 @@ def set_home(
     monkeypatch.setenv("HOME", str(user_path))
 ```
 
-## See examples
-
-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).
-
-libtmux's tests `autouse` the {ref}`recommended-fixtures` above to ensure stable, assertions and
-object lookups in the test grid.
-
-## API reference
+## Fixtures
 
 ```{eval-rst}
 .. automodule:: libtmux.pytest_plugin
@@ -95,3 +95,11 @@ object lookups in the test grid.
     :show-inheritance:
     :member-order: bysource
 ```
+
+## Test utilities
+
+```{toctree}
+:maxdepth: 1
+
+test
+```

docs/internals/test.md renamed to docs/pytest-plugin/test.md

@@ -5,3 +5,4 @@
 "traversal.md" "topics/traversal.md"
 "sessions.md" "reference/sessions.md"
 "api.md" "internals/index.md"
+"pytest-plugin.md" "pytest-plugin/index.md"

docs/redirects.txt

@@ -27,6 +27,16 @@ class RandomStrSequence:
     def __init__(
         self, characters: str = "abcdefghijklmnopqrstuvwxyz0123456789_"
     ) -> None:
+        """Create a random letter / number generator. 8 chars in length.
+
+        >>> rng = RandomStrSequence()
+        >>> next(rng)
+        '...'
+        >>> len(next(rng))
+        8
+        >>> type(next(rng))
+        <class 'str'>
+        """
         self.characters: str = characters
 
     def __iter__(self) -> "RandomStrSequence":
@@ -68,7 +78,6 @@ def retry_until(
 
     Examples
     --------
-
     >>> def fn():
     ...     p = session.attached_window.attached_pane
     ...     p.server._update_panes()
@@ -110,6 +119,15 @@ def get_test_session_name(server: "Server", prefix: str = TEST_SESSION_PREFIX) -
     -------
     str
         Random session name guaranteed to not collide with current ones.
+
+    Examples
+    --------
+    >>> get_test_session_name(server=server)
+    'libtmux_...'
+
+    Never the same twice:
+    >>> get_test_session_name(server=server) != get_test_session_name(server=server)
+    True
     """
     while True:
         session_name = prefix + next(namer)
@@ -138,6 +156,15 @@ def get_test_window_name(
     -------
     str
         Random window name guaranteed to not collide with current ones.
+
+    Examples
+    --------
+    >>> get_test_window_name(session=session)
+    'libtmux_...'
+
+    Never the same twice:
+    >>> get_test_window_name(session=session) != get_test_window_name(session=session)
+    True
     """
     assert prefix is not None
     while True:
@@ -178,10 +205,9 @@ def temp_session(
 
     Examples
     --------
-
     >>> with temp_session(server) as session:
     ...     session.new_window(window_name='my window')
-    Window(@... ...:..., Session($... ...))
+    Window(@3 2:my window, Session($... ...))
     """
 
     if "session_name" in kwargs:
@@ -230,17 +256,15 @@ def temp_window(
 
     Examples
     --------
-
     >>> with temp_window(session) as window:
     ...     window
-    Window(@... ...:..., Session($... ...))
+    Window(@2 2:... Session($1 libtmux_...))
 
 
     >>> with temp_window(session) as window:
     ...     window.split_window()
-    Pane(%... Window(@... ...:..., Session($... ...)))
+    Pane(%4 Window(@3 2:libtmux_..., Session($1 libtmux_...)))
     """
-
     if "window_name" not in kwargs:
         window_name = get_test_window_name(session)
     else:
@@ -262,21 +286,18 @@ def temp_window(
 
 
 class EnvironmentVarGuard:
-
     """Mock environmental variables safetly.
 
     Helps rotect the environment variable properly.  Can be used as context
     manager.
 
     Notes
     -----
-
     Vendorized to fix issue with Anaconda Python 2 not including test module,
     see #121 [1]_
 
     References
     ----------
-
     .. [1] Just installed, "ImportError: cannot import name test_support".
        GitHub issue for tmuxp. https://github.com/tmux-python/tmuxp/issues/121.
        Created October 12th, 2015. Accessed April 7th, 2018.