| Server IP : 127.0.0.2 / Your IP : 18.222.48.95 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/docutils-doc/docs/dev/ |
Upload File : |
<?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.12: http://docutils.sourceforge.net/" />
<title>Docutils Testing</title>
<meta name="authors" content="Lea Wiemann <LeWiemann@gmail.com> David Goodger <goodger@python.org>" />
<meta name="date" content="2012-06-22" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="docutils-testing">
<h1 class="title"><a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> Testing</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Authors:</th>
<td>Lea Wiemann <LeWiemann@gmail.com>
<br />David Goodger <goodger@python.org></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7463</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2012-06-22</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#running-the-test-suite" id="id5">Running the Test Suite</a></li>
<li><a class="reference internal" href="#python-versions" id="id6">Python Versions</a></li>
<li><a class="reference internal" href="#unit-tests" id="id7">Unit Tests</a><ul>
<li><a class="reference internal" href="#writing-new-tests" id="id8">Writing New Tests</a></li>
</ul>
</li>
<li><a class="reference internal" href="#functional-tests" id="id9">Functional Tests</a><ul>
<li><a class="reference internal" href="#directory-structure" id="id10">Directory Structure</a></li>
<li><a class="reference internal" href="#the-testing-process" id="id11">The Testing Process</a></li>
<li><a class="reference internal" href="#creating-new-tests" id="id12">Creating New Tests</a></li>
<li><a class="reference internal" href="#the-default-configuration-file" id="id13">The Default Configuration File</a></li>
</ul>
</li>
</ul>
</div>
<p>When adding new functionality (or fixing bugs), be sure to add test
cases to the test suite. Practise test-first programming; it's fun,
it's addictive, and it works!</p>
<p>This document describes how to run the Docutils test suite, how the
tests are organized and how to add new tests or modify existing tests.</p>
<div class="section" id="running-the-test-suite">
<h1><a class="toc-backref" href="#id5">Running the Test Suite</a></h1>
<p>Before checking in any changes, run the entire Docutils test suite to
be sure that you haven't broken anything. From a shell:</p>
<pre class="literal-block">
cd docutils/test
./alltests.py
</pre>
</div>
<div class="section" id="python-versions">
<h1><a class="toc-backref" href="#id6">Python Versions</a></h1>
<p>The Docutils 0.10 release supports Python 2.4 or later. Therefore, you should
actually have Pythons 2.4, as well as the latest Python (3.2 at the time
of this writing) installed and always run the tests on all of them. (A good
way to do that is to always run the test suite through a short script that
runs <tt class="docutils literal">alltests.py</tt> under each version of Python.) If you can't afford
installing 3 or more Python versions, the edge cases (2.4, and 3.2) should
cover most of it.</p>
<p>Good resources covering the differences between Python versions:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.python.org/doc/2.4.4/whatsnew/whatsnew24.html">What's New in Python 2.4</a></li>
<li><a class="reference external" href="http://www.python.org/doc/2.5.2/whatsnew/whatsnew25.html">What's New in Python 2.5</a></li>
<li><a class="reference external" href="http://docs.python.org/whatsnew/2.6.html">What's New in Python 2.6</a></li>
<li><a class="reference external" href="http://www.python.org/peps/pep-0290.html">PEP 290 - Code Migration and Modernization</a></li>
</ul>
</div>
<div class="section" id="unit-tests">
<h1><a class="toc-backref" href="#id7">Unit Tests</a></h1>
<p>Unit tests test single functions or modules (i.e. whitebox testing).</p>
<p>If you are implementing a new feature, be sure to write a test case
covering its functionality. It happens very frequently that your
implementation (or even only a part of it) doesn't work with an older
(or even newer) Python version, and the only reliable way to detect
those cases is using tests.</p>
<p>Often, it's easier to write the test first and then implement the
functionality required to make the test pass.</p>
<div class="section" id="writing-new-tests">
<h2><a class="toc-backref" href="#id8">Writing New Tests</a></h2>
<p>When writing new tests, it very often helps to see how a similar test
is implemented. For example, the files in the
<tt class="docutils literal">test_parsers/test_rst/</tt> directory all look very similar. So when
adding a test, you don't have to reinvent the wheel.</p>
<p>If there is no similar test, you can write a new test from scratch
using Python's <tt class="docutils literal">unittest</tt> module. For an example, please have a
look at the following imaginary <tt class="docutils literal">test_square.py</tt>:</p>
<pre class="literal-block">
#! /usr/bin/env python
# $Id: testing.txt 7463 2012-06-22 19:49:51Z milde $
# Author: Your Name <your_email_address@example.org>
# Copyright: This module has been placed in the public domain.
"""
Test module for docutils.square.
"""
import unittest
import docutils.square
class SquareTest(unittest.TestCase):
def test_square(self):
self.assertEqual(docutils.square.square(0), 0)
self.assertEqual(docutils.square.square(5), 25)
self.assertEqual(docutils.square.square(7), 49)
def test_square_root(self):
self.assertEqual(docutils.square.sqrt(49), 7)
self.assertEqual(docutils.square.sqrt(0), 0)
self.assertRaises(docutils.square.SquareRootError,
docutils.square.sqrt, 20)
if __name__ == '__main__':
unittest.main()
</pre>
<p>For more details on how to write tests, please refer to the
documentation of the <tt class="docutils literal">unittest</tt> module.</p>
</div>
</div>
<div class="section" id="functional-tests">
<span id="functional"></span><h1><a class="toc-backref" href="#id9">Functional Tests</a></h1>
<p>The directory <tt class="docutils literal">test/functional/</tt> contains data for functional tests.</p>
<p>Performing functional testing means testing the Docutils system as a
whole (i.e. blackbox testing).</p>
<div class="section" id="directory-structure">
<h2><a class="toc-backref" href="#id10">Directory Structure</a></h2>
<ul class="simple">
<li><tt class="docutils literal">functional/</tt> The main data directory.<ul>
<li><tt class="docutils literal">input/</tt> The input files.<ul>
<li><tt class="docutils literal">some_test.txt</tt>, for example.</li>
</ul>
</li>
<li><tt class="docutils literal">output/</tt> The actual output.<ul>
<li><tt class="docutils literal">some_test.html</tt>, for example.</li>
</ul>
</li>
<li><tt class="docutils literal">expected/</tt> The expected output.<ul>
<li><tt class="docutils literal">some_test.html</tt>, for example.</li>
</ul>
</li>
<li><tt class="docutils literal">tests/</tt> The config files for processing the input files.<ul>
<li><tt class="docutils literal">some_test.py</tt>, for example.</li>
<li><tt class="docutils literal">_default.py</tt>, the <a class="reference internal" href="#default-configuration-file">default configuration file</a>.</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="the-testing-process">
<h2><a class="toc-backref" href="#id11">The Testing Process</a></h2>
<p>When running <tt class="docutils literal">test_functional.py</tt>, all config files in
<tt class="docutils literal">functional/tests/</tt> are processed. (Config files whose names begin
with an underscore are ignored.) The current working directory is
always Docutils' main test directory (<tt class="docutils literal">test/</tt>).</p>
<p>For example, <tt class="docutils literal">functional/tests/some_test.py</tt> could read like this:</p>
<pre class="literal-block">
# Source and destination file names.
test_source = "some_test.txt"
test_destination = "some_test.html"
# Keyword parameters passed to publish_file.
reader_name = "standalone"
parser_name = "rst"
writer_name = "html"
settings_overrides['output-encoding'] = 'utf-8'
# Relative to main ``test/`` directory.
settings_overrides['stylesheet_path'] = '../docutils/writers/html4css1/html4css1.css'
</pre>
<p>The two variables <tt class="docutils literal">test_source</tt> and <tt class="docutils literal">test_destination</tt> contain the
input file name (relative to <tt class="docutils literal">functional/input/</tt>) and the output
file name (relative to <tt class="docutils literal">functional/output/</tt> and
<tt class="docutils literal">functional/expected/</tt>). Note that the file names can be chosen
arbitrarily. However, the file names in <tt class="docutils literal">functional/output/</tt> <em>must</em>
match the file names in <tt class="docutils literal">functional/expected/</tt>.</p>
<p>If defined, <tt class="docutils literal">_test_more</tt> must be a function with the following
signature:</p>
<pre class="literal-block">
def _test_more(expected_dir, output_dir, test_case, parameters):
</pre>
<p>This function is called from the test case to perform tests beyond the
simple comparison of expected and actual output files.</p>
<p><tt class="docutils literal">test_source</tt> and <tt class="docutils literal">test_destination</tt> are removed from the
namespace, as are all variables whose names begin with an underscore
("_"). The remaining names are passed as keyword arguments to
<tt class="docutils literal">docutils.core.publish_file</tt>, so you can set reader, parser, writer
and anything else you want to configure. Note that
<tt class="docutils literal">settings_overrides</tt> is already initialized as a dictionary <em>before</em>
the execution of the config file.</p>
</div>
<div class="section" id="creating-new-tests">
<h2><a class="toc-backref" href="#id12">Creating New Tests</a></h2>
<p>In order to create a new test, put the input test file into
<tt class="docutils literal">functional/input/</tt>. Then create a config file in
<tt class="docutils literal">functional/tests/</tt> which sets at least input and output file names,
reader, parser and writer.</p>
<p>Now run <tt class="docutils literal">test_functional.py</tt>. The test will fail, of course,
because you do not have an expected output yet. However, an output
file will have been generated in <tt class="docutils literal">functional/output/</tt>. Check this
output file for validity and correctness. Then copy the file to
<tt class="docutils literal">functional/expected/</tt>.</p>
<p>If you rerun <tt class="docutils literal">test_functional.py</tt> now, it should pass.</p>
<p>If you run <tt class="docutils literal">test_functional.py</tt> later and the actual output doesn't
match the expected output anymore, the test will fail.</p>
<p>If this is the case and you made an intentional change, check the
actual output for validity and correctness, copy it to
<tt class="docutils literal">functional/expected/</tt> (overwriting the old expected output), and
commit the change.</p>
</div>
<div class="section" id="the-default-configuration-file">
<span id="default-configuration-file"></span><h2><a class="toc-backref" href="#id13">The Default Configuration File</a></h2>
<p>The file <tt class="docutils literal">functional/tests/_default.py</tt> contains default settings.
It is executed just before the actual configuration files, which has
the same effect as if the contents of <tt class="docutils literal">_default.py</tt> were prepended
to every configuration file.</p>
</div>
</div>
</div>
</body>
</html>