· 7 min read

JUnit XML Format: Elements, Attributes and What Each Runner Writes

JUnit XML has no official spec. The elements and attributes readers expect, what junit-10.xsd requires, and what pytest, Playwright, Jest, Go and Maven write.

The JUnit XML tree: an optional testsuites root, testsuite elements with properties and test cases, and a failure, error or skipped child on every test case that did not pass.
The JUnit XML tree: an optional testsuites root, testsuite elements with properties and test cases, and a failure, error or skipped child on every test case that did not pass.

JUnit XML is the file CI systems read to show test results, but no standards body owns it. Each test runner writes its own dialect and each reader accepts its own subset, so the same run can show different numbers in two places. The closest thing to a reference is junit-10.xsd from the Jenkins xUnit plugin: pytest's default output targets it, and Maven Surefire publishes its own schema for the files it writes. This guide covers the element tree, the attributes each schema requires, and what pytest, Playwright, Jest, Go and Maven Surefire actually put in the file, checked against each tool's documentation or source as of November 2026.

The element tree

A trimmed file with one test of each outcome, reformatted for reading:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="unit" tests="4" failures="1" errors="1" time="2.481">
  <testsuite name="tests.test_cart" tests="4" failures="1" errors="1" skipped="1"
             time="2.481" timestamp="2026-11-21T10:15:00+00:00" hostname="runner-7">
    <properties>
      <property name="python" value="3.13"/>
    </properties>
    <testcase classname="tests.test_cart" name="test_add_item" time="0.412"/>
    <testcase classname="tests.test_cart" name="test_coupon" time="0.051">
      <failure message="assert 12 == 10">Full traceback of the failed assertion</failure>
    </testcase>
    <testcase classname="tests.test_cart" name="test_checkout" time="2.018">
      <error message="failed on setup with &quot;ConnectionError&quot;">Traceback of the setup error</error>
    </testcase>
    <testcase classname="tests.test_cart" name="test_gift_wrap" time="0.000">
      <skipped message="gift wrap is off"/>
    </testcase>
  </testsuite>
</testsuites>
  • <testsuites> is an optional root that groups suites. Maven Surefire leaves it out and writes one <testsuite> per file.
  • <testsuite> is a group of tests: a file, a class, a package or a whole run, depending on the runner. It carries the counts.
  • <properties> holds name and value pairs about the run, such as the environment.
  • <testcase> is one test. With no child result element, it passed.
  • <failure>, <error> and <skipped> mark a test that didn't pass. The message attribute is the short reason and the element text is the stack trace or other detail.
  • <system-out> and <system-err> carry captured output, on a test case or a suite.

The split between <failure> and <error> is a convention, and runners draw it in different places: pytest uses <error> for a failed setup or teardown, Playwright for a thrown exception such as a timeout. A dashboard or release gate that reads only failures misses every test counted under errors. Count both as failed.

What junit-10.xsd and the Surefire schema require

The Jenkins xUnit plugin's junit-10.xsd is the schema pytest names for its default xunit2 output. Its rules, element by element:

ElementRequired attributesOptional attributes
<testsuites>nonename, tests, failures, errors, time
<testsuite>name, tests, failures, errorsskipped, time, timestamp, hostname, id, package, file, group, log, url, version
<testcase>nameclassname, time, group
<failure>, <error>, <skipped>nonemessage, type
<property>name, valuenone

Three details in it explain most validation errors:

  • <testcase> has no file attribute and no <properties> child. pytest drops file and line in its default mode for this reason, and its docs warn that record_property, which adds properties to a test case, breaks validation against the latest schema.
  • <testsuites> declares no skipped count. Skipped tests are counted on each <testsuite>.
  • Suite time has a pattern: digits with up to three decimals, and optional commas as thousands separators, so 1,234.567 is valid there. A reader that parses time as a plain number gets nothing from it, and a decimal comma such as 1,75 matches neither the pattern nor a number parser.

Maven Surefire's own surefire-test-report.xsd (version 3.0.2) is stricter in other places. Its only top-level element is <testsuite>, which must have name, tests, errors, skipped and failures and may have a flakes count. Every <testcase> needs name and time. Times are typed as numbers (xs:float), so the thousands separators that junit-10.xsd allows are invalid here, and <properties> only appears on the suite. It adds four retry elements, covered under Surefire below.

What each runner writes

pytest

pytest --junit-xml=report.xml writes the file (pytest docs). What lands in it, per the docs and the junitxml.py source of pytest 9.2.0:

  • A <testsuites name="pytest tests"> root with one <testsuite name="pytest"> for the whole run. Set junit_suite_name in the config to change the suite name.
  • The suite carries errors, failures, skipped, tests, time, timestamp and hostname. The timestamp is local time with its UTC offset and microseconds, such as 2026-11-21T10:15:00.123456+01:00.
  • classname is the dotted module path plus the class, as in tests.test_cart.TestCart, and name is the test function, with the parameter ID in brackets for a parametrized test: test_coupon[SAVE10].
  • time covers setup, call and teardown. junit_duration_report = call reports the call alone.
  • A failed assertion writes <failure>, a failure in a fixture's setup or teardown writes <error message='failed on setup with "..."'>, and skips write <skipped type="pytest.skip"> or, for expected failures, type="pytest.xfail".
  • Captured output stays out of the file unless junit_logging says otherwise; its default is no.

The default junit_family has been xunit2 since pytest 6.1 (reference). Setting junit_family = xunit1 brings back file and line on each test case and keeps attributes added with record_xml_attribute, which xunit2 filters out. Under xunit2, record_property still writes its properties but warns that it needs xunit1.

Playwright

npx playwright test --reporter=junit prints the XML to stdout; set PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml or reporter: [['junit', { outputFile: 'results.xml' }]] in the config to write a file (reporters docs). A file shaped like the reporter's output in Playwright 1.65.1, with example values:

<testsuites id="" name="" tests="3" failures="1" skipped="0" errors="1" time="9.8">
  <testsuite name="checkout.spec.ts" timestamp="2026-11-21T10:15:00.000Z" hostname="chromium"
             tests="3" failures="1" skipped="0" time="12.9" errors="1">
    <testcase name="checkout › pays by card" classname="checkout.spec.ts" time="4.1">
    </testcase>
    <testcase name="checkout › applies a coupon" classname="checkout.spec.ts" time="3.3">
      <failure message="expect(locator).toHaveText(expected) failed" type="expect.toHaveText">Error details</failure>
    </testcase>
    <testcase name="checkout › pays by invoice" classname="checkout.spec.ts" time="5.5">
      <error message="locator.click: Timeout 5000ms exceeded." type="TimeoutError">Error details</error>
    </testcase>
  </testsuite>
</testsuites>
  • One <testsuite> per test file and project. Its name is the file path, and hostname holds the project name, not a machine.
  • A test case's name joins its describe titles and its own title with ›, and classname is the file path. includeProjectInTestName puts the project in front of the name, which keeps the same test from two browser projects apart.
  • A failed expect writes <failure> with the matcher as type; any other thrown error, a timeout included, writes <error> with the error's name as type.
  • A test case's time adds up all its attempts, retries included. A suite's time sums its tests, while the root's time is the run's wall-clock time, so with parallel workers the suites add up to more than the root.
  • Test annotations become <properties> on the test case, which the source ties to the JUnit extensions of the Xray test management tool, and attachments such as traces are listed in <system-out> as [[ATTACHMENT|path]] lines.
  • id and name on the root are empty unless PLAYWRIGHT_JUNIT_SUITE_ID and PLAYWRIGHT_JUNIT_SUITE_NAME are set.

For a sharded run, merge the shards first and write one JUnit file from the merged result; the sharded reports guide shows the merge config.

Jest with jest-junit

Jest writes JUnit XML through the jest-junit reporter: npm install --save-dev jest-junit, then jest --ci --reporters=default --reporters=jest-junit writes junit.xml in the working directory (jest-junit README). Its defaults:

  • The root is <testsuites name="jest tests">, set by JEST_SUITE_NAME.
  • Each test file becomes a <testsuite> named by the template {title}.
  • A test case's classname and name both default to {classname} {title}, the describe path plus the test title, so the two attributes are identical. A reader that groups by class then shows one group per test.

Setting JEST_JUNIT_CLASSNAME="{classname}" and JEST_JUNIT_TITLE="{title}" splits them into the describe path and the test title. JEST_JUNIT_ADD_FILE_ATTRIBUTE="true" adds a file attribute, which the README notes was validated on CircleCI and GitLab CI.

Go with gotestsum

For Go tests, gotestsum writes JUnit XML with gotestsum --junitfile unit-tests.xml. The testsuite name and the test case classname are the full package path by default. --junitfile-testsuite-name and --junitfile-testcase-classname take short (the package's own name), relative (the path from the repository root) or full, for readers that expect a shorter name.

Maven Surefire

Surefire runs in mvn test and writes one TEST-<class>.xml per test class into target/surefire-reports, each with a <testsuite> root. Run with retries, as in mvn -Dsurefire.rerunFailingTestsCount=2 test, it records them inside the test case (rerun docs):

<testcase name="retriesPayment" classname="com.example.PaymentTest" time="0.31">
  <flakyFailure message="expected: &lt;200&gt; but was: &lt;503&gt;" type="org.opentest4j.AssertionFailedError">
    <stackTrace>Stack trace of the first attempt</stackTrace>
  </flakyFailure>
</testcase>

<flakyFailure> and <flakyError> mean a failed run followed by a pass. A test that never passes keeps its <failure> or <error> and gets a <rerunFailure> or <rerunError> for each further failing run. Readers that don't know these elements see the flaky test above as a plain pass.

Checking a file before CI reads it

Most broken JUnit files fail in the same few ways: suite counts that disagree with the test cases after a merge script or a crashed writer, times with a decimal comma, duplicate test names, and empty suites from a run that collected no tests. The JUnit XML validator checks for those with the line number of each, and the JUnit XML viewer shows the run as a table of failures, slow tests and suites. Both read the file in the browser and upload nothing.

When the numbers on a dashboard disagree with what the suite did, start with three questions: does the reader count errors as failures, does it read the counts from <testsuite> attributes or from the test cases, and does it understand the runner's retry elements. The JUnit XML analysis skill works through those questions on your own report files in Claude Code.

Start with qa-starter.

10 plugins every tester needs on any stack: test planning, test data, environments, reporting, flaky tests, bug reports and exploratory testing.

/plugin install qa-starter@testland-qa