Package: trestle
Trestle: doctest for REST(ful services)---------------------------------------About~~~~~Trestle is a nose plugin that enables you to write testable documentation forweb apps (or shell commands, but more on that later).To use trestle, write a `reStructured Text`_ document (like this one) using aset of special directives to indicate the **fixtures** to be used for testing(including the http or mock http client), each **request** to be sent via theclient, and the **expected response** from the application under test.A simple trestle test document might look like this::Frog: A web service for doing things with frogs-----------------------------------------------.. fixtures :: frog_fixturesFrog is a web service for doing things with frogs.You can list the available frogs... request :: List available frogsGET /frogs..The response is in a plain-text format... response ::bullfrogpoison darttreefrog.....You can find out if something is a frog... request :: Get bullfrog detailsGET /frogs/bullfrog..If the requested term is a frog, details about the frog will be returned... response ::Bullfrogs are really big frogs...Otherwise, a 404 response is returned... request :: Get details for a non-frogGET /frogs/toad.... response ::404 ......"toad" is not a frog...You can create frogs... request :: Create a frogPOST /frogs/pouched+frogA pouched frog camouflages itself to look like dead leaves..... response ::201 Created........Trestle directives^^^^^^^^^^^^^^^^^^Fixtures for a trestle test file are set like so::.. fixtures:: aboutA fixtures directive is required in every document to be tested. Thedirective must name a python module. The module must include thefollowing attribute:clientA client application to be called with methods .get(), .post(),.put(), etc. Each method must accept at least the arguments url anddata, and may accept others but may not requirethem. `paste.fixtures.TestApp`_ is such a client, though it nativelysupports only .get() and .post().And may include the following functions:setup_all(cls)Setup fixture run before the first request.teardown_all(cls)Teardown fixture run after the last request.setup_each(inst)Setup fixture run before each request.teardown_each(inst)Teardown fixture run after each request.Tests in a trestle document consist of a ``.. request`` directive, followed byone or more ``.. response`` directives. The ``.. request`` directive definesthe request to be sent to the web app under test, using the client defined inthe fixtures module.A simple request directive looks like this::.. request:: A simple getGET /foo/bar..If the request is a POST or PUT that includes data to be sent, includethat data in the body of the request, after the request line::.. request:: A postPOST /foo/bara=1&b=2..The response expected to be returned to the client is defined using aresponse block::.. response::Ponies!!1!.... note:: Conclude each block with ``..`` alone on a line to avoid rst parsingerrors that can result in text following a block being thrown away.The testing process is simple: each request is executed using theclient defined in the fixtures module, and each expected responsefollowing that request in the text is compared against the actualresponse. If all responses match, the test passes. Otherwise, itfails... raw:: html<p>Passing examples are given a <span class="pass">pleasing greenbackground</span>, failures a <span class="fail">sinister red</span>.Details of the failed match are included following thefailed example.</p>Fixture commands^^^^^^^^^^^^^^^^At times it may be necessary to execute a unique fixture before executing arequest. While it's usually better to make the test depend only on public apisand not internal details or externalities, sometimes (e.g. when testingtime-dependent operations) that isn't possible or reasonable. For those times,use the **:setup:** argument to the request. The body of the exec argumentwill be evaluated in the context of the fixture module before running therequest. Naturally, there is also a **:teardown:** argument, which will beexecuted after the request is run and the response processed. Here's anexample::.. request:: Get something special:setup: client.set_special(true):teardown: client.set_special(false)GET /special..Shell examples^^^^^^^^^^^^^^Trestle also supports shell examples. When a shell example is executed, theshell command given is executed, and the stdout produced by the command iscompared to the body of the ``..shell`` example using the normal doctestoutput checker. A simple shell example looks like this::.. shell :: echo "Hello"Hello..Shell examples support the standard ``:setup:`` and ``:teardown`` options, aswell as three others: ``:cwd:``, which can be used to set the cwd of the shellcommand; ``:post:``, which names a fixture callable to be used to post-processthe output of the shell command before checking it against the expectedoutput, and the flag ``:stderr:``, which indicates that the example outputshould be compared against the stderr output of the shell command, rather thanstdout (which is the default)... _`reStructured Text`: http://docutils.sourceforge.net/rst.html.. _`paste.fixtures.TestApp` : http://pythonpaste.org/testing-applications.html