Install & Compatibility
Where this runs
tested against v1.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.116s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.092s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TestSuite
✓ from junit_xml import TestSuite
TestCase
✓ from junit_xml import TestCase
This quickstart demonstrates how to create `TestCase` objects, add them to a `TestSuite`, and then write the complete JUnit XML structure to a file. It includes examples of successful and failed tests, and uses `stdout` and `stderr` for additional messaging.
from junit_xml import TestSuite, TestCase
import os
# Create some test cases
test_cases = [
TestCase('Test case 1', 'com.example.package', 1.23, stdout='Output for TC1', stderr='Error for TC1'),
TestCase('Test case 2', 'com.example.package', 0.5,
stdout='Another output', stderr='Another error')
]
# A failed test case example
failed_test_case = TestCase('Failed test', 'com.example.package', 0.1)
failed_test_case.add_failure_info('Assertion failed', 'Expected 1, got 0')
test_cases.append(failed_test_case)
# Create a test suite and add test cases
# The timestamp should be in ISO 8601 format
test_suite = TestSuite(
"My example test suite",
test_cases,
hostname="localhost",
id="0",
package="com.example.package",
timestamp="2024-07-08T10:30:00"
)
# Write the test suite to an XML file
output_filename = os.environ.get('JUNIT_XML_OUTPUT_FILE', 'output.xml')
with open(output_filename, 'w', encoding='utf-8') as f:
TestSuite.to_file(f, [test_suite], prettyprint=True)
print(f"JUnit XML written to {output_filename}")
Debug
Known issues
breakingThe constructor signature for `TestCase` changed significantly in version 1.0.0. Arguments like `output` and `error` were removed and replaced with `stdout` and `stderr` attributes, and the order of arguments was altered.fixReview the new `TestCase` constructor signature and attribute names (`stdout`, `stderr`) in the documentation when upgrading from versions prior to 1.0.0.
affects: <1.0.0 to >=1.0.0
breakingThe constructor signature for `TestSuite` was also updated in version 1.0.0. The `testcases` argument became a required positional argument after the suite name, and other keyword arguments were added or modified.fixWhen upgrading from versions prior to 1.0.0, ensure your `TestSuite` instantiation matches the new signature, particularly the position of the `test_cases` list.
affects: <1.0.0 to >=1.0.0
gotchaThe `timestamp` argument for `TestSuite` expects an ISO 8601 formatted string (e.g., 'YYYY-MM-DDTHH:MM:SS'). Providing other formats may lead to invalid XML or parsing issues in consuming tools.fixUse `datetime.now().isoformat()` or similar to generate a correctly formatted timestamp string.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'junit_xml'
The 'junit-xml' Python package has not been installed in the current environment.
fixRun `pip install junit-xml` to install the library.
org.xml.sax.SAXParseException: An invalid XML character (Unicode: 0x...) was found in the element content of the document.
The generated JUnit XML contains characters that are not valid according to the XML 1.0 specification, often originating from test output (stdout, stderr, or failure messages) which can cause CI/CD tools to fail parsing.
fixEnsure that all strings passed into `TestSuite` and `TestCase` objects, especially for `stdout`, `stderr`, and `message` attributes of failures/errors, only contain valid XML characters. The `junit-xml` library (version 1.9) automatically strips some illegal Unicode characters, but manual sanitization of problematic input may be necessary if issues persist.
Attribute 'errors' must appear on element 'testsuite' (or similar errors like missing 'failures', 'tests', 'classname')
The JUnit XML report generated by `junit-xml` is missing required attributes that continuous integration tools (like Jenkins, GitLab CI) expect in the `testsuite` or `testcase` elements, often due to strict schema validation.
fixEnsure that all `TestSuite` objects are initialized with `errors`, `failures`, and `tests` attributes (even if zero), and `TestCase` objects include `classname`, `name`, and `time` to meet the expectations of most JUnit XML parsers.
Upgrade
Version history
1.9latest on PyPI · released Feb 22, 2020
Audit
Dependencies
No dependency data recorded yet.