README.rst
1python-junit-xml
2================
3.. image:: https://travis-ci.org/kyrus/python-junit-xml.png?branch=master
4
5About
6-----
7
8A Python module for creating JUnit XML test result documents that can be
9read by tools such as Jenkins or Bamboo. If you are ever working with test tool or
10test suite written in Python and want to take advantage of Jenkins' or Bamboo's
11pretty graphs and test reporting capabilities, this module will let you
12generate the XML test reports.
13
14*As there is no definitive Jenkins JUnit XSD that I could find, the XML
15documents created by this module support a schema based on Google
16searches and the Jenkins JUnit XML reader source code. File a bug if
17something doesn't work like you expect it to.
18For Bamboo situation is the same.*
19
20Installation
21------------
22
23Install using pip or easy_install:
24
25::
26
27 pip install junit-xml
28 or
29 easy_install junit-xml
30
31You can also clone the Git repository from Github and install it manually:
32
33::
34
35 git clone https://github.com/kyrus/python-junit-xml.git
36 python setup.py install
37
38Using
39-----
40
41Create a test suite, add a test case, and print it to the screen:
42
43.. code-block:: python
44
45 from junit_xml import TestSuite, TestCase
46
47 test_cases = [TestCase('Test1', 'some.class.name', 123.345, 'I am stdout!', 'I am stderr!')]
48 ts = TestSuite("my test suite", test_cases)
49 # pretty printing is on by default but can be disabled using prettyprint=False
50 print(TestSuite.to_xml_string([ts]))
51
52Produces the following output
53
54.. code-block:: xml
55
56 <?xml version="1.0" ?>
57 <testsuites>
58 <testsuite errors="0" failures="0" name="my test suite" tests="1">
59 <testcase classname="some.class.name" name="Test1" time="123.345000">
60 <system-out>
61 I am stdout!
62 </system-out>
63 <system-err>
64 I am stderr!
65 </system-err>
66 </testcase>
67 </testsuite>
68 </testsuites>
69
70Writing XML to a file:
71
72.. code-block:: python
73
74 # you can also write the XML to a file and not pretty print it
75 with open('output.xml', 'w') as f:
76 TestSuite.to_file(f, [ts], prettyprint=False)
77
78See the docs and unit tests for more examples.
79
80NOTE: Unicode characters identified as "illegal or discouraged" are automatically
81stripped from the XML string or file.
82
83Running the tests
84-----------------
85
86::
87
88 # activate your virtualenv
89 pip install tox
90 tox
91
92Releasing a new version
93-----------------------
94
951. Bump version in `setup.py`
962. Build distribution with `python setup.py sdist bdist_wheel`
973. Upload to Pypi with `twine upload dist/*`
984. Verify the new version was uploaded at https://pypi.org/project/junit-xml/#history
99
