dynamic-systems-testing-framework 1.0.1__tar.gz → 1.1.0__tar.gz

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/.gitignore

@@ -6,8 +6,9 @@ dist/
 build/
 *.egg
 
-# Virtual environments
+# Virtual environments (.venv-example/: the one docs/guides/first-run.md makes)
 .venv/
+.venv-example/
 venv/
 .env
 
@@ -46,6 +47,9 @@ testing_output/
 # Generated reports (dashboard.html, interactive plots, comparison_data.json)
 reports/
 
+# The documentation site, built (sphinx-build docs docs/_build/html)
+docs/_build/
+
 # Reference-FMUs binaries (fetched by scripts/fetch_reference_fmus.py)
 examples/fmu/reference-fmus-binaries/
 

dynamic_systems_testing_framework-1.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: dynamic-systems-testing-framework
+Version: 1.1.0
+Summary: Dynamic Systems Testing Framework — regression & unit testing for time-dependent system behavior, with plug-in backends: Modelica (Dymola, OpenModelica), FMU (FMPy), Julia (ModelingToolkit) and Python to start
+Project-URL: Homepage, https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework
+Project-URL: Repository, https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework
+Project-URL: Documentation, https://dstf.readthedocs.io/
+Project-URL: Issues, https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/issues
+Project-URL: Changelog, https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/blob/main/CHANGELOG.md
+Author: Scott Greenwood
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dymola,fmi,fmu,julia,modelica,modelingtoolkit,openmodelica,regression-testing,simulation,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: numpy>=1.20
+Requires-Dist: psutil>=5.9
+Provides-Extra: author
+Requires-Dist: nicegui>=3.16; extra == 'author'
+Requires-Dist: regex>=2026.9.10; extra == 'author'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Requires-Dist: scipy>=1.10; extra == 'dev'
+Requires-Dist: types-regex>=2026.9.10; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.8.6; extra == 'docs'
+Requires-Dist: myst-parser>=4.0; extra == 'docs'
+Requires-Dist: sphinx>=8.1; extra == 'docs'
+Provides-Extra: fmpy
+Requires-Dist: fmpy>=0.3; extra == 'fmpy'
+Provides-Extra: om
+Requires-Dist: ompython>=3.5; extra == 'om'
+Description-Content-Type: text/markdown
+
+# Dynamic Systems Testing Framework (DSTF)
+
+[![quality](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/actions/workflows/quality.yml/badge.svg)](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/actions/workflows/quality.yml)
+
+DSTF is regression and unit testing for the behaviour of time-dependent
+systems: Modelica libraries, FMUs, Julia models, or anything Python can
+compute. It finds a library's tests, simulates them with a backend — Dymola,
+OpenModelica, FMPy, Julia or Python, or one a plug-in adds — and scores each
+result against a stored baseline by the criteria you write. It reports a
+verdict per test on the command line, as JUnit XML for CI, and as a dashboard
+and a page per test in the browser.
+
+DSTF is in beta: the command line and the testing.json keys may still change
+between minor versions; the changelog says when.
+
+## Install
+
+```console
+$ uv tool install dynamic-systems-testing-framework
+```
+
+or `pipx install dynamic-systems-testing-framework`. The command is `dstf`.
+The `author` extra adds `dstf author`, a browser tool for writing criteria
+beside the plots they score; `fmpy` and `om` add what the FMPy and
+OpenModelica backends drive.
+
+## A first run
+
+The Python example library needs no simulator. From a clone of this
+repository, in a Python environment with numpy and scipy:
+
+```console
+$ git clone https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework.git
+$ cd DynamicSystemsTestingFramework
+$ python3 -m pip install numpy scipy
+$ dstf --config examples/python/PythonTestingLib/Resources/ReferenceResults/testing.json run
+```
+
+It runs three tests, compares each with its stored baseline, prints a verdict
+per test and opens the dashboard:
+
+![The dashboard: one row per test with its status, worst NRMSE, criteria passed and times](https://raw.githubusercontent.com/ORNL-Modelica/DynamicSystemsTestingFramework/main/docs/img/dashboard.png)
+
+## Documentation
+
+<https://dstf.readthedocs.io/> — a first run, setting up `testing.json` for
+your library, adding tests, reading results, baselines, criteria, CI, a page
+per simulator, writing a backend plug-in, and a reference of every command,
+key and comparison mode.
+
+## Changelog and licence
+
+What changed in each version is in
+[CHANGELOG.md](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/blob/main/CHANGELOG.md).
+DSTF is released under the MIT licence:
+[LICENSE](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/blob/main/LICENSE).

dynamic_systems_testing_framework-1.1.0/README.md

@@ -0,0 +1,56 @@
+# Dynamic Systems Testing Framework (DSTF)
+
+[![quality](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/actions/workflows/quality.yml/badge.svg)](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/actions/workflows/quality.yml)
+
+DSTF is regression and unit testing for the behaviour of time-dependent
+systems: Modelica libraries, FMUs, Julia models, or anything Python can
+compute. It finds a library's tests, simulates them with a backend — Dymola,
+OpenModelica, FMPy, Julia or Python, or one a plug-in adds — and scores each
+result against a stored baseline by the criteria you write. It reports a
+verdict per test on the command line, as JUnit XML for CI, and as a dashboard
+and a page per test in the browser.
+
+DSTF is in beta: the command line and the testing.json keys may still change
+between minor versions; the changelog says when.
+
+## Install
+
+```console
+$ uv tool install dynamic-systems-testing-framework
+```
+
+or `pipx install dynamic-systems-testing-framework`. The command is `dstf`.
+The `author` extra adds `dstf author`, a browser tool for writing criteria
+beside the plots they score; `fmpy` and `om` add what the FMPy and
+OpenModelica backends drive.
+
+## A first run
+
+The Python example library needs no simulator. From a clone of this
+repository, in a Python environment with numpy and scipy:
+
+```console
+$ git clone https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework.git
+$ cd DynamicSystemsTestingFramework
+$ python3 -m pip install numpy scipy
+$ dstf --config examples/python/PythonTestingLib/Resources/ReferenceResults/testing.json run
+```
+
+It runs three tests, compares each with its stored baseline, prints a verdict
+per test and opens the dashboard:
+
+![The dashboard: one row per test with its status, worst NRMSE, criteria passed and times](https://raw.githubusercontent.com/ORNL-Modelica/DynamicSystemsTestingFramework/main/docs/img/dashboard.png)
+
+## Documentation
+
+<https://dstf.readthedocs.io/> — a first run, setting up `testing.json` for
+your library, adding tests, reading results, baselines, criteria, CI, a page
+per simulator, writing a backend plug-in, and a reference of every command,
+key and comparison mode.
+
+## Changelog and licence
+
+What changed in each version is in
+[CHANGELOG.md](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/blob/main/CHANGELOG.md).
+DSTF is released under the MIT licence:
+[LICENSE](https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/blob/main/LICENSE).

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "dynamic-systems-testing-framework"
-version = "1.0.1"
-description = "Dynamic Systems Testing Framework — regression & unit testing for time-dependent system behavior across Modelica (Dymola, OpenModelica), FMU (FMPy), Julia (ModelingToolkit), and Python backends"
+version = "1.1.0"
+description = "Dynamic Systems Testing Framework — regression & unit testing for time-dependent system behavior, with plug-in backends: Modelica (Dymola, OpenModelica), FMU (FMPy), Julia (ModelingToolkit) and Python to start"
 # What the package index shows: the README as the project page (its one image
 # is an absolute URL for that), the license by its SPDX name with the file
 # beside it, and where the source and the docs are.
@@ -14,6 +14,7 @@ keywords = [
     "modelingtoolkit", "simulation", "regression-testing", "testing",
 ]
 classifiers = [
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
@@ -59,12 +60,18 @@ fmpy = ["fmpy>=0.3"]
 # subprocess path instead.
 # Install with: uv sync --extra om --locked --inexact
 om = ["OMPython>=3.5"]
+# The documentation site (docs/conf.py): Sphinx, Markdown pages through MyST,
+# the Furo theme. Build it with:
+#   uv sync --extra docs --locked --inexact
+#   uv run sphinx-build -W --keep-going -b html docs docs/_build/html
+docs = ["sphinx>=8.1", "myst-parser>=4.0", "furo>=2024.8.6"]
 
 [project.urls]
 Homepage = "https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework"
 Repository = "https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework"
-Documentation = "https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/blob/main/docs/usage.md"
+Documentation = "https://dstf.readthedocs.io/"
 Issues = "https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/issues"
+Changelog = "https://github.com/ORNL-Modelica/DynamicSystemsTestingFramework/blob/main/CHANGELOG.md"
 
 [project.scripts]
 dstf = "dstf.cli:main_entry"
@@ -90,7 +97,7 @@ markers = [
     "fmpy: requires fmpy package",
     "ompython: requires OMPython package (persistent-worker OpenModelica)",
     "reference_fmus: requires Reference-FMUs binaries at examples/fmu/reference-fmus-binaries",
-    "julia: requires Julia 1.10+ with ModelingToolkit + OrdinaryDiffEq installed in examples/julia/JuliaMtkTestingLib",
+    "julia: requires Julia 1.11+ with ModelingToolkit + OrdinaryDiffEq installed in examples/julia/JuliaMtkTestingLib",
     "playwright: browser-driven reporter tests (requires playwright + chromium); until D97 this marker did not exist and -m 'not playwright' was a no-op filter",
 ]
 filterwarnings = [
@@ -151,6 +158,9 @@ files = [
     "src/dstf/plugins.py",
     "src/dstf/storage",
     "src/dstf/config.py",
+    "src/dstf/config_shape.py",
+    "src/dstf/json_types.py",
+    "src/dstf/backends/locate.py",
     "src/dstf/pipeline.py",
     "src/dstf/reporting/rows.py",
 ]

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/builtin/edit_criteria.py

@@ -130,7 +130,7 @@ class EditCriteria:
         sel = s.selection
         model_id = next(iter(sel.tests)) if len(sel.tests) == 1 else None
         if model_id is None or sel.leaf_path is None:
-            return "select one leaf"
+            return "select one criterion"
         # A compared test whose tree the Session will not materialize: its
         # leaves are on the plots, but every edit is refused — the Session's
         # reason, as the editor's why-line, not the view's leaf as if
@@ -154,7 +154,7 @@ class EditCriteria:
         # The panel is rebuilt after edits made elsewhere: Edit tree wrapping
         # the selected leaf leaves the selection's path naming a combinator.
         if leaf is None:
-            ui.label("this leaf is not in the scored tree")
+            ui.label("this criterion is not in the scored tree")
             return
         #: A folded row's members as they are read now: the act refuses
         #: the edit if a path no longer holds that member (`act`).

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/builtin/edit_on_plot.py

@@ -151,9 +151,9 @@ def _leaf_at(s: SessionView, model_id: str, path: str) -> dict:
         except (KeyError, IndexError, TypeError, ValueError):
             node = None
     if not isinstance(node, dict):
-        raise ValueError(f"{path} names no leaf of {model_id}")
+        raise ValueError(f"{path} names no criterion of {model_id}")
     if "combinator" in node:
-        raise ValueError(f"{path} is a combinator, not a leaf")
+        raise ValueError(f"{path} is a group, not a criterion")
     return node
 
 
@@ -463,7 +463,7 @@ def dragged(
     paths = [p for p, _ in _leaf_paths(s, model_id, variable)]
     path = _leaf_path_of(handle, paths)
     if path is None:
-        raise ValueError(f"{handle} names no leaf on {variable} of {model_id}")
+        raise ValueError(f"{handle} names no criterion on {variable} of {model_id}")
     if view is None:
         view = s.view(model_id, variable)  # full resolution, not the figure
     leaf = next((lv for lv in view.leaves if lv.path == path), None)

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/session.py

@@ -26,7 +26,7 @@ from ..backends import BackendUnavailableError, dataset_kind_for, select_backend
 from ..backends.base import Backend
 from ..backends.common.result_variables import tracked_results
 from ..backends.pool import ItemState, QueueItem, Refused, StartingWorker
-from ..backends.progress import recorded_backend
+from ..backends.progress import recorded_backend, refuse_unregistered
 from ..backends.types import (
     DatasetType,
     TestResult,
@@ -60,6 +60,7 @@ from ..discovery.spec_update import (
     implicit_tree_op,
     is_literal_variable,
     needs_materialization,
+    not_stored_notes,
     unknown_override_modes,
     validate_entry_keys,
     validate_entry_metric_tree,
@@ -375,6 +376,7 @@ def resolve_project(
         assert config.work_dir is not None  # resolved in __post_init__
         recorded, warning = recorded_backend(config.work_dir)
         if recorded and recorded != config.backend_name:
+            refuse_unregistered(recorded, config.work_dir)
             config = Config(
                 config_file=config_path, backend_name=recorded, work_dir=work_dir
             )
@@ -848,7 +850,7 @@ class Session:
     def rescore(self, model_id: str) -> TestComparison:
         """Score ``model_id`` against the spec with pending ops applied. A
         flat-override test first gets the same ``add /metrics`` op
-        ``spec-update`` prepends, so the document the tool edits and the one
+        ``spec update`` prepends, so the document the tool edits and the one
         it saves never differ in shape — but only when that tree scores
         exactly what the flat path scored (Conventions #7); otherwise the
         test is scored as loaded and nothing is staged. That op does not
@@ -1086,6 +1088,15 @@ class Session:
             result = replace(result, variables=tracked_results(test, result))
         return tracked_names(scored, result)
 
+    def not_stored_notes(self, model_id: str) -> list[str]:
+        """A sentence per baseline the test's entry, as staged, names that
+        this folder stores none of (:func:`~dstf.discovery.spec_update.
+        not_stored_notes`): `stage` took it — a soft check of another
+        folder — and the pending preview says it is not scored here, as
+        ``spec update`` prints it."""
+        project = self._require_project()
+        return not_stored_notes(self.spec.entry(model_id), model_id, project.store)
+
     def variable_texts(self, model_id: str) -> dict[str, VariableText]:
         """``{name: VariableText}`` for this test — both readings of every
         variable its page can show, from the ONE scope builder the report
@@ -1790,7 +1801,7 @@ class Session:
         return out
 
     def save(self) -> None:
-        """Apply exactly the pending ops through ``spec-update``'s
+        """Apply exactly the pending ops through ``spec update``'s
         read-modify-write, then reload. Refuses when the file changed on
         disk since it was loaded, and when the edits leave a criterion that
         can never be scored (`UnscorableSaveError`: `stage` took it, for its
@@ -2265,7 +2276,7 @@ class Session:
                 # class it reads results through — and silenced: the tool's
                 # process never narrates a run to the console it was
                 # started from.
-                backend = select_backend(project.config, persistent=True)
+                backend = select_backend(project.config, persistent=True, to_run=True)
                 backend.quiet = True
                 self._pool = open_pool(
                     project.config,

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/shell/app.py

@@ -18,7 +18,7 @@ def run_app(
     *,
     filter: str | None = None,
     package: str | None = None,
-    port: int | None = None,
+    port: int,
     work_dir: Path | None = None,
     backend: str | None = None,
     show: bool = True,
@@ -46,7 +46,7 @@ def run_app(
     ui.run(
         shell.index,
         host="127.0.0.1",
-        port=port or 8080,
+        port=port,
         show=show,
         reload=False,
         title="DSTF",

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/shell/header.py

@@ -758,6 +758,11 @@ class PendingDrawer:
         ]
         for text in dict.fromkeys(said):
             ui.label(text).classes("text-xs dstf-mono").mark("drawer-gesture")
+        # A baseline the entry names that this folder does not store: staged
+        # all the same — a soft check of another folder — and said here, in
+        # the line `spec update` prints for it.
+        for text in session.not_stored_notes(model_id):
+            ui.label(text).classes("text-xs text-secondary").mark("drawer-not-stored")
         # Never an empty box: edits that cancel out are not here at all, and
         # neither is a tree written out and not edited (a `rescore`, a value
         # typed and cleared on a flat test) — an entry put back as saved has

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/shell/tree_card.py

@@ -307,7 +307,7 @@ def leaf_readout(leaf: dict) -> str:
     to — which ALREADY carries the score ("NRMSE 1.531e-01 vs tolerance
     1.000e-02 → FAIL"), so the display beside it said the number twice (the
     first screenshot) — else the display alone. A sentinel's criterion says
-    the reason itself ("scalar leaf not scored — …"), so the error is not a
+    the reason itself ("scalar criterion not scored — …"), so the error is not a
     branch of its own. The trailing verdict is not stripped: `tube` and
     `range` do not end with it ("… → FAIL (requires 0)"), so a strip would
     read the string wrong for half the modes."""

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/situation.py

@@ -9,7 +9,7 @@ anything the last scoring said).
 There is no state for edits to the simulation settings (the owner's ruling
 Q2 A drew one): ``/simulation`` is not stageable — `patch_apply`'s default
 whitelist is ``/comparison``, ``/metrics`` and ``/plots``, and widening it
-changes ``spec-update``, a seam another repository relies on. It waits for
+changes ``spec update``, a seam another repository relies on. It waits for
 a simulation-settings editor."""
 
 from __future__ import annotations

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/authoring/unscorable.py

@@ -137,5 +137,5 @@ def refuse_bounds(metric: str, params: Mapping[str, object]) -> None:
     if lo == hi and metric in STRICT_BOUNDS:
         raise Refused(
             f"min_value {_num(lo)} equals max_value {_num(hi)}; "
-            f"a {metric} leaf needs min_value < max_value"
+            f"a {metric} criterion needs min_value < max_value"
         )

{dynamic_systems_testing_framework-1.0.1 → dynamic_systems_testing_framework-1.1.0}/src/dstf/backends/__init__.py

@@ -27,7 +27,11 @@ __all__ = [
     "resolve_variable_patterns",
     "get_backend",
     "get_backend_class",
+    "backend_class",
+    "backend_family",
+    "backend_names",
     "select_backend",
+    "source_types",
     "dataset_kind_for",
 ]
 
@@ -117,12 +121,23 @@ def _validate_capabilities(cls: type[Backend], name: str) -> None:
 
 
 def register(name: str):
-    """Class decorator that registers a Backend subclass.
+    """Register a backend class under a name: the class decorator a backend
+    plug-in is declared with.
 
-    Validates capability honesty at decoration time — see
-    :func:`_validate_capabilities`. A typo or stale flag becomes an
-    ``ImportError`` (via ``TypeError``) at module-import time rather
-    than a confusing ``NotImplementedError`` mid-run.
+    The name is what ``testing.json``'s ``backend`` and ``backends`` say, and
+    what ``--backend`` takes. An entry named ``"<name> 2025"`` is this
+    backend's too.
+
+    Args:
+        name: The backend's name.
+
+    Returns:
+        The decorator, which returns the class unchanged.
+
+    Raises:
+        TypeError: At decoration, when the class declares a
+            :class:`~dstf.backends.types.Capability` without overriding the
+            method it needs.
     """
 
     def decorator(cls: type[Backend]) -> type[Backend]:
@@ -150,55 +165,89 @@ def get_backend_class(config: Config) -> type[Backend]:
     unavailable-backend ``RuntimeError`` an optional dependency's absence
     signals (FmpyBackend.__init__ imports fmpy).
     """
-    backend = config.backend
-    if backend not in _REGISTRY:
-        _import_builtin_backend(backend)
-    cls = _REGISTRY.get(backend)
+    cls = backend_class(config.backend)
     if cls is None:
         available = ", ".join(sorted(_REGISTRY)) or "(none)"
         raise ValueError(
-            f"Unsupported backend: {backend} "
+            f"Unsupported backend: {config.backend} "
             f"(from '{config.backend_name}'). Available: {available}"
         )
     return cls
 
 
+def backend_class(name: str) -> type[Backend] | None:
+    """The backend registered under ``name`` — a built-in is imported on
+    first use — or None."""
+    if name not in _REGISTRY:
+        _import_builtin_backend(name)
+    return _REGISTRY.get(name)
+
+
+def backend_names() -> list[str]:
+    """Every backend there is a class for: the built-ins, then what a
+    plug-in or a caller registered, in registration order. The order
+    ``dstf check`` lists them in, and the one a project that names no
+    backend is searched in (``Backend.source_types``)."""
+    return [*_BUILTINS, *(name for name in _REGISTRY if name not in _BUILTINS)]
+
+
+def source_types() -> list[str]:
+    """Every ``source_type`` a project may say: the ones a registered
+    backend runs (``Backend.source_types``), in the backends' order — the
+    built-ins' ``modelica``, ``fmu``, ``julia``, ``python``, then a
+    plug-in's. ``Config`` refuses any other, and the published schema
+    lists these."""
+    found: dict[str, None] = {}
+    for name in backend_names():
+        cls = backend_class(name)
+        if cls is not None:
+            found.update(dict.fromkeys(sorted(cls.source_types)))
+    return list(found)
+
+
+def backend_family(backend_name: str) -> str:
+    """The backend a named entry is of: ``"Dymola 2025"`` is a ``"Dymola"``,
+    ``"OpenModelica 1.23"`` an ``"OpenModelica"`` — the registered name it
+    starts with, the longest where two do. A name that starts with none is
+    its own (and no backend, as :func:`get_backend_class` then says)."""
+    for name in sorted(backend_names(), key=len, reverse=True):
+        if backend_name.startswith(name):
+            return name
+    return backend_name
+
+
 class BackendUnavailableError(RuntimeError):
-    """The configured backend cannot be built on this machine.
-
-    Not a bug: an unregistered backend name, a missing executable, or a
-    persistent variant whose dependency probe failed. Callers decide what
-    to do about it — the CLI prints the message and exits 1
-    (:func:`cli.run_cmds._get_backend`), the authoring tool shows it on the
-    job that asked for the run, and ``Session.open`` turns it into a
-    ``ConfigError`` so ``dstf author`` refuses the project with one line.
+    """The project's backend cannot be built on this machine: no backend of
+    that name is registered, its program was not found, or what it needs is not
+    installed. ``str()`` says which, in words true wherever it is shown — the
+    command line and `dstf author`'s Queue alike.
+
+    ``batch_runs``: only the variant whose workers stay alive is refused;
+    the backend's per-test script mode would run. A caller that offers that
+    mode says so in its own words (the CLI's ``--batch``).
     """
 
+    def __init__(self, message: str, *, batch_runs: bool = False):
+        super().__init__(message)
+        self.batch_runs = batch_runs
 
-def select_backend(config, *, persistent: bool) -> Backend:
-    """Instantiate the backend for *config*, persistent variant when asked.
 
-    When *persistent* is True and the backend **declares**
-    :attr:`Capability.PERSISTENT_WORKERS`, pre-flight the variant's
-    dependency probe and instantiate it. When the probe raises
-    :class:`RuntimeError`, raise :class:`BackendUnavailableError` naming
-    both fixes (install the dep, or re-run with ``--batch``) — no silent
-    fallback.
+def select_backend(config, *, persistent: bool, to_run: bool = False) -> Backend:
+    """Build the backend a project runs with.
 
-    The declaration is what gates, not the presence of the hook: a backend
-    that ships an experimental ``persistent_backend_cls`` it isn't ready to
-    have driven says so by leaving the flag off, and lands on the batch
-    path. Registration-time validation (:func:`_validate_capabilities`)
-    guarantees the converse — flag implies a real override — so a declaring
-    backend always has a class to return.
+    Args:
+        config: The project's configuration.
+        persistent: Build the variant that keeps the simulator open between
+            tests, where the backend has one; ``--batch`` is False.
+        to_run: The backend will simulate, not only read results: one that was
+            not found on this machine is refused.
 
-    Backend-agnostic: no string matching on backend names. New persistent
-    backends plug in by declaring the capability and overriding
-    ``persistent_backend_cls`` + ``preflight`` on their backend classes.
+    Returns:
+        The backend.
 
-    This function itself reads ``config.backend`` only to phrase the
-    persistent-failure message; :func:`get_backend_class`, which it calls
-    first, requires the attribute.
+    Raises:
+        BackendUnavailableError: The backend is not registered, not found, or
+            cannot be used here; the message says why and what to do.
     """
     try:
         batch_cls = get_backend_class(config)
@@ -206,10 +255,17 @@ def select_backend(config, *, persistent: bool) -> Backend:
         # An unregistered backend name is a configuration problem, not a
         # bug; same class of failure as a missing executable.
         raise BackendUnavailableError(str(exc)) from exc
+    if to_run:
+        try:
+            batch_cls.require_found(config)
+        except RuntimeError as exc:
+            raise BackendUnavailableError(str(exc)) from exc
     if not persistent or Capability.PERSISTENT_WORKERS not in batch_cls.capabilities:
         # Batch-only backend (FMPy, Python today). Persistent flag is a
         # no-op rather than an error so a single CLI works across mixed
-        # backends in a multi-library config.
+        # backends in a multi-library config. A `--batch` WRITTEN for such
+        # a backend is another matter, and the CLI's to refuse
+        # (`cli.run_cmds._refuse_batch_without_workers`).
         return _instantiate(batch_cls, config)
     pcls = batch_cls.persistent_backend_cls()
     if pcls is None:
@@ -220,12 +276,8 @@ def select_backend(config, *, persistent: bool) -> Backend:
         pcls.preflight(config)
     except RuntimeError as exc:
         raise BackendUnavailableError(
-            f"Persistent-worker {config.backend} unavailable.\n"
-            f"\n"
-            f"{exc}\n"
-            f"\n"
-            f"Or re-run with `--batch` to use the per-test subprocess "
-            f"backend instead."
+            f"Persistent-worker {config.backend} unavailable.\n\n{exc}",
+            batch_runs=True,
         ) from exc
     return _instantiate(pcls, config)
 
@@ -245,16 +297,20 @@ def _instantiate(cls: type[Backend], config) -> Backend:
         raise BackendUnavailableError(str(exc)) from exc
 
 
+#: The built-in backends and the module each registers itself from. Their
+#: order is the order :func:`backend_names` lists them in.
+_BUILTINS = {
+    "Dymola": ".dymola",
+    "OpenModelica": ".openmodelica",
+    "FMPy": ".fmpy",
+    "Julia": ".julia",
+    "Python": ".python",
+}
+
+
 def _import_builtin_backend(name: str) -> None:
     """Import a built-in backend module so it registers itself."""
-    builtins = {
-        "Dymola": ".dymola",
-        "FMPy": ".fmpy",
-        "OpenModelica": ".openmodelica",
-        "Julia": ".julia",
-        "Python": ".python",
-    }
-    module = builtins.get(name)
+    module = _BUILTINS.get(name)
     if module:
         import importlib