repository·master·Indexed 43 days ago
https://github.com/xmlrunner/unittest-xml-reportingA test runner for Python's unittest framework that generates test results in xUnit-compatible XML format for consumption by CI/CD tools like Jenkins and various IDEs. It provides the XMLTestRunner class for Python scripts and a command-line interface via the xmlrunner module, including specialized support for Django projects and doctest suites.
The generated XML files are designed for consumption by Jenkins plugins:
transform utility mentioned in the Transform XML reports section.The unittest concept of subTest does not map directly to the standard xUnit schema. As a result:
unittest does not report successful sub-tests, the total counts in the report may not be perfectly exact.The easiest way to install the package is using pip.
$ pip install unittest-xml-reportingYou can use unittest-xml-reporting (also known as xmlrunner) as a drop-in replacement for the standard unittest module to save test results to XML (JUnit) files. This allows CI/CD tools to consume your test results.
Run tests using the following command patterns:
python -m xmlrunner test_modulepython -m xmlrunner module.TestClasspython -m xmlrunner module.Class.test_methodpython -m xmlrunner discover [options]python -m xmlrunner test_module
python -m xmlrunner module.TestClass
python -m xmlrunner module.Class.test_method
python -m xmlrunner discover [options]To integrate the XML reporter directly into your test scripts, use xmlrunner.XMLTestRunner as the testRunner argument in unittest.main().
You can specify the output directory using the output parameter. To ensure that certain unittest options (like failfast, buffer, or catchbreak) do not appear in the help menu when they are not applicable to the XML runner, you should explicitly set them to False or their desired values.
import unittest
import xmlrunner
if __name__ == '__main__':
unittest.main(
testRunner=xmlrunner.XMLTestRunner(output='test-reports'),
failfast=False,
buffer=False,
catchbreak=False
)To integrate xmlrunner into a Django project, update your settings.py to use the specialized Django test runner:
TEST_RUNNER = 'xmlrunner.extra.djangotestrunner.XMLTestRunner'Use the following settings in settings.py to fine-tune report generation:
| Setting | Default | Values | Description |
|---|---|---|---|
TEST_OUTPUT_VERBOSE | 1 | 0, 1, 2 | Controls verbosity of information printed to sys.stderr. |
TEST_OUTPUT_DESCRIPTIONS | False | True, False | If True, displays test docstrings instead of method names (requires TEST_OUTPUT_VERBOSE = 2). |
TEST_OUTPUT_DIR | . | <str> | Directory where XML reports are stored. Created if it doesn't exist. |
TEST_OUTPUT_FILE_NAME | None | <str> | If set, outputs a single XML report with this filename in TEST_OUTPUT_DIR. Note: This keeps results in memory longer. |
If you are using the Jenkins xUnit plugin and need to remove extra attributes to ensure compatibility, use the transform function from xmlrunner.extra.xunit_plugin.
from xmlrunner.extra.xunit_plugin import transform
# Assuming 'out' is a BytesIO object containing the raw XML output
with open('TEST-report.xml', 'wb') as report:
report.write(transform(out.getvalue()))from xmlrunner.extra.xunit_plugin import transform
with open('TEST-report.xml', 'wb') as report:
report.write(transform(out.getvalue()))To use XMLTestRunner in your own Python test scripts, pass an instance of xmlrunner.XMLTestRunner to the testRunner argument of unittest.main().
By default, providing a string to output creates a directory for the reports.
import unittest
import xmlrunner
if __name__ == '__main__':
unittest.main(
testRunner=xmlrunner.XMLTestRunner(output='test-reports'),
failfast=False, buffer=False, catchbreak=False)To consolidate results into one specific file, pass a file object to the output parameter.
import unittest
import xmlrunner
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)XMLTestRunner can also be used to report on doctest suites.
import doctest
import xmlrunner
# ... (doctest definitions) ...
if __name__ == '__main__':
suite = doctest.DocTestSuite()
xmlrunner.XMLTestRunner().run(suite)You can run tests and generate XML reports directly from the command line using the xmlrunner module.
Use python -m xmlrunner to run tests in the current directory, or python -m xmlrunner discover to discover tests in a specific directory.
Example: Run discovery on a specific test directory and save reports to a specific output folder:
python -m xmlrunner discover -t ~/mycode/tests -o /tmp/build/junit-reports