docs(flaky-tests): document the Swift report sources added in CLI 0.15.5

[dfrankland]

Documents --swift-test-xunit-paths (trunk-io/analytics-cli#1181, trunk-io/analytics-uploader#144) and --use-experimental-xcresult-test-locations (trunk-io/analytics-cli#1180), across four pages.

Hold this until 0.15.5 is out of beta. Both flags exist only in 0.15.5-beta.1/beta.2 today; latest still resolves to 0.15.4, so the GitHub Actions snippet here fails with an unknown-argument error until the stable release lands. The pages state "requires 0.15.5 or newer" rather than pinning a beta version.

Swift Testing page

The page said the report lands at ./junit.xml. It does not, for a Swift Testing suite: one swift test --xunit-output junit.xml --parallel run writes two files — junit-swift-testing.xml for @Test/@Suite and junit.xml for XCTest — and without --parallel the XCTest file is never written even though those tests ran. Anyone following the old page uploaded the wrong file, or half a run without being told.

The upload example now uses --swift-test-xunit-paths, with a section on why it is a separate argument from --junit-paths: that XML carries no file path for any test case, so Trunk resolves each test to its declaring file by querying sourcekit-lsp over the checkout. That is what CODEOWNERS attribution and file-level links need. Requirements (sourcekit-lsp on PATH, running inside the checkout) are listed.

A <Warning> covers the history impact, which seemed worse to leave for a customer to discover: file feeds the test id, so a repository moving off --junit-paths changes every affected id once, and the same test uploaded as .xcresult and as xunit XML is two distinct tests.

XCTest page

Adds --use-experimental-xcresult-test-locations as an opt-in beta. It is hide = true in clap, so this is a deliberate call to surface it — flagging that here for review. The case for documenting it: it is the only way a passing xcresult test gets a file at all, and an Objective-C heavy repository will quietly fail to resolve everything until TRUNK_XCRESULT_TEST_LOCATIONS_BUDGET_SECS is raised, which nobody can find without docs. The Quick / +testInvocations limitation and the "unset rather than set to false" env-var wart are both noted, along with a tuning table carrying the real defaults from Limits.

Also adds a pointer for SwiftPM users, who have no .xcresult to upload, toward the Swift Testing page.

CLI reference and GitHub Actions

Swift tabs in the upload and test format tab groups, argument-table rows for both flags, and a swift-test-xunit-paths example in the Actions CodeGroup.

Testing

Read the flag definitions, handle_swift_test_xunit, test_locations.rs and the swift-test-xunit fixture on origin/main of both repos; every default and behavior claim here traces to that code. Prose only — no nav or docs.json changes. mintlify broken-links could not run locally (unsupported on Node 25), so the four internal links were checked by hand against the file tree and heading anchors.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
trunk	🟢 Ready	View Preview	Sep 16, 2026, 7:21 PM

[dfrankland]

Pushed b4b583f, folding in the customer-facing instructions from this thread. Three things it covered that the pages did not, plus one correction:

• An offline trial of the xcresult flag. --dry-run with --disable-quarantining (the quarantine lookup being the one call --dry-run doesn't skip), then grep -c 'file="' bundle_upload/junit/0 — which is zero without the flag for an all-passing bundle, so the reader sees the difference directly.
• Tuning knobs are flags too. The table now carries --xcresult-test-locations-* alongside the env vars, since the flag is what you reach for while trialling by hand. Same for the = that require_equals makes mandatory when passing a value.
• What unresolved tests look like. A test that doesn't resolve is left blank rather than failing the upload, which is how a mismatched checkout presents. Split by log level while documenting it: the xcresult test files: N from a declaration, N with no declaration found summary is info! and prints by default, only the per-test is declared at line is debug! and needs -v.

One correction to the thread, worth knowing before these instructions go to a customer again: "we find sourcekit-lsp through xcrun" is macOS-only. Since trunk-io/analytics-cli#1179, find_program tries xcrun --find on macOS and falls back to PATH, and on Linux it's PATH only — which is what makes --swift-test-xunit-paths work on a Linux runner, where the Swift toolchain ships sourcekit-lsp and there is no xcrun. The Swift Testing page states it that way.

[dfrankland]

Pushed bcb4e56: --swift-test-xunit-paths takes globs now, per trunk-io/analytics-cli#1201, so the "files, not globs" wording is gone from all three places it appeared.

The Swift Testing and GitHub Actions snippets glob rather than naming both files — junit*.xml reaches the pair a single run writes, which is a better example than spelling them out, and it stops the XCTest half from being quietly dropped by someone who copies the line and only edits one filename. The cli-reference tabs still list both files explicitly, since that is where the two-file behavior is worth showing.

Also noted what the dedupe does: a file matched by more than one pattern is uploaded once. That is the question a glob raises and a file list does not, and the answer is not guessable.

No new version note — globs ship in the same 0.15.5 these pages already require. That does assume analytics-cli#1201 lands before 0.15.5 goes stable; if it slips to 0.15.6, this needs a revisit.

Merge order for the set, all gated on that release: analytics-cli#1201 → analytics-uploader#147 → this.