Testing examples and docs.

7 files changed, 132 insertions, 9 deletions

diff --git a/libpathod/templates/docs_test.html b/libpathod/templates/docs_test.html
index 27129f1c..c9162f87 100644
--- a/libpathod/templates/docs_test.html
+++ b/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 %}  
diff --git a/libpathod/templates/examples_context.html b/libpathod/templates/examples_context.html
new file mode 100644
index 00000000..3d33e76d
--- /dev/null
+++ b/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>
diff --git a/libpathod/templates/examples_test.html b/libpathod/templates/examples_setup.html
index 57d39534..bde45840 100644
--- a/libpathod/templates/examples_test.html
+++ b/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="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="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="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>
diff --git a/libpathod/templates/examples_setupall.html b/libpathod/templates/examples_setupall.html
new file mode 100644
index 00000000..b7f79975
--- /dev/null
+++ b/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>
diff --git a/libpathod/templates/index.html b/libpathod/templates/index.html
index c31d4414..b020d60b 100644
--- a/libpathod/templates/index.html
+++ b/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>
diff --git a/libpathod/templates/request_previewform.html b/libpathod/templates/request_previewform.html
index f38758ea..263b501e 100644
--- a/libpathod/templates/request_previewform.html
+++ b/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"
diff --git a/libpathod/test.py b/libpathod/test.py
index 53daa5bf..e431be18 100644
--- a/libpathod/test.py
+++ b/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.