From 55851a3a077a9577ba968fb39bc729fee3bfa904 Mon Sep 17 00:00:00 2001 From: David Anthoff Date: Sat, 15 Aug 2026 08:20:42 -0700 Subject: [PATCH] Document the test item id format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ids appear in the results JSON and the JUnit XML and were documented nowhere. Covers what the parts mean, that they are stable under editing, and that an id identifies a test item within its package rather than within a workspace — so two checkouts of one package share an id, and it is the file path that distinguishes them. Also flags that the `path:name` shown in progress output is a display form rather than an id, which reads confusingly now that real ids exist. Co-Authored-By: Claude Opus 5 (1M context) --- guide/cli.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/guide/cli.md b/guide/cli.md index 5163175..596a22d 100644 --- a/guide/cli.md +++ b/guide/cli.md @@ -187,6 +187,37 @@ juliati --junit-xml junit.xml One `` per source file, one `` per (test item, profile), with captured output in `` and per-item performance statistics as ``. The JSON results are richer; the JUnit XML is far more portable. Writing both is fine. +## Test item ids + +Both output formats identify each test item by an id that looks like this: + +``` +MyPkg@a1b2c3d4/test/parsing_tests.jl::parses floats +``` + +That is `/::`. The package is its name plus the first eight hex digits +of its UUID — the name is what you recognise, and the UUID fragment separates two different +packages that happen to share a name, such as a vendored copy beside a dev checkout. The path +is relative to the package root and always uses `/`, so an id is identical on Windows and +Linux, and identical in a dev checkout and on a CI runner. That last property is what makes +ids usable for tracking a test across runs. + +Ids are stable under editing: inserting or removing other test items does not change them. +The one exception is two test items sharing a name in one file, which is a definition error — +every occurrence is then suffixed `#1`, `#2`, … so each stays individually addressable. + +An id identifies a test item **within its package**, not within a workspace. The same package +checked out into two folders produces the same id from both, deliberately: two checkouts +differ only by location, and location differs between your machine and CI, so an id cannot be +both unique across a workspace and portable across machines. Where the difference matters — +the console output, the `uri` field in the JSON results, and the `classname` in the JUnit XML — +the file path distinguishes them. + +::: tip +The progress output above shows `test/test_parsing.jl:parse basics`, which is a display +form, not an id. Ids appear in `--results-json` and `--junit-xml`. +::: + ## Exit codes | Code | Meaning |