Source test cases from other repositories

[PranjalManhgaye]

What this is about

(closes #538)

right now, every entry in tests.yaml assumes the tutorial folder is already in this repo. you give a path like flow-over-heated-plate, and the runner finds it under the local precice/tutorials checkout.

Issue #538 asks for a way to run cases that live somewhere else — another git repo, a fork, or from a direct download link (e.g. a .tar.gz ), without copying the files into this repo first.

This PR adds an optional source block in tests.yaml for that.

What happens at runtime

I have not touched the local behaviour : if there is no source field, behaviour is the same as today.

If source is set:

1. The runner fetches the tutorial (git shallow clone or archive download) into a cache directory (~/.cache/precice-tutorials by default, or PRECICE_EXTERNAL_CACHE_DIR if you set it).
2. It loads metadata.yaml from that folder, same as for in-repo tutorials.
3. It copies the tutorial into the usual run directory and continues with Docker build, docker compose up, and fieldcompare.

TUTORIALS_REF / TUTORIALS_PR still only affect local tutorials. For external ones, the version is whatever you put in source.ref.

Example

Git:

- path: flow-over-heated-plate
  source:
    type: git
    url: https://github.com/precice/tutorials.git
    ref: develop
    subdir: .
  case_combination:
    - fluid-openfoam
    - solid-openfoam
  reference_result: ./flow-over-heated-plate/reference-results/fluid-openfoam_solid-openfoam.tar.gz

Archive:

- path: some-tutorial
  source:
    type: archive
    url: https://example.org/tutorial-bundle.tar.gz
  case_combination: [...]
  reference_result: ./some-tutorial/reference-results/...

type can be git or archive. If you omit source, it stays local.

For git, if clone --branch ref fails, there is a small fallback that tries fetching without a branch and then checks a few common default branch names.

How it works

flowchart LR
  A[tests.yaml entry] --> B{Has source?}
  B -->|No| C[Use local tutorial]
  B -->|Yes| D[Fetch git or archive]
  D --> E[Resolve tutorial folder]
  E --> F[Copy into run directory]
  F --> G[Docker build and run]
  G --> H[fieldcompare vs reference]

Loading

Files touched

• tools/tests/systemtests/sources.py — new: fetch + cache + resolve_tutorial_root
• tools/tests/systemtests/TestSuite.py — read source, load external metadata when needed
• tools/tests/systemtests/Systemtest.py — copy from resolved path; ref/PR checkout only for local
• tools/tests/metadata_parser/metdata.py — Tutorial.source, ReferenceResult.base_dir
• tools/tests/README.md — short how-to
• changelog-entries/732.md

I did not add a real source: entry to tests.yaml yet, so existing suites should behave as before until someone opts in.

Rebased onto current develop and fixed the merge conflicts in README / Systemtest.py / TestSuite.py.

testing

I ran the usual checks on external-source-fix after rebasing onto develop:
python3 -m compileall on tools/tests/systemtests and metadata_parser — no issues.

Loaded all 13 suites from tests.yaml — unchanged for entries without source.

For git, I used a smoke test that drops quickstart from the local index and points at precice/tutorials on develop. The tutorial was fetched into PRECICE_EXTERNAL_CACHE_DIR, source.type was git, and the quickstart systemtest (fluid-openfoam + solid-cpp) passed end to end. No tutorials_ref symlink in the run directory.

For archive, I built a quickstart-develop.tar.gz from the same develop checkout (symlinks resolved so scripts are real files), served it via a file:// URL, and ran the same smoke path with source.type: archive. Download, extract, cache, copy, Docker build/run, and fieldcompare all passed. Again, no tutorials_ref.

I also ran the normal quickstart entry from tests.yaml with TUTORIALS_REF:develop so local tutorials still behave as today when the path exists in the repo.

Docker images were already cached, so both external runs were on the order of ~15–20s each; the steps were still the full pipeline.

Checklist

• Changelog entry in changelog-entries/732.md

[PranjalManhgaye]

@MakisH , sir happy to update anything needed before review .

[precice-bot]

This pull request has been mentioned on preCICE Forum on Discourse. There might be relevant details there:

https://precice.discourse.group/t/gsoc-2026-pranjal-manhgaye/2769/6

[MakisH]

@PranjalManhgaye this seems quite long. Is it still intended for review in its current form?

In the PR description, I would expect some explanation of the whole concept.

Please also resolve the conflicts.

[PranjalManhgaye]

thanks @MakisH , i will take an another look of this pr and will inform you if its indeed necessary to review it .

[PranjalManhgaye]

@MakisH , i updated the description, rebased on develop, resolved the conflicts, and retested everything locally ,Existing suites are unchanged and both external git + archive quickstart paths are passing now. i think everything should be good now, but happy to change anything if you spot something ,,