From f183aac117f2d37b0d3115f4b4eac8dc3a0c5740 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 18 Sep 2022 21:59:13 -0500 Subject: [PATCH 1/5] tests: Add doctests --- src/libtmux/test.py | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) 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)) + + """ 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. From fc75c0d2350b343d433da20d0ce2db2c0637ae4a Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 18 Sep 2022 22:07:15 -0500 Subject: [PATCH 2/5] docs: pytest-plugin/ --- docs/index.md | 2 +- docs/{pytest-plugin.md => pytest-plugin/index.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{pytest-plugin.md => pytest-plugin/index.md} (100%) 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/pytest-plugin.md b/docs/pytest-plugin/index.md similarity index 100% rename from docs/pytest-plugin.md rename to docs/pytest-plugin/index.md From 3e7d5b04c323d19da69020dc8be00d5ec4ddd6c6 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 18 Sep 2022 22:07:56 -0500 Subject: [PATCH 3/5] docs(redirects): Update to pytest-plugin --- docs/redirects.txt | 1 + 1 file changed, 1 insertion(+) 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" From 3df720945ae979e508eeae32599803922edd6bad Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 18 Sep 2022 22:09:02 -0500 Subject: [PATCH 4/5] docs(tests): Move into pytest --- docs/internals/index.md | 5 ----- docs/pytest-plugin/index.md | 5 +++++ docs/{internals => pytest-plugin}/test.md | 0 3 files changed, 5 insertions(+), 5 deletions(-) rename docs/{internals => pytest-plugin}/test.md (100%) 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/pytest-plugin/index.md b/docs/pytest-plugin/index.md index 36b727d34..9fa2670af 100644 --- a/docs/pytest-plugin/index.md +++ b/docs/pytest-plugin/index.md @@ -5,6 +5,11 @@ libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an independent tmux server. +```{toctree} + +test +``` + ```{seealso} Using the pytest plugin? Do you want more flexbility? Correctness? Power? Defaults changed? [Connect with us] on the tracker, we want to know 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 From 1f1aebacbc7ab571f62499242d7674565e746934 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 18 Sep 2022 22:13:37 -0500 Subject: [PATCH 5/5] docs: Organize pytest-plugin --- docs/pytest-plugin/index.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/pytest-plugin/index.md b/docs/pytest-plugin/index.md index 9fa2670af..bceb87f08 100644 --- a/docs/pytest-plugin/index.md +++ b/docs/pytest-plugin/index.md @@ -5,11 +5,6 @@ libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an independent tmux server. -```{toctree} - -test -``` - ```{seealso} Using the pytest plugin? Do you want more flexbility? Correctness? Power? Defaults changed? [Connect with us] on the tracker, we want to know @@ -33,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 ` - so read up on those! @@ -82,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 @@ -100,3 +95,11 @@ object lookups in the test grid. :show-inheritance: :member-order: bysource ``` + +## Test utilities + +```{toctree} +:maxdepth: 1 + +test +```