Testing examples and docs.

.sources/examples_context.py

@@ -0,0 +1,23 @@
+import requests
+from libpathod import test
+
+class Test:
+    """
+        Testing the requests module with 
+        a pathod context manager.
+    """
+    def test_simple(self):
+        # Start pathod in a separate thread
+        with test.Daemon() as d:
+            # Get a URL for a pathod spec
+            url = d.p("200:b@100")
+            # ... and request it
+            r = requests.put(url)
+
+            # Check the returned data
+            assert r.status_code == 200
+            assert len(r.content) == 100
+
+            # Check pathod's internal log
+            log = d.last_log()["request"]
+            assert log["method"] == "PUT"

.sources/examples_setup.py

@@ -0,0 +1,28 @@
+import requests
+from libpathod import test
+
+class Test:
+    """
+        Testing the requests module with 
+        a pathod instance started for 
+        each test.
+    """
+    def setUp(self):
+        self.d = test.Daemon()
+
+    def tearDown(self):
+        self.d.shutdown()
+
+    def test_simple(self):
+        # Get a URL for a pathod spec
+        url = self.d.p("200:b@100")
+        # ... and request it
+        r = requests.put(url)
+
+        # Check the returned data
+        assert r.status_code == 200
+        assert len(r.content) == 100
+
+        # Check pathod's internal log
+        log = self.d.last_log()["request"]
+        assert log["method"] == "PUT"

.sources/examples_setupall.py

@@ -0,0 +1,37 @@
+import requests
+from libpathod import test
+
+class Test:
+    """
+        Testing the requests module with 
+        a single pathod instance started 
+        for the test suite.
+    """
+    @classmethod
+    def setUpAll(cls):
+        cls.d = test.Daemon()
+
+    @classmethod
+    def tearDownAll(cls):
+        cls.d.shutdown()
+
+    def setUp(self):
+        # Clear the pathod logs between tests
+        self.d.clear_log()
+
+    def test_simple(self):
+        # Get a URL for a pathod spec
+        url = self.d.p("200:b@100")
+        # ... and request it
+        r = requests.put(url)
+
+        # Check the returned data
+        assert r.status_code == 200
+        assert len(r.content) == 100
+
+        # Check pathod's internal log
+        log = self.d.last_log()["request"]
+        assert log["method"] == "PUT"
+
+    def test_two(self):
+        assert not self.d.log()

.sources/examples_test.py

@@ -1,17 +0,0 @@
-import requests
-from libpathod import test
-
-class Test:
-    def setUp(self):
-        self.daemon = test.Daemon()
-
-    def tearDown(self):
-        self.daemon.shutdown()
-
-    def test_simple(self):
-        path = self.daemon.p("200:b@100")
-        r = requests.get(path)
-        assert r.status_code == 200
-        assert len(r.content) == 100
-        log = self.daemon.last_log()
-        assert log["request"]["method"] == "GET"

.sources/make

@@ -1,2 +1,4 @@
 #!/bin/sh
-pygmentize -f html ./examples_test.py > ../libpathod/templates/examples_test.html
+pygmentize -f html ./examples_context.py > ../libpathod/templates/examples_context.html
+pygmentize -f html ./examples_setup.py > ../libpathod/templates/examples_setup.html
+pygmentize -f html ./examples_setupall.py > ../libpathod/templates/examples_setupall.html

libpathod/templates/docs_test.html

@@ -6,4 +6,47 @@
         <small>Using pathod and pathoc in your unit tests.</small>
     </h1>
 </div>
+
+<div class="row">
+    <div class="span6">
+
+        <p> The <b>libpathod.test</b> module is a light, flexible testing layer
+        for HTTP clients. It works by firing up a Pathod instance in a separate
+        thread, letting you use Pathod's full abilities to generate responses,
+        and then query Pathod's internal logs to establish what happened. All
+        the mechanics of startup, shutdown, finding free ports and so forth are
+        taken care of for you. </p>
+
+        <p> The canonical docs can be accessed using pydoc: </p>
+
+        <pre class="terminal">pydoc libpathod.testing</pre>
+
+        <p> The remainder of this page demonstrates some common interaction
+        patterns using <a
+        href="http://nose.readthedocs.org/en/latest/">nose</a>. These examples
+        are also applicable with only minor modification to most commonly used
+        Python testing engines.</p>
+
+    </div>
+    <div class="span6">
+        <h1> Context Decorator </h1>
+
+        {% include "examples_context.html" %}
+    </div>
+</div>
+
+<div class="row">
+    <div class="span6">
+        <h1> One instance per test </h1>
+
+        {% include "examples_setup.html" %}
+    </div>
+    <div class="span6">
+        <h1> One instance per suite </h1>
+
+        {% include "examples_setupall.html" %}
+    </div>
+</div>
+
+
 {% endblock %}  

libpathod/templates/examples_context.html

@@ -0,0 +1,24 @@
+<div class="highlight"><pre><span class="kn">import</span> <span class="nn">requests</span>
+<span class="kn">from</span> <span class="nn">libpathod</span> <span class="kn">import</span> <span class="n">test</span>
+
+<span class="k">class</span> <span class="nc">Test</span><span class="p">:</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Testing the requests module with </span>
+<span class="sd">        a pathod context manager.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">def</span> <span class="nf">test_simple</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="c"># Start pathod in a separate thread</span>
+        <span class="k">with</span> <span class="n">test</span><span class="o">.</span><span class="n">Daemon</span><span class="p">()</span> <span class="k">as</span> <span class="n">d</span><span class="p">:</span>
+            <span class="c"># Get a URL for a pathod spec</span>
+            <span class="n">url</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">p</span><span class="p">(</span><span class="s">&quot;200:b@100&quot;</span><span class="p">)</span>
+            <span class="c"># ... and request it</span>
+            <span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
+
+            <span class="c"># Check the returned data</span>
+            <span class="k">assert</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span>
+            <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">content</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span>
+
+            <span class="c"># Check pathod&#39;s internal log</span>
+            <span class="n">log</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">last_log</span><span class="p">()[</span><span class="s">&quot;request&quot;</span><span class="p">]</span>
+            <span class="k">assert</span> <span class="n">log</span><span class="p">[</span><span class="s">&quot;method&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="s">&quot;PUT&quot;</span>
+</pre></div>

libpathod/templates/examples_setup.html

@@ -2,17 +2,28 @@
 <span class="kn">from</span> <span class="nn">libpathod</span> <span class="kn">import</span> <span class="n">test</span>
 
 <span class="k">class</span> <span class="nc">Test</span><span class="p">:</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Testing the requests module with </span>
+<span class="sd">        a pathod instance started for </span>
+<span class="sd">        each test.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
     <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">daemon</span> <span class="o">=</span> <span class="n">test</span><span class="o">.</span><span class="n">Daemon</span><span class="p">()</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">d</span> <span class="o">=</span> <span class="n">test</span><span class="o">.</span><span class="n">Daemon</span><span class="p">()</span>
 
     <span class="k">def</span> <span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">daemon</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
 
     <span class="k">def</span> <span class="nf">test_simple</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="n">path</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">daemon</span><span class="o">.</span><span class="n">p</span><span class="p">(</span><span class="s">&quot;200:b@100&quot;</span><span class="p">)</span>
+        <span class="c"># Get a URL for a pathod spec</span>
-        <span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
+        <span class="n">url</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">p</span><span class="p">(</span><span class="s">&quot;200:b@100&quot;</span><span class="p">)</span>
+        <span class="c"># ... and request it</span>
+        <span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
+
+        <span class="c"># Check the returned data</span>
         <span class="k">assert</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span>
         <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">content</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span>
-        <span class="n">log</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">daemon</span><span class="o">.</span><span class="n">last_log</span><span class="p">()</span>
+
-        <span class="k">assert</span> <span class="n">log</span><span class="p">[</span><span class="s">&quot;request&quot;</span><span class="p">][</span><span class="s">&quot;method&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="s">&quot;GET&quot;</span>
+        <span class="c"># Check pathod&#39;s internal log</span>
+        <span class="n">log</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">last_log</span><span class="p">()[</span><span class="s">&quot;request&quot;</span><span class="p">]</span>
+        <span class="k">assert</span> <span class="n">log</span><span class="p">[</span><span class="s">&quot;method&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="s">&quot;PUT&quot;</span>
 </pre></div>

libpathod/templates/examples_setupall.html

@@ -0,0 +1,38 @@
+<div class="highlight"><pre><span class="kn">import</span> <span class="nn">requests</span>
+<span class="kn">from</span> <span class="nn">libpathod</span> <span class="kn">import</span> <span class="n">test</span>
+
+<span class="k">class</span> <span class="nc">Test</span><span class="p">:</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Testing the requests module with </span>
+<span class="sd">        a single pathod instance started </span>
+<span class="sd">        for the test suite.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="nd">@classmethod</span>
+    <span class="k">def</span> <span class="nf">setUpAll</span><span class="p">(</span><span class="n">cls</span><span class="p">):</span>
+        <span class="n">cls</span><span class="o">.</span><span class="n">d</span> <span class="o">=</span> <span class="n">test</span><span class="o">.</span><span class="n">Daemon</span><span class="p">()</span>
+
+    <span class="nd">@classmethod</span>
+    <span class="k">def</span> <span class="nf">tearDownAll</span><span class="p">(</span><span class="n">cls</span><span class="p">):</span>
+        <span class="n">cls</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
+
+    <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="c"># Clear the pathod logs between tests</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">clear_log</span><span class="p">()</span>
+
+    <span class="k">def</span> <span class="nf">test_simple</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="c"># Get a URL for a pathod spec</span>
+        <span class="n">url</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">p</span><span class="p">(</span><span class="s">&quot;200:b@100&quot;</span><span class="p">)</span>
+        <span class="c"># ... and request it</span>
+        <span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
+
+        <span class="c"># Check the returned data</span>
+        <span class="k">assert</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span>
+        <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">content</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span>
+
+        <span class="c"># Check pathod&#39;s internal log</span>
+        <span class="n">log</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">last_log</span><span class="p">()[</span><span class="s">&quot;request&quot;</span><span class="p">]</span>
+        <span class="k">assert</span> <span class="n">log</span><span class="p">[</span><span class="s">&quot;method&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="s">&quot;PUT&quot;</span>
+
+    <span class="k">def</span> <span class="nf">test_two</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">assert</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">d</span><span class="o">.</span><span class="n">log</span><span class="p">()</span>
+</pre></div>

libpathod/templates/index.html

@@ -70,9 +70,9 @@
         <div class="well">
             <h1> <a href="/docs/test">libpathod.test</a> </h1>
 
-            <p>Using pathod and pathoc in your unit tests.</p>
+            <p>Using pathod in your unit tests.</p>
 
-            {% include "examples_test.html" %}
+            {% include "examples_context.html" %}
 
         </div>
     </div>

libpathod/templates/request_previewform.html

@@ -1,6 +1,6 @@
 <form style="margin-bottom: 0" class="form-inline" method="GET" action="/request_preview">
     <input 
-        style="width: 20em"
+        style="width: 18em"
         id="spec"
         name="spec"
         class="input-medium search-query"

libpathod/test.py

@@ -12,6 +12,13 @@ class Daemon:
         self.port = self.q.get(True, 5)
         self.urlbase = "%s://%s:%s"%("https" if ssl else "http", self.IFACE, self.port)
 
+    def __enter__(self):
+        return self
+
+    def __exit__(self, type, value, traceback):
+        self.shutdown()
+        return False
+
     def p(self, spec):
         """
             Return a URL that will render the response in spec.

test/test_test.py

@@ -7,11 +7,10 @@ logging.disable(logging.CRITICAL)
 
 class TestDaemonManual:
     def test_simple(self):
-        d = test.Daemon()
+        with test.Daemon() as d:
             rsp = requests.get("http://localhost:%s/p/202"%d.port)
             assert rsp.ok
             assert rsp.status_code == 202
-        d.shutdown()
         tutils.raises(requests.ConnectionError, requests.get, "http://localhost:%s/p/202"%d.port)
 
     def test_startstop_ssl(self):