New Release with context-manager oriented server start/stop and basic…

… documentation

CHANGES.txt

@@ -1,3 +1,10 @@
+0.2.0
+=====
+
+  - Support for context managers to start/stop servers
+  - Add aliases to make easier to import WSGITestServer and get_application
+  - Add a basic documentation
+
 0.1.1
 =====
 

README.rst

@@ -4,7 +4,70 @@ wsgitest
 |Build Status| |Coverage Status|
 
 
-TODO
+You can use `wsgitest` to start a HTTP server for a WSGI application and
+control the process:
+
+.. code-block:: python
+
+    @Request.application
+    def application(request):
+        return Response('Hello World!')
+
+    class AppServerTestCase(TestCase):
+        def test_hello_app(self):
+            server = WSGITestServer.create(application)
+            try:
+                response = requests.get(server.application_url)
+                self.assertEqual(response.status_code, 200)
+                self.assertEqual(response.content, b"Hello World!")
+            finally:
+                server.terminate()
+
+        def test_hello_app_reference(self):
+            server = WSGITestServer.create("tests.test_server.application")
+            try:
+                response = requests.get(server.application_url)
+                self.assertEqual(response.status_code, 200)
+                self.assertEqual(response.content, b"Hello World!")
+            finally:
+                server.terminate()
+
+The method `WSGITestServer.create()` initialize a `multiprocessing.Process`_
+and wait for the server startup.
+
+You can use server as a context manager to avoid that tests get stucked when
+you forget to "terminate" server:
+
+.. code-block:: python
+
+    @Request.application
+    def application(request):
+        return Response('Hello World!')
+
+    class AppServerTestCase(TestCase):
+        def test_hello_app(self):
+            with WSGITestServer(application) as server:
+                response = requests.get(server.application_url)
+                self.assertEqual(response.status_code, 200)
+                self.assertEqual(response.content, b"Hello World!")
+
+You can also start server with an specific host/ip or TCP port:
+
+.. code-block:: python
+
+    @Request.application
+    def application(request):
+        return Response('Hello World!')
+
+    class AppServerTestCase(TestCase):
+        def test_hello_app(self):
+            with WSGITestServer(application, "0.0.0.0", 5000) as server:
+                response = requests.get(server.application_url)
+                self.assertEqual(response.status_code, 200)
+                self.assertEqual(response.content, b"Hello World!")
+
+
+.. _multiprocessing.Process: https://docs.python.org/3/library/multiprocessing.html#the-process-class
 
 
 .. |Build Status| image:: https://travis-ci.org/osantana/wsgitest.png?branch=master

tests/test_server.py

@@ -15,7 +15,7 @@
 
 from werkzeug.wrappers import Request, Response
 
-from wsgitest.server import WSGITestServer
+from wsgitest import WSGITestServer
 
 
 @Request.application
@@ -35,12 +35,15 @@ def test_start(self):
             requests.get(urljoin(server.application_url, "/"))
 
     def test_application_reference(self):
-        server = WSGITestServer.create("tests.test_server.application")
-        try:
+        with WSGITestServer("tests.test_server.application") as server:
+            response = requests.get(urljoin(server.application_url, "/"))
+            self.assertEqual(response.status_code, 200)
+
+    def test_specific_host_and_port(self):
+        with WSGITestServer(application, "0.0.0.0", 4000) as server:
+            self.assertEqual(server.application_url, "http://0.0.0.0:4000/")
             response = requests.get(urljoin(server.application_url, "/"))
             self.assertEqual(response.status_code, 200)
-        finally:
-            server.terminate()
 
 
 class AppServerTestCase(TestCase):

tests/test_utils.py

@@ -0,0 +1,24 @@
+# coding: utf-8
+
+
+from unittest import TestCase
+
+try:
+    from urllib.parse import urljoin
+except ImportError:
+    # noinspection PyUnresolvedReferences
+    from urlparse import urljoin
+
+
+from wsgitest import get_application
+
+
+identificator = None
+
+class UtilsTestCase(TestCase):
+    def test_get_application(self):
+        self.assertEqual(get_application("tests.test_utils.identificator"), identificator)
+
+    def test_fail_get_invalid_reference(self):
+        with self.assertRaises(ImportError):
+            get_application("tests.test_utils.unknown")

wsgitest/__init__.py

@@ -1 +1,5 @@
 # coding: utf-8
+
+
+from .server import WSGITestServer
+from .utils import get_application

wsgitest/server.py

@@ -85,3 +85,11 @@ def create(cls, application, host=None, port=None):
         server.start()
         server.wait()
         return server
+
+    def __enter__(self):
+        self.start()
+        self.wait()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.terminate()

wsgitest/utils.py

@@ -12,4 +12,4 @@ def get_application(dotted_path):
     except (ValueError, AttributeError):
         raise ImportError("Invalid reference {!r}".format(dotted_path))
 
-    return application
+    return application