/usr/share/doc/python-twill/html/testing.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Testing Web sites with twill</title>
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
:Revision: $Revision: 4224 $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="testing-web-sites-with-twill">
<h1 class="title">Testing Web sites with twill</h1>
<p>twill was initially designed for testing Web sites, although since then
people have also figured out that it's good for <a class="reference" href="browsing.html">browsing</a> unsuspecting
Web sites.</p>
<div class="section">
<h1><a id="using-twill-sh" name="using-twill-sh">Using twill-sh</a></h1>
<p>The simplest way to test Web sites is to write one or more twill scripts
and then simply run</p>
<pre class="literal-block">
twill-sh [ -u initial_url ] script(s)
</pre>
<p>either from the command-line (for development purposes), via a cron job
(to check to see if sites are up and responding), or from your functional
or unit tests (see below).</p>
<p>twill-sh will try to run each script given to it on the command line
once, and will report the number of scripts that failed.  The exit value
of the script will be 0 if there are no failures, so you can use it in
a shell script easily enough.</p>
<p>twill-sh will gather scripts from directories, so you can create a whole
directory hierarchy containing your scripts and they will all be gathered
and run, in standard lexical order.</p>
<p>The <tt class="docutils literal"><span class="pre">-u</span></tt> flag can be used to give twill-sh an initial URL; this is
equivalent to placing a &quot;go (initial_url)&quot; command at the top of the
script, but is particularly handy for test frameworks where the URL
might change depending on the developer.</p>
</div>
<div class="section">
<h1><a id="stress-testing" name="stress-testing">Stress testing</a></h1>
<p>You can use the <cite>twill-fork</cite> script to do some stress testing.  The syntax is</p>
<pre class="literal-block">
twill-fork -n &lt;number to execute&gt; -p &lt;number of processes&gt; script [ scripts... ]
</pre>
<p>For example,</p>
<pre class="literal-block">
twill-fork -n 500 -p 10 test-script
</pre>
<p>will fork 10 times and run <cite>test-script</cite> 50 times in each process.
<cite>twill-fork</cite> will record the time it takes to run all of the scripts specified
on the command and print a summary at the end.</p>
<p>The time recorded is <em>not</em> the CPU time used.  (This would lead to an
inaccurate estimate because the client code uses blocking calls to
retrieve Web pages.)  Rather, the time recorded is the clock time
measured between the start and end of script execution.</p>
<p>Try <cite>twill-fork -h</cite> to get a list of other command line arguments.</p>
<p>Note that twill-fork still needs a lot of work...</p>
</div>
<div class="section">
<h1><a id="unit-testing" name="unit-testing">Unit testing</a></h1>
<p>twill can be used in unit testing, and it contains
some Python support infrastructure for this purpose.</p>
<p>As an example, here's the code from twill's own unit test, testing the
unit-test support code:</p>
<pre class="literal-block">
import os
import testlib
import twill.unit
import twilltestserver
from quixote.server.simple_server import run as quixote_run

def test():
    # port to run the server on
    PORT=8090

    # create a function to run the server
    def run_server_fn():
        quixote_run(twilltestserver.create_publisher, port=PORT)

    # abspath to the script
    script = os.path.join(testlib.testdir, 'test-unit-support.twill')

    # create test_info object
    test_info = twill.unit.TestInfo(script, run_server_fn, PORT)

    # run tests!
    twill.unit.run_test(test_info)
</pre>
<p>Here, I'm unit testing the Quixote application <tt class="docutils literal"><span class="pre">twilltestserver</span></tt>, which
is run by <tt class="docutils literal"><span class="pre">quixote_run</span></tt> (a.k.a. <tt class="docutils literal"><span class="pre">quixote.server.simple_server.run</span></tt>) on
port <tt class="docutils literal"><span class="pre">PORT</span></tt>, using the twill script <tt class="docutils literal"><span class="pre">test-unit-support.twill</span></tt>.  That
script contains this code:</p>
<pre class="literal-block">
# starting URL is provided to it by the unit test support framework.

go ./multisubmitform
code 200
</pre>
<p>A few things to note:</p>
<blockquote>
<ul class="simple">
<li>the initial URL is set based on the URL reported by <tt class="docutils literal"><span class="pre">TestInfo</span></tt>,
which calculates it based on the <tt class="docutils literal"><span class="pre">PORT</span></tt> argument.  (This can be overriden
by subclasses.)</li>
<li><tt class="docutils literal"><span class="pre">TestInfo</span></tt> contains code to (a) run the server function in a new
process, and (b) run the twill script against that server.  It then
kills the server after script completion.</li>
<li>You can also pass a 'sleep' argument to the <tt class="docutils literal"><span class="pre">TestInfo</span></tt> constructor that
specifies how many seconds to wait for the server to start before
executing the script.</li>
</ul>
</blockquote>
</div>
<div class="section">
<h1><a id="testing-wsgi-applications-in-process" name="testing-wsgi-applications-in-process">Testing WSGI applications &quot;in-process&quot;</a></h1>
<p>twill has some built-in support for testing <a class="reference" href="http://www.python.org/peps/pep-0333.html">WSGI
applications</a>.</p>
<p>twill contains two functions,
<cite>add_wsgi_intercept</cite> and <cite>remove_wsgi_intercept</cite>, that allow Python
applications to redirect HTTP calls into a WSGI application
&quot;in-process&quot;, without going via an external Internet call.  This is
particularly useful for unit tests, where setting up an externally
available Web server can be inconvenient.</p>
<p>For example, the following code redirects all <tt class="docutils literal"><span class="pre">localhost:80</span></tt> calls to
the given WSGI app:</p>
<pre class="literal-block">
def create_app():
    return wsgi_app

twill.add_wsgi_intercept('localhost', 80, create_app)
</pre>
<p>See the <tt class="docutils literal"><span class="pre">tests/test-wsgi-intercept.py</span></tt> unit test for more information.</p>
</div>
</div>
</body>
</html>
python-twill 0.9-3 / usr / share / doc / python-twill / html / testing.html
