unittest-xml-reporting is a unittest test runner that can save test results to XML files that can be consumed by a wide range of tools, such as build systems, IDEs and continuous integration servers.
- Python 2.7 or 3.3+
- Please note Python 2.6 end-of-life was in Oct 2013, last version supporting 2.6 was 1.14.0
The easiest way to install unittest-xml-reporting is via Pip:
$ pip install unittest-xml-reporting
If you use Git and want to get the latest development version:
$ git clone https://github.com/xmlrunner/unittest-xml-reporting.git $ cd unittest-xml-reporting $ sudo python setup.py install
Or get the latest development version as a tarball:
$ wget https://github.com/xmlrunner/unittest-xml-reporting/archive/master.zip $ unzip master.zip $ cd unittest-xml-reporting $ sudo python setup.py install
Or you can manually download the latest released version from PyPI.
The script below, adapted from the
unittest, shows how to use
XMLTestRunner in a very simple way. In fact, the only difference between
this script and the original one is the last line:
import random import unittest import xmlrunner class TestSequenceFunctions(unittest.TestCase): def setUp(self): self.seq = list(range(10)) @unittest.skip("demonstrating skipping") def test_skipped(self): self.fail("shouldn't happen") def test_shuffle(self): # make sure the shuffled sequence does not lose any elements random.shuffle(self.seq) self.seq.sort() self.assertEqual(self.seq, list(range(10))) # should raise an exception for an immutable sequence self.assertRaises(TypeError, random.shuffle, (1,2,3)) def test_choice(self): element = random.choice(self.seq) self.assertTrue(element in self.seq) def test_sample(self): with self.assertRaises(ValueError): random.sample(self.seq, 20) for element in random.sample(self.seq, 5): self.assertTrue(element in self.seq) if __name__ == '__main__': unittest.main( testRunner=xmlrunner.XMLTestRunner(output='test-reports'), # these make sure that some options that are not applicable # remain hidden from the help menu. failfast=False, buffer=False, catchbreak=False)
Reporting to a single file
if __name__ == '__main__': with open('/path/to/results.xml', 'wb') as output: unittest.main( testRunner=xmlrunner.XMLTestRunner(output=output), failfast=False, buffer=False, catchbreak=False)
The XMLTestRunner can also be used to report on docstrings style tests.
import doctest import xmlrunner def twice(n): """ >>> twice(5) 10 """ return 2 * n class Multiplicator(object): def threetimes(self, n): """ >>> Multiplicator().threetimes(5) 15 """ return 3 * n if __name__ == "__main__": suite = doctest.DocTestSuite() xmlrunner.XMLTestRunner().run(suite)
In order to plug
XMLTestRunner to a Django project, add the following
TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'
Also, the following settings are provided so you can fine tune the reports:
1, choose between
Besides the XML reports generated by the test runner, a bunch of useful
information is printed to the
sys.stderr stream, just like the
TextTestRunner does. Use this setting to choose between a verbose and a
If your test methods contains docstrings, you can display such docstrings
instead of display the test name (ex:
order to use this feature, you have to enable verbose output by setting
TEST_OUTPUT_VERBOSE = 2.
Tells the test runner where to put the XML reports. If the directory couldn't be found, the test runner will try to create it before generate the XML files.
Tells the test runner to output a single XML report with this filename
os.path.join(TEST_OUTPUT_DIR, TEST_OUTPUT_FILE_NAME). Please note
that for long running tests, this will keep the results in memory for
a longer time than multiple reports, and may use up more resources.
We are always looking for good contributions, so please just fork the repository and send pull requests (with tests!).
If you would like write access to the repository, or become a maintainer, feel free to get in touch.
Testing changes with
tox to test your changes before sending a pull request.
You can find more information about
tox at https://testrun.org/tox/latest/.
$ pip install tox $ tox
Work in progress
There is a rewrite branch which contains better unit tests and uses a different runner. It
CompositeTestResult which allows the use of both
XMLTestResult as delegates. If you would like to help reconcile both
branches, pull requests are welcome.