Update document about test utils

docs/test.rst

@@ -1,125 +1,128 @@
 Test Utilities
 ==============
 
-WDOM provides two Utility classes (``WebDriverTestCase`` and
-``RemoteBrowserTestCase``) and some functions for running test on browser with
-Selenium WebDriver.
+.. warning:: This document is incomplete and all APIs are not stable.
 
-WebDriverTestCase class
------------------------
+.. automodule:: wdom.testing
 
-``wdom.testing.WebDriverTestCase`` class is designed for end-to-end UI test,
-which is useful for testing your app on browser. This class runs your app on
-subprocess and prepare WebDriver for tests.
+    .. autofunction:: reset
 
-Usage
-^^^^^
+    .. autofunction:: suppress_logging
 
-Example code using `py.test <http://pytest.org/>`_ as a test runner.
+    .. autoclass:: TestCase
 
-.. code-block:: python
+    .. autoclass:: HTTPTestCase
+      :members:
 
-    # in your_test_dir/conftest.py
-    import pytest
-    from wdom.testing import start_webdriver, close_webdriver
 
-    @pytest.fixture(scope='session', autouse=True)
-    def browser(request):
-        start_webdriver()  # Start WebDriver for this session
-        request.addfinalizer(close_webdriver)
+.. ::
+    WebDriverTestCase class
+    -----------------------
 
+    ``wdom.testing.WebDriverTestCase`` class is designed for end-to-end UI test,
+    which is useful for testing your app on browser. This class runs your app on
+    subprocess and prepare WebDriver for tests.
 
-    # in your test file
-    from unittest import TestCase
-    from wdom.misc import install_asyncio
-    form wdom.testing import WebDriverTestCase
+    Usage
+    ^^^^^
 
-    def setUpModule():
-        install_asyncio()  # force tornado to use asyncio
+    Example code using `py.test <http://pytest.org/>`_ as a test runner.
 
-    class TestApp(WebDriverTestCase, TestCase):
-        def setUp(self):
-            # do some setup, if need.
-            super().setUp()  # MUST call base class's setUp.
+    .. code-block:: python
 
-        def get_app() -> wdom.server.Application:
-            # Prepare and return application you want to test
-            return your_app
+        # in your_test_dir/conftest.py
+        import pytest
+        from wdom.testing import start_webdriver, close_webdriver
 
-        def test_case1(self):
-            # Write your test here
-            self.wd.get(self.url)  # you can access webdriver by self.wd
+        @pytest.fixture(scope='session', autouse=True)
+        def browser(request):
+            start_webdriver()  # Start WebDriver for this session
+            request.addfinalizer(close_webdriver)
 
-        def test_case2(self):
-            # Write your another test here
-            ...
 
+        # in your test file
+        from unittest import TestCase
+        from wdom.misc import install_asyncio
+        form wdom.testing import WebDriverTestCase
 
-RemoteBrowserTestCase Class
-----------------------------
+        def setUpModule():
+            install_asyncio()  # force tornado to use asyncio
 
-``RemoteBrowserTestCase`` class is design to test ``wdom`` itself. Its features
-might not be so useful for library's users. ``RemoteBrowserTestCase`` class
-helps you to test your app by directly controlling ``Node`` object on python,
-from test scripts in the same process. This class is **Largely Experimental**.
+        class TestApp(WebDriverTestCase, TestCase):
+            def setUp(self):
+                # do some setup, if need.
+                super().setUp()  # MUST call base class's setUp.
 
-``RemoteBrowserTestCase`` runs application server on the same process, which is
-running tests, so that objects on the server can be directly controlled from
-test scripts. WebDriver is run on subprocess, and controlled by passing messages
-on pipe. This messaging process is wrapped by ``RemoteBrowserTestCase`` class
-and users don't need to care it, but owing to this architecture, not all of the
-features of WebDriver is available.
+            def get_app() -> wdom.server.Application:
+                # Prepare and return application you want to test
+                return your_app
 
-Usage
-^^^^^
+            def test_case1(self):
+                # Write your test here
+                self.wd.get(self.url)  # you can access webdriver by self.wd
 
-Example code using `py.test <http://pytest.org/>`_ as a test runner.
+            def test_case2(self):
+                # Write your another test here
+                ...
 
-.. code-block:: python
 
-    # in your_test_dir/conftest.py
-    import pytest
-    from wdom.testinsg import start_remote_browser, close_remote_browser
+    RemoteBrowserTestCase Class
+    ----------------------------
 
-    @pytest.fixture(scope='session', autouse=True)
-    def browser(request):
-        start_remote_browser()  # Start browser process for this session
-        request.addfinalizer(close_remote_browser)
+    ``RemoteBrowserTestCase`` class is design to test ``wdom`` itself. Its features
+    might not be so useful for library's users. ``RemoteBrowserTestCase`` class
+    helps you to test your app by directly controlling ``Node`` object on python,
+    from test scripts in the same process. This class is **Largely Experimental**.
 
+    ``RemoteBrowserTestCase`` runs application server on the same process, which is
+    running tests, so that objects on the server can be directly controlled from
+    test scripts. WebDriver is run on subprocess, and controlled by passing messages
+    on pipe. This messaging process is wrapped by ``RemoteBrowserTestCase`` class
+    and users don't need to care it, but owing to this architecture, not all of the
+    features of WebDriver is available.
 
-    # in your test file
-    from unittest import TestCase
-    from wdom.tag import Div
-    from wdom.document import get_document
-    from wdom.server import get_app
-    from wdom.tests.util import install_asyncio
-    from wdom.testing import RemoteBrowserTestCase
+    Usage
+    ^^^^^
 
-    def setup_module():
-        install_asyncio()  # force tornado to use asyncio module
+    Example code using `py.test <http://pytest.org/>`_ as a test runner.
 
-    class TestYourApp(RemoteBrowserTestCase, TestCase):
-        def get_app(self) -> wdom.server.Application:
-            # Prepare and return application you want to test
-            self.root_node = Div()
-            self.root_node.textContent = 'RootNode'
-            self.doc = get_document()
-            self.doc.body.prepend(self.root_node)
-            self.app = get_app(self.doc)
-            return self.app
+    .. code-block:: python
 
-        def test_senario1(self):
-            self.set_element(self.root)  # find and set element
-            # get text content of the target element
-            self.assertEqual(self.text, 'RootNode')
+        # in your_test_dir/conftest.py
+        import pytest
+        from wdom.testinsg import start_remote_browser, close_remote_browser
 
+        @pytest.fixture(scope='session', autouse=True)
+        def browser(request):
+            start_remote_browser()  # Start browser process for this session
+            request.addfinalizer(close_remote_browser)
 
-For more examples, see wdom/tests/remote_browser and wdom/tests/webdriver directory.
 
-.. automodule:: wdom.testing
+        # in your test file
+        from unittest import TestCase
+        from wdom.tag import Div
+        from wdom.document import get_document
+        from wdom.server import get_app
+        from wdom.tests.util import install_asyncio
+        from wdom.testing import RemoteBrowserTestCase
 
-   .. autoclass:: RemoteBrowserTestCase
-      :members:
+        def setup_module():
+            install_asyncio()  # force tornado to use asyncio module
 
-   .. autoclass:: WebDriverTestCase
-      :members:
+        class TestYourApp(RemoteBrowserTestCase, TestCase):
+            def get_app(self) -> wdom.server.Application:
+                # Prepare and return application you want to test
+                self.root_node = Div()
+                self.root_node.textContent = 'RootNode'
+                self.doc = get_document()
+                self.doc.body.prepend(self.root_node)
+                self.app = get_app(self.doc)
+                return self.app
+
+            def test_senario1(self):
+                self.set_element(self.root)  # find and set element
+                # get text content of the target element
+                self.assertEqual(self.text, 'RootNode')
+
+
+    For more examples, see wdom/tests/remote_browser and wdom/tests/webdriver directory.

wdom/testing.py

@@ -1,6 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
+"""Provides utility functions/classes for tests.
+
+This module depend on selenium webdriver, so please install selenium before
+use this module::
+
+    pip install selenium
+
+"""
+
 import sys
 import time
 import logging