git clone https://github.com/experimaestro/experimaestro-python.git
cd experimaestro-python
uv sync --all-extrasAll contributions must pass the pre-commit hooks
defined in .pre-commit-config.yaml. Install them once after cloning:
uv tool install pre-commit # or: pipx install pre-commit
pre-commit install # installs both the pre-commit and commit-msg hooksThe hooks then run on every git commit:
- ruff (lint with
--fix) and ruff-format - mypy on the whole package (see Type checking)
- YAML check, end-of-file and trailing-whitespace fixers
- no blanket
# noqa, noeval(), noFIXME:/TODO:markers - web UI build sync: if you change
app/, rebuild withcd app && npm run buildand stagesrc/experimaestro/webui/data/in the same commit - Conventional Commits for the commit message (see below)
When a hook modifies files (e.g. formatting), the commit is aborted: stage the changes and commit again. A convenient pattern is:
git add <files> && pre-commit; git add -u && git commit -m "fix: ..."Before opening a pull request, run the hooks on every file you touched:
pre-commit run --all-filesDo not bypass the hooks with --no-verify, except for the documented web UI
case where a change under app/ does not affect the build output.
Commit messages follow Conventional Commits — they are used to generate the changelog with git-cliff:
feat(scheduler): add per-task retry limit
fix: release the lock when a job is cancelled
docs: document workspace triggers
Common types: feat, fix, docs, perf, refactor, test, chore,
ci, build.
mypy (with the experimaestro plugin) checks the whole package in pre-commit
(for the minimum supported Python version) and in CI (for each supported
version). Modules that do not type-check yet are listed in the last
[[tool.mypy.overrides]] of pyproject.toml (ignore_errors = true): this
list may only shrink. New modules must type-check; when you make a listed
module clean, remove it from the list.
uv run mypy src/experimaestrouv run pytest -n auto # all tests, in parallel
uv run pytest # all tests, sequentially
uv run pytest src/experimaestro/tests/test_identifier.py # one fileAdd tests for bug fixes and new features. Test data must not contain personal information (real names, emails, …): use made-up values.
Features of the monitoring interfaces (TUI and web UI) are tested once, for
both, in src/experimaestro/tests/ui/. Each test drives a
UIDriver — what a user does (open an
experiment, type a filter, kill a job) and what the interface shows — and runs
with every driver:
| Driver | What it runs |
|---|---|
tui |
the Textual app, under App.run_test() |
web |
the web server, through its WebSocket protocol |
browser |
the web UI in headless Chromium (Playwright), opt-in |
All of them read the same made-up workspace
(scenario.py). When you add or
change a UI feature:
- add the operation to
UIDriverand implement it in every driver; - write the test once, against the
uifixture; - if an interface does not have the feature, mark the test
@pytest.mark.ui("tui"); if it has a known defect, mark it@pytest.mark.ui_gap("web", reason="...")(a strict xfail: it fails once the defect is fixed, so that the marker gets removed).
Logic shared by the interfaces belongs outside of them (e.g.
scheduler/job_operations.py for kill/delete, cli/filter.py for the filter
language), so that the tests check the same behaviour everywhere.
The browser tests use the committed frontend build
(src/experimaestro/webui/data/, rebuild it after changing app/), and need
the browser dependency group and Chromium; they run in a dedicated CI job:
uv sync --all-extras --group browser
uv run playwright install chromium
XPM_TEST_BROWSER=1 uv run pytest src/experimaestro/tests/ui- Keep each pull request focused on one change.
- Make sure
pre-commit run --all-filesanduv run pytestpass locally. - Update the documentation (
docs/source/) when you change the CLI or a public API. - If you change the frontend (
app/), commit the rebuilt assets insrc/experimaestro/webui/data/.