Add docs for test utilities. Add get_test_window_name and temp_window.

temp_session now passes thru to Server.new_session's args.

Author: tony

doc/api.rst

@@ -125,4 +125,17 @@ Exceptions
 
 .. autoexception:: tmuxp.exc.ConfigError
 
+Test tools
+----------
+
+.. automethod:: tmuxp.testsuite.helpers.get_test_session_name
+
+.. automethod:: tmuxp.testsuite.helpers.get_test_window_name
+
+.. automethod:: tmuxp.testsuite.helpers.get_test_pane_name
+
+.. automethod:: tmuxp.testsuite.helpers.temp_session
+
+.. automethod:: tmuxp.testsuite.helpers.temp_window
 
+.. automethod:: tmuxp.testsuite.helpers.temp_pane

tmuxp/testsuite/__init__.py

@@ -10,23 +10,27 @@
 
 import logging
 import sys
-
-from .. import log
-from .._compat import string_types, PY2, reraise
-from ..server import Server
+import pkgutil
 
 try:
     import unittest2 as unittest
 except ImportError:  # Python 2.7
     import unittest
 
-import pkgutil
-
-logger = logging.getLogger()
+from .. import log
+from .._compat import string_types, PY2, reraise
+from ..server import Server
 
 t = Server()
 t.socket_name = 'tmuxp_test'
 
+from . import helpers
+
+
+# Logger functionality
+
+logger = logging.getLogger()
+
 if not logger.handlers:
     channel = logging.StreamHandler()
     channel.setFormatter(log.DebugLogFormatter())

tmuxp/testsuite/helpers.py

@@ -36,6 +36,14 @@ def get_test_session_name(server, prefix='tmuxp_'):
     return session_name
 
 
+def get_test_window_name(session, prefix='tmuxp_'):
+    while True:
+        window_name = prefix + str(randint(0, 9999999))
+        if not session.findWhere(window_name=window_name):
+            break
+    return window_name
+
+
 @contextlib.contextmanager
 def temp_session(server, session_name=None):
     if not session_name:
@@ -50,6 +58,81 @@ def temp_session(server, session_name=None):
     return
 
 
+@contextlib.contextmanager
+def temp_session(server, *args, **kwargs):
+    """Return a context manager with a temporary session.
+
+    e.g.::
+
+        with temp_session(server) as session:
+            session.new_window(window_name='my window')
+
+    The session will destroy itself upon closing with :meth:`Session.
+    kill_session()`.
+
+    If no ``session_name`` is entered, :func:`get_test_session_name` will make
+    an unused session name.
+
+    :args: Same arguments as :meth:`Server.new_session`
+    :yields: Temporary session
+    :rtype: :class:`Session`
+    """
+
+    if 'session_name' in kwargs:
+        session_name = kwargs.pop('session_name')
+    else:
+        session_name = get_test_session_name(server)
+
+    print(kwargs)
+
+    session = server.new_session(session_name, *args, **kwargs)
+
+    try:
+        yield session
+    finally:
+        if server.has_session(session_name):
+            session.kill_session()
+    return
+
+
+@contextlib.contextmanager
+def temp_window(session, *args, **kwargs):
+    """Return a context manager with a temporary window.
+
+    e.g.::
+
+        with temp_window(session) as window:
+            my_pane = window.split_window()
+
+    The window will destroy itself upon closing with :meth:`window.
+    kill_window()`.
+
+    If no ``window_name`` is entered, :func:`get_test_window_name` will make
+    an unused window name.
+
+    :args: Same arguments as :meth:`Session.new_window`
+    :yields: Temporary window
+    :rtype: :class:`Window`
+    """
+
+    if 'window_name' not in kwargs:
+        window_name = get_test_window_name(session)
+    else:
+        window_name = kwargs.pop('window_name')
+
+    window = session.new_window(window_name, *args, **kwargs)
+
+    # Get ``window_id`` before returning it, it may be killed within context.
+    window_id = window.get('window_id')
+
+    try:
+        yield session
+    finally:
+        if session.findWhere(window_id=window_id):
+            window.kill_window()
+    return
+
+
 class TestCase(unittest.TestCase):
 
     """Base TestClass so we don't have to try: unittest2 every module. """
@@ -68,6 +151,9 @@ class TmuxTestCase(TestCase):
     #: Session name for the TestCase.
     TEST_SESSION_NAME = None
 
+    def temp_session(self, session_name=None):
+        return temp_session(self.server, session_name)
+
     def setUp(self):
         """Run bootstrap if :attr:`~.session` is not set."""
 

tmuxp/testsuite/test_utils.py

@@ -5,7 +5,7 @@
     with_statement, unicode_literals
 
 from .helpers import get_test_session_name, temp_session, TestCase, \
-    TmuxTestCase, unittest
+    TmuxTestCase, unittest  # , temp_window, temp_pane
 
 
 class TempSession(TmuxTestCase):
@@ -37,6 +37,10 @@ def test_if_session_killed_before(self):
         # really dead?
         self.assertFalse(server.has_session(session_name))
 
+    def test_if_session_name_works(self):
+        """should allow custom ``session_name``."""
+        pass
+
 
 def suite():
     suite = unittest.TestSuite()

tmuxp/testsuite/workspacebuilder.py

@@ -567,7 +567,7 @@ def test_throw_error_if_retcode_false(self):
 
         builder = WorkspaceBuilder(sconf=sconfig)
 
-        with temp_session(self.server) as sess:
+        with self.temp_session() as sess:
             session_name = sess.get('session_name')
 
             with self.assertRaises(subprocess.CalledProcessError):
@@ -591,7 +591,7 @@ def test_throw_error_if_file_not_exists(self):
 
         builder = WorkspaceBuilder(sconf=sconfig)
 
-        with temp_session(self.server) as sess:
+        with self.temp_session() as sess:
             session_name = sess.get('session_name')
             temp_session_exists = self.server.has_session(sess.get('session_name'))
             self.assertTrue(temp_session_exists)
@@ -618,7 +618,7 @@ def test_true_if_test_passes(self):
 
         builder = WorkspaceBuilder(sconf=sconfig)
 
-        with temp_session(self.session.server) as session:
+        with self.temp_session() as session:
             builder.build(session=self.session)