Improve DeferrableViewTestCase (#249)

This commit...

1. adds docstrings to briefly describe test case usage
2. restores preferences after closing view
3. provides basic default settings to apply to a test view via `view_settings`.

   Functionality, which alters content in maybe unexpected or indirect ways,
   may cause unwanted side effects.

4. adds unittests for both `DeferrableViewTestCase` and `ViewTestCase`

Author: deathaxe

tests/_Deferred/tests/test.py

@@ -9,7 +9,7 @@ def test_defer(self):
         self.setCaretTo(0, 0)
         self.defer(100, self.insertText, "foo")
         yield 200
-        self.assertEqual(self.getRowText(0), "foofoo")
+        self.assertRowContentsEqual(0, "foofoo")
 
     def test_condition(self):
         x = []

tests/test_deferrable_view_test_case.py

@@ -0,0 +1,48 @@
+import sublime
+from unittesting import DeferrableViewTestCase
+
+
+class TestViewTestCase(DeferrableViewTestCase):
+
+    def test_window_object(self):
+        self.assertIsInstance(self.window, sublime.Window)
+
+    def test_view_object(self):
+        self.assertIsInstance(self.view, sublime.View)
+
+    def test_view_settings(self):
+        for key, value in self.view_settings.items():
+            self.assertEqual(self.view.settings().get(key), value)
+
+    def test_clear_text_equal(self):
+        self.clearText()
+        yield 10
+        self.assertViewContentsEqual("")
+
+    def test_assert_view_content_equal(self):
+        text = "hello world\ni am here"
+        self.setText(text)
+        yield 10
+        self.assertViewContentsEqual(text)
+
+    def test_assert_row_content_equal(self):
+        self.setText("hello world\ni am here")
+        yield 10
+        self.assertRowContentsEqual(0, "hello world")
+        self.assertRowContentsEqual(1, "i am here")
+
+    def test_assert_caret_at(self):
+        self.setText("hello world")
+        yield 10
+        self.setCaretTo(0, 5)
+        yield 10
+        self.assertCaretAt(0, 5)
+
+    def test_assert_carets_at(self):
+        self.setText("hello world")
+        yield 10
+        self.setCaretTo(0, 5)
+        yield 10
+        self.addCaretAt(0, 10)
+        yield 10
+        self.assertCaretsAt(((0, 5), (0, 10)))

tests/test_view_test_case.py

@@ -0,0 +1,40 @@
+import sublime
+from unittesting import ViewTestCase
+
+
+class TestViewTestCase(ViewTestCase):
+
+    def test_window_object(self):
+        self.assertIsInstance(self.window, sublime.Window)
+
+    def test_view_object(self):
+        self.assertIsInstance(self.view, sublime.View)
+
+    def test_view_settings(self):
+        for key, value in self.view_settings.items():
+            self.assertEqual(self.view.settings().get(key), value)
+
+    def test_clear_text_equal(self):
+        self.clearText()
+        self.assertViewContentsEqual("")
+
+    def test_assert_view_content_equal(self):
+        text = "hello world\ni am here"
+        self.setText(text)
+        self.assertViewContentsEqual(text)
+
+    def test_assert_row_content_equal(self):
+        self.setText("hello world\ni am here")
+        self.assertRowContentsEqual(0, "hello world")
+        self.assertRowContentsEqual(1, "i am here")
+
+    def test_assert_caret_at(self):
+        self.setText("hello world")
+        self.setCaretTo(0, 5)
+        self.assertCaretAt(0, 5)
+
+    def test_assert_carets_at(self):
+        self.setText("hello world")
+        self.setCaretTo(0, 5)
+        self.addCaretAt(0, 10)
+        self.assertCaretsAt(((0, 5), (0, 10)))

unittesting/helpers/view_test_case.py

@@ -10,13 +10,23 @@
 
 
 class ViewTestCaseMixin:
+    view_settings = {
+        "detect_indentation": False,
+        "translate_tabs_to_spaces": False,
+        "word_wrap": False,
+    }
+
     def setUp(self):
-        self.view = sublime.active_window().new_file()
+        self.window = sublime.active_window()
+        self.view = self.window.new_file()
 
         # make sure we have a window to work with
         settings = sublime.load_settings("Preferences.sublime-settings")
-        settings.set("close_windows_when_empty", False)
+        self._orig_close_empty_window = settings.get("close_windows_when_empty")
+        if self._orig_close_empty_window:
+            settings.set("close_windows_when_empty", False)
 
+        # apply pre-defined settings
         settings = self.view.settings()
         default_settings = getattr(self.__class__, "view_settings", {})
         for key, value in default_settings.items():
@@ -27,29 +37,64 @@ def tearDown(self):
             self.view.set_scratch(True)
             self.view.close()
 
+        # restore original settings
+        settings = sublime.load_settings("Preferences.sublime-settings")
+        if self._orig_close_empty_window:
+            settings.set("close_windows_when_empty", self._orig_close_empty_window)
+            self._orig_close_empty_window = False
+
     def addCaretAt(self, row, col):
-        """Add caret to given point (row, col)."""
+        """
+        Add caret to given point (row, col).
+
+        :param row:  The 0-based row number specifying target caret position.
+        :param col:  The 0-based column number specifying target caret position.
+        """
         self.view.sel().add(self.textPoint(row, col))
 
     def setCaretTo(self, row, col):
-        """Move caret to given point (row, col)."""
+        """
+        Move caret to given position (row, col).
+
+        :param row:  The 0-based row number specifying target caret position.
+        :param col:  The 0-based column number specifying target caret position.
+        """
         self.view.sel().clear()
         self.view.sel().add(self.textPoint(row, col))
 
     def textPoint(self, row, col):
-        """Return textpoint for given row,col coordinats."""
+        """
+        Return textpoint for given row,col coordinats.
+
+        This method is an alias for ``self.view.text_point(row, col)``.
+
+        :param row:  The 0-based row number.
+        :param col:  The 0-based column number.
+
+        :returns: Integer value of text point, belowing to row,col combination.
+        """
         return self.view.text_point(row, col)
 
     def getRowText(self, row):
-        """Return given row's content text."""
+        """
+        Return given row's content text.
+
+        :param row: The row to return contents for.
+
+        :return: unicode string with content of given row.
+        """
         return self.view.substr(self.view.line(self.view.text_point(row, 0)))
 
     def getText(self):
         """Return view's content text."""
         return self.view.substr(sublime.Region(0, self.view.size()))
 
     def setText(self, text):
-        """Set whole view's content, replacing anything existing."""
+        """
+        Set whole view's content, replacing anything existing.
+
+        :param text: The text to replace the view's content with.
+        """
         self.clearText()
         self.insertText(text)
 
@@ -59,17 +104,114 @@ def clearText(self):
         self.view.run_command("right_delete")
 
     def insertText(self, text):
-        """Insert text at current position."""
+        """
+        Insert text at current position.
+
+        :param text: The text to insert at current caret position.
+        """
         self.view.run_command("insert", {"characters": text})
 
+    def assertCaretAt(self, row, col):
+        """
+        Assert caret to be located at a certain position.
+
+        :param row:  The 0-based row number.
+        :param col:  The 0-based column number.
+        """
+        self.assertEqual(self.view.sel()[0].begin(), self.textPoint(row, col))
+
+    def assertCaretsAt(self, carets):
+        """
+        Assert carets to be located at a certain positions.
+
+        :param carets:
+            The tuple of (row, col) tuples of 0-based row, col numbers.
+        """
+        expected = tuple(self.textPoint(row, col) for row, col in carets)
+        found = tuple(sel.begin() for sel in self.view.sel())
+        self.assertEqual(found, expected)
+
+    def assertRowContentsEqual(self, row, text):
+        """
+        Expect given row's content to match ``text``.
+
+        :param row:  The 0-based row number.
+        :param col:  The 0-based column number.
+        :param text: The expected content of given row.
+        """
+        self.assertEqual(self.getRowText(row), text)
+
     def assertViewContentsEqual(self, text):
-        self.assertEqual(self.getText(), text)
+        """
+        Expect view's content to match ``text``.
 
+        :param text: The expected content of the view.
+        """
+        self.assertEqual(self.getText(), text)
 
 
 class ViewTestCase(ViewTestCaseMixin, TestCase):
+    """
+    This class describes a  view test case.
+
+    This class provides infrastructure to run unit tests on dedicated ``sublime.View()`` objects.
+
+    A new ``view`` object is created within the active ``window`` for each ``ViewTestCase``.
+
+    The view is accessible via ``self.view`` from within each test method.
+
+    The owning window can be accessed via ``self.window``.
+
+    ```py
+    class MyTestCase(ViewTestCase):
+        # settings to apply to the created view
+        view_settings = {
+            "detect_indentation": False,
+            "tab_size": 4,
+            "translate_tabs_to_spaces": False,
+            "word_wrap": False,
+        }
+
+        def test_editing(self):
+            self.setText("foo")
+            self.setCaretTo(0, 0)
+            self.assertRowContentsEqual(0, "foofoo")
+    ```
+    """
+
     pass
 
 
 class DeferrableViewTestCase(ViewTestCaseMixin, DeferrableTestCase):
+    """
+    This class describes a deferrable view test case.
+
+    This class provides infrastructure to run unit tests on dedicated ``sublime.View()`` objects,
+    which includes catching asynchronous events.
+
+    A new ``view`` object is created within the active ``window`` for each ``ViewTestCase``.
+
+    The view is accessible via ``self.view`` from within each test method.
+
+    The owning window can be accessed via ``self.window``.
+
+    ```py
+    class MyTestCase(DeferrableViewTestCase):
+        # settings to apply to the created view
+        view_settings = {
+            "detect_indentation": False,
+            "tab_size": 4,
+            "translate_tabs_to_spaces": False,
+            "word_wrap": False,
+        }
+
+        def test_editing(self):
+            self.setText("foo")
+            self.setCaretTo(0, 0)
+            self.defer(100, self.insertText, "foo")
+            yield 200
+            self.assertRowContentsEqual(0, "foofoo")
+    ```
+    """
+
     pass