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

Issue:
Migrate `libtmux.test` into `libtmux.pytest_plugin`
Also #427


-   [Test helpers](https://libtmux.git-pull.com/internals/test.html)
    -   [retry_until()](https://libtmux.git-pull.com/internals/test.html#libtmux.test.retry_until)
    -   [get_test_session_name()](https://libtmux.git-pull.com/internals/test.html#libtmux.test.get_test_session_name)
    -   [get_test_window_name()](https://libtmux.git-pull.com/internals/test.html#libtmux.test.get_test_window_name)
    -   [temp_session()](https://libtmux.git-pull.com/internals/test.html#libtmux.test.temp_session)
    -   [temp_window()](https://libtmux.git-pull.com/internals/test.html#libtmux.test.temp_window) #427
    -   [EnvironmentVarGuard](https://libtmux.git-pull.com/internals/test.html#libtmux.test.EnvironmentVarGuard)


Discussion / hints:

Fix patch:
diff --git a/docs/index.md b/docs/index.md
index a908e3e37..67c779bcf 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,7 +19,7 @@ quickstart
 about
 topics/index
 reference/index
-pytest-plugin
+pytest-plugin/index
 ```
 
 ```{toctree}
diff --git a/docs/internals/index.md b/docs/internals/index.md
index 531cfbbfd..348a1df32 100644
--- a/docs/internals/index.md
+++ b/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)=
diff --git a/docs/redirects.txt b/docs/redirects.txt
index c237369f5..9188d36fa 100644
--- a/docs/redirects.txt
+++ b/docs/redirects.txt
@@ -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"


Test patch:
diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin/index.md
similarity index 96%
rename from docs/pytest-plugin.md
rename to docs/pytest-plugin/index.md
index 36b727d34..bceb87f08 100644
--- a/docs/pytest-plugin.md
+++ b/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
+```
diff --git a/docs/internals/test.md b/docs/pytest-plugin/test.md
similarity index 100%
rename from docs/internals/test.md
rename to docs/pytest-plugin/test.md
diff --git a/src/libtmux/test.py b/src/libtmux/test.py
index 19e9a8b29..ae65716bd 100644
--- a/src/libtmux/test.py
+++ b/src/libtmux/test.py
@@ -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,7 +286,6 @@ def temp_window(
 
 
 class EnvironmentVarGuard:
-
     """Mock environmental variables safetly.
 
     Helps rotect the environment variable properly.  Can be used as context
@@ -270,13 +293,11 @@ class EnvironmentVarGuard:
 
     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.