unittest-xml-reporting

unittest-xml-reporting (also known as xmlrunner) is a drop-in test runner for Python’s standard unittest framework that writes machine-readable test results in the xUnit/JUnit XML format. Instead of only printing pass/fail output to the console, it emits structured XML files that continuous-integration servers, IDEs, and build systems can parse to display per-test results, timings, and failure details.

It plugs into existing unittest suites with minimal changes, ships a Django test-runner integration, and produces output compatible with Jenkins, GitLab CI, and other tools that understand the JUnit XML schema. This makes it a common bridge between a plain Python test suite and the reporting dashboards of a CI pipeline.

What You Get

• An XMLTestRunner that is a drop-in replacement for unittest.TextTestRunner, writing one or more xUnit XML report files.
• Compatibility with JUnit XML consumers including Jenkins JUnit/xUnit plugins and GitLab CI test reports.
• A Django test runner (xmlrunner.extra.djangotestrunner.XMLTestRunner) for producing XML reports from Django test suites.
• Control over output directory, per-suite vs. single-file output, stdout/stderr capture, and report formatting.
• A helper to strip and post-process output for stricter XSD-validating consumers.

Common Use Cases

• Publishing Python unittest results to a Jenkins or GitLab CI dashboard as JUnit XML.
• Adding structured test reporting to a Django project’s test suite.
• Feeding test timing and failure data into build systems and IDEs that parse xUnit XML.

Under The Hood

Architecture - The package layers onto the standard library: xmlrunner/unittest.py vendors a subset of unittest primitives, result.py defines _XMLTestResult which collects _TestInfo records per test, and runner.py’s XMLTestRunner drives the run and serializes results via builder.py into JUnit-style <testsuite>/<testcase> XML. The extra/ package holds the Django runner and an xunit_plugin helper for stricter XSD consumers.

Tech Stack - Pure Python (3.10+), packaged via pyproject.toml, with no runtime dependencies beyond the standard library. It builds XML with Python’s xml modules and integrates with unittest and optionally Django. Tests run under tox across supported Python versions.

Code Quality - The codebase is small, focused, and covered by a tests/ suite exercised in CI with coverage reporting (codecov/coveralls badges). Code handles tricky edge cases such as stripping illegal XML control characters and capturing stdout/stderr per test, showing attention to real-world CI output. Naming is conventional and the public surface is narrow.

API Design - The primary entry point mirrors unittest.TextTestRunner, so adoption is a near one-line swap for anyone already using unittest. Configuration is done through constructor keyword arguments (output directory, single-file vs. per-suite, output capture), which keeps the getting-started boilerplate minimal while still exposing the knobs CI setups need.