test: read the instance library from a small library kept with the tests

[ehennestad]

Stacked on #188. Test infrastructure for the instance library, and no change to the toolbox.

Why

InstanceLibraryTest read the library the toolbox downloads, so it depended on a network, on seventy megabytes arriving intact, and on whatever upstream held on the day. Its assumeNotEmpty guards turned a missing or incomplete download into a silent skip, which is what CI was doing for two of its tests earlier in this stack. And the cases that need the library in a known state, a damaged document, an empty version folder, a folder that is not a library at all, could only be checked by hand, and were.

getSingleton(folderPath) existed for a caller with a clone of the instances repository somewhere else, and nothing in the toolbox called it. A test library is that caller.

What

A small library kept with the tests, under tools/tests/fixtures/instances/latest: six real instance documents, 24 KB, chosen to cover the layouts the class has to read. Two age categories and a biological sex, one type per folder under terminologies, so a folder that names a type is told apart from a subgroup. A license and a content type, under the plural folder names their IRIs also use, for the segment lookup. A parcellation entity in a subfolder of its atlas, for the subgroup. Every type exists in every model version from v3.0 on, so a pipeline bump cannot strand it.

ommtest.helper.InstanceLibraryFixture, beside ModelVersionFixture and in its pattern. It copies the test library into a temporary folder and makes that the library in use, so a test reads known instances and may change its copy. Afterwards the library in use is deleted rather than read again from the default location, so a suite that never needs the downloaded library never downloads it; the next bare getSingleton() reads the default again. Each application makes its own copy.

InstanceLibraryTest rewritten on the fixture. Expectations are now exact, a table of the six instances with their types and modules, rather than "no row is empty". The cases checked by hand earlier in the stack are tests: a document without a readable @type is reported by name and left untyped while its neighbours are typed; an empty version folder reads as an empty library with its columns in place; a location that does not exist, and one that exists but holds no version folder, are rejected before the library in use is touched.

InstanceLibraryIntegrationTest keeps what only the downloaded library can answer: that every instance upstream ships today resolves to a type in the model, which is the regression check for the next upstream rename, and that the library follows the model version across the versions upstream publishes. It keeps its assumption.

Notes

The fixture hands out the library as fixture.Library. A bare getSingleton() means the library at the default location, and asking for it from inside a fixture-backed test replaces the fixture's library with the downloaded one; the fixture's help says so. Consumers such as listControlledInstances and parseInstanceIRI call it bare, so the fixture serves tests of the class itself, not tests of those consumers.

Locally, .git/info/exclude may list *.jsonld; the fixture documents were added with git add -f and are tracked like the other fixtures.

🤖 Generated with Claude Code

[github-actions]

Test Results (R2026a)

854 tests  +2   852 ✅ +2   4m 4s ⏱️ -5s
 26 suites +1     2 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 75c3ca5. ± Comparison against base commit 24a3d6e.

♻️ This comment has been updated with latest results.

[github-actions]

Test Results (R2022a)

854 tests  +2   850 ✅ +2   3m 21s ⏱️ -19s
 26 suites +1     4 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 75c3ca5. ± Comparison against base commit 24a3d6e.

♻️ This comment has been updated with latest results.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.67%. Comparing base (24a3d6e) to head (75c3ca5).

Additional details and impacted files

@@                            Coverage Diff                             @@
##           report-unresolved-controlled-instances     #190      +/-   ##
==========================================================================
+ Coverage                                   80.19%   80.67%   +0.47%     
==========================================================================
  Files                                         423      423              
  Lines                                        4387     4387              
==========================================================================
+ Hits                                         3518     3539      +21     
+ Misses                                        869      848      -21     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.