From 3e4ba70cdcdc3ec670276261b390edb115e70f84 Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Fri, 13 Nov 2026 12:51:06 +0100 Subject: [PATCH 01/10] Rebuild the HIL tests on master The hardware-in-the-loop tests (imswitch/imcontrol/_test/hil) of test_hil-runner, moved onto master d6d0d3c9 (#329, #330) as one commit. The upstream commits the old branch carried are already in master through those squash merges, so only the hil folder and .gitignore remain. Previous history: 6dedef49. Co-Authored-By: Claude Opus 5.5 --- .gitignore | 2 + imswitch/imcontrol/_test/hil/README.md | 108 +++++++ imswitch/imcontrol/_test/hil/__main__.py | 121 +++++++ imswitch/imcontrol/_test/hil/conftest.py | 20 ++ imswitch/imcontrol/_test/hil/firmware_sync.py | 106 +++++++ imswitch/imcontrol/_test/hil/hil_client.py | 102 ++++++ imswitch/imcontrol/_test/hil/hil_report.py | 158 ++++++++++ imswitch/imcontrol/_test/hil/pytest.ini | 5 + .../imcontrol/_test/hil/test_board_link.py | 15 + .../_test/hil/test_camera_capture.py | 77 +++++ .../_test/hil/test_firmware_server.py | 90 ++++++ .../imcontrol/_test/hil/test_ledmatrix.py | 185 +++++++++++ .../imcontrol/_test/hil/test_lightsource.py | 212 +++++++++++++ .../_test/hil/test_motor_axis_move.py | 35 +++ .../_test/hil/test_motor_motion_camera.py | 294 ++++++++++++++++++ .../_test/hil/test_objective_switch.py | 247 +++++++++++++++ 16 files changed, 1777 insertions(+) create mode 100644 imswitch/imcontrol/_test/hil/README.md create mode 100644 imswitch/imcontrol/_test/hil/__main__.py create mode 100644 imswitch/imcontrol/_test/hil/conftest.py create mode 100644 imswitch/imcontrol/_test/hil/firmware_sync.py create mode 100644 imswitch/imcontrol/_test/hil/hil_client.py create mode 100644 imswitch/imcontrol/_test/hil/hil_report.py create mode 100644 imswitch/imcontrol/_test/hil/pytest.ini create mode 100644 imswitch/imcontrol/_test/hil/test_board_link.py create mode 100644 imswitch/imcontrol/_test/hil/test_camera_capture.py create mode 100644 imswitch/imcontrol/_test/hil/test_firmware_server.py create mode 100644 imswitch/imcontrol/_test/hil/test_ledmatrix.py create mode 100644 imswitch/imcontrol/_test/hil/test_lightsource.py create mode 100644 imswitch/imcontrol/_test/hil/test_motor_axis_move.py create mode 100644 imswitch/imcontrol/_test/hil/test_motor_motion_camera.py create mode 100644 imswitch/imcontrol/_test/hil/test_objective_switch.py diff --git a/.gitignore b/.gitignore index 6502dc232..9b0440ae2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ __pycache__/ *.py[cod] venv +.venv/ .ipynb_checkpoints/ tools/ # mypy @@ -45,6 +46,7 @@ pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports +out/ htmlcov/ .tox/ .coverage diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md new file mode 100644 index 000000000..81261f8ff --- /dev/null +++ b/imswitch/imcontrol/_test/hil/README.md @@ -0,0 +1,108 @@ +# Hardware-in-the-loop (HIL) tests + +Tests of a running ImSwitch on a real microscope, through its HTTP API only. They sit next to +`../unit/` (no server) and `../api/` (headless server), but never import ImSwitch: they need only +`pytest`, `requests`, `pillow` and `numpy`. + +**They move the stage and switch light.** Each test file says in its first line what it does. + +| Test | Checks | Hardware | +|---|---|---| +| `board_link` | the UC2 board is connected and runs the CANopen master firmware | reads | +| `firmware_server` | the firmware server has images; every board runs its version | reads | +| `camera_capture` | every camera returns a frame at its resolution | reads | +| `objective_switch` | switching the objective shows in the image, and light still gets through | **moves** turret and Z, **light** | +| `lightsource` | lasers/LEDs switch; every LED reaches the cameras | **light** | +| `ledmatrix` | the LED matrix reaches the cameras | **light** | +| `motor_axis_move` | each axis steps 10 µm and back | **moves** | +| `motor_motion_camera` | the observation camera sees X/Y/Z/A move | **moves** (parks at the transport position), **light** | + +Hardware a setup does not have skips its tests. Hardware that is there but does not work fails. + +## Run + +```bash +python -m imswitch.imcontrol._test.hil REPORT_DIR [TEST ...] [--sync-firmware] +``` + +```bash +python -m imswitch.imcontrol._test.hil out # everything +python -m imswitch.imcontrol._test.hil out board_link camera_capture # only these tests +python -m imswitch.imcontrol._test.hil out --sync-firmware # FLASHES every board first +``` + +`TEST` is the name from the table: `board_link` runs `test_board_link.py`. + +It waits until ImSwitch answers, the board is connected and every camera gives a frame, then +runs the tests and writes `junit.xml`, `report.html` (results, output and photos in one file) +and `summary.md` to `REPORT_DIR`. Both reports name the setup file the rig ran with. Exit code: `0` all passed, `1` a test failed, `2` the tests +could not run (not ready, firmware sync failed, unknown test, everything skipped). + +The test rig (os-rpi, `.github/hil/`) runs exactly this command inside the ImSwitch container. +That one line is all the two repositories share, so the tests always belong to the ImSwitch +version under test. + +From a laptop against a rig, without ImSwitch installed: + +```bash +IMSWITCH_URL=http:///imswitch python imswitch/imcontrol/_test/hil out board_link +``` + +While writing a test, plain pytest works too and shows more: + +```bash +cd imswitch/imcontrol/_test/hil +IMSWITCH_URL=http:///imswitch pytest test_camera_capture.py -s +``` + +## Files + +Every `test_*.py` is one test and stands on its own: its settings are at its top, its helper +functions below them. No test imports another one. Deleting a test is deleting its file. + +What the tests share has nothing to do with what they check: + +| File | Holds | +|---|---| +| `hil_client.py` | HTTP (`get_json`, `post_json`, `wait_until`), `setup()`, `parametrize_from_rig` | +| `hil_report.py` | `attach(label, image)` and the HTML/Markdown report | +| `conftest.py` | marks the tests `hardware`; skips everything when ImSwitch is not reachable | +| `__main__.py` | the command above | +| `firmware_sync.py` | `--sync-firmware` | + +## Which hardware a test uses + +There is no list of the rig's hardware here. The tests read it from the setup file ImSwitch +runs with: `ImSwitchConfig/imcontrol_setups/.json`, where `` is the `setupFileName` +in `ImSwitchConfig/config/imcontrol_options.json`. `client.setup_file()` returns the name, +`client.setup()` the content as a dict. ImSwitch parses the file before it answers, so a field +the file leaves out comes back with ImSwitch's default (e.g. `"forAcquisition": false`). + +| Setup | Used for | +|---|---| +| `detectors`, `forAcquisition` | the cameras; `true` is an acquisition detector, `false` the observation camera | +| `lasers`, `valueRangeMax` | the lasers and LEDs, and the value they are switched on with | +| `LEDMatrixs` | whether there is an LED matrix | +| `positioners`, `axes` | the stage axes | +| `objective` | whether there is an objective turret | + +So a rig with other hardware needs another setup file in ImSwitch, not other tests. + +## Writing a test + +Copy the test that is closest to the new one, rename it `test_.py`, and change it. It +runs with the others from then on; nothing else has to be registered. A test file has: + +1. a first line saying what it checks and what it does to the rig; +2. its settings, as constants; +3. its helper functions and fixtures; +4. the tests, whose steps read top to bottom. + +- Call ImSwitch with `client.get_json("/Controller/method", {"param": value})`. +- Take what the rig has from `client.setup()`, and thresholds, distances and timeouts from the + constants at the top of the file. +- Add a photo to the report with `attach("label", image)`. +- Whatever a test switches on or moves, it puts back, also when it fails (`try/finally`, or a + fixture with `yield`). +- Code that a second test needs is copied, not shared: a test must stay readable and removable + by itself. diff --git a/imswitch/imcontrol/_test/hil/__main__.py b/imswitch/imcontrol/_test/hil/__main__.py new file mode 100644 index 000000000..68260bbbb --- /dev/null +++ b/imswitch/imcontrol/_test/hil/__main__.py @@ -0,0 +1,121 @@ +"""Run the hardware-in-the-loop (HIL) tests against a live ImSwitch and write a report. + + python -m imswitch.imcontrol._test.hil REPORT_DIR [TEST ...] [--sync-firmware] + + python -m imswitch.imcontrol._test.hil out # everything + python -m imswitch.imcontrol._test.hil out board_link camera_capture # only these tests + python -m imswitch.imcontrol._test.hil out --sync-firmware # FLASHES every board first + +TEST is the name of a test file without "test_" and ".py": board_link is test_board_link.py. +Without TEST every test runs, which MOVES THE STAGE AND SWITCHES LIGHT. +REPORT_DIR receives junit.xml, report.html and summary.md; both reports name the ImSwitch +setup file (ImSwitchConfig/imcontrol_setups/.json) the rig ran with. + +Exit code: 0 all passed, 1 a test failed, 2 the tests could not run. +The test rig (os-rpi) runs exactly this command inside the ImSwitch container. +""" +import argparse +import sys +from pathlib import Path + +HERE = Path(__file__).parent +sys.path.insert(0, str(HERE)) # so the modules of this folder import as they do under pytest + +import pytest # noqa: E402 +import requests # noqa: E402 + +import firmware_sync # noqa: E402 +import hil_client as client # noqa: E402 +import hil_report # noqa: E402 + +PASSED, FAILED, COULD_NOT_RUN = 0, 1, 2 + +READY_API_TIMEOUT = 180 # seconds ImSwitch may take to answer +READY_DETECTOR_TIMEOUT = 300 # seconds each camera may take to give its first frame + + +def can_snap(detector, for_acquisition): + """Whether the camera gives a frame yet; right after a start its driver may still load.""" + try: + if for_acquisition: + return client.get("/RecordingController/snapNumpyToFastAPI", params={ + "detectorName": detector, "resizeFactor": 0.1}).status_code == 200 + # 400: no observation camera is connected. Waiting does not change that, and the + # tests that need it skip. + return client.post("/ExperimentController/snapOverviewImage", timeout=30, params={ + "slot_id": "1", "camera_name": "hil_ready_check"}).status_code in (200, 400) + except requests.RequestException: + return False + + +def why_not_ready(): + """Wait for ImSwitch, the board and every camera. Returns None, or what is missing.""" + if not client.wait_until(client.reachable, READY_API_TIMEOUT, interval=5): + return f"ImSwitch did not answer at {client.IMSWITCH_URL} within {READY_API_TIMEOUT}s" + if client.get_json("/UC2ConfigController/uc2_board_is_connected") is not True: + return "the UC2 board is not connected" + detectors = client.setup()["detectors"] + if not detectors: + return "the setup has no detectors" + for name, detector in detectors.items(): + for_acquisition = detector["forAcquisition"] + if for_acquisition: # an acquisition detector gives frames only while its live view runs + status = client.post_json("/LiveViewController/startLiveView", + {"detectorName": name}, timeout=60).get("status") + if status not in ("success", "already_running"): + return f"{name}: startLiveView answered {status!r}" + if not client.wait_until(lambda: can_snap(name, for_acquisition), READY_DETECTOR_TIMEOUT, + interval=5): + return f"{name} gave no frame within {READY_DETECTOR_TIMEOUT}s" + print(f"[hil] {name} is ready", flush=True) + return None + + +def main(): + parser = argparse.ArgumentParser(prog="python -m imswitch.imcontrol._test.hil") + parser.add_argument("report_dir", help="folder for junit.xml, report.html and summary.md") + parser.add_argument("tests", nargs="*", + help="tests, e.g. board_link camera_capture; default all") + parser.add_argument("--sync-firmware", action="store_true", + help="FLASH every board to the firmware server's version first") + args = parser.parse_args() + + files = [HERE / f"test_{name}.py" for name in args.tests] + unknown = [name for name, file in zip(args.tests, files) if not file.is_file()] + if unknown: + known = " ".join(sorted(file.stem[len("test_"):] for file in HERE.glob("test_*.py"))) + print(f"[hil] no such test: {' '.join(unknown)}. There are: {known}") + return COULD_NOT_RUN + + try: + problem = why_not_ready() + if problem is None: + print(f"[hil] setup: {client.setup_file()}", flush=True) + if problem is None and args.sync_firmware: + firmware_sync.sync() + except (requests.RequestException, AssertionError, firmware_sync.SyncFailed) as error: + problem = str(error) + if problem: + print(f"[hil] not running the tests: {problem}") + return COULD_NOT_RUN + + report_dir = Path(args.report_dir) + code = pytest.main( + [*[str(file) for file in files or [HERE]], + "-c", str(HERE / "pytest.ini"), "-ra", f"--junitxml={report_dir / 'junit.xml'}"], + plugins=[hil_report.ReportPlugin(report_dir, client.setup_file())]) + + counts = hil_report.counts() + print("[hil] " + " · ".join(f"{n} {status}" for status, n in counts.items())) + if code == pytest.ExitCode.TESTS_FAILED: + return FAILED + if code != pytest.ExitCode.OK: + return COULD_NOT_RUN + if not counts["passed"]: + print("[hil] every test skipped: nothing on this rig was actually tested") + return COULD_NOT_RUN + return PASSED + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/imswitch/imcontrol/_test/hil/conftest.py b/imswitch/imcontrol/_test/hil/conftest.py new file mode 100644 index 000000000..1994a0856 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/conftest.py @@ -0,0 +1,20 @@ +"""What applies to every HIL test. Nothing here knows what a test checks.""" +from pathlib import Path + +import pytest + +import hil_client as client + + +def pytest_collection_modifyitems(items): + """Mark every HIL test ``hardware``, so ``pytest -m "not hardware"`` leaves the suite out.""" + for item in items: + if Path(__file__).parent in Path(item.fspath).parents: + item.add_marker(pytest.mark.hardware) + + +@pytest.fixture(scope="session", autouse=True) +def imswitch_reachable(): + """Without a server the whole suite skips.""" + if not client.reachable(): + pytest.skip(f"ImSwitch not reachable at {client.IMSWITCH_URL}") diff --git a/imswitch/imcontrol/_test/hil/firmware_sync.py b/imswitch/imcontrol/_test/hil/firmware_sync.py new file mode 100644 index 000000000..68735714b --- /dev/null +++ b/imswitch/imcontrol/_test/hil/firmware_sync.py @@ -0,0 +1,106 @@ +"""Bring every board to the firmware server's version. FLASHES FIRMWARE. + +A sync, not an update: a board with a newer developer build is flashed back as well. The +flashing itself is ImSwitch's own firmware update (startFirmwareUpdate), which checks every +image and counts a board as done only when it reports the new version. +""" +import time + +import requests + +import hil_client as client + +SCAN_TIMEOUT = 5 # seconds checkFirmwareUpdates waits for the boards on the CAN bus +SYNC_TIMEOUT = 1800 # seconds one firmware update may take + +# update_status values of a board that differs from the server and has an image to flash. +OUT_OF_SYNC = ("update_available", "device_newer") + + +class SyncFailed(Exception): + pass + + +def label(device): + return f"CAN {device.get('canId')} ({device.get('deviceTypeStr')}, {device['connection']})" + + +def scan_came_back_empty(result): + """True if the CAN scan found nothing: then even the master is listed without a canId.""" + usb = next((d for d in result.get("devices") or [] if d["connection"] == "usb"), None) + return (usb is not None and "can" in (usb.get("deviceTypeStr") or "").lower() + and usb.get("canId") is None) + + +def check(): + """checkFirmwareUpdates; asked up to three times, because the CAN scan sometimes is empty.""" + for _ in range(3): + result = client.get_json("/UC2ConfigController/checkFirmwareUpdates", + {"timeout": SCAN_TIMEOUT}, timeout=120) + if not scan_came_back_empty(result): + break + time.sleep(3) + else: + raise SyncFailed("the CAN scan came back empty three times") + if not result.get("server_version"): + raise SyncFailed(f"{result.get('firmware_server')} publishes no version.json") + return result + + +def out_of_sync(result, connection): + """The boards on "usb" (the master) or "can" (the nodes) that need flashing.""" + return [d for d in result["devices"] + if d["connection"] == connection and d["update_status"] in OUT_OF_SYNC] + + +def flash(can_ids, include_master): + """Start one ImSwitch firmware update and wait until it ended; raises unless it succeeded.""" + started = client.post_json("/UC2ConfigController/startFirmwareUpdate", json=can_ids, + params={"include_master": include_master}, timeout=120) + if started.get("status") != "started": + raise SyncFailed(f"ImSwitch refused the update: {started}") + + deadline = time.monotonic() + SYNC_TIMEOUT + status, message = {"state": "running"}, None + while status.get("state") == "running": + if time.monotonic() > deadline: + raise SyncFailed(f"the update still runs after {SYNC_TIMEOUT}s") + time.sleep(5) + try: + status = client.get_json("/UC2ConfigController/getFirmwareUpdateStatus", timeout=120) + except requests.RequestException: + continue # ImSwitch can be too busy flashing to answer; the update goes on + if status.get("message") != message: + message = status.get("message") + print(f"sync: {message}", flush=True) + + for step in status.get("steps") or []: + print(f"sync: {label(step)}: {step['status']} {step.get('message') or ''}", flush=True) + if status.get("homing_required"): + print("sync: the updated motors restarted and need homing", flush=True) + if status.get("state") != "success": + raise SyncFailed(f"the update ended {status.get('state')!r}") + + +def sync(): + """Flash every board that differs from the server; raises SyncFailed if one still does.""" + result = check() + print(f"sync: server version {result['server_version']}", flush=True) + for device in result["devices"]: + print(f"sync: {label(device)}: {device.get('installed_version') or 'no version'} " + f"[{device['update_status']}]", flush=True) + + # The master first, on its own: old master firmware cuts off the version the nodes report, + # so behind it no node would count as updated. + if out_of_sync(result, "usb"): + flash([], include_master=True) + result = check() + nodes = out_of_sync(result, "can") + if nodes: + flash([d["canId"] for d in nodes], include_master=False) + result = check() + + left = out_of_sync(result, "usb") + out_of_sync(result, "can") + if left: + raise SyncFailed("still out of sync: " + ", ".join(label(d) for d in left)) + print(f"sync: every board runs {result['server_version']}", flush=True) diff --git a/imswitch/imcontrol/_test/hil/hil_client.py b/imswitch/imcontrol/_test/hil/hil_client.py new file mode 100644 index 000000000..d55b7be1c --- /dev/null +++ b/imswitch/imcontrol/_test/hil/hil_client.py @@ -0,0 +1,102 @@ +"""HTTP access to the ImSwitch under test, and the setup it has loaded. + +An endpoint is written "/Controller/method", as in ImSwitch's API documentation: + + client.get_json("/PositionerController/getPositionerPositions") + client.get_json("/SettingsController/getCameraStatus", {"detectorName": "WidefieldCamera"}) + +What hardware the rig has is read from ImSwitch's own setup file: + + client.setup()["lasers"] # {"LED": {"valueRangeMax": 1023, ...}, ...} + +Only the server URL comes from the environment, so the suite can also run from a laptop. +""" +import functools +import os +import time + +import pytest +import requests + +IMSWITCH_URL = os.environ.get("IMSWITCH_URL", "http://localhost:8001").rstrip("/") + + +def get(endpoint, **kwargs): + """``requests.get`` on an endpoint; returns the response whatever its status.""" + kwargs.setdefault("timeout", 30) + return requests.get(f"{IMSWITCH_URL}/api{endpoint}", **kwargs) + + +def post(endpoint, **kwargs): + """``requests.post`` on an endpoint; returns the response whatever its status.""" + kwargs.setdefault("timeout", 30) + return requests.post(f"{IMSWITCH_URL}/api{endpoint}", **kwargs) + + +def json_of(response): + """The JSON of a response; any status but 200 fails the test.""" + assert response.status_code == 200, ( + f"{response.request.method} {response.url} -> {response.status_code}: {response.text}") + return response.json() + + +def get_json(endpoint, params=None, timeout=30): + return json_of(get(endpoint, params=params, timeout=timeout)) + + +def post_json(endpoint, params=None, json=None, timeout=30): + return json_of(post(endpoint, params=params, json=json, timeout=timeout)) + + +def reachable(): + try: + return get("/version", timeout=10).status_code == 200 + except requests.RequestException: + return False + + +@functools.lru_cache(maxsize=None) # asked once per run; an error is not cached +def setup_file(): + """The name of the setup file ImSwitch runs with, as imcontrol_options.json names it. + + The file is ImSwitchConfig/imcontrol_setups/; the name may also be a full path. + """ + return get_json("/UC2ConfigController/getCurrentSetupFilename")["current_setup"] + + +@functools.lru_cache(maxsize=None) +def setup(): + """The content of setup_file(), as a dict. + + ImSwitch parses the file before it answers, so a field the file leaves out comes back with + ImSwitch's default (e.g. "forAcquisition": false). The sections the tests use are + "detectors", "lasers", "LEDMatrixs", "positioners" and "objective". A section the rig does + not have is empty or None. + """ + return get_json("/UC2ConfigController/readSetupFile", {"setupFileName": setup_file()}) + + +def wait_until(check, timeout, interval=0.1): + """Call ``check()`` until it returns something true and return that; None after ``timeout``.""" + deadline = time.monotonic() + timeout + while True: + result = check() + if result or time.monotonic() >= deadline: + return result or None + time.sleep(interval) + + +def parametrize_from_rig(argnames, fetch, reason): + """``pytest.mark.parametrize(argnames, fetch())`` for values the rig reports, e.g. its axes. + + pytest reads the values while it collects the tests, where an error would stop the whole + run. So without a server, or with nothing to test, the test is skipped with ``reason``. + """ + try: + values = fetch() + except (requests.RequestException, AssertionError) as error: + values, reason = [], f"ImSwitch not reachable: {error}" + if not values: + nothing = [None] * len(argnames.split(",")) + values = [pytest.param(*nothing, id="none", marks=pytest.mark.skip(reason=reason))] + return pytest.mark.parametrize(argnames, values) diff --git a/imswitch/imcontrol/_test/hil/hil_report.py b/imswitch/imcontrol/_test/hil/hil_report.py new file mode 100644 index 000000000..b4eecbeec --- /dev/null +++ b/imswitch/imcontrol/_test/hil/hil_report.py @@ -0,0 +1,158 @@ +"""The report of a run: report.html (results, output and photos in one file) and summary.md. + +A test adds a photo with ``attach("dark", image)``. ``__main__.py`` passes ``ReportPlugin`` to +pytest, which collects every result and writes the two files at the end. Under plain pytest +nothing is written. +""" +import base64 +import html +import io +import os +import time +from pathlib import Path + +import numpy as np +from PIL import Image + +PHOTO_WIDTH = 640 # photos are scaled down to this, so a report with dozens of them stays small +STATUSES = ["failed", "error", "skipped", "passed"] # the order in the report + +_started = time.time() +_photos = {} # test id -> [(label, base64 PNG)] +_results = {} # test id -> {"status", "duration", "details", "output"} + + +def attach(label, image): + """Add a photo to the test that is running. ``image`` is a PIL image or a numpy array.""" + test = os.environ.get("PYTEST_CURRENT_TEST") # "camera/test_x.py::test_y[cam] (call)" + if not test: + return + if isinstance(image, np.ndarray): + image = Image.fromarray(np.clip(image, 0, 255).astype(np.uint8)) + if image.mode not in ("L", "RGB"): + image = image.convert("RGB") + if image.width > PHOTO_WIDTH: + image = image.resize((PHOTO_WIDTH, round(image.height * PHOTO_WIDTH / image.width))) + buffer = io.BytesIO() + image.save(buffer, format="PNG", optimize=True) + photo = base64.b64encode(buffer.getvalue()).decode("ascii") + _photos.setdefault(test.rsplit(" (", 1)[0], []).append((str(label), photo)) + + +def counts(): + """``{"failed": 0, "error": 0, "skipped": 1, "passed": 29}``""" + statuses = [result["status"] for result in _results.values()] + return {status: statuses.count(status) for status in STATUSES} + + +class ReportPlugin: + """Collects the results while pytest runs and writes the report files into ``report_dir``. + + ``setup_file`` is the ImSwitch setup the rig ran with; both files name it at the top. + """ + + def __init__(self, report_dir, setup_file): + self.report_dir = Path(report_dir) + self.setup_file = setup_file + + def pytest_runtest_logreport(self, report): + """Called three times per test: for its setup, the test itself (call) and its teardown.""" + result = _results.setdefault(report.nodeid, { + "status": "passed", "duration": 0.0, "details": "", "output": ""}) + result["duration"] += report.duration + result["output"] = report.capstdout or result["output"] + if report.failed and result["status"] != "failed": + # A failure outside the test itself is a broken fixture, not a failed assertion. + result["status"] = "failed" if report.when == "call" else "error" + result["details"] = str(report.longrepr) + elif report.skipped and result["status"] == "passed": + result["status"] = "skipped" + result["details"] = report.longrepr[2] # (file, line, reason) + + def pytest_sessionfinish(self): + self.report_dir.mkdir(parents=True, exist_ok=True) + (self.report_dir / "summary.md").write_text(summary(self.setup_file), encoding="utf-8") + (self.report_dir / "report.html").write_text(page(self.setup_file), encoding="utf-8") + + +def summary(setup_file): + """Markdown, short enough for a CI step summary: the setup, the counts, one line per failure.""" + totals = " · ".join(f"{n} {status}" for status, n in counts().items()) + lines = ["### HIL report", "", f"setup `{setup_file}`", "", totals, ""] + for test, result in _results.items(): + if result["status"] in ("failed", "error"): + last_line = (result["details"].strip().splitlines() or [""])[-1] + lines.append(f"- **{result['status']}** `{test}`: {last_line[:300]}") + return "\n".join(lines) + "\n" + + +def page(setup_file): + """The HTML report: failures first, then skips, then passes.""" + tests = sorted(_results.items(), key=lambda item: STATUSES.index(item[1]["status"])) + started = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(_started)) + totals = "".join(f'{n} {status}' + for status, n in counts().items()) + return PAGE.format(css=CSS, setup=html.escape(setup_file), started=started, + took=time.time() - _started, totals=totals, + tests="\n".join(card(test, result) for test, result in tests)) + + +def card(test, result): + photos = "".join(PHOTO.format(label=html.escape(label), data=data) + for label, data in _photos.get(test, [])) + details = f"
{html.escape(result['details'])}
" if result["details"] else "" + output = OUTPUT.format(output=html.escape(result["output"])) if result["output"].strip() else "" + return CARD.format(status=result["status"], test=html.escape(test), details=details, + duration=result["duration"], photos=photos, output=output) + + +PAGE = """ + + +HIL report +

HIL report

+
setup {setup} · started {started} · took {took:.0f} s
+
{totals}
+{tests} + +""" + +CARD = """
+

{status}{test} +{duration:.1f} s

+{details} +
{photos}
+{output} +
""" + +PHOTO = ('
{label}' + '
{label}
') + +OUTPUT = "
output
{output}
" + +CSS = """ +:root { --bg:#fff; --fg:#1d1d1f; --muted:#6e6e73; --card:#f5f5f7; --line:#d2d2d7; + --passed:#1a7f37; --failed:#cf222e; --error:#bc4c00; --skipped:#6e6e73; } +@media (prefers-color-scheme: dark) { + :root { --bg:#161618; --fg:#f5f5f7; --muted:#a1a1a6; --card:#222225; --line:#3a3a3d; + --passed:#3fb950; --failed:#f85149; --error:#db6d28; --skipped:#a1a1a6; } } +body { background:var(--bg); color:var(--fg); margin:0 auto; max-width:1100px; + padding:24px 16px; font:15px/1.5 system-ui, sans-serif; } +h1 { font-size:22px; margin:0 0 4px; } +.meta { color:var(--muted); margin-bottom:16px; } +.counts span { margin-right:16px; font-weight:600; } +.test { background:var(--card); border:1px solid var(--line); border-left-width:6px; + border-radius:8px; padding:12px 16px; margin:12px 0; } +.test h2 { font-size:15px; margin:0; word-break:break-all; } +.badge { display:inline-block; min-width:64px; font-size:12px; font-weight:700; + text-transform:uppercase; margin-right:8px; } +.duration { color:var(--muted); font-weight:400; margin-left:8px; } +pre { background:var(--bg); border:1px solid var(--line); border-radius:6px; padding:8px; + overflow-x:auto; font-size:12.5px; white-space:pre-wrap; } +summary { cursor:pointer; color:var(--muted); margin-top:8px; } +.photos { display:flex; flex-wrap:wrap; gap:12px; margin-top:10px; } +figure { margin:0; max-width:100%; } +figure img { max-width:min(100%, 480px); border:1px solid var(--line); border-radius:4px; + display:block; } +figcaption { color:var(--muted); font-size:13px; } +""" diff --git a/imswitch/imcontrol/_test/hil/pytest.ini b/imswitch/imcontrol/_test/hil/pytest.ini new file mode 100644 index 000000000..dd89cfc19 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/pytest.ini @@ -0,0 +1,5 @@ +[pytest] +# The HIL suite is its own pytest project, so pytest does not import the ImSwitch packages above. +addopts = -p no:arkitekt_next -p no:cacheprovider -v --tb=short +markers = + hardware: needs a real rig; conftest.py sets it on every HIL test diff --git a/imswitch/imcontrol/_test/hil/test_board_link.py b/imswitch/imcontrol/_test/hil/test_board_link.py new file mode 100644 index 000000000..b29515b7a --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_board_link.py @@ -0,0 +1,15 @@ +"""The UC2 board is connected and runs the CANopen master firmware. Only reads.""" +import hil_client as client + + +def test_uc2_board_connected(): + connected = client.get_json("/UC2ConfigController/is_connected", timeout=5) + assert connected is True, "UC2/ESP32 board is not reported as connected" + + +def test_correct_esp32_firmware(): + info = client.get_json("/UC2ConfigController/getFirmwareInfo", timeout=5) + print(f"\nESP32 firmware: {info}") + assert info.get("connected") is True, f"ESP32 not connected: {info}" + assert info.get("isMaster") is True, f"ESP32 is not the CANopen master: {info}" + assert info.get("pindef") == "UC2_canopen_master", f"wrong firmware type: {info.get('pindef')}" diff --git a/imswitch/imcontrol/_test/hil/test_camera_capture.py b/imswitch/imcontrol/_test/hil/test_camera_capture.py new file mode 100644 index 000000000..db8f34f1f --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_camera_capture.py @@ -0,0 +1,77 @@ +"""Every configured camera returns a frame, at the resolution it reports. Only reads. + +ImSwitch reads the two kinds of camera in different ways: +- an acquisition detector ("forAcquisition": true in the setup) with snapNumpyToFastAPI, which + only works while its live view runs; the runner (__main__.py) has started it; +- the observation camera ("forAcquisition": false) with snapOverviewImage, at any time. +""" +import base64 +import io + +import pytest +from PIL import Image + +import hil_client as client +from hil_report import attach + +SNAP_RESIZE = 0.1 # resizeFactor of the acquisition frame, to keep the transfer small + + +def detectors(): + return list(client.setup()["detectors"]) + + +def is_observation_camera(detector): + return not client.setup()["detectors"][detector]["forAcquisition"] + + +def camera_status(detector): + """getCameraStatus; skips the test if the camera has an error or is ImSwitch's mock camera.""" + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in status or status.get("status") == "error": + pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") + if status.get("isMock") or str(status.get("model", "")).lower() == "mock": + pytest.skip(f"{detector}: ImSwitch served a mock camera (model={status.get('model')!r})") + return status + + +def snap(detector): + """One frame as (PIL image, the resize factor ImSwitch applied to it).""" + if is_observation_camera(detector): + # camera_name only names the folder ImSwitch saves the frame to. + body = client.post_json("/ExperimentController/snapOverviewImage", timeout=10, + params={"slot_id": "1", "camera_name": "hil_camera_capture"}) + frame = Image.open(io.BytesIO(base64.b64decode(body["imageBase64"]))) + assert frame.format == "JPEG", f"snapOverviewImage returned {frame.format}" + return frame, 1.0 + response = client.get("/RecordingController/snapNumpyToFastAPI", timeout=10, params={ + "detectorName": detector, "resizeFactor": SNAP_RESIZE}) + assert response.status_code == 200, response.text + frame = Image.open(io.BytesIO(response.content)) + assert frame.format == "PNG", f"snapNumpyToFastAPI returned {frame.format}" + return frame, SNAP_RESIZE + + +every_detector = client.parametrize_from_rig("detector", detectors, "the setup has no detectors") + + +@every_detector +def test_camera_returns_image(detector): + camera_status(detector) + frame, _ = snap(detector) + attach(detector, frame) + assert frame.width > 0 and frame.height > 0 + + +@every_detector +def test_camera_matches_sensor_resolution(detector): + status = camera_status(detector) + width = status.get("currentWidth") or status.get("sensorWidth") + height = status.get("currentHeight") or status.get("sensorHeight") + if not width or not height: + pytest.skip(f"{detector}: getCameraStatus reports no frame size ({width}x{height})") + frame, resize = snap(detector) + expected = (int(width * resize), int(height * resize)) + assert frame.size == expected, ( + f"{detector}: got {frame.width}x{frame.height}, expected {expected[0]}x{expected[1]} " + f"({width}x{height} at resizeFactor {resize})") diff --git a/imswitch/imcontrol/_test/hil/test_firmware_server.py b/imswitch/imcontrol/_test/hil/test_firmware_server.py new file mode 100644 index 000000000..c93333f7d --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_firmware_server.py @@ -0,0 +1,90 @@ +"""The firmware server is usable and every board runs its version. Only reads, flashes nothing. + +checkFirmwareUpdates is ImSwitch's own comparison of the server's version.json with what each +board reports. To flash before the tests, start the suite with --sync-firmware. +""" +import pytest + +import hil_client as client + +SCAN_TIMEOUT = 5 # seconds checkFirmwareUpdates waits for the boards on the CAN bus +# update_status values of a board that differs from the server and has an image to flash. +OUT_OF_SYNC = ("update_available", "device_newer") + + +def label(device): + return f"CAN {device.get('canId')} ({device.get('deviceTypeStr')}, {device['connection']})" + + +def scan_came_back_empty(result): + """True if the CAN scan found nothing: then even the master is listed without a canId.""" + usb = next((d for d in result.get("devices") or [] if d["connection"] == "usb"), None) + return (usb is not None and "can" in (usb.get("deviceTypeStr") or "").lower() + and usb.get("canId") is None) + + +@pytest.fixture(scope="module") +def check(): + """The answer of checkFirmwareUpdates, asked once: it scans the CAN bus.""" + result = client.get_json("/UC2ConfigController/checkFirmwareUpdates", + {"timeout": SCAN_TIMEOUT}, timeout=60) + assert not scan_came_back_empty(result), ( + "the CAN scan came back empty: no node listed, the master without canId") + print() + for device in result["devices"]: + print(f"{label(device)}: {device.get('installed_version') or 'no version'}, " + f"image {device.get('filename') or 'none'} [{device['update_status']}]") + return result + + +@pytest.fixture(scope="module") +def answering(check): + """The boards that answered the scan. The others may just be powered down.""" + boards = [d for d in check["devices"] if d["update_status"] != "unreachable"] + if not boards: + pytest.skip("no board answered") + return boards + + +def test_master_firmware_is_reported(): + info = client.get_json("/UC2ConfigController/getFirmwareInfo", timeout=60) + if info.get("status") == "error": + pytest.skip(f"getFirmwareInfo failed: {info.get('message')}") + print(f"\nmaster: {info}") + assert info.get("connected") is True, f"master board is not connected: {info}" + for field in ("name", "version", "date", "pindef"): + assert info.get(field), f"master firmware reports no {field}: {info}" + + +def test_firmware_server_is_configured(): + url = client.get_json("/UC2ConfigController/getOTAFirmwareServer").get("firmware_server_url") + print(f"\nfirmware server: {url}") + assert url, "no OTA firmware server configured" + + +def test_firmware_server_lists_binaries(): + listing = client.get_json("/UC2ConfigController/listAllFirmwareFiles", timeout=60) + if listing.get("status") != "success": + pytest.skip(f"firmware server unusable: {listing.get('message')}") + files = listing.get("files") or [] + print(f"\n{len(files)} firmware files on {listing.get('firmware_server')}") + assert files, f"firmware server {listing.get('firmware_server')} offers no .bin files" + for entry in files: + assert entry.get("filename", "").endswith(".bin"), entry + assert entry.get("url"), entry + + +def test_answering_boards_have_firmware(check, answering): + missing = [label(d) for d in answering + if d["update_status"] == "no_firmware" or not d.get("filename")] + assert not missing, f"no image on {check.get('firmware_server')} for: {', '.join(missing)}" + + +def test_boards_run_server_version(check, answering): + """Exactly the server's version: a board with a newer build fails too.""" + server = check.get("server_version") + if not server: + pytest.skip(f"{check.get('firmware_server')} names no version (no version.json?)") + stale = [f"{label(d)} runs {d.get('installed_version')}" + for d in answering if d["update_status"] in OUT_OF_SYNC] + assert not stale, f"not on the server's version {server}: {', '.join(stale)}" diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix.py b/imswitch/imcontrol/_test/hil/test_ledmatrix.py new file mode 100644 index 000000000..54fb7c6cd --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix.py @@ -0,0 +1,185 @@ +"""The LED matrix answers, and its light reaches the cameras. SWITCHES LIGHT. + +The matrix counts as visible when it changes the image by more than the camera's own noise: +take a few dark frames, measure how much they differ, then compare a dark and a lit frame. +""" +import base64 +import contextlib +import io +import time + +import pytest +from PIL import Image, ImageChops, ImageStat + +import hil_client as client +from hil_report import attach + +MATRIX_INTENSITY = 500 # per colour, of setAllLED +LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it +AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time +FRAME_RESIZE = 0.25 # the frames are compared at this share of their size +# The matrix must change the image by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. +# The noise is the largest difference between NOISE_SAMPLES dark frames. +MIN_CHANGE = 1.5 +NOISE_FACTOR = 1.5 +NOISE_SAMPLES = 6 +NOISE_DELAY_S = 0.5 + + +# --- lights ----------------------------------------------------------------------------------- + +def all_lights_off(): + """Every laser, LED and the LED matrix off, so only the matrix changes the image.""" + for name in client.setup()["lasers"]: + client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": 0}) + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": False}) + client.get_json("/LEDMatrixController/setAllLEDOff") + time.sleep(LIGHT_SETTLE_S) + + +# --- cameras ---------------------------------------------------------------------------------- +# An acquisition detector ("forAcquisition": true in the setup) gives frames only while its +# live view runs. The observation camera ("forAcquisition": false) gives them at any time. + +def is_observation_camera(detector): + return not client.setup()["detectors"][detector]["forAcquisition"] + + +def take_image(detector): + """One small greyscale frame (PIL) of either kind of camera.""" + if is_observation_camera(detector): + # camera_name only names the folder ImSwitch saves the frame to. + response = client.post("/ExperimentController/snapOverviewImage", timeout=60, + params={"slot_id": "1", "camera_name": "hil_ledmatrix"}) + if response.status_code == 400: + pytest.skip(f"observation camera not connected: {response.text}") + raw = base64.b64decode(client.json_of(response)["imageBase64"]) + frame = Image.open(io.BytesIO(raw)).convert("L") + return frame.resize((max(1, int(frame.width * FRAME_RESIZE)), + max(1, int(frame.height * FRAME_RESIZE)))) + response = client.get("/RecordingController/snapNumpyToFastAPI", timeout=60, + params={"detectorName": detector, "resizeFactor": FRAME_RESIZE}) + assert response.status_code == 200, response.text + return Image.open(io.BytesIO(response.content)).convert("L") + + +def image_difference(first, second): + """Mean absolute grey-value difference between two frames.""" + return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] + + +def dark_baseline(detector): + """Measure the camera noise with the scene unchanged. + + Returns (last frame, noise floor, change the matrix must exceed). + """ + previous = take_image(detector) + drifts = [] + for _ in range(NOISE_SAMPLES - 1): + time.sleep(NOISE_DELAY_S) + current = take_image(detector) + drifts.append(image_difference(previous, current)) + previous = current + noise_floor = max(drifts) + required = max(MIN_CHANGE, noise_floor * NOISE_FACTOR) + print(f"\n{detector} dark noise: drifts={[round(d, 2) for d in drifts]}, " + f"noise_floor={noise_floor:.2f}, required_change={required:.2f}") + return previous, noise_floor, required + + +@contextlib.contextmanager +def live_view(detector): + """Keep an acquisition detector streaming inside a ``with`` block. + + Only a live view that was started here is stopped again. + """ + # The HTTP status is 200 even when ImSwitch refuses, so only the "status" field tells. + status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, + timeout=60).get("status") + if status == "long_exposure": + pytest.skip(f"{detector}: exposure too long for live view") + assert status in ("success", "already_running"), ( + f"{detector}: startLiveView answered {status!r}") + time.sleep(0.4) + try: + yield + finally: + if status == "success": + client.get_json("/LiveViewController/stopLiveView", {"detectorName": detector}) + + +def auto_expose(detector): + """One auto-exposure pass on the scene as it is now; needs a running live view.""" + client.get_json("/SettingsController/setDetectorExposureOnce", + {"detectorName": detector, "resetDelayMs": AUTO_EXPOSURE_RESET_MS}) + time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) + + +# --- fixtures --------------------------------------------------------------------------------- + +@pytest.fixture(scope="module", autouse=True) +def led_matrix(): + if not client.setup()["LEDMatrixs"]: + pytest.skip("the setup has no LED matrix") + + +@pytest.fixture(scope="module", params=["acquisition", "observation"]) +def camera(request): + """A camera that is ready to take frames; with it a test runs once per kind of camera. + + The exposure is set once, in the dark, so that the dark and the lit frames share it. The + observation camera is left alone: it has no live view for the auto exposure to act on. + """ + wanted = request.param == "observation" + names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] + if not names: + pytest.skip(f"the setup has no {request.param} camera") + detector = names[0] + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in status or status.get("status") == "error": + pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") + if status.get("isMock") or str(status.get("model", "")).lower() == "mock": + pytest.skip(f"{detector}: ImSwitch served a mock camera") + + all_lights_off() + if wanted: + yield detector + else: + with live_view(detector): + auto_expose(detector) + yield detector + all_lights_off() + + +@pytest.fixture +def dark(): + """Every light off before and after the test.""" + all_lights_off() + yield + all_lights_off() + + +# --- tests ------------------------------------------------------------------------------------ + +def test_all_leds_off_is_accepted(): + response = client.get("/LEDMatrixController/setAllLEDOff", timeout=5) + assert response.status_code == 200, f"setAllLEDOff -> {response.status_code}: {response.text}" + + +def test_led_matrix_is_visible_to_camera(camera, dark): + unlit, noise_floor, required = dark_baseline(camera) + + client.get_json("/LEDMatrixController/setAllLED", { + "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, + "intensity_b": MATRIX_INTENSITY}) + time.sleep(LIGHT_SETTLE_S) + lit = take_image(camera) + + attach("dark", unlit) + attach("bright", lit) + change = image_difference(unlit, lit) + print(f"\nLED matrix @ {MATRIX_INTENSITY}: pixel_change={change:.2f} " + f"noise_floor={noise_floor:.2f} required={required:.2f}") + assert lit.getextrema()[1] > 0, "the LED matrix is on but every pixel is still 0" + assert change >= required, (f"LED matrix: image changed only by {change:.2f}; camera noise " + f"floor is {noise_floor:.2f}, need >= {required:.2f}") diff --git a/imswitch/imcontrol/_test/hil/test_lightsource.py b/imswitch/imcontrol/_test/hil/test_lightsource.py new file mode 100644 index 000000000..2990611d7 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_lightsource.py @@ -0,0 +1,212 @@ +"""Every laser/LED switches through the API, and every LED reaches the cameras. SWITCHES LIGHT. + +A light counts as visible when it changes the image by more than the camera's own noise: +take a few dark frames, measure how much they differ, then compare a dark and a lit frame. +""" +import base64 +import contextlib +import io +import time + +import pytest +from PIL import Image, ImageChops, ImageStat + +import hil_client as client +from hil_report import attach + +LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it +AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time +FRAME_RESIZE = 0.25 # the frames are compared at this share of their size +# A light must change the image by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. +# The noise is the largest difference between NOISE_SAMPLES dark frames. +MIN_CHANGE = 1.5 +NOISE_FACTOR = 1.5 +NOISE_SAMPLES = 6 +NOISE_DELAY_S = 0.5 + + +# --- lights ----------------------------------------------------------------------------------- + +def light_sources(): + """Names of every laser and LED of the setup.""" + return list(client.setup()["lasers"]) + + +def leds(): + """Names of the LEDs. The lasers are left out: on these rigs their beam misses the sensor. + + The setup lists lasers and LEDs alike under "lasers", so only the name tells them apart. + """ + return [name for name in light_sources() + if "led" in name.lower() and "laser" not in name.lower()] + + +def set_light(name, on): + """Switch one laser/LED on (at the highest value its setup allows) or off.""" + value = client.setup()["lasers"][name]["valueRangeMax"] if on else 0 + client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": value}) + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": on}) + time.sleep(LIGHT_SETTLE_S) + + +def all_lights_off(): + """Every laser, LED and the LED matrix off, so only the light under test changes the image.""" + for name in light_sources(): + client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": 0}) + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": False}) + if client.setup()["LEDMatrixs"]: + client.get_json("/LEDMatrixController/setAllLEDOff") + time.sleep(LIGHT_SETTLE_S) + + +# --- cameras ---------------------------------------------------------------------------------- +# An acquisition detector ("forAcquisition": true in the setup) gives frames only while its +# live view runs. The observation camera ("forAcquisition": false) gives them at any time. + +def is_observation_camera(detector): + return not client.setup()["detectors"][detector]["forAcquisition"] + + +def take_image(detector): + """One small greyscale frame (PIL) of either kind of camera.""" + if is_observation_camera(detector): + # camera_name only names the folder ImSwitch saves the frame to. + response = client.post("/ExperimentController/snapOverviewImage", timeout=60, + params={"slot_id": "1", "camera_name": "hil_lightsource"}) + if response.status_code == 400: + pytest.skip(f"observation camera not connected: {response.text}") + raw = base64.b64decode(client.json_of(response)["imageBase64"]) + frame = Image.open(io.BytesIO(raw)).convert("L") + return frame.resize((max(1, int(frame.width * FRAME_RESIZE)), + max(1, int(frame.height * FRAME_RESIZE)))) + response = client.get("/RecordingController/snapNumpyToFastAPI", timeout=60, + params={"detectorName": detector, "resizeFactor": FRAME_RESIZE}) + assert response.status_code == 200, response.text + return Image.open(io.BytesIO(response.content)).convert("L") + + +def image_difference(first, second): + """Mean absolute grey-value difference between two frames.""" + return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] + + +def dark_baseline(detector): + """Measure the camera noise with the scene unchanged. + + Returns (last frame, noise floor, change a light must exceed). + """ + previous = take_image(detector) + drifts = [] + for _ in range(NOISE_SAMPLES - 1): + time.sleep(NOISE_DELAY_S) + current = take_image(detector) + drifts.append(image_difference(previous, current)) + previous = current + noise_floor = max(drifts) + required = max(MIN_CHANGE, noise_floor * NOISE_FACTOR) + print(f"\n{detector} dark noise: drifts={[round(d, 2) for d in drifts]}, " + f"noise_floor={noise_floor:.2f}, required_change={required:.2f}") + return previous, noise_floor, required + + +@contextlib.contextmanager +def live_view(detector): + """Keep an acquisition detector streaming inside a ``with`` block. + + Only a live view that was started here is stopped again. + """ + # The HTTP status is 200 even when ImSwitch refuses, so only the "status" field tells. + status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, + timeout=60).get("status") + if status == "long_exposure": + pytest.skip(f"{detector}: exposure too long for live view") + assert status in ("success", "already_running"), ( + f"{detector}: startLiveView answered {status!r}") + time.sleep(0.4) + try: + yield + finally: + if status == "success": + client.get_json("/LiveViewController/stopLiveView", {"detectorName": detector}) + + +def auto_expose(detector): + """One auto-exposure pass on the scene as it is now; needs a running live view.""" + client.get_json("/SettingsController/setDetectorExposureOnce", + {"detectorName": detector, "resetDelayMs": AUTO_EXPOSURE_RESET_MS}) + time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) + + +# --- fixtures --------------------------------------------------------------------------------- + +@pytest.fixture(scope="module", params=["acquisition", "observation"]) +def camera(request): + """A camera that is ready to take frames; with it a test runs once per kind of camera. + + The exposure is set once, in the dark, so that the dark and the lit frames share it. The + observation camera is left alone: it has no live view for the auto exposure to act on. + """ + wanted = request.param == "observation" + names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] + if not names: + pytest.skip(f"the setup has no {request.param} camera") + detector = names[0] + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in status or status.get("status") == "error": + pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") + if status.get("isMock") or str(status.get("model", "")).lower() == "mock": + pytest.skip(f"{detector}: ImSwitch served a mock camera") + + all_lights_off() + if wanted: + yield detector + else: + with live_view(detector): + auto_expose(detector) + yield detector + all_lights_off() + + +@pytest.fixture +def dark(): + """Every light off before and after the test.""" + all_lights_off() + yield + all_lights_off() + + +# --- tests ------------------------------------------------------------------------------------ + +@client.parametrize_from_rig("name", light_sources, "the setup has no lasers/LEDs") +def test_lightsource_reports_active(name): + """ImSwitch's own state follows the commands (at value 1); this does not prove light.""" + try: + client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": 1}) + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": True}) + active = client.get_json("/LaserController/getLaserActive", {"laserName": name}) + value = client.get_json("/LaserController/getLaserValue", {"laserName": name}) + assert active is True, f"{name}: did not become active" + assert (value or 0) > 0, f"{name}: value is not positive" + + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": False}) + active = client.get_json("/LaserController/getLaserActive", {"laserName": name}) + assert active is False, f"{name}: did not become inactive" + finally: + set_light(name, False) + + +@client.parametrize_from_rig("name", leds, "no LED among the light sources of the setup") +def test_light_source_is_visible_to_camera(name, camera, dark): + unlit, noise_floor, required = dark_baseline(camera) + + set_light(name, True) + lit = take_image(camera) + + attach("dark", unlit) + attach("bright", lit) + change = image_difference(unlit, lit) + print(f"\n{name}: pixel_change={change:.2f} noise_floor={noise_floor:.2f} " + f"required={required:.2f}") + assert lit.getextrema()[1] > 0, f"{name} is on but every pixel is still 0" + assert change >= required, (f"{name}: image changed only by {change:.2f}; camera noise floor " + f"is {noise_floor:.2f}, need >= {required:.2f}") diff --git a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py new file mode 100644 index 000000000..10e675bc9 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py @@ -0,0 +1,35 @@ +"""Every axis reports a small relative step, then steps back. MOVES REAL HARDWARE (10 µm).""" +import time + +import pytest + +import hil_client as client + +STEP_UM = 10 +SETTLE_S = 0.5 # wait before reading the position back + + +def axes(): + """Every (positioner, axis) pair of the setup, e.g. ("ESP32Stage", "X").""" + return [(name, axis) for name, positioner in client.setup()["positioners"].items() + if positioner["forPositioning"] for axis in positioner["axes"]] + + +def position(positioner, axis): + return client.get_json("/PositionerController/getPositionerPositions")[positioner][axis] + + +@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") +def test_axis_moves_by_step(positioner, axis): + step = {"positionerName": positioner, "axis": axis, "dist": STEP_UM} + back = {"positionerName": positioner, "axis": axis, "dist": -STEP_UM} + + before = position(positioner, axis) + try: + client.get_json("/PositionerController/movePositioner", step) + time.sleep(SETTLE_S) + after = position(positioner, axis) + assert after == pytest.approx(before + STEP_UM, abs=0.1), ( + f"{positioner} {axis}: {before} -> {after}, expected {before + STEP_UM}") + finally: + client.get_json("/PositionerController/movePositioner", back) diff --git a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py new file mode 100644 index 000000000..d3984a046 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py @@ -0,0 +1,294 @@ +"""Stage motion as the observation camera sees it. MOVES REAL HARDWARE and SWITCHES LIGHT. + +The stage parks at the transport position (ImSwitch switches the Z hard limits off there, and +the turret goes to slot 0) and the LED matrix lights the sample. Then every axis moves out and +back once, and three tests judge that one measurement: + +- test_axis_motion_is_visible (every axis): the image changed more than its noise +- test_axis_motion_direction (X, Y): +X moves the image right, +Y moves it down +- test_z_motion_changes_scale (Z): the image got larger or smaller +""" +import base64 +import functools +import io +import time + +import numpy as np +import pytest +from PIL import Image + +import hil_client as client +from hil_report import attach + +# Distances are in µm, times in seconds. +DISTANCE_UM = 3000 +Z_DISTANCE_UM = 5000 +Z_DIRECTION = -1 # away from Z home: at the transport position the limits are off +SPEED = 15000 +SETTLE_S = 0.5 # wait after a move, before the frame +TRANSPORT_SPEED = 20000 # above 30000 the stage loses steps +TRANSPORT_TIMEOUT = 120 +TURRET_TIMEOUT = 120 +MATRIX_INTENSITY = 255 # the firmware's maximum per colour +MATRIX_SETTLE_S = 3.5 # wait after switching the matrix on, before the first frame + +EXPECTED_DIRECTION = {"X": "right", "Y": "down"} # of the image, when the axis moves by +distance +MIN_RATIO = 1.8 # image change over noise that counts as movement, X and Y +MIN_RATIO_AZ = 1.25 # the same for A and Z, which change the image less +ROI = (150, 355, 150, 340) # X/Y are judged in frame[y1:y2, x1:x2] of the 640x360 image +TOP_CROP_PERCENT = 25 # A/Z are judged below this top share of the image +Z_SCALE_MIN = 0.90 # the image scales that are tried to find the Z zoom +Z_SCALE_MAX = 1.10 +Z_SCALE_STEP = 0.002 +Z_MIN_SCALE_CHANGE = 0.001 +Z_SCALE_NOISE_RATIO = 1.4 + +SNAP = {"slot_id": "1", "camera_name": "hil_motion"} # camera_name: folder ImSwitch saves to + + +# --- stage ------------------------------------------------------------------------------------ + +def axes(): + """Every (positioner, axis) pair of the setup, e.g. ("ESP32Stage", "X").""" + return [(name, axis) for name, positioner in client.setup()["positioners"].items() + if positioner["forPositioning"] for axis in positioner["axes"]] + + +def xy_axes(): + return [pair for pair in axes() if pair[1].upper() in EXPECTED_DIRECTION] + + +def z_axes(): + return [pair for pair in axes() if pair[1].upper() == "Z"] + + +def move(positioner, axis, distance): + """Move one axis by ``distance`` µm and wait until it has arrived and settled.""" + client.get_json("/PositionerController/movePositioner", timeout=60, params={ + "positionerName": positioner, "axis": axis, "dist": distance, + "isBlocking": True, "speed": SPEED}) + time.sleep(SETTLE_S) + + +def wait_until_stopped(): + """The positions once two reads agree; some endpoints answer before the stage has arrived.""" + previous = client.get_json("/PositionerController/getPositionerPositions") + deadline = time.monotonic() + TRANSPORT_TIMEOUT + while time.monotonic() < deadline: + time.sleep(0.5) + current = client.get_json("/PositionerController/getPositionerPositions") + if current == previous: + break + previous = current + return previous + + +def park_at_transport(): + """Move to the transport position and turn the turret to slot 0; returns the positions.""" + client.get_json("/PositionerController/moveToTransportPosition", timeout=TRANSPORT_TIMEOUT, + params={"speed": TRANSPORT_SPEED, "isBlocking": True}) + wait_until_stopped() + if client.setup()["objective"]: + status = client.get_json("/ObjectiveController/getstatus") + if status.get("isActive") and status.get("hasMotor") and status["slotConfigured"][0]: + # skipZ: the turret must not apply the slot's Z offset to the parked stage. + started = client.get_json("/ObjectiveController/moveToObjective", + {"slot": 0, "skipZ": True}) + assert started.get("accepted"), f"the turret refused slot 0: {started}" + + def turned(): + # moveToObjective only starts the move; the status tells when it is done. + now = client.get_json("/ObjectiveController/getstatus") + return (not now.get("isMovingObjective") and + now.get("lastCompletedObjectiveRequestId") == started["requestId"]) + + assert client.wait_until(turned, TURRET_TIMEOUT), ( + f"the turret did not reach slot 0 in {TURRET_TIMEOUT}s") + return wait_until_stopped() + + +# --- observation camera ----------------------------------------------------------------------- + +def frame(): + """One full-size greyscale frame of the observation camera, as a float array.""" + body = client.post_json("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) + image = Image.open(io.BytesIO(base64.b64decode(body["imageBase64"]))).convert("L") + return np.asarray(image, dtype=np.float32) + + +# --- image maths: frames are greyscale float arrays ------------------------------------------- + +def difference(before, after): + """Mean absolute grey-value difference.""" + assert before.shape == after.shape + return float(np.mean(np.abs(after - before))) + + +def roi(image): + """The part of the frame in which X/Y motion is judged (ROI).""" + y1, y2, x1, x2 = ROI + height, width = image.shape + assert 0 <= x1 < x2 <= width, f"invalid ROI x-range {x1}:{x2} for image width {width}" + assert 0 <= y1 < y2 <= height, f"invalid ROI y-range {y1}:{y2} for image height {height}" + return image[y1:y2, x1:x2] + + +def below_top(image): + """The frame without its top TOP_CROP_PERCENT, where A/Z motion is judged.""" + return image[image.shape[0] * TOP_CROP_PERCENT // 100:, :] + + +def shift(before, after): + """How far AFTER is moved against BEFORE: (dx, dy, peak) in pixels, +dx right, +dy down. + + Phase correlation: the peak of the correlation of the two images lies at their shift, and + its height says how clear the match is. + """ + assert before.shape == after.shape + before, after = before.astype(np.float64), after.astype(np.float64) + # Fade the edges out, or the FFT takes the jump from one edge to the other for structure. + window = np.hanning(before.shape[0])[:, None] * np.hanning(before.shape[1])[None, :] + f_before = np.fft.fft2((before - before.mean()) * window) + f_after = np.fft.fft2((after - after.mean()) * window) + cross_power = np.conj(f_before) * f_after + cross_power /= np.maximum(np.abs(cross_power), 1e-12) + correlation = np.fft.fftshift(np.abs(np.fft.ifft2(cross_power))) + peak_y, peak_x = np.unravel_index(np.argmax(correlation), correlation.shape) + dy = peak_y - correlation.shape[0] // 2 + dx = peak_x - correlation.shape[1] // 2 + return float(dx), float(dy), float(correlation[peak_y, peak_x]) + + +def direction(dx, dy, min_shift=2): + """ "right", "left", "down" or "up"; None if the shift is under ``min_shift`` pixels.""" + if np.hypot(dx, dy) < min_shift: + return None + if abs(dx) > abs(dy): + return "right" if dx > 0 else "left" + return "down" if dy > 0 else "up" + + +def scale(before, after): + """The zoom of AFTER against BEFORE; above 1 means the image got larger. + + Tries every scale from Z_SCALE_MIN to Z_SCALE_MAX: zoom BEFORE by it, cut or pad it back + to the frame size, and keep the scale whose result matches AFTER best. + """ + height, width = before.shape + image = Image.fromarray(np.ascontiguousarray(before, dtype=np.float32)) + best_scale, best_peak = 1.0, -1.0 + for candidate in np.arange(Z_SCALE_MIN, Z_SCALE_MAX + Z_SCALE_STEP / 2, Z_SCALE_STEP): + zoomed = np.asarray(image.resize((max(1, round(width * candidate)), + max(1, round(height * candidate))), Image.BILINEAR)) + zoomed_height, zoomed_width = zoomed.shape + # Offsets in the zoomed image (when it is larger) and in the frame (when it is smaller). + from_y, to_y = max(0, (zoomed_height - height) // 2), max(0, (height - zoomed_height) // 2) + from_x, to_x = max(0, (zoomed_width - width) // 2), max(0, (width - zoomed_width) // 2) + h, w = min(zoomed_height, height), min(zoomed_width, width) + resized = np.full(before.shape, float(np.median(before)), dtype=np.float32) + resized[to_y:to_y + h, to_x:to_x + w] = zoomed[from_y:from_y + h, from_x:from_x + w] + peak = shift(resized, after)[2] + if peak > best_peak: + best_scale, best_peak = round(float(candidate), 6), peak + return best_scale + + +# --- the measurement and its tests ------------------------------------------------------------ + +@pytest.fixture(scope="module", autouse=True) +def parked_and_lit(): + """Check the camera before anything moves, then park the stage and switch the matrix on.""" + setup = client.setup() + cameras = [name for name, detector in setup["detectors"].items() + if not detector["forAcquisition"]] + if not cameras: + pytest.skip("the setup has no observation camera") + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": cameras[0]}) + if "error" in status or status.get("status") == "error": + pytest.skip(f"{cameras[0]}: getCameraStatus failed: {status.get('error')}") + if status.get("isMock") or status.get("isConnected") is False: + pytest.skip(f"{cameras[0]} is a mock camera or not connected: {status}") + response = client.post("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) + if response.status_code != 200: + pytest.skip(f"{cameras[0]} cannot deliver an image: {response.text}") + roi(frame()) # fails here if ROI does not fit the image + + print(f"\ntransport position reached: {park_at_transport()}") + has_matrix = bool(setup["LEDMatrixs"]) + if has_matrix: + client.get_json("/LEDMatrixController/setAllLED", { + "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, + "intensity_b": MATRIX_INTENSITY}) + time.sleep(MATRIX_SETTLE_S) + yield + if has_matrix: + client.get_json("/LEDMatrixController/setAllLEDOff") + + +@functools.lru_cache(maxsize=None) # each axis moves once; the tests share the result +def measure(positioner, axis): + """Move one axis out and back, and return what the frames before and after show.""" + is_xy = axis.upper() in EXPECTED_DIRECTION + is_z = axis.upper() == "Z" + distance = Z_DISTANCE_UM * Z_DIRECTION if is_z else DISTANCE_UM + # X and Y shift the image, so they are judged in a region that stays on the sample. + region = roi if is_xy else below_top + + still = frame() + time.sleep(SETTLE_S) + before = frame() + move(positioner, axis, distance) + try: + after = frame() + finally: + move(positioner, axis, -distance) + attach(f"{axis} before", before) + attach(f"{axis} after {distance:+d} um", after) + + noise = difference(region(still), region(before)) + change = difference(region(before), region(after)) + result = {"noise": noise, "change": change, "ratio": change / max(noise, 1e-6)} + if is_xy: + dx, dy, peak = shift(region(before), region(after)) + result["direction"] = direction(dx, dy) + result["shift"] = f"dx={dx:+.1f}px, dy={dy:+.1f}px, peak={peak:.4f}" + if is_z: + result["scale"] = scale(roi(before), roi(after)) + result["scale_change"] = abs(result["scale"] - 1) + result["scale_noise"] = abs(scale(roi(still), roi(before)) - 1) + print(f"\n{positioner} {axis} {distance:+d} um: {result}") + return result + + +@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") +def test_axis_motion_is_visible(positioner, axis): + result = measure(positioner, axis) + required = MIN_RATIO if axis.upper() in EXPECTED_DIRECTION else MIN_RATIO_AZ + assert result["ratio"] >= required, ( + f"{positioner} {axis}: movement was not clearly visible. change={result['change']:.3f}, " + f"noise={result['noise']:.3f}, ratio={result['ratio']:.2f}x, required={required:.2f}x") + + +@client.parametrize_from_rig("positioner, axis", xy_axes, "the setup has no X/Y axes") +def test_axis_motion_direction(positioner, axis): + """Only the wrong direction fails. A shift too small to measure skips.""" + result = measure(positioner, axis) + if result["direction"] is None: + pytest.skip(f"{positioner} {axis}: no clear translation ({result['shift']})") + expected = EXPECTED_DIRECTION[axis.upper()] + assert result["direction"] == expected, ( + f"{positioner} {axis}: image moved {result['direction']}, expected {expected} " + f"({result['shift']})") + + +@client.parametrize_from_rig("positioner, axis", z_axes, "the setup has no Z axis") +def test_z_motion_changes_scale(positioner, axis): + """Larger or smaller does not matter. An unclear scale skips as long as the move was seen.""" + result = measure(positioner, axis) + clear = (result["scale_change"] >= Z_MIN_SCALE_CHANGE + and result["scale_change"] >= result["scale_noise"] * Z_SCALE_NOISE_RATIO) + evidence = (f"scale={result['scale']:.4f}, change={result['scale_change']:.4f}, " + f"noise={result['scale_noise']:.4f}, ratio={result['ratio']:.2f}x") + if not clear and result["ratio"] >= MIN_RATIO_AZ: + pytest.skip(f"{positioner} {axis}: moved, but the scale change is unclear. {evidence}") + assert clear, f"{positioner} {axis}: no scale change and no movement seen. {evidence}" diff --git a/imswitch/imcontrol/_test/hil/test_objective_switch.py b/imswitch/imcontrol/_test/hil/test_objective_switch.py new file mode 100644 index 000000000..344d9a5b6 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_objective_switch.py @@ -0,0 +1,247 @@ +"""Switching the objective changes the image, and light still reaches the camera through it. + +MOVES REAL HARDWARE: turns the turret, applies the Z offset stored for the slot, and runs the +autofocus (moves Z). SWITCHES LIGHT. + +The turret switches once; both tests read that one measurement. Afterwards the LED is off and +the turret is back on the slot it started from, also when the measurement failed. +""" +import contextlib +import io +import time + +import pytest +from PIL import Image, ImageChops, ImageStat + +import hil_client as client + +SETTLE_S = 0.5 # wait after the turret, the autofocus or a light has changed +MOVE_TIMEOUT = 120 # seconds the turret may take +AUTOFOCUS_TIMEOUT = 180 +AUTOFOCUS_RANGE_UM = 100 +AUTOFOCUS_STEP_UM = 10 +AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time +FRAME_RESIZE = 0.25 # the frames are compared at this share of their size +# The image must change by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. +# The noise is the largest difference between NOISE_SAMPLES frames of an unchanged scene. +MIN_CHANGE = 1.5 +NOISE_FACTOR = 1.5 +NOISE_SAMPLES = 6 +NOISE_DELAY_S = 0.5 + + +# --- objective turret and autofocus ----------------------------------------------------------- + +def objective_status(): + return client.get_json("/ObjectiveController/getstatus") + + +def switch_objective(slot): + """Turn the turret to ``slot`` (with the slot's Z offset) and wait; returns the status. + + A busy turret or an unconfigured slot skips the test, any other problem fails it. + """ + started = client.get_json("/ObjectiveController/moveToObjective", + {"slot": slot, "skipZ": False}) + if not started.get("accepted"): + if started.get("reason") in ("slot_not_configured", "busy"): + pytest.skip(f"objective slot {slot} unavailable: {started}") + pytest.fail(f"objective slot {slot} refused: {started}") + + def finished(): + # moveToObjective only starts the move, so the status tells when this request is done. + status = objective_status() + done = (not status.get("isMovingObjective") + and status.get("lastCompletedObjectiveRequestId") == started["requestId"]) + return status if done or status.get("lastObjectiveMoveError") else None + + status = client.wait_until(finished, MOVE_TIMEOUT) + assert status, f"objective move to slot {slot} did not finish in {MOVE_TIMEOUT}s" + assert not status.get("lastObjectiveMoveError"), ( + f"objective move to slot {slot} failed: {status.get('lastObjectiveMoveError')}") + assert status.get("currentObjective") == slot, ( + f"objective reports slot {status.get('currentObjective')}, expected {slot}") + time.sleep(SETTLE_S) + return status + + +def autofocus(): + """Run the software autofocus (moves Z) and wait for it. + + An autofocus that does not work skips the test: then the rig cannot measure, which says + nothing about the objective. + """ + started = client.get_json("/AutofocusController/autoFocus", timeout=60, params={ + "rangez": AUTOFOCUS_RANGE_UM, "resolutionz": AUTOFOCUS_STEP_UM}) + if started.get("status") == "error": + pytest.skip(f"autofocus did not start: {started.get('message')}") + + def finished(): + status = client.get_json("/AutofocusController/getAutofocusStatus") + if status.get("state") in ("error", "aborted"): + pytest.skip(f"autofocus ended as {status.get('state')!r}") + done = not status.get("isRunning") and status.get("state") in ("finished", "idle") + return status if done else None + + status = client.wait_until(finished, AUTOFOCUS_TIMEOUT) + if status is None: + client.get_json("/AutofocusController/stopAutofocus") + pytest.fail(f"autofocus did not finish in {AUTOFOCUS_TIMEOUT}s") + print(f"\nautofocus: z={status.get('currentZ')}, quality={status.get('lastQuality')}") + time.sleep(SETTLE_S) + + +# --- light ------------------------------------------------------------------------------------ + +def set_light(name, on): + """Switch one LED on (at the highest value its setup allows) or off.""" + value = client.setup()["lasers"][name]["valueRangeMax"] if on else 0 + client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": value}) + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": on}) + time.sleep(SETTLE_S) + + +# --- camera ----------------------------------------------------------------------------------- + +def take_image(detector): + """One small greyscale frame (PIL) of the acquisition detector; needs its live view.""" + response = client.get("/RecordingController/snapNumpyToFastAPI", timeout=60, + params={"detectorName": detector, "resizeFactor": FRAME_RESIZE}) + assert response.status_code == 200, response.text + return Image.open(io.BytesIO(response.content)).convert("L") + + +def image_difference(first, second): + """Mean absolute grey-value difference between two frames.""" + return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] + + +def noise_baseline(detector): + """Measure the camera noise with the scene unchanged. + + Returns (last frame, noise floor, change that counts as a real difference). + """ + previous = take_image(detector) + drifts = [] + for _ in range(NOISE_SAMPLES - 1): + time.sleep(NOISE_DELAY_S) + current = take_image(detector) + drifts.append(image_difference(previous, current)) + previous = current + noise_floor = max(drifts) + return previous, noise_floor, max(MIN_CHANGE, noise_floor * NOISE_FACTOR) + + +@contextlib.contextmanager +def live_view(detector): + """Keep the detector streaming inside a ``with`` block. + + Only a live view that was started here is stopped again. + """ + # The HTTP status is 200 even when ImSwitch refuses, so only the "status" field tells. + status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, + timeout=60).get("status") + if status == "long_exposure": + pytest.skip(f"{detector}: exposure too long for live view") + assert status in ("success", "already_running"), ( + f"{detector}: startLiveView answered {status!r}") + time.sleep(0.4) + try: + yield + finally: + if status == "success": + client.get_json("/LiveViewController/stopLiveView", {"detectorName": detector}) + + +def auto_expose(detector): + """One auto-exposure pass on the scene as it is now; needs a running live view.""" + client.get_json("/SettingsController/setDetectorExposureOnce", + {"detectorName": detector, "resetDelayMs": AUTO_EXPOSURE_RESET_MS}) + time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) + + +# --- the measurement and its tests ------------------------------------------------------------ + +@pytest.fixture(scope="module") +def measurement(): + """Switch to another objective and measure; returns the numbers the tests check.""" + setup = client.setup() + if not setup["objective"]: + pytest.skip("the setup has no objective turret") + status = objective_status() + slots = [slot for slot, configured in enumerate(status.get("slotConfigured") or []) + if configured] + if not status.get("isActive") or not status.get("hasMotor") or len(slots) < 2: + pytest.skip(f"this rig cannot switch between two objectives: {status}") + # Lasers and LEDs are listed alike under "lasers"; on these rigs only an LED lights the + # sensor, and only the name tells them apart. + leds = [name for name in setup["lasers"] + if "led" in name.lower() and "laser" not in name.lower()] + if not leds: + pytest.skip("no LED among the light sources of the setup") + led = leds[0] + # Only an acquisition detector looks through the objective. + detectors = [name for name, detector in setup["detectors"].items() + if detector["forAcquisition"]] + if not detectors: + pytest.skip("the setup has no acquisition detector") + detector = detectors[0] + camera = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in camera or camera.get("status") == "error": + pytest.skip(f"{detector}: getCameraStatus failed: {camera.get('error')}") + if camera.get("isMock") or str(camera.get("model", "")).lower() == "mock": + pytest.skip(f"{detector}: ImSwitch served a mock camera") + + start = status.get("currentObjective") + if start not in slots: # a turret that was never calibrated reports no slot + start = slots[0] + switch_objective(start) + target = next(slot for slot in slots if slot != start) + result = {"led": led} + + with live_view(detector): + try: + # 1. Does the switch change the image? LED on, turret still: measure the noise. + set_light(led, True) + auto_expose(detector) + autofocus() + before, result["switch_noise"], result["switch_required"] = noise_baseline(detector) + print(f"\nswitching objective: slot {start} -> {target}") + result["objective"] = switch_objective(target).get("objectiveName") + result["switch_change"] = image_difference(before, take_image(detector)) + + # 2. Does the LED reach the camera through the new objective? + autofocus() + auto_expose(detector) # before the dark frame: dark and bright share the exposure + set_light(led, False) + dark, result["light_noise"], result["light_required"] = noise_baseline(detector) + set_light(led, True) + bright = take_image(detector) + result["light_change"] = image_difference(dark, bright) + result["brightest_pixel"] = bright.getextrema()[1] + finally: + set_light(led, False) + # A move that was interrupted still runs, and ImSwitch refuses a second one meanwhile. + client.wait_until(lambda: not objective_status().get("isMovingObjective"), + MOVE_TIMEOUT) + if objective_status().get("currentObjective") != start: + switch_objective(start) + print(f"\nobjective switch {start} -> {target}: {result}") + return result + + +def test_objective_switch_is_visible(measurement): + m = measurement + assert m["switch_change"] >= m["switch_required"], ( + f"switching to {m['objective']} changed the image only by {m['switch_change']:.2f}; " + f"camera noise floor is {m['switch_noise']:.2f}, need >= {m['switch_required']:.2f} - " + f"the turret may not have moved") + + +def test_light_is_visible_after_objective_switch(measurement): + m = measurement + assert m["brightest_pixel"] > 0, ( + f"{m['led']} is on but every pixel is still 0: no light through {m['objective']}") + assert m["light_change"] >= m["light_required"], ( + f"{m['led']}: image changed only by {m['light_change']:.2f} through {m['objective']}; " + f"camera noise floor is {m['light_noise']:.2f}, need >= {m['light_required']:.2f}") From 1cbc5264b60ec5609ec8d5957d351262494aea06 Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Fri, 13 Nov 2026 12:54:51 +0100 Subject: [PATCH 02/10] Add HIL tests for setLEDs and the FRAME calibration test_ledmatrix_single lights the most central LED alone with the new LEDMatrixController/setLEDs and checks that the cameras see it, dimmer than every LED. test_frame_calibration runs the one-button FRAME calibration on the target in the holder and attaches its report figures. It turns the manual-focus fallback off for the run, so a missing focus fails instead of waiting for a user, and saves the setup as it was before into the report folder (HIL_REPORT_DIR, set by __main__), since the calibration result is kept. Co-Authored-By: Claude Opus 5.5 --- imswitch/imcontrol/_test/hil/README.md | 5 +- imswitch/imcontrol/_test/hil/__main__.py | 3 + .../_test/hil/test_frame_calibration.py | 158 ++++++++++++ .../_test/hil/test_ledmatrix_single.py | 228 ++++++++++++++++++ 4 files changed, 393 insertions(+), 1 deletion(-) create mode 100644 imswitch/imcontrol/_test/hil/test_frame_calibration.py create mode 100644 imswitch/imcontrol/_test/hil/test_ledmatrix_single.py diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md index 81261f8ff..105680ba5 100644 --- a/imswitch/imcontrol/_test/hil/README.md +++ b/imswitch/imcontrol/_test/hil/README.md @@ -14,6 +14,8 @@ Tests of a running ImSwitch on a real microscope, through its HTTP API only. The | `objective_switch` | switching the objective shows in the image, and light still gets through | **moves** turret and Z, **light** | | `lightsource` | lasers/LEDs switch; every LED reaches the cameras | **light** | | `ledmatrix` | the LED matrix reaches the cameras | **light** | +| `ledmatrix_single` | one LED lights alone (`setLEDs`) and is dimmer than every LED | **light** | +| `frame_calibration` | the one-button FRAME calibration runs through; needs the calibration target in the holder | **moves** (homes, turret), **light**, **writes the setup** (backup: `setup_before_frame_calibration.json`) | | `motor_axis_move` | each axis steps 10 µm and back | **moves** | | `motor_motion_camera` | the observation camera sees X/Y/Z/A move | **moves** (parks at the transport position), **light** | @@ -35,7 +37,8 @@ python -m imswitch.imcontrol._test.hil out --sync-firmware # FLASHES It waits until ImSwitch answers, the board is connected and every camera gives a frame, then runs the tests and writes `junit.xml`, `report.html` (results, output and photos in one file) -and `summary.md` to `REPORT_DIR`. Both reports name the setup file the rig ran with. Exit code: `0` all passed, `1` a test failed, `2` the tests +and `summary.md` to `REPORT_DIR`. A test may leave further files there; it finds the folder in +the environment variable `HIL_REPORT_DIR`. Both reports name the setup file the rig ran with. Exit code: `0` all passed, `1` a test failed, `2` the tests could not run (not ready, firmware sync failed, unknown test, everything skipped). The test rig (os-rpi, `.github/hil/`) runs exactly this command inside the ImSwitch container. diff --git a/imswitch/imcontrol/_test/hil/__main__.py b/imswitch/imcontrol/_test/hil/__main__.py index 68260bbbb..64017a174 100644 --- a/imswitch/imcontrol/_test/hil/__main__.py +++ b/imswitch/imcontrol/_test/hil/__main__.py @@ -15,6 +15,7 @@ The test rig (os-rpi) runs exactly this command inside the ImSwitch container. """ import argparse +import os import sys from pathlib import Path @@ -100,6 +101,8 @@ def main(): return COULD_NOT_RUN report_dir = Path(args.report_dir) + # A test that leaves a file for the report (e.g. a backup) writes it here. + os.environ["HIL_REPORT_DIR"] = str(report_dir.resolve()) code = pytest.main( [*[str(file) for file in files or [HERE]], "-c", str(HERE / "pytest.ini"), "-ra", f"--junitxml={report_dir / 'junit.xml'}"], diff --git a/imswitch/imcontrol/_test/hil/test_frame_calibration.py b/imswitch/imcontrol/_test/hil/test_frame_calibration.py new file mode 100644 index 000000000..d2bae84fa --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_frame_calibration.py @@ -0,0 +1,158 @@ +"""The one-button FRAME calibration runs through on the calibration target in the holder. + +MOVES REAL HARDWARE: homes X, Y, Z and the turret, moves the stage across the target, focuses, +switches the objective. SWITCHES LIGHT. WRITES THE SETUP: the calibration stores its result +(stage offset, objective offsets, pixel calibration) in the setup file the rig runs with. That +result stays, it is what the calibration is for; the setup as it was before is saved as +setup_before_frame_calibration.json in the report folder, to go back to by hand. + +The calibration target (plate or pinhole slides, setting "target") must be in the holder. +Afterwards the settings this test changed are back and every light is off. +""" +import io +import json +import os +import time +from pathlib import Path + +import pytest +from PIL import Image + +import hil_client as client +from hil_report import attach + +RUN_TIMEOUT = 1800 # seconds the whole calibration may take +POLL_S = 2 # seconds between two status requests +STOP_TIMEOUT = 60 # seconds a stopped calibration may take to end +# Without a focus the calibration would wait for someone to focus by hand and press Continue. +# Nobody is there in a test, so the run fails instead. +TEST_SETTINGS = {"manualFocusFallback": False} +BACKUP_NAME = "setup_before_frame_calibration.json" +ENDED = ("finished", "failed", "aborted") + + +# --- the calibration -------------------------------------------------------------------------- + +def status(): + return client.get_json("/FrameCalibrationController/getFrameCalibrationStatus") + + +def settings(): + return client.get_json("/FrameCalibrationController/getFrameCalibrationSettings") + + +def set_settings(values): + return client.post_json("/FrameCalibrationController/setFrameCalibrationSettings", + json=values) + + +def stop_and_wait(): + """Stop a calibration that still runs, and wait until it has ended.""" + if status()["state"] in ENDED + ("idle",): + return + client.post_json("/FrameCalibrationController/stopFrameCalibration") + client.wait_until(lambda: status()["state"] in ENDED + ("idle",), STOP_TIMEOUT, + interval=POLL_S) + + +def run_calibration(): + """Start the calibration and follow it to its end; returns the last status. + + Every step's change is printed once, so the output reads as the calibration's log. + """ + started = client.post_json("/FrameCalibrationController/startFrameCalibration") + assert started.get("success"), f"startFrameCalibration refused: {started}" + printed = {} + deadline = time.monotonic() + RUN_TIMEOUT + while True: + current = status() + for step in current["steps"]: + line = (step["status"], step["detail"], len(step["warnings"])) + if printed.get(step["name"]) != line and step["status"] != "pending": + printed[step["name"]] = line + print(f"[{step['status']}] {step['title']}: {step['detail']}", flush=True) + if current["state"] in ENDED: + return current + # The test turned the manual focus off; a wait for the user would never end. + assert current["state"] != "waiting", ( + f"the calibration waits for the user: {current['message']}") + assert time.monotonic() < deadline, ( + f"the calibration did not end within {RUN_TIMEOUT}s (step {current['step']!r})") + time.sleep(POLL_S) + + +def attach_figures(): + """Every report figure of the run (yellow = expected, green = measured) into the report.""" + for figure in client.get_json("/FrameCalibrationController/getFrameCalibrationFigures"): + response = client.get("/FrameCalibrationController/getFrameCalibrationFigure", + params={"figureId": figure["id"]}) + if response.headers.get("content-type", "").startswith("image/"): + mark = "" if figure.get("ok") in (True, None) else " (NOT OK)" + attach(f"{figure['title']}{mark}", Image.open(io.BytesIO(response.content))) + + +# --- the rig before and after ----------------------------------------------------------------- + +def all_lights_off(): + for name in client.setup()["lasers"]: + client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": 0}) + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": False}) + if client.setup()["LEDMatrixs"]: + client.get_json("/LEDMatrixController/setAllLEDOff") + + +def save_setup_backup(): + """Write the setup as it is now into the report folder; returns the file.""" + folder = Path(os.environ.get("HIL_REPORT_DIR", ".")) + folder.mkdir(parents=True, exist_ok=True) + file = folder / BACKUP_NAME + backup = {"setupFile": client.setup_file(), "setup": client.setup()} + file.write_text(json.dumps(backup, indent=2), encoding="utf-8") + print(f"\nsetup before the calibration saved to {file.resolve()}") + return file + + +@pytest.fixture(scope="module") +def calibration(): + """Run the calibration once; returns its last status. Puts the settings and light back.""" + setup = client.setup() + if not setup["positioners"]: + pytest.skip("the setup has no stage") + response = client.get("/FrameCalibrationController/getFrameCalibrationSettings") + if response.status_code == 404: + pytest.skip("this ImSwitch has no FrameCalibrationController") + original = client.json_of(response) + if status()["state"] not in ENDED + ("idle",): + pytest.skip(f"a FRAME calibration is already running: {status()['state']}") + + save_setup_backup() + print(f"target {original['target']!r}, settings changed for the test: {TEST_SETTINGS}") + try: + set_settings(TEST_SETTINGS) + result = run_calibration() + finally: + stop_and_wait() + set_settings({key: original[key] for key in TEST_SETTINGS}) + all_lights_off() + attach_figures() + print(f"\n{result['state']}: {result['message']}") + return result + + +# --- tests ------------------------------------------------------------------------------------ + +def test_calibration_finishes(calibration): + assert calibration["state"] == "finished", ( + f"the calibration ended as {calibration['state']!r} in step {calibration['step']!r}: " + f"{calibration['message']} - is the calibration target in the holder?") + + +def test_every_step_succeeds(calibration): + """Optional steps may fail without stopping the calibration; this test lists them.""" + failed = [f"{step['title']}: {step['detail']}" for step in calibration["steps"] + if step["status"] in ("failed", "aborted")] + assert not failed, "steps that failed:\n" + "\n".join(failed) + warned = [f"{step['title']}: {'; '.join(step['warnings'])}" for step in calibration["steps"] + if step["warnings"]] + if warned: + print("\nwarnings:\n" + "\n".join(warned)) diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py new file mode 100644 index 000000000..02c014d15 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py @@ -0,0 +1,228 @@ +"""One LED of the matrix lights alone, and the cameras see it. SWITCHES LIGHT. + +setLEDs lights exactly the LEDs it is given. One LED must change the image by more than the +camera's own noise, and the whole matrix must give a brighter image than that one LED. +The LED is the one closest to the optical axis (from the DPC LED layout), so that it lights the +sample in brightfield; without the DPC controller it is the centre of the setup's Nx x Ny grid. +""" +import base64 +import contextlib +import io +import time + +import pytest +from PIL import Image, ImageChops, ImageStat + +import hil_client as client +from hil_report import attach + +SINGLE_INTENSITY = 255 # per colour, of setLEDs (0..255) +MATRIX_INTENSITY = 255 # per colour, of setAllLED, the same as one LED +LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it +AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time +FRAME_RESIZE = 0.25 # the frames are compared at this share of their size +# One LED must change the image by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. +# The noise is the largest difference between NOISE_SAMPLES dark frames. +MIN_CHANGE = 1.5 +NOISE_FACTOR = 1.5 +NOISE_SAMPLES = 6 +NOISE_DELAY_S = 0.5 + + +# --- lights ----------------------------------------------------------------------------------- + +def all_lights_off(): + """Every laser, LED and the LED matrix off, so only the matrix changes the image.""" + for name in client.setup()["lasers"]: + client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": 0}) + client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": False}) + client.get_json("/LEDMatrixController/setAllLEDOff") + time.sleep(LIGHT_SETTLE_S) + + +def central_led(): + """Chain index of the LED closest to the optical axis. + + The DPC controller knows every LED's illumination NA; the smallest NA is the most central + LED. Without it, the middle of the Nx x Ny grid the setup declares (ImSwitch's default + layout) is taken; its chain order is not known here, so that LED may lie off centre. + """ + response = client.get("/DPCController/get_led_layout") + if response.status_code == 200: + leds = response.json().get("leds") or [] + if leds: + led = min(leds, key=lambda led: led["na_x"] ** 2 + led["na_y"] ** 2) + return led["id"], f"smallest illumination NA ({led['na_x']:.3f}, {led['na_y']:.3f})" + matrix = next(iter(client.setup()["LEDMatrixs"].values())) + props = matrix.get("managerProperties") or {} + nx, ny = int(props.get("Nx", 8)), int(props.get("Ny", 8)) + return (ny // 2) * nx + nx // 2, f"middle of the {nx} x {ny} grid (no DPC layout)" + + +# --- cameras ---------------------------------------------------------------------------------- +# An acquisition detector ("forAcquisition": true in the setup) gives frames only while its +# live view runs. The observation camera ("forAcquisition": false) gives them at any time. + +def is_observation_camera(detector): + return not client.setup()["detectors"][detector]["forAcquisition"] + + +def take_image(detector): + """One small greyscale frame (PIL) of either kind of camera.""" + if is_observation_camera(detector): + # camera_name only names the folder ImSwitch saves the frame to. + response = client.post("/ExperimentController/snapOverviewImage", timeout=60, + params={"slot_id": "1", "camera_name": "hil_ledmatrix_single"}) + if response.status_code == 400: + pytest.skip(f"observation camera not connected: {response.text}") + raw = base64.b64decode(client.json_of(response)["imageBase64"]) + frame = Image.open(io.BytesIO(raw)).convert("L") + return frame.resize((max(1, int(frame.width * FRAME_RESIZE)), + max(1, int(frame.height * FRAME_RESIZE)))) + response = client.get("/RecordingController/snapNumpyToFastAPI", timeout=60, + params={"detectorName": detector, "resizeFactor": FRAME_RESIZE}) + assert response.status_code == 200, response.text + return Image.open(io.BytesIO(response.content)).convert("L") + + +def image_difference(first, second): + """Mean absolute grey-value difference between two frames.""" + return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] + + +def brightness(image): + """Mean grey value of a frame.""" + return ImageStat.Stat(image).mean[0] + + +def dark_baseline(detector): + """Measure the camera noise with the scene unchanged. + + Returns (last frame, noise floor, change one LED must exceed). + """ + previous = take_image(detector) + drifts = [] + for _ in range(NOISE_SAMPLES - 1): + time.sleep(NOISE_DELAY_S) + current = take_image(detector) + drifts.append(image_difference(previous, current)) + previous = current + noise_floor = max(drifts) + required = max(MIN_CHANGE, noise_floor * NOISE_FACTOR) + print(f"\n{detector} dark noise: drifts={[round(d, 2) for d in drifts]}, " + f"noise_floor={noise_floor:.2f}, required_change={required:.2f}") + return previous, noise_floor, required + + +@contextlib.contextmanager +def live_view(detector): + """Keep an acquisition detector streaming inside a ``with`` block. + + Only a live view that was started here is stopped again. + """ + # The HTTP status is 200 even when ImSwitch refuses, so only the "status" field tells. + status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, + timeout=60).get("status") + if status == "long_exposure": + pytest.skip(f"{detector}: exposure too long for live view") + assert status in ("success", "already_running"), ( + f"{detector}: startLiveView answered {status!r}") + time.sleep(0.4) + try: + yield + finally: + if status == "success": + client.get_json("/LiveViewController/stopLiveView", {"detectorName": detector}) + + +def auto_expose(detector): + """One auto-exposure pass on the scene as it is now; needs a running live view.""" + client.get_json("/SettingsController/setDetectorExposureOnce", + {"detectorName": detector, "resetDelayMs": AUTO_EXPOSURE_RESET_MS}) + time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) + + +# --- fixtures --------------------------------------------------------------------------------- + +@pytest.fixture(scope="module", autouse=True) +def led_matrix(): + if not client.setup()["LEDMatrixs"]: + pytest.skip("the setup has no LED matrix") + if client.get("/LEDMatrixController/setLEDs", params={"ledIds": ""}).status_code == 404: + pytest.skip("this ImSwitch has no LEDMatrixController/setLEDs") + + +@pytest.fixture(scope="module", params=["acquisition", "observation"]) +def camera(request): + """A camera that is ready to take frames; with it a test runs once per kind of camera. + + The test sets the exposure itself, with every LED on, so that no frame saturates. + """ + wanted = request.param == "observation" + names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] + if not names: + pytest.skip(f"the setup has no {request.param} camera") + detector = names[0] + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in status or status.get("status") == "error": + pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") + if status.get("isMock") or str(status.get("model", "")).lower() == "mock": + pytest.skip(f"{detector}: ImSwitch served a mock camera") + + all_lights_off() + if wanted: + yield detector + else: + with live_view(detector): + yield detector + all_lights_off() + + +@pytest.fixture +def dark(): + """Every light off before and after the test.""" + all_lights_off() + yield + all_lights_off() + + +# --- tests ------------------------------------------------------------------------------------ + +def test_single_led_is_visible_and_dimmer_than_all(camera, dark): + led, why = central_led() + + # 1. Every LED on; the exposure is set on this, the brightest scene, so nothing saturates. + # The observation camera has no live view for the auto exposure to act on. + client.get_json("/LEDMatrixController/setAllLED", { + "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, + "intensity_b": MATRIX_INTENSITY}) + time.sleep(LIGHT_SETTLE_S) + if not is_observation_camera(camera): + auto_expose(camera) + every = take_image(camera) + + # 2. Only the one LED: setLEDs switches every other LED off. + client.get_json("/LEDMatrixController/setLEDs", { + "ledIds": str(led), "intensity_r": SINGLE_INTENSITY, "intensity_g": SINGLE_INTENSITY, + "intensity_b": SINGLE_INTENSITY}) + time.sleep(LIGHT_SETTLE_S) + single = take_image(camera) + + # 3. Dark, at the same exposure: the noise the single LED must exceed. + all_lights_off() + unlit, noise_floor, required = dark_baseline(camera) + + attach("dark", unlit) + attach(f"LED {led} alone", single) + attach("every LED", every) + change = image_difference(unlit, single) + print(f"\nLED {led} ({why}): pixel_change={change:.2f} noise_floor={noise_floor:.2f} " + f"required={required:.2f}; brightness dark={brightness(unlit):.2f} " + f"single={brightness(single):.2f} all={brightness(every):.2f}") + assert change >= required, ( + f"LED {led} alone changed the image only by {change:.2f}; camera noise floor is " + f"{noise_floor:.2f}, need >= {required:.2f} - setLEDs may not have lit it") + assert brightness(every) > brightness(single), ( + f"every LED ({brightness(every):.2f}) is not brighter than LED {led} alone " + f"({brightness(single):.2f}) - setLEDs may have lit more than one LED, or the camera " + f"saturates") From afd17700e711de92ac5e839f4cd71f17ca7915b8 Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Fri, 13 Nov 2026 16:44:30 +0100 Subject: [PATCH 03/10] improve test execution order; remove obsolete tests --- imswitch/imcontrol/_test/hil/README.md | 17 +- imswitch/imcontrol/_test/hil/conftest.py | 44 ++- .../_test/hil/test_frame_calibration.py | 8 +- .../_test/hil/test_motor_axis_move.py | 35 --- .../_test/hil/test_motor_motion_camera.py | 294 ------------------ .../_test/hil/test_objective_switch.py | 247 --------------- 6 files changed, 61 insertions(+), 584 deletions(-) delete mode 100644 imswitch/imcontrol/_test/hil/test_motor_axis_move.py delete mode 100644 imswitch/imcontrol/_test/hil/test_motor_motion_camera.py delete mode 100644 imswitch/imcontrol/_test/hil/test_objective_switch.py diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md index 105680ba5..c345ba8b7 100644 --- a/imswitch/imcontrol/_test/hil/README.md +++ b/imswitch/imcontrol/_test/hil/README.md @@ -11,16 +11,22 @@ Tests of a running ImSwitch on a real microscope, through its HTTP API only. The | `board_link` | the UC2 board is connected and runs the CANopen master firmware | reads | | `firmware_server` | the firmware server has images; every board runs its version | reads | | `camera_capture` | every camera returns a frame at its resolution | reads | -| `objective_switch` | switching the objective shows in the image, and light still gets through | **moves** turret and Z, **light** | | `lightsource` | lasers/LEDs switch; every LED reaches the cameras | **light** | | `ledmatrix` | the LED matrix reaches the cameras | **light** | | `ledmatrix_single` | one LED lights alone (`setLEDs`) and is dimmer than every LED | **light** | | `frame_calibration` | the one-button FRAME calibration runs through; needs the calibration target in the holder | **moves** (homes, turret), **light**, **writes the setup** (backup: `setup_before_frame_calibration.json`) | -| `motor_axis_move` | each axis steps 10 µm and back | **moves** | -| `motor_motion_camera` | the observation camera sees X/Y/Z/A move | **moves** (parks at the transport position), **light** | Hardware a setup does not have skips its tests. Hardware that is there but does not work fails. +They run in the order of the table: the boards, the cameras, the lights, then the calibration. +The order is the list `ORDER` in `conftest.py`. + +The calibration is the test of the motors. It homes Z, X, Y and the turret, reads the position +back after every move, follows X and Y in the observation camera, focuses with Z and switches +the objective. It does not start when a test before it failed: without boards, cameras and +light it can only fail. A step the calibration skips (e.g. the second objective on a rig with +one) is listed in the test's output as not tested. + ## Run ```bash @@ -69,7 +75,7 @@ What the tests share has nothing to do with what they check: |---|---| | `hil_client.py` | HTTP (`get_json`, `post_json`, `wait_until`), `setup()`, `parametrize_from_rig` | | `hil_report.py` | `attach(label, image)` and the HTML/Markdown report | -| `conftest.py` | marks the tests `hardware`; skips everything when ImSwitch is not reachable | +| `conftest.py` | the order of the tests (`ORDER`); skips the calibration after a failure; marks the tests `hardware`; skips everything when ImSwitch is not reachable | | `__main__.py` | the command above | | `firmware_sync.py` | `--sync-firmware` | @@ -94,7 +100,8 @@ So a rig with other hardware needs another setup file in ImSwitch, not other tes ## Writing a test Copy the test that is closest to the new one, rename it `test_.py`, and change it. It -runs with the others from then on; nothing else has to be registered. A test file has: +runs with the others from then on, after the tests listed in `ORDER` (`conftest.py`); add its +name there to give it another place. A test file has: 1. a first line saying what it checks and what it does to the rig; 2. its settings, as constants; diff --git a/imswitch/imcontrol/_test/hil/conftest.py b/imswitch/imcontrol/_test/hil/conftest.py index 1994a0856..3e355e144 100644 --- a/imswitch/imcontrol/_test/hil/conftest.py +++ b/imswitch/imcontrol/_test/hil/conftest.py @@ -1,18 +1,58 @@ -"""What applies to every HIL test. Nothing here knows what a test checks.""" +"""What applies to every HIL test: the order they run in, and when they do not run at all. + +Nothing here knows what a test checks. +""" from pathlib import Path import pytest import hil_client as client +# The order the test files run in. A test file that is not listed runs after these. +ORDER = [ + "board_link", "firmware_server", # 1. the boards and their firmware versions + "camera_capture", # 2. the cameras + "lightsource", "ledmatrix", "ledmatrix_single", # 3. the lights + "frame_calibration", # 4. the calibration: moves every motor +] +# Not started when a test before it failed: it moves the stage for up to half an hour, and +# without boards, cameras and light it can only fail. +GUARDED = "frame_calibration" + +_failed_before = [] # the tests outside GUARDED that failed so far in this run + + +def name_of(item_or_report): + """ "board_link" for a test of test_board_link.py.""" + file = item_or_report.nodeid.split("::")[0] # "test_board_link.py::test_uc2_board_connected" + return Path(file).stem[len("test_"):] + def pytest_collection_modifyitems(items): - """Mark every HIL test ``hardware``, so ``pytest -m "not hardware"`` leaves the suite out.""" + """Put the tests in ORDER, and mark every HIL test ``hardware``. + + The mark lets ``pytest -m "not hardware"`` leave the suite out. + """ + # The sort keeps the order of the tests inside a file. + items.sort(key=lambda item: ORDER.index(name_of(item)) if name_of(item) in ORDER + else len(ORDER)) for item in items: if Path(__file__).parent in Path(item.fspath).parents: item.add_marker(pytest.mark.hardware) +def pytest_runtest_logreport(report): + """Called with every test's result: remember the failures before GUARDED.""" + if report.failed and name_of(report) != GUARDED: + _failed_before.append(report.nodeid) + + +def pytest_runtest_setup(item): + """Called before a test and its fixtures start: skip GUARDED after a failure.""" + if name_of(item) == GUARDED and _failed_before: + pytest.skip(f"not started, because {_failed_before[0]} failed") + + @pytest.fixture(scope="session", autouse=True) def imswitch_reachable(): """Without a server the whole suite skips.""" diff --git a/imswitch/imcontrol/_test/hil/test_frame_calibration.py b/imswitch/imcontrol/_test/hil/test_frame_calibration.py index d2bae84fa..8d5ed73ee 100644 --- a/imswitch/imcontrol/_test/hil/test_frame_calibration.py +++ b/imswitch/imcontrol/_test/hil/test_frame_calibration.py @@ -26,7 +26,9 @@ STOP_TIMEOUT = 60 # seconds a stopped calibration may take to end # Without a focus the calibration would wait for someone to focus by hand and press Continue. # Nobody is there in a test, so the run fails instead. -TEST_SETTINGS = {"manualFocusFallback": False} +# The light value is set, not kept ("illuminationValue" 0 = keep its current value): the +# teardown turns every light to 0, so a kept value would be 0 in the next run - a black camera. +TEST_SETTINGS = {"manualFocusFallback": False, "illuminationValue": 500} BACKUP_NAME = "setup_before_frame_calibration.json" ENDED = ("finished", "failed", "aborted") @@ -156,3 +158,7 @@ def test_every_step_succeeds(calibration): if step["warnings"]] if warned: print("\nwarnings:\n" + "\n".join(warned)) + # A skipped step did not test its part of the rig, e.g. the turret without a second objective. + skipped = [step["title"] for step in calibration["steps"] if step["status"] == "skipped"] + if skipped: + print("\nskipped, so not tested:\n" + "\n".join(skipped)) diff --git a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py deleted file mode 100644 index 10e675bc9..000000000 --- a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py +++ /dev/null @@ -1,35 +0,0 @@ -"""Every axis reports a small relative step, then steps back. MOVES REAL HARDWARE (10 µm).""" -import time - -import pytest - -import hil_client as client - -STEP_UM = 10 -SETTLE_S = 0.5 # wait before reading the position back - - -def axes(): - """Every (positioner, axis) pair of the setup, e.g. ("ESP32Stage", "X").""" - return [(name, axis) for name, positioner in client.setup()["positioners"].items() - if positioner["forPositioning"] for axis in positioner["axes"]] - - -def position(positioner, axis): - return client.get_json("/PositionerController/getPositionerPositions")[positioner][axis] - - -@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") -def test_axis_moves_by_step(positioner, axis): - step = {"positionerName": positioner, "axis": axis, "dist": STEP_UM} - back = {"positionerName": positioner, "axis": axis, "dist": -STEP_UM} - - before = position(positioner, axis) - try: - client.get_json("/PositionerController/movePositioner", step) - time.sleep(SETTLE_S) - after = position(positioner, axis) - assert after == pytest.approx(before + STEP_UM, abs=0.1), ( - f"{positioner} {axis}: {before} -> {after}, expected {before + STEP_UM}") - finally: - client.get_json("/PositionerController/movePositioner", back) diff --git a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py deleted file mode 100644 index d3984a046..000000000 --- a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py +++ /dev/null @@ -1,294 +0,0 @@ -"""Stage motion as the observation camera sees it. MOVES REAL HARDWARE and SWITCHES LIGHT. - -The stage parks at the transport position (ImSwitch switches the Z hard limits off there, and -the turret goes to slot 0) and the LED matrix lights the sample. Then every axis moves out and -back once, and three tests judge that one measurement: - -- test_axis_motion_is_visible (every axis): the image changed more than its noise -- test_axis_motion_direction (X, Y): +X moves the image right, +Y moves it down -- test_z_motion_changes_scale (Z): the image got larger or smaller -""" -import base64 -import functools -import io -import time - -import numpy as np -import pytest -from PIL import Image - -import hil_client as client -from hil_report import attach - -# Distances are in µm, times in seconds. -DISTANCE_UM = 3000 -Z_DISTANCE_UM = 5000 -Z_DIRECTION = -1 # away from Z home: at the transport position the limits are off -SPEED = 15000 -SETTLE_S = 0.5 # wait after a move, before the frame -TRANSPORT_SPEED = 20000 # above 30000 the stage loses steps -TRANSPORT_TIMEOUT = 120 -TURRET_TIMEOUT = 120 -MATRIX_INTENSITY = 255 # the firmware's maximum per colour -MATRIX_SETTLE_S = 3.5 # wait after switching the matrix on, before the first frame - -EXPECTED_DIRECTION = {"X": "right", "Y": "down"} # of the image, when the axis moves by +distance -MIN_RATIO = 1.8 # image change over noise that counts as movement, X and Y -MIN_RATIO_AZ = 1.25 # the same for A and Z, which change the image less -ROI = (150, 355, 150, 340) # X/Y are judged in frame[y1:y2, x1:x2] of the 640x360 image -TOP_CROP_PERCENT = 25 # A/Z are judged below this top share of the image -Z_SCALE_MIN = 0.90 # the image scales that are tried to find the Z zoom -Z_SCALE_MAX = 1.10 -Z_SCALE_STEP = 0.002 -Z_MIN_SCALE_CHANGE = 0.001 -Z_SCALE_NOISE_RATIO = 1.4 - -SNAP = {"slot_id": "1", "camera_name": "hil_motion"} # camera_name: folder ImSwitch saves to - - -# --- stage ------------------------------------------------------------------------------------ - -def axes(): - """Every (positioner, axis) pair of the setup, e.g. ("ESP32Stage", "X").""" - return [(name, axis) for name, positioner in client.setup()["positioners"].items() - if positioner["forPositioning"] for axis in positioner["axes"]] - - -def xy_axes(): - return [pair for pair in axes() if pair[1].upper() in EXPECTED_DIRECTION] - - -def z_axes(): - return [pair for pair in axes() if pair[1].upper() == "Z"] - - -def move(positioner, axis, distance): - """Move one axis by ``distance`` µm and wait until it has arrived and settled.""" - client.get_json("/PositionerController/movePositioner", timeout=60, params={ - "positionerName": positioner, "axis": axis, "dist": distance, - "isBlocking": True, "speed": SPEED}) - time.sleep(SETTLE_S) - - -def wait_until_stopped(): - """The positions once two reads agree; some endpoints answer before the stage has arrived.""" - previous = client.get_json("/PositionerController/getPositionerPositions") - deadline = time.monotonic() + TRANSPORT_TIMEOUT - while time.monotonic() < deadline: - time.sleep(0.5) - current = client.get_json("/PositionerController/getPositionerPositions") - if current == previous: - break - previous = current - return previous - - -def park_at_transport(): - """Move to the transport position and turn the turret to slot 0; returns the positions.""" - client.get_json("/PositionerController/moveToTransportPosition", timeout=TRANSPORT_TIMEOUT, - params={"speed": TRANSPORT_SPEED, "isBlocking": True}) - wait_until_stopped() - if client.setup()["objective"]: - status = client.get_json("/ObjectiveController/getstatus") - if status.get("isActive") and status.get("hasMotor") and status["slotConfigured"][0]: - # skipZ: the turret must not apply the slot's Z offset to the parked stage. - started = client.get_json("/ObjectiveController/moveToObjective", - {"slot": 0, "skipZ": True}) - assert started.get("accepted"), f"the turret refused slot 0: {started}" - - def turned(): - # moveToObjective only starts the move; the status tells when it is done. - now = client.get_json("/ObjectiveController/getstatus") - return (not now.get("isMovingObjective") and - now.get("lastCompletedObjectiveRequestId") == started["requestId"]) - - assert client.wait_until(turned, TURRET_TIMEOUT), ( - f"the turret did not reach slot 0 in {TURRET_TIMEOUT}s") - return wait_until_stopped() - - -# --- observation camera ----------------------------------------------------------------------- - -def frame(): - """One full-size greyscale frame of the observation camera, as a float array.""" - body = client.post_json("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) - image = Image.open(io.BytesIO(base64.b64decode(body["imageBase64"]))).convert("L") - return np.asarray(image, dtype=np.float32) - - -# --- image maths: frames are greyscale float arrays ------------------------------------------- - -def difference(before, after): - """Mean absolute grey-value difference.""" - assert before.shape == after.shape - return float(np.mean(np.abs(after - before))) - - -def roi(image): - """The part of the frame in which X/Y motion is judged (ROI).""" - y1, y2, x1, x2 = ROI - height, width = image.shape - assert 0 <= x1 < x2 <= width, f"invalid ROI x-range {x1}:{x2} for image width {width}" - assert 0 <= y1 < y2 <= height, f"invalid ROI y-range {y1}:{y2} for image height {height}" - return image[y1:y2, x1:x2] - - -def below_top(image): - """The frame without its top TOP_CROP_PERCENT, where A/Z motion is judged.""" - return image[image.shape[0] * TOP_CROP_PERCENT // 100:, :] - - -def shift(before, after): - """How far AFTER is moved against BEFORE: (dx, dy, peak) in pixels, +dx right, +dy down. - - Phase correlation: the peak of the correlation of the two images lies at their shift, and - its height says how clear the match is. - """ - assert before.shape == after.shape - before, after = before.astype(np.float64), after.astype(np.float64) - # Fade the edges out, or the FFT takes the jump from one edge to the other for structure. - window = np.hanning(before.shape[0])[:, None] * np.hanning(before.shape[1])[None, :] - f_before = np.fft.fft2((before - before.mean()) * window) - f_after = np.fft.fft2((after - after.mean()) * window) - cross_power = np.conj(f_before) * f_after - cross_power /= np.maximum(np.abs(cross_power), 1e-12) - correlation = np.fft.fftshift(np.abs(np.fft.ifft2(cross_power))) - peak_y, peak_x = np.unravel_index(np.argmax(correlation), correlation.shape) - dy = peak_y - correlation.shape[0] // 2 - dx = peak_x - correlation.shape[1] // 2 - return float(dx), float(dy), float(correlation[peak_y, peak_x]) - - -def direction(dx, dy, min_shift=2): - """ "right", "left", "down" or "up"; None if the shift is under ``min_shift`` pixels.""" - if np.hypot(dx, dy) < min_shift: - return None - if abs(dx) > abs(dy): - return "right" if dx > 0 else "left" - return "down" if dy > 0 else "up" - - -def scale(before, after): - """The zoom of AFTER against BEFORE; above 1 means the image got larger. - - Tries every scale from Z_SCALE_MIN to Z_SCALE_MAX: zoom BEFORE by it, cut or pad it back - to the frame size, and keep the scale whose result matches AFTER best. - """ - height, width = before.shape - image = Image.fromarray(np.ascontiguousarray(before, dtype=np.float32)) - best_scale, best_peak = 1.0, -1.0 - for candidate in np.arange(Z_SCALE_MIN, Z_SCALE_MAX + Z_SCALE_STEP / 2, Z_SCALE_STEP): - zoomed = np.asarray(image.resize((max(1, round(width * candidate)), - max(1, round(height * candidate))), Image.BILINEAR)) - zoomed_height, zoomed_width = zoomed.shape - # Offsets in the zoomed image (when it is larger) and in the frame (when it is smaller). - from_y, to_y = max(0, (zoomed_height - height) // 2), max(0, (height - zoomed_height) // 2) - from_x, to_x = max(0, (zoomed_width - width) // 2), max(0, (width - zoomed_width) // 2) - h, w = min(zoomed_height, height), min(zoomed_width, width) - resized = np.full(before.shape, float(np.median(before)), dtype=np.float32) - resized[to_y:to_y + h, to_x:to_x + w] = zoomed[from_y:from_y + h, from_x:from_x + w] - peak = shift(resized, after)[2] - if peak > best_peak: - best_scale, best_peak = round(float(candidate), 6), peak - return best_scale - - -# --- the measurement and its tests ------------------------------------------------------------ - -@pytest.fixture(scope="module", autouse=True) -def parked_and_lit(): - """Check the camera before anything moves, then park the stage and switch the matrix on.""" - setup = client.setup() - cameras = [name for name, detector in setup["detectors"].items() - if not detector["forAcquisition"]] - if not cameras: - pytest.skip("the setup has no observation camera") - status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": cameras[0]}) - if "error" in status or status.get("status") == "error": - pytest.skip(f"{cameras[0]}: getCameraStatus failed: {status.get('error')}") - if status.get("isMock") or status.get("isConnected") is False: - pytest.skip(f"{cameras[0]} is a mock camera or not connected: {status}") - response = client.post("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) - if response.status_code != 200: - pytest.skip(f"{cameras[0]} cannot deliver an image: {response.text}") - roi(frame()) # fails here if ROI does not fit the image - - print(f"\ntransport position reached: {park_at_transport()}") - has_matrix = bool(setup["LEDMatrixs"]) - if has_matrix: - client.get_json("/LEDMatrixController/setAllLED", { - "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, - "intensity_b": MATRIX_INTENSITY}) - time.sleep(MATRIX_SETTLE_S) - yield - if has_matrix: - client.get_json("/LEDMatrixController/setAllLEDOff") - - -@functools.lru_cache(maxsize=None) # each axis moves once; the tests share the result -def measure(positioner, axis): - """Move one axis out and back, and return what the frames before and after show.""" - is_xy = axis.upper() in EXPECTED_DIRECTION - is_z = axis.upper() == "Z" - distance = Z_DISTANCE_UM * Z_DIRECTION if is_z else DISTANCE_UM - # X and Y shift the image, so they are judged in a region that stays on the sample. - region = roi if is_xy else below_top - - still = frame() - time.sleep(SETTLE_S) - before = frame() - move(positioner, axis, distance) - try: - after = frame() - finally: - move(positioner, axis, -distance) - attach(f"{axis} before", before) - attach(f"{axis} after {distance:+d} um", after) - - noise = difference(region(still), region(before)) - change = difference(region(before), region(after)) - result = {"noise": noise, "change": change, "ratio": change / max(noise, 1e-6)} - if is_xy: - dx, dy, peak = shift(region(before), region(after)) - result["direction"] = direction(dx, dy) - result["shift"] = f"dx={dx:+.1f}px, dy={dy:+.1f}px, peak={peak:.4f}" - if is_z: - result["scale"] = scale(roi(before), roi(after)) - result["scale_change"] = abs(result["scale"] - 1) - result["scale_noise"] = abs(scale(roi(still), roi(before)) - 1) - print(f"\n{positioner} {axis} {distance:+d} um: {result}") - return result - - -@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") -def test_axis_motion_is_visible(positioner, axis): - result = measure(positioner, axis) - required = MIN_RATIO if axis.upper() in EXPECTED_DIRECTION else MIN_RATIO_AZ - assert result["ratio"] >= required, ( - f"{positioner} {axis}: movement was not clearly visible. change={result['change']:.3f}, " - f"noise={result['noise']:.3f}, ratio={result['ratio']:.2f}x, required={required:.2f}x") - - -@client.parametrize_from_rig("positioner, axis", xy_axes, "the setup has no X/Y axes") -def test_axis_motion_direction(positioner, axis): - """Only the wrong direction fails. A shift too small to measure skips.""" - result = measure(positioner, axis) - if result["direction"] is None: - pytest.skip(f"{positioner} {axis}: no clear translation ({result['shift']})") - expected = EXPECTED_DIRECTION[axis.upper()] - assert result["direction"] == expected, ( - f"{positioner} {axis}: image moved {result['direction']}, expected {expected} " - f"({result['shift']})") - - -@client.parametrize_from_rig("positioner, axis", z_axes, "the setup has no Z axis") -def test_z_motion_changes_scale(positioner, axis): - """Larger or smaller does not matter. An unclear scale skips as long as the move was seen.""" - result = measure(positioner, axis) - clear = (result["scale_change"] >= Z_MIN_SCALE_CHANGE - and result["scale_change"] >= result["scale_noise"] * Z_SCALE_NOISE_RATIO) - evidence = (f"scale={result['scale']:.4f}, change={result['scale_change']:.4f}, " - f"noise={result['scale_noise']:.4f}, ratio={result['ratio']:.2f}x") - if not clear and result["ratio"] >= MIN_RATIO_AZ: - pytest.skip(f"{positioner} {axis}: moved, but the scale change is unclear. {evidence}") - assert clear, f"{positioner} {axis}: no scale change and no movement seen. {evidence}" diff --git a/imswitch/imcontrol/_test/hil/test_objective_switch.py b/imswitch/imcontrol/_test/hil/test_objective_switch.py deleted file mode 100644 index 344d9a5b6..000000000 --- a/imswitch/imcontrol/_test/hil/test_objective_switch.py +++ /dev/null @@ -1,247 +0,0 @@ -"""Switching the objective changes the image, and light still reaches the camera through it. - -MOVES REAL HARDWARE: turns the turret, applies the Z offset stored for the slot, and runs the -autofocus (moves Z). SWITCHES LIGHT. - -The turret switches once; both tests read that one measurement. Afterwards the LED is off and -the turret is back on the slot it started from, also when the measurement failed. -""" -import contextlib -import io -import time - -import pytest -from PIL import Image, ImageChops, ImageStat - -import hil_client as client - -SETTLE_S = 0.5 # wait after the turret, the autofocus or a light has changed -MOVE_TIMEOUT = 120 # seconds the turret may take -AUTOFOCUS_TIMEOUT = 180 -AUTOFOCUS_RANGE_UM = 100 -AUTOFOCUS_STEP_UM = 10 -AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time -FRAME_RESIZE = 0.25 # the frames are compared at this share of their size -# The image must change by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. -# The noise is the largest difference between NOISE_SAMPLES frames of an unchanged scene. -MIN_CHANGE = 1.5 -NOISE_FACTOR = 1.5 -NOISE_SAMPLES = 6 -NOISE_DELAY_S = 0.5 - - -# --- objective turret and autofocus ----------------------------------------------------------- - -def objective_status(): - return client.get_json("/ObjectiveController/getstatus") - - -def switch_objective(slot): - """Turn the turret to ``slot`` (with the slot's Z offset) and wait; returns the status. - - A busy turret or an unconfigured slot skips the test, any other problem fails it. - """ - started = client.get_json("/ObjectiveController/moveToObjective", - {"slot": slot, "skipZ": False}) - if not started.get("accepted"): - if started.get("reason") in ("slot_not_configured", "busy"): - pytest.skip(f"objective slot {slot} unavailable: {started}") - pytest.fail(f"objective slot {slot} refused: {started}") - - def finished(): - # moveToObjective only starts the move, so the status tells when this request is done. - status = objective_status() - done = (not status.get("isMovingObjective") - and status.get("lastCompletedObjectiveRequestId") == started["requestId"]) - return status if done or status.get("lastObjectiveMoveError") else None - - status = client.wait_until(finished, MOVE_TIMEOUT) - assert status, f"objective move to slot {slot} did not finish in {MOVE_TIMEOUT}s" - assert not status.get("lastObjectiveMoveError"), ( - f"objective move to slot {slot} failed: {status.get('lastObjectiveMoveError')}") - assert status.get("currentObjective") == slot, ( - f"objective reports slot {status.get('currentObjective')}, expected {slot}") - time.sleep(SETTLE_S) - return status - - -def autofocus(): - """Run the software autofocus (moves Z) and wait for it. - - An autofocus that does not work skips the test: then the rig cannot measure, which says - nothing about the objective. - """ - started = client.get_json("/AutofocusController/autoFocus", timeout=60, params={ - "rangez": AUTOFOCUS_RANGE_UM, "resolutionz": AUTOFOCUS_STEP_UM}) - if started.get("status") == "error": - pytest.skip(f"autofocus did not start: {started.get('message')}") - - def finished(): - status = client.get_json("/AutofocusController/getAutofocusStatus") - if status.get("state") in ("error", "aborted"): - pytest.skip(f"autofocus ended as {status.get('state')!r}") - done = not status.get("isRunning") and status.get("state") in ("finished", "idle") - return status if done else None - - status = client.wait_until(finished, AUTOFOCUS_TIMEOUT) - if status is None: - client.get_json("/AutofocusController/stopAutofocus") - pytest.fail(f"autofocus did not finish in {AUTOFOCUS_TIMEOUT}s") - print(f"\nautofocus: z={status.get('currentZ')}, quality={status.get('lastQuality')}") - time.sleep(SETTLE_S) - - -# --- light ------------------------------------------------------------------------------------ - -def set_light(name, on): - """Switch one LED on (at the highest value its setup allows) or off.""" - value = client.setup()["lasers"][name]["valueRangeMax"] if on else 0 - client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": value}) - client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": on}) - time.sleep(SETTLE_S) - - -# --- camera ----------------------------------------------------------------------------------- - -def take_image(detector): - """One small greyscale frame (PIL) of the acquisition detector; needs its live view.""" - response = client.get("/RecordingController/snapNumpyToFastAPI", timeout=60, - params={"detectorName": detector, "resizeFactor": FRAME_RESIZE}) - assert response.status_code == 200, response.text - return Image.open(io.BytesIO(response.content)).convert("L") - - -def image_difference(first, second): - """Mean absolute grey-value difference between two frames.""" - return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] - - -def noise_baseline(detector): - """Measure the camera noise with the scene unchanged. - - Returns (last frame, noise floor, change that counts as a real difference). - """ - previous = take_image(detector) - drifts = [] - for _ in range(NOISE_SAMPLES - 1): - time.sleep(NOISE_DELAY_S) - current = take_image(detector) - drifts.append(image_difference(previous, current)) - previous = current - noise_floor = max(drifts) - return previous, noise_floor, max(MIN_CHANGE, noise_floor * NOISE_FACTOR) - - -@contextlib.contextmanager -def live_view(detector): - """Keep the detector streaming inside a ``with`` block. - - Only a live view that was started here is stopped again. - """ - # The HTTP status is 200 even when ImSwitch refuses, so only the "status" field tells. - status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, - timeout=60).get("status") - if status == "long_exposure": - pytest.skip(f"{detector}: exposure too long for live view") - assert status in ("success", "already_running"), ( - f"{detector}: startLiveView answered {status!r}") - time.sleep(0.4) - try: - yield - finally: - if status == "success": - client.get_json("/LiveViewController/stopLiveView", {"detectorName": detector}) - - -def auto_expose(detector): - """One auto-exposure pass on the scene as it is now; needs a running live view.""" - client.get_json("/SettingsController/setDetectorExposureOnce", - {"detectorName": detector, "resetDelayMs": AUTO_EXPOSURE_RESET_MS}) - time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) - - -# --- the measurement and its tests ------------------------------------------------------------ - -@pytest.fixture(scope="module") -def measurement(): - """Switch to another objective and measure; returns the numbers the tests check.""" - setup = client.setup() - if not setup["objective"]: - pytest.skip("the setup has no objective turret") - status = objective_status() - slots = [slot for slot, configured in enumerate(status.get("slotConfigured") or []) - if configured] - if not status.get("isActive") or not status.get("hasMotor") or len(slots) < 2: - pytest.skip(f"this rig cannot switch between two objectives: {status}") - # Lasers and LEDs are listed alike under "lasers"; on these rigs only an LED lights the - # sensor, and only the name tells them apart. - leds = [name for name in setup["lasers"] - if "led" in name.lower() and "laser" not in name.lower()] - if not leds: - pytest.skip("no LED among the light sources of the setup") - led = leds[0] - # Only an acquisition detector looks through the objective. - detectors = [name for name, detector in setup["detectors"].items() - if detector["forAcquisition"]] - if not detectors: - pytest.skip("the setup has no acquisition detector") - detector = detectors[0] - camera = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) - if "error" in camera or camera.get("status") == "error": - pytest.skip(f"{detector}: getCameraStatus failed: {camera.get('error')}") - if camera.get("isMock") or str(camera.get("model", "")).lower() == "mock": - pytest.skip(f"{detector}: ImSwitch served a mock camera") - - start = status.get("currentObjective") - if start not in slots: # a turret that was never calibrated reports no slot - start = slots[0] - switch_objective(start) - target = next(slot for slot in slots if slot != start) - result = {"led": led} - - with live_view(detector): - try: - # 1. Does the switch change the image? LED on, turret still: measure the noise. - set_light(led, True) - auto_expose(detector) - autofocus() - before, result["switch_noise"], result["switch_required"] = noise_baseline(detector) - print(f"\nswitching objective: slot {start} -> {target}") - result["objective"] = switch_objective(target).get("objectiveName") - result["switch_change"] = image_difference(before, take_image(detector)) - - # 2. Does the LED reach the camera through the new objective? - autofocus() - auto_expose(detector) # before the dark frame: dark and bright share the exposure - set_light(led, False) - dark, result["light_noise"], result["light_required"] = noise_baseline(detector) - set_light(led, True) - bright = take_image(detector) - result["light_change"] = image_difference(dark, bright) - result["brightest_pixel"] = bright.getextrema()[1] - finally: - set_light(led, False) - # A move that was interrupted still runs, and ImSwitch refuses a second one meanwhile. - client.wait_until(lambda: not objective_status().get("isMovingObjective"), - MOVE_TIMEOUT) - if objective_status().get("currentObjective") != start: - switch_objective(start) - print(f"\nobjective switch {start} -> {target}: {result}") - return result - - -def test_objective_switch_is_visible(measurement): - m = measurement - assert m["switch_change"] >= m["switch_required"], ( - f"switching to {m['objective']} changed the image only by {m['switch_change']:.2f}; " - f"camera noise floor is {m['switch_noise']:.2f}, need >= {m['switch_required']:.2f} - " - f"the turret may not have moved") - - -def test_light_is_visible_after_objective_switch(measurement): - m = measurement - assert m["brightest_pixel"] > 0, ( - f"{m['led']} is on but every pixel is still 0: no light through {m['objective']}") - assert m["light_change"] >= m["light_required"], ( - f"{m['led']}: image changed only by {m['light_change']:.2f} through {m['objective']}; " - f"camera noise floor is {m['light_noise']:.2f}, need >= {m['light_required']:.2f}") From 9f1c4fff9d4f36ec821374b447dbefeae35c6b32 Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Sat, 14 Nov 2026 10:39:56 +0100 Subject: [PATCH 04/10] Implement HIL PDF reporting and calibration enhancements --- imswitch/imcontrol/_test/hil/README.md | 29 ++- imswitch/imcontrol/_test/hil/__main__.py | 62 ++++-- imswitch/imcontrol/_test/hil/conftest.py | 22 +- imswitch/imcontrol/_test/hil/hil_pdf.py | 111 ++++++++++ imswitch/imcontrol/_test/hil/hil_report.py | 47 +++- .../_test/hil/test_frame_calibration.py | 103 +++++++-- .../_test/unit/test_hil_reporting.py | 201 ++++++++++++++++++ .../controllers/frame_calibration_report.py | 93 +++++--- pyproject.toml | 2 + uv.lock | 26 +++ 10 files changed, 596 insertions(+), 100 deletions(-) create mode 100644 imswitch/imcontrol/_test/hil/hil_pdf.py create mode 100644 imswitch/imcontrol/_test/unit/test_hil_reporting.py diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md index c345ba8b7..b02ef2756 100644 --- a/imswitch/imcontrol/_test/hil/README.md +++ b/imswitch/imcontrol/_test/hil/README.md @@ -2,7 +2,7 @@ Tests of a running ImSwitch on a real microscope, through its HTTP API only. They sit next to `../unit/` (no server) and `../api/` (headless server), but never import ImSwitch: they need only -`pytest`, `requests`, `pillow` and `numpy`. +`pytest`, `requests`, `pillow`, `numpy`, `reportlab` and `pypdf`. **They move the stage and switch light.** Each test file says in its first line what it does. @@ -23,8 +23,8 @@ The order is the list `ORDER` in `conftest.py`. The calibration is the test of the motors. It homes Z, X, Y and the turret, reads the position back after every move, follows X and Y in the observation camera, focuses with Z and switches -the objective. It does not start when a test before it failed: without boards, cameras and -light it can only fail. A step the calibration skips (e.g. the second objective on a rig with +the objective. It is attempted even when an earlier test failed; its own preflight and busy checks +decide whether it can proceed. Earlier failures still fail the overall run. A step the calibration skips (e.g. the second objective on a rig with one) is listed in the test's output as not tested. ## Run @@ -41,9 +41,11 @@ python -m imswitch.imcontrol._test.hil out --sync-firmware # FLASHES `TEST` is the name from the table: `board_link` runs `test_board_link.py`. -It waits until ImSwitch answers, the board is connected and every camera gives a frame, then -runs the tests and writes `junit.xml`, `report.html` (results, output and photos in one file) -and `summary.md` to `REPORT_DIR`. A test may leave further files there; it finds the folder in +It waits until ImSwitch answers and its setup is readable. Camera startup errors are recorded +without preventing the tests or calibration. It then runs the tests and writes `junit.xml`, `report.html` (results, output and photos in one file) +and `summary.md` to `REPORT_DIR`. `hil-report.pdf` contains the test summary, diagnostics and +photos followed by the original PDF of this run's calibration (`calibration-report.pdf`). +A failed or unstarted calibration is explicitly identified; an older report is never substituted. A test may leave further files there; it finds the folder in the environment variable `HIL_REPORT_DIR`. Both reports name the setup file the rig ran with. Exit code: `0` all passed, `1` a test failed, `2` the tests could not run (not ready, firmware sync failed, unknown test, everything skipped). @@ -75,7 +77,7 @@ What the tests share has nothing to do with what they check: |---|---| | `hil_client.py` | HTTP (`get_json`, `post_json`, `wait_until`), `setup()`, `parametrize_from_rig` | | `hil_report.py` | `attach(label, image)` and the HTML/Markdown report | -| `conftest.py` | the order of the tests (`ORDER`); skips the calibration after a failure; marks the tests `hardware`; skips everything when ImSwitch is not reachable | +| `conftest.py` | the order of the tests (`ORDER`); runs calibration last even after failures; marks the tests `hardware`; skips everything when ImSwitch is not reachable | | `__main__.py` | the command above | | `firmware_sync.py` | `--sync-firmware` | @@ -116,3 +118,16 @@ name there to give it another place. A test file has: fixture with `yield`). - Code that a second test needs is copied, not shared: a test must stay readable and removable by itself. + +## Combined report and retained calibration + +The suite waits for the calibration thread to finish cleanup before exporting its PDF through +`getFrameCalibrationReportPdf`. It checks the run's `startedAt` before and after export. +Calibration results remain in the instrument's setup, even after os-rpi restores the deployment. +A failed calibration may have written partial changes; the setup backup is for manual recovery. +No automatic rollback is performed. Cleanup/export failures are reported as errors. + +Optional `HIL_TARGET` and `HIL_RUN_URL` identify the tested image/pallet and Actions run in the +PDF. os-rpi supplies these; laptop runs show that the target was not supplied. +ReportLab renders the test pages; pypdf appends the original calibration PDF. Full captured +output remains in HTML. A PDF generation failure preserves HTML/Markdown and fails the run. diff --git a/imswitch/imcontrol/_test/hil/__main__.py b/imswitch/imcontrol/_test/hil/__main__.py index 64017a174..930354683 100644 --- a/imswitch/imcontrol/_test/hil/__main__.py +++ b/imswitch/imcontrol/_test/hil/__main__.py @@ -50,28 +50,31 @@ def can_snap(detector, for_acquisition): def why_not_ready(): - """Wait for ImSwitch, the board and every camera. Returns None, or what is missing.""" + """Wait for ImSwitch and a readable setup. Returns None, or what is missing.""" if not client.wait_until(client.reachable, READY_API_TIMEOUT, interval=5): return f"ImSwitch did not answer at {client.IMSWITCH_URL} within {READY_API_TIMEOUT}s" - if client.get_json("/UC2ConfigController/uc2_board_is_connected") is not True: - return "the UC2 board is not connected" - detectors = client.setup()["detectors"] - if not detectors: - return "the setup has no detectors" - for name, detector in detectors.items(): - for_acquisition = detector["forAcquisition"] - if for_acquisition: # an acquisition detector gives frames only while its live view runs - status = client.post_json("/LiveViewController/startLiveView", - {"detectorName": name}, timeout=60).get("status") - if status not in ("success", "already_running"): - return f"{name}: startLiveView answered {status!r}" - if not client.wait_until(lambda: can_snap(name, for_acquisition), READY_DETECTOR_TIMEOUT, - interval=5): - return f"{name} gave no frame within {READY_DETECTOR_TIMEOUT}s" - print(f"[hil] {name} is ready", flush=True) + client.setup() # A readable setup is needed to collect the tests. return None +def prepare_cameras(): + """Give cameras time to start; record failures without blocking calibration.""" + problems = [] + for name, detector in client.setup()["detectors"].items(): + try: + acquisition = detector["forAcquisition"] + if acquisition: + result = client.post_json("/LiveViewController/startLiveView", + {"detectorName": name}, timeout=60) + assert result.get("status") in ("success", "already_running"), result + assert client.wait_until(lambda: can_snap(name, acquisition), + READY_DETECTOR_TIMEOUT, interval=5), "no frame before timeout" + except (requests.RequestException, AssertionError) as error: + problems.append(f"{name}: {error}") + return problems + + + def main(): parser = argparse.ArgumentParser(prog="python -m imswitch.imcontrol._test.hil") parser.add_argument("report_dir", help="folder for junit.xml, report.html and summary.md") @@ -81,11 +84,22 @@ def main(): help="FLASH every board to the firmware server's version first") args = parser.parse_args() + report_dir = Path(args.report_dir) + report_dir.mkdir(parents=True, exist_ok=True) + os.environ["HIL_REPORT_DIR"] = str(report_dir.resolve()) + hil_report.reset() + # A reused local report directory must not expose artifacts from an older run. + for name in ("hil-report.pdf", "test-report.pdf", "calibration-report.pdf", + "calibration-status.json", "setup_before_frame_calibration.json", "report-error.txt", + "report.html", "summary.md", "junit.xml"): + (report_dir / name).unlink(missing_ok=True) files = [HERE / f"test_{name}.py" for name in args.tests] unknown = [name for name, file in zip(args.tests, files) if not file.is_file()] if unknown: known = " ".join(sorted(file.stem[len("test_"):] for file in HERE.glob("test_*.py"))) - print(f"[hil] no such test: {' '.join(unknown)}. There are: {known}") + problem = f"no such test: {' '.join(unknown)}. There are: {known}" + hil_report.record_problem("startup", problem) + hil_report.write_reports(report_dir, "unavailable") return COULD_NOT_RUN try: @@ -98,11 +112,13 @@ def main(): problem = str(error) if problem: print(f"[hil] not running the tests: {problem}") + hil_report.record_problem("startup", problem) + hil_report.write_reports(report_dir, "unavailable") return COULD_NOT_RUN - report_dir = Path(args.report_dir) - # A test that leaves a file for the report (e.g. a backup) writes it here. - os.environ["HIL_REPORT_DIR"] = str(report_dir.resolve()) + for problem in prepare_cameras(): + hil_report.record_problem(f"camera preparation: {problem.split(':', 1)[0]}", problem) + code = pytest.main( [*[str(file) for file in files or [HERE]], "-c", str(HERE / "pytest.ini"), "-ra", f"--junitxml={report_dir / 'junit.xml'}"], @@ -110,7 +126,9 @@ def main(): counts = hil_report.counts() print("[hil] " + " · ".join(f"{n} {status}" for status, n in counts.items())) - if code == pytest.ExitCode.TESTS_FAILED: + if hil_report.report_error: + return COULD_NOT_RUN + if code == pytest.ExitCode.TESTS_FAILED or counts["failed"] or counts["error"]: return FAILED if code != pytest.ExitCode.OK: return COULD_NOT_RUN diff --git a/imswitch/imcontrol/_test/hil/conftest.py b/imswitch/imcontrol/_test/hil/conftest.py index 3e355e144..393d99644 100644 --- a/imswitch/imcontrol/_test/hil/conftest.py +++ b/imswitch/imcontrol/_test/hil/conftest.py @@ -15,12 +15,6 @@ "lightsource", "ledmatrix", "ledmatrix_single", # 3. the lights "frame_calibration", # 4. the calibration: moves every motor ] -# Not started when a test before it failed: it moves the stage for up to half an hour, and -# without boards, cameras and light it can only fail. -GUARDED = "frame_calibration" - -_failed_before = [] # the tests outside GUARDED that failed so far in this run - def name_of(item_or_report): """ "board_link" for a test of test_board_link.py.""" @@ -34,25 +28,13 @@ def pytest_collection_modifyitems(items): The mark lets ``pytest -m "not hardware"`` leave the suite out. """ # The sort keeps the order of the tests inside a file. - items.sort(key=lambda item: ORDER.index(name_of(item)) if name_of(item) in ORDER - else len(ORDER)) + items.sort(key=lambda item: (name_of(item) == "frame_calibration", + ORDER.index(name_of(item)) if name_of(item) in ORDER else len(ORDER))) for item in items: if Path(__file__).parent in Path(item.fspath).parents: item.add_marker(pytest.mark.hardware) -def pytest_runtest_logreport(report): - """Called with every test's result: remember the failures before GUARDED.""" - if report.failed and name_of(report) != GUARDED: - _failed_before.append(report.nodeid) - - -def pytest_runtest_setup(item): - """Called before a test and its fixtures start: skip GUARDED after a failure.""" - if name_of(item) == GUARDED and _failed_before: - pytest.skip(f"not started, because {_failed_before[0]} failed") - - @pytest.fixture(scope="session", autouse=True) def imswitch_reachable(): """Without a server the whole suite skips.""" diff --git a/imswitch/imcontrol/_test/hil/hil_pdf.py b/imswitch/imcontrol/_test/hil/hil_pdf.py new file mode 100644 index 000000000..2ae128aeb --- /dev/null +++ b/imswitch/imcontrol/_test/hil/hil_pdf.py @@ -0,0 +1,111 @@ +"""Printable HIL results followed by the server's original calibration PDF.""" +import base64 +import io +import os +from datetime import datetime, timezone +from xml.sax.saxutils import escape + +from pypdf import PdfReader, PdfWriter +from reportlab.lib import colors +from reportlab.lib.pagesizes import A4 +from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet +from reportlab.lib.utils import ImageReader +from reportlab.platypus import ( + SimpleDocTemplate, Paragraph, Spacer, Table, TableStyle, Image, PageBreak, KeepTogether, +) + +INK = colors.HexColor("#16324f") +MUTED = colors.HexColor("#526579") +STATUS = {"passed": "#187448", "failed": "#b42332", "error": "#a34a12", "skipped": "#526579"} + + +def write_pdf(folder, setup, results, photos, calibration, started): + """Only an explicitly collected, current-run PDF may be appended.""" + styles = getSampleStyleSheet() + styles.add(ParagraphStyle("TitleHIL", fontName="Helvetica-Bold", fontSize=25, + leading=30, textColor=INK, spaceAfter=15)) + styles.add(ParagraphStyle("SectionHIL", fontName="Helvetica-Bold", fontSize=15, + leading=20, textColor=INK, spaceBefore=14, spaceAfter=9, + keepWithNext=True)) + styles.add(ParagraphStyle("BodyHIL", fontSize=9, leading=13, textColor=INK, + spaceAfter=7, splitLongWords=True)) + styles.add(ParagraphStyle("SmallHIL", parent=styles["BodyHIL"], fontSize=8, + leading=11, textColor=MUTED)) + + def p(text, style="BodyHIL"): + return Paragraph(escape(str(text)).replace("\n", "
"), styles[style]) + + def footer(canvas, doc): + canvas.setStrokeColor(colors.HexColor("#dce4ec")) + canvas.line(42, 37, A4[0] - 42, 37) + canvas.setFont("Helvetica", 8) + canvas.setFillColor(MUTED) + canvas.drawString(42, 24, "openUC2 | Hardware tests and FRAME calibration") + canvas.drawRightString(A4[0] - 42, 24, f"Tests / {doc.page}") + + story = [p("Hardware tests\n& FRAME calibration", "TitleHIL")] + totals = {state: sum(r["status"] == state for r in results.values()) for state in STATUS} + outcome = "FAILED" if totals["failed"] or totals["error"] else "PASSED" if totals["passed"] else "NOT RUN" + story += [p(f"TEST RESULT: {outcome}", "SectionHIL"), + p(" | ".join(f"{n} {state}" for state, n in totals.items()))] + metadata = [("Started (UTC)", datetime.fromtimestamp(started, timezone.utc).isoformat(timespec="seconds")), + ("Setup", setup), ("Tested target", os.environ.get("HIL_TARGET", "Not supplied")), + ("Run", os.environ.get("HIL_RUN_URL", "Local run")), + ("Calibration", calibration.get("state", "not started"))] + table = Table([[p(k, "SmallHIL"), p(v)] for k, v in metadata], colWidths=[100, A4[0] - 184]) + table.setStyle(TableStyle([("VALIGN", (0, 0), (-1, -1), "TOP"), + ("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#f0f4f8")), + ("LEFTPADDING", (0, 0), (-1, -1), 9), + ("TOPPADDING", (0, 0), (-1, -1), 6)])) + story += [table, Spacer(1, 12), p("Calibration results are retained on the instrument. " + "Deployment restoration does not roll back the setup. A failed calibration may have written partial changes."), + p("The pre-calibration setup backup and full diagnostic output are included in the report artifacts.", "SmallHIL"), + p("Test overview", "SectionHIL")] + rows = [[p("Test", "SmallHIL"), p("Result", "SmallHIL"), p("Time", "SmallHIL")]] + for name, r in results.items(): + rows.append([p(name, "SmallHIL"), Paragraph(f'{r["status"].upper()}', styles["SmallHIL"]), p(f"{r['duration']:.1f}s", "SmallHIL")]) + table = Table(rows, colWidths=[A4[0] - 220, 80, 56], repeatRows=1, hAlign="LEFT") + table.setStyle(TableStyle([("VALIGN", (0, 0), (-1, -1), "TOP"), + ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#e2ebf3")), + ("LINEBELOW", (0, 0), (-1, -1), .3, colors.HexColor("#dce4ec")), + ("TOPPADDING", (0, 0), (-1, -1), 7), + ("BOTTOMPADDING", (0, 0), (-1, -1), 7)])) + story.append(table) + if results: + story.append(PageBreak()) + for name, r in results.items(): + story += [p(name, "SectionHIL"), p(f"{r['status'].upper()} | {r['duration']:.1f} seconds")] + if r["details"]: + # Individual paragraphs let even a very long traceback paginate. + story.extend(p(line, "SmallHIL") for line in r["details"].splitlines()) + # The calibration PDF contains its full-size figures; do not duplicate them here. + if "test_frame_calibration.py" not in name: + for label, data in photos.get(name, []): + raw = io.BytesIO(base64.b64decode(data)) + width, height = ImageReader(raw).getSize() + scale = min((A4[0] - 84) / width, 285 / height) + story += [KeepTogether([p(label), Image(raw, width=width * scale, height=height * scale)]), Spacer(1, 12)] + if not calibration.get("pdf") or calibration.get("error"): + story += [PageBreak(), p("FRAME calibration", "TitleHIL"), + p(f"State: {calibration.get('state', 'not started')}", "SectionHIL"), + p(calibration.get("message", "Calibration was not selected or could not start. See test results."))] + if calibration.get("error"): + story += [p("Calibration / report collection error", "SectionHIL"), p(calibration["error"])] + if not calibration.get("pdf"): + story.append(p("No calibration PDF from this run is available. No historical report has been substituted.")) + front = folder / "test-report.pdf" + SimpleDocTemplate(str(front), pagesize=A4, rightMargin=42, leftMargin=42, + topMargin=42, bottomMargin=50, title="Hardware tests and FRAME calibration").build( + story, onFirstPage=footer, onLaterPages=footer) + with PdfWriter() as writer: + writer.append(str(front), outline_item="Hardware tests") + if calibration.get("pdf"): + reader = PdfReader(calibration["pdf"]) + if not len(reader.pages): + raise ValueError("Calibration PDF contains no pages") + writer.append(reader, outline_item="FRAME calibration (original report)") + writer.add_metadata({"/Title": "Hardware tests and FRAME calibration", "/Author": "openUC2"}) + target = folder / "hil-report.pdf" + temporary = folder / "hil-report.pending.pdf" + writer.write(str(temporary)) + temporary.replace(target) diff --git a/imswitch/imcontrol/_test/hil/hil_report.py b/imswitch/imcontrol/_test/hil/hil_report.py index b4eecbeec..3a21284ed 100644 --- a/imswitch/imcontrol/_test/hil/hil_report.py +++ b/imswitch/imcontrol/_test/hil/hil_report.py @@ -21,6 +21,44 @@ _photos = {} # test id -> [(label, base64 PNG)] _results = {} # test id -> {"status", "duration", "details", "output"} +calibration = {} +report_error = None + + +def reset(): + global _started, report_error + _started = time.time() + report_error = None + _photos.clear() + _results.clear() + calibration.clear() + + +def record_problem(name, message): + _results[name] = {"status": "error", "duration": 0.0, "details": str(message), "output": ""} + + +def write_reports(report_dir, setup_file): + global report_error + report_dir.mkdir(parents=True, exist_ok=True) + if not calibration: + skipped = [r["details"] for name, r in _results.items() + if "test_frame_calibration.py" in name and r["details"]] + calibration.update(state="not started", message="; ".join(skipped) or + "Calibration was not selected or the suite could not start.") + (report_dir / "hil-report.pdf").unlink(missing_ok=True) + (report_dir / "report-error.txt").unlink(missing_ok=True) + try: + from hil_pdf import write_pdf + write_pdf(report_dir, setup_file, _results, _photos, calibration, _started) + except Exception as error: + report_error = str(error) + record_problem("PDF generation", report_error) + (report_dir / "report-error.txt").write_text(report_error, encoding="utf-8") + print(f"[hil] PDF generation failed: {error}", flush=True) + (report_dir / "summary.md").write_text(summary(setup_file), encoding="utf-8") + (report_dir / "report.html").write_text(page(setup_file), encoding="utf-8") + def attach(label, image): """Add a photo to the test that is running. ``image`` is a PIL image or a numpy array.""" @@ -70,15 +108,15 @@ def pytest_runtest_logreport(self, report): result["details"] = report.longrepr[2] # (file, line, reason) def pytest_sessionfinish(self): - self.report_dir.mkdir(parents=True, exist_ok=True) - (self.report_dir / "summary.md").write_text(summary(self.setup_file), encoding="utf-8") - (self.report_dir / "report.html").write_text(page(self.setup_file), encoding="utf-8") + write_reports(self.report_dir, self.setup_file) def summary(setup_file): """Markdown, short enough for a CI step summary: the setup, the counts, one line per failure.""" totals = " · ".join(f"{n} {status}" for status, n in counts().items()) - lines = ["### HIL report", "", f"setup `{setup_file}`", "", totals, ""] + lines = ["### HIL report", "", f"setup `{setup_file}`", "", totals, "", + f"Calibration: **{calibration.get('state', 'not started')}**. Results retained on the instrument.", + "", "Combined PDF: `hil-report.pdf` (artifact: `hil-report-pdf`).", ""] for test, result in _results.items(): if result["status"] in ("failed", "error"): last_line = (result["details"].strip().splitlines() or [""])[-1] @@ -111,6 +149,7 @@ def card(test, result): HIL report

HIL report

+

Download combined test and calibration PDF

setup {setup} · started {started} · took {took:.0f} s
{totals}
{tests} diff --git a/imswitch/imcontrol/_test/hil/test_frame_calibration.py b/imswitch/imcontrol/_test/hil/test_frame_calibration.py index 8d5ed73ee..92d1e5133 100644 --- a/imswitch/imcontrol/_test/hil/test_frame_calibration.py +++ b/imswitch/imcontrol/_test/hil/test_frame_calibration.py @@ -19,6 +19,7 @@ from PIL import Image import hil_client as client +import hil_report from hil_report import attach RUN_TIMEOUT = 1800 # seconds the whole calibration may take @@ -48,22 +49,53 @@ def set_settings(values): json=values) -def stop_and_wait(): - """Stop a calibration that still runs, and wait until it has ended.""" - if status()["state"] in ENDED + ("idle",): - return - client.post_json("/FrameCalibrationController/stopFrameCalibration") - client.wait_until(lambda: status()["state"] in ENDED + ("idle",), STOP_TIMEOUT, - interval=POLL_S) +def running(): + return client.get_json("/FrameCalibrationController/isFrameCalibrationRunning") is True -def run_calibration(): +def stop_and_wait(): + """The terminal status alone does not mean cleanup/report writing has finished.""" + if not running(): + return + if status()["state"] not in ENDED: + client.post_json("/FrameCalibrationController/stopFrameCalibration") + assert client.wait_until(lambda: not running(), STOP_TIMEOUT, interval=POLL_S), ( + f"calibration thread did not stop within {STOP_TIMEOUT}s") + + +def collect_report(run): + """Export only the completed calibration started by this test, never an older one.""" + assert not running(), "cannot export while calibration still runs" + current = status() + assert run.get("startedAt") and current["startedAt"] == run["startedAt"], ( + "calibration identity changed; refusing to attach another run's report") + hil_report.calibration.update(state=current["state"], message=current["message"], + startedAt=current["startedAt"]) + folder = Path(os.environ.get("HIL_REPORT_DIR", ".")) + folder.mkdir(parents=True, exist_ok=True) + (folder / "calibration-status.json").write_text(json.dumps(current, indent=2), encoding="utf-8") + response = client.get("/FrameCalibrationController/getFrameCalibrationReportPdf", timeout=120) + assert response.status_code == 200 and response.content.startswith(b"%PDF-"), ( + f"calibration PDF export failed: HTTP {response.status_code}") + # Recheck after export because the endpoint returns the running/last report. + assert status()["startedAt"] == run["startedAt"], "calibration changed during PDF export" + from pypdf import PdfReader + assert len(PdfReader(io.BytesIO(response.content)).pages), "calibration PDF has no pages" + path = folder / "calibration-report.pdf" + path.write_bytes(response.content) + hil_report.calibration["pdf"] = str(path) + + +def run_calibration(run): """Start the calibration and follow it to its end; returns the last status. Every step's change is printed once, so the output reads as the calibration's log. """ started = client.post_json("/FrameCalibrationController/startFrameCalibration") assert started.get("success"), f"startFrameCalibration refused: {started}" + run["accepted"] = True + hil_report.calibration.update(state="running", message="Calibration accepted") + run["startedAt"] = status()["startedAt"] printed = {} deadline = time.monotonic() + RUN_TIMEOUT while True: @@ -73,7 +105,8 @@ def run_calibration(): if printed.get(step["name"]) != line and step["status"] != "pending": printed[step["name"]] = line print(f"[{step['status']}] {step['title']}: {step['detail']}", flush=True) - if current["state"] in ENDED: + assert current["startedAt"] == run["startedAt"], "calibration replaced during polling" + if current["state"] in ENDED and not running(): return current # The test turned the manual focus off; a wait for the user would never end. assert current["state"] != "waiting", ( @@ -83,8 +116,9 @@ def run_calibration(): time.sleep(POLL_S) -def attach_figures(): +def attach_figures(run): """Every report figure of the run (yellow = expected, green = measured) into the report.""" + assert not running() and status()["startedAt"] == run.get("startedAt"), "not this run's completed figures" for figure in client.get_json("/FrameCalibrationController/getFrameCalibrationFigures"): response = client.get("/FrameCalibrationController/getFrameCalibrationFigure", params={"figureId": figure["id"]}) @@ -96,11 +130,22 @@ def attach_figures(): # --- the rig before and after ----------------------------------------------------------------- def all_lights_off(): + actions = [] for name in client.setup()["lasers"]: - client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": 0}) - client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": False}) + actions.extend([ + ("/LaserController/setLaserValue", {"laserName": name, "value": 0}), + ("/LaserController/setLaserActive", {"laserName": name, "active": False}), + ]) if client.setup()["LEDMatrixs"]: - client.get_json("/LEDMatrixController/setAllLEDOff") + actions.append(("/LEDMatrixController/setAllLEDOff", None)) + errors = [] + for endpoint, params in actions: + try: + client.get_json(endpoint, params) + except Exception as error: + errors.append(f"{endpoint} {params}: {error}") + if errors: + raise RuntimeError("; ".join(errors)) def save_setup_backup(): @@ -124,19 +169,39 @@ def calibration(): if response.status_code == 404: pytest.skip("this ImSwitch has no FrameCalibrationController") original = client.json_of(response) - if status()["state"] not in ENDED + ("idle",): + if running(): pytest.skip(f"a FRAME calibration is already running: {status()['state']}") save_setup_backup() print(f"target {original['target']!r}, settings changed for the test: {TEST_SETTINGS}") + run, errors = {}, [] + result = None + hil_report.calibration.update(state="not started", message="Calibration start not yet accepted") try: set_settings(TEST_SETTINGS) - result = run_calibration() + result = run_calibration(run) + except Exception as error: + errors.append(("calibration", error)) finally: - stop_and_wait() - set_settings({key: original[key] for key in TEST_SETTINGS}) - all_lights_off() - attach_figures() + actions = [] + if run.get("accepted"): + actions.append(("stop/wait", stop_and_wait)) + actions.extend([ + ("restore settings", lambda: set_settings({key: original[key] for key in TEST_SETTINGS})), + ("lights off", all_lights_off), + ]) + if run.get("accepted"): + actions.extend([("export PDF", lambda: collect_report(run)), + ("attach figures", lambda: attach_figures(run))]) + for label, action in actions: + try: + action() + except Exception as error: + errors.append((label, error)) + if errors: + detail = "; ".join(f"{label}: {error}" for label, error in errors) + hil_report.calibration["error"] = detail + raise RuntimeError(detail) from errors[0][1] print(f"\n{result['state']}: {result['message']}") return result diff --git a/imswitch/imcontrol/_test/unit/test_hil_reporting.py b/imswitch/imcontrol/_test/unit/test_hil_reporting.py new file mode 100644 index 000000000..2676dec99 --- /dev/null +++ b/imswitch/imcontrol/_test/unit/test_hil_reporting.py @@ -0,0 +1,201 @@ +"""Offline checks of HIL orchestration and printable reports; never contact a rig.""" +import importlib.util +import io +import sys +from pathlib import Path +from types import SimpleNamespace + +import pytest +from pypdf import PdfReader +from reportlab.pdfgen.canvas import Canvas + +HIL = Path(__file__).parents[1] / "hil" +sys.path.insert(0, str(HIL)) +import hil_report +import hil_pdf + + +def load(name, path): + spec = importlib.util.spec_from_file_location(name, path) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +@pytest.fixture +def calibration_module(): + hil_report.reset() + return load("hil_calibration_test", HIL / "test_frame_calibration.py") + + +def pdf_bytes(text="Calibration evidence"): + data = io.BytesIO() + canvas = Canvas(data) + canvas.drawString(40, 700, text) + canvas.save() + return data.getvalue() + + +def test_pdf_merge_keeps_original_pages_and_long_failures(tmp_path): + original = tmp_path / "calibration-report.pdf" + original.write_bytes(pdf_bytes()) + results = {"test_camera.py::test_capture": { + "status": "failed", "duration": 2., "details": "Diagnostic line\n" * 140 + "LAST ERROR LINE", "output": ""}} + hil_pdf.write_pdf(tmp_path, "FRAME.json", results, {}, + {"state": "finished", "pdf": str(original)}, 0) + reader = PdfReader(tmp_path / "hil-report.pdf") + assert len(reader.pages) > 3 + text = "\n".join(page.extract_text() for page in reader.pages) + assert "LAST ERROR LINE" in text and "TEST RESULT: FAILED" in text + assert "Calibration evidence" in reader.pages[-1].extract_text() + assert len(reader.outline) == 2 + + +def test_old_pdf_is_not_appended_without_current_run(tmp_path): + (tmp_path / "calibration-report.pdf").write_bytes(pdf_bytes("OLD RUN")) + hil_report.reset() + hil_report.record_problem("startup", "server unavailable") + hil_report.write_reports(tmp_path, "unavailable") + text = "".join(p.extract_text() for p in PdfReader(tmp_path / "hil-report.pdf").pages) + assert "OLD RUN" not in text and "No calibration PDF" in text + + +def test_pdf_failure_preserves_other_reports_and_removes_stale_pdf(tmp_path, monkeypatch): + hil_report.reset() + (tmp_path / "hil-report.pdf").write_bytes(pdf_bytes("OLD RUN")) + def fail(*args): + raise ValueError("broken PDF") + monkeypatch.setattr(hil_pdf, "write_pdf", fail) + hil_report.write_reports(tmp_path, "FRAME.json") + assert hil_report.report_error == "broken PDF" + assert not (tmp_path / "hil-report.pdf").exists() + assert "broken PDF" in (tmp_path / "summary.md").read_text() + assert (tmp_path / "report.html").exists() + + +def test_stop_timeout_is_an_error(calibration_module, monkeypatch): + m = calibration_module + monkeypatch.setattr(m, "running", lambda: True) + monkeypatch.setattr(m, "status", lambda: {"state": "finished"}) + monkeypatch.setattr(m.client, "wait_until", lambda *a, **k: False) + with pytest.raises(AssertionError, match="thread did not stop"): + m.stop_and_wait() + + +def test_poll_waits_for_thread_after_terminal_status(calibration_module, monkeypatch): + m = calibration_module + monkeypatch.setattr(m.client, "post_json", lambda *a, **k: {"success": True}) + monkeypatch.setattr(m, "status", lambda: {"state": "finished", "startedAt": "now", "steps": []}) + states = iter([True, False]) + monkeypatch.setattr(m, "running", lambda: next(states)) + monkeypatch.setattr(m.time, "sleep", lambda _: None) + run = {} + assert m.run_calibration(run)["state"] == "finished" + assert run == {"accepted": True, "startedAt": "now"} + + +def test_export_rejects_other_run(calibration_module, monkeypatch): + m = calibration_module + monkeypatch.setattr(m, "running", lambda: False) + monkeypatch.setattr(m, "status", lambda: {"startedAt": "older"}) + with pytest.raises(AssertionError, match="identity changed"): + m.collect_report({"startedAt": "ours"}) + + +def test_failed_calibration_pdf_is_collected(calibration_module, monkeypatch, tmp_path): + m = calibration_module + monkeypatch.setenv("HIL_REPORT_DIR", str(tmp_path)) + monkeypatch.setattr(m, "running", lambda: False) + monkeypatch.setattr(m, "status", lambda: {"startedAt": "ours", "state": "failed", "message": "no focus"}) + monkeypatch.setattr(m.client, "get", lambda *a, **k: SimpleNamespace(status_code=200, content=pdf_bytes())) + m.collect_report({"startedAt": "ours"}) + assert hil_report.calibration["state"] == "failed" + assert (tmp_path / "calibration-report.pdf").exists() + + +def test_calibration_is_last_without_failure_guard(): + conf = load("hil_hooks", HIL / "conftest.py") + items = [SimpleNamespace(nodeid=f"test_{name}.py::test_it", fspath=HIL / f"test_{name}.py", + add_marker=lambda _: None) for name in ("frame_calibration", "new_test", "board_link")] + conf.pytest_collection_modifyitems(items) + assert conf.name_of(items[-1]) == "frame_calibration" + assert not hasattr(conf, "pytest_runtest_setup") + + +def test_calibration_summary_overflow_keeps_last_step(tmp_path): + report = load("frame_pdf", HIL.parents[1] / "controller/controllers/frame_calibration_report.py") + status = {"state": "failed", "steps": [dict(title=f"Step {i}", status="failed", detail="long detail " * 100, + warnings=["warning " * 50]) for i in range(12)]} + path = tmp_path / "calibration.pdf" + report.write_pdf(path, status, {"target": "plate"}, []) + reader = PdfReader(path) + assert len(reader.pages) > 1 + assert "Step 11" in "".join(p.extract_text() for p in reader.pages) + + +def test_camera_preparation_failure_does_not_prevent_test_execution(tmp_path, monkeypatch): + main = load("hil_main", HIL / "__main__.py") + monkeypatch.setattr(sys, "argv", ["hil", str(tmp_path)]) + monkeypatch.setattr(main, "why_not_ready", lambda: None) + monkeypatch.setattr(main, "prepare_cameras", lambda: ["camera A: no frame"]) + monkeypatch.setattr(main.client, "setup_file", lambda: "FRAME.json") + called = [] + def tests(*args, **kwargs): + called.append(True) + return pytest.ExitCode.OK + monkeypatch.setattr(main.pytest, "main", tests) + assert main.main() == main.FAILED + assert called == [True] + assert hil_report.counts()["error"] == 1 + + +def test_unreachable_server_still_writes_report(tmp_path, monkeypatch): + main = load("hil_main", HIL / "__main__.py") + (tmp_path / "calibration-report.pdf").write_bytes(pdf_bytes("old calibration")) + (tmp_path / "report-error.txt").write_text("old error") + monkeypatch.setattr(sys, "argv", ["hil", str(tmp_path)]) + monkeypatch.setattr(main, "why_not_ready", lambda: "server unavailable") + assert main.main() == main.COULD_NOT_RUN + assert (tmp_path / "hil-report.pdf").exists() + assert not (tmp_path / "calibration-report.pdf").exists() + assert not (tmp_path / "report-error.txt").exists() + + +def test_cleanup_error_does_not_prevent_lights_off_or_export(calibration_module, tmp_path, monkeypatch): + m = calibration_module + monkeypatch.setenv("HIL_REPORT_DIR", str(tmp_path)) + monkeypatch.setattr(m.client, "setup", lambda: {"positioners": {"stage": {}}, "lasers": {}, "LEDMatrixs": {}}) + monkeypatch.setattr(m.client, "get", lambda *a, **k: SimpleNamespace(status_code=200)) + monkeypatch.setattr(m.client, "json_of", lambda _: {"target": "plate", **m.TEST_SETTINGS}) + monkeypatch.setattr(m, "running", lambda: False) + monkeypatch.setattr(m, "save_setup_backup", lambda: None) + monkeypatch.setattr(m, "set_settings", lambda _: None) + called = [] + def run(ctx): + ctx.update(accepted=True, startedAt="ours") + raise AssertionError("original failure") + def stop(): + raise AssertionError("stop timeout") + monkeypatch.setattr(m, "run_calibration", run) + monkeypatch.setattr(m, "stop_and_wait", stop) + monkeypatch.setattr(m, "all_lights_off", lambda: called.append("off")) + monkeypatch.setattr(m, "collect_report", lambda _: called.append("pdf")) + monkeypatch.setattr(m, "attach_figures", lambda _: called.append("figures")) + with pytest.raises(RuntimeError, match="original failure.*stop timeout"): + m.calibration.__wrapped__() + assert called == ["off", "pdf", "figures"] + + +def test_pytest_continues_to_calibration_after_failure(tmp_path): + import os + import subprocess + conf = (HIL / "conftest.py").read_text() + (tmp_path / "conftest.py").write_text(conf + "\nclient.reachable = lambda: True\n") + (tmp_path / "test_board_link.py").write_text("def test_board():\n assert False, 'offline simulated failure'\n") + (tmp_path / "test_frame_calibration.py").write_text( + "from pathlib import Path\ndef test_calibration():\n Path(__file__).with_suffix('.ran').touch()\n") + env = dict(os.environ, PYTHONPATH=str(HIL), PYTEST_DISABLE_PLUGIN_AUTOLOAD="1") + result = subprocess.run([sys.executable, "-m", "pytest", str(tmp_path), "--confcutdir", str(tmp_path), "-q"], + env=env, capture_output=True, text=True, timeout=60) + assert result.returncode == 1, result.stdout + result.stderr + assert (tmp_path / "test_frame_calibration.ran").exists() diff --git a/imswitch/imcontrol/controller/controllers/frame_calibration_report.py b/imswitch/imcontrol/controller/controllers/frame_calibration_report.py index 6babb0f1e..661caf3d3 100644 --- a/imswitch/imcontrol/controller/controllers/frame_calibration_report.py +++ b/imswitch/imcontrol/controller/controllers/frame_calibration_report.py @@ -122,46 +122,83 @@ def wrap(s, n=110): with PdfPages(path) as pdf: fig = Figure(figsize=(8.27, 11.69)) y = 0.96 - fig.text(0.06, y, "FRAME calibration report", fontsize=16, weight="bold") - y -= 0.03 + + def lines(text, size=9, color="black", bold=False, indent=0.06, width=100): + nonlocal fig, y + for line in wrap(text, width).splitlines(): + if y < 0.07: + pdf.savefig(fig) + fig = Figure(figsize=(8.27, 11.69)) + y = 0.96 + fig.text(0.06, y, "FRAME calibration report (continued)", fontsize=14, weight="bold") + y -= 0.04 + fig.text(indent, y, line, fontsize=size, family="monospace", va="top", + color=color, weight="bold" if bold else "normal") + y -= max(0.016, size / 600) + y -= 0.007 + + lines("FRAME calibration report", size=16, bold=True) res = status.get("result") or {} cam = status.get("camera") or {} - for line in (f"state: {status.get('state')} started {status.get('startedAt')} finished {status.get('finishedAt')}", - wrap(status.get("message", ""), 100), f"report folder: {status.get('reportDir', '')}", - f"stored calibration: {res.get('timestamp', 'none')} camera: exposure {cam.get('exposureMs')} ms, " - f"gain {cam.get('gainDb')} dB ({cam.get('note', '')})"): - fig.text(0.06, y, line, fontsize=9, family="monospace", va="top") - y -= 0.022 * (1 + line.count("\n")) - y -= 0.01 + lines(f"state: {status.get('state')} started {status.get('startedAt')} finished {status.get('finishedAt')}") + lines(status.get("message", "")) + lines(f"report folder: {status.get('reportDir', '')}") + lines(f"stored calibration: {res.get('timestamp', 'none')} camera: exposure {cam.get('exposureMs')} ms, " + f"gain {cam.get('gainDb')} dB ({cam.get('note', '')})") for st in status.get("steps", []): head = f"[{st.get('status', ''):>7}] {st.get('title', '')}" + (f" ({st['seconds']} s)" if st.get("seconds") is not None else "") - body = "\n".join(filter(None, [wrap(st.get("detail", ""), 100)] + [wrap("warning: " + w, 100) for w in st.get("warnings", [])])) color = {"failed": "tab:red", "warn": "tab:orange", "ok": "tab:green"}.get(st.get("status"), "black") - fig.text(0.06, y, head, fontsize=9, family="monospace", va="top", color=color, weight="bold") - y -= 0.018 - if body: - fig.text(0.09, y, body, fontsize=7.5, family="monospace", va="top") - y -= 0.0145 * (1 + body.count("\n")) + 0.004 - if y < 0.12: - break + lines(head, color=color, bold=True) + lines(st.get("detail", ""), size=7.5, indent=0.09) + for warning in st.get("warnings", []): + lines("warning: " + warning, size=7.5, indent=0.09) if settings: - fig.text(0.06, 0.08, wrap("settings: " + ", ".join(f"{k}={v}" for k, v in settings.items()), 120), - fontsize=6.5, family="monospace", va="top", color="dimgray") + lines("settings: " + ", ".join(f"{k}={v}" for k, v in settings.items()), + size=6.5, color="dimgray", width=120) pdf.savefig(fig) - for i in range(0, len(figures), 2): + def needs_full_page(f): + return (len(wrap(f.get("title", ""), 95).splitlines()) > 1 or + len(wrap(f.get("expected", ""), 100).splitlines()) > 2 or + len(wrap(f.get("measured", ""), 100).splitlines()) > 3) + + i = 0 + while i < len(figures): fig = Figure(figsize=(8.27, 11.69)) - for j, f in enumerate(figures[i:i + 2]): + if needs_full_page(figures[i]): + f = figures[i] + y = 0.96 + lines(f"{f.get('step', '')}: {f.get('title', '')}", size=10, bold=True) img = cv2.imdecode(np.frombuffer(f["jpg"], np.uint8), cv2.IMREAD_COLOR) - top = 0.97 - j * 0.49 - ax = fig.add_axes([0.06, top - 0.33, 0.88, 0.31]) + if y < 0.5: + pdf.savefig(fig) + fig = Figure(figsize=(8.27, 11.69)) + y = 0.96 + ax = fig.add_axes([0.06, y - 0.34, 0.88, 0.32]) ax.imshow(img[..., ::-1]) ax.set_axis_off() - ok = {True: " - ok", False: " - FAILED"}.get(f.get("ok"), "") - fig.text(0.06, top, f"{f.get('step', '')}: {f.get('title', '')}{ok}", fontsize=10, weight="bold", va="top", - color="tab:red" if f.get("ok") is False else "black") - fig.text(0.06, top - 0.345, wrap("expected (yellow): " + f.get("expected", ""), 105), fontsize=8, va="top", color="#a07800") - fig.text(0.06, top - 0.395, wrap("measured (green): " + f.get("measured", ""), 105), fontsize=8, va="top", color="darkgreen") + y -= 0.36 + lines("expected (yellow): " + f.get("expected", ""), size=8, color="#a07800") + lines("measured (green): " + f.get("measured", ""), size=8, color="darkgreen") + if f.get("ok") is not None: + lines("Result: " + ("ok" if f["ok"] else "FAILED"), size=9) + i += 1 + else: + group = [figures[i]] + if i + 1 < len(figures) and not needs_full_page(figures[i + 1]): + group.append(figures[i + 1]) + for j, f in enumerate(group): + img = cv2.imdecode(np.frombuffer(f["jpg"], np.uint8), cv2.IMREAD_COLOR) + top = 0.97 - j * 0.49 + ax = fig.add_axes([0.06, top - 0.33, 0.88, 0.31]) + ax.imshow(img[..., ::-1]) + ax.set_axis_off() + ok = {True: " - ok", False: " - FAILED"}.get(f.get("ok"), "") + fig.text(0.06, top, f"{f.get('step', '')}: {f.get('title', '')}{ok}", fontsize=10, weight="bold", va="top", + color="tab:red" if f.get("ok") is False else "black") + fig.text(0.06, top - 0.345, wrap("expected (yellow): " + f.get("expected", ""), 105), fontsize=8, va="top", color="#a07800") + fig.text(0.06, top - 0.395, wrap("measured (green): " + f.get("measured", ""), 105), fontsize=8, va="top", color="darkgreen") + i += len(group) pdf.savefig(fig) diff --git a/pyproject.toml b/pyproject.toml index d7861cb92..22589199b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,6 +48,8 @@ dependencies = [ "fastapi >= 0.86.0", "uvicorn[standard] >= 0.19.0", "matplotlib == 3.9.2", + "reportlab>=4,<5", + "pypdf>=6,<7", "aiortc >= 1.9.0", "jupyter", "python-multipart >= 0.0.5", diff --git a/uv.lock b/uv.lock index cfa258c49..b4994c756 100644 --- a/uv.lock +++ b/uv.lock @@ -1825,12 +1825,14 @@ dependencies = [ { name = "psutil", marker = "python_full_version < '3.14'" }, { name = "psygnal", marker = "python_full_version < '3.14'" }, { name = "pydantic", marker = "python_full_version < '3.14'" }, + { name = "pypdf", marker = "python_full_version < '3.14'" }, { name = "pyserial", marker = "python_full_version < '3.14'" }, { name = "python-dateutil", marker = "python_full_version < '3.14'" }, { name = "python-multipart", marker = "python_full_version < '3.14'" }, { name = "python-socketio", marker = "python_full_version < '3.14'" }, { name = "pyvisa-py", marker = "python_full_version < '3.14'" }, { name = "rekuest", marker = "python_full_version < '3.14'" }, + { name = "reportlab", marker = "python_full_version < '3.14'" }, { name = "requests", marker = "python_full_version < '3.14'" }, { name = "scikit-image", marker = "python_full_version < '3.14'" }, { name = "send2trash", marker = "python_full_version < '3.14'" }, @@ -1917,6 +1919,7 @@ requires-dist = [ { name = "pydantic", specifier = "==2.12.5" }, { name = "pygame-ce", marker = "extra == 'slm'", specifier = ">=2.5" }, { name = "pymmcore-plus", marker = "extra == 'pymmcore'", specifier = ">=0.10" }, + { name = "pypdf", specifier = ">=6,<7" }, { name = "pyserial", specifier = ">=3.4" }, { name = "pytest", marker = "extra == 'dev'" }, { name = "python-dateutil", specifier = ">=2.8.1" }, @@ -1924,6 +1927,7 @@ requires-dist = [ { name = "python-socketio", extras = ["asyncio"], specifier = ">=5.11,<6" }, { name = "pyvisa-py", specifier = "==0.4.1" }, { name = "rekuest", specifier = "==7.1.0" }, + { name = "reportlab", specifier = ">=4,<5" }, { name = "requests", specifier = ">=2.25" }, { name = "rpi-gpio", marker = "extra == 'lepmon'" }, { name = "scikit-image", specifier = "==0.25.2" }, @@ -4260,6 +4264,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/10/5e/1aa9a93198c6b64513c9d7752de7422c06402de6600a8767da1524f9570b/pyparsing-3.2.5-py3-none-any.whl", hash = "sha256:e38a4f02064cf41fe6593d328d0512495ad1f3d8a91c4f73fc401b3079a59a5e", size = 113890, upload-time = "2025-09-21T04:11:04.117Z" }, ] +[[package]] +name = "pypdf" +version = "6.21.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/1e/e1/ec8f4d155c997c45917153a5521e60d6ee6389d68abdcbc8e44e564caffc/pypdf-6.21.4.tar.gz", hash = "sha256:c8817e3f888d47a087872ded69812c1ef30cacb871d6e053e0c00bbaf0bc2163", size = 7109255, upload-time = "2026-10-28T17:00:54.81Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3f/4b/77e8ad4ac42c9d93600f40541a50e9feb3a61d2bbee2d76f659346072051/pypdf-6.21.4-py3-none-any.whl", hash = "sha256:33e4fb41ca352810eb4e9838aa0d82d6888a5f8bf682f43e99cce5faa666255c", size = 410430, upload-time = "2026-10-28T17:00:53.146Z" }, +] + [[package]] name = "pyreadline3" version = "3.5.4" @@ -4593,6 +4606,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/98/eb/d1f7fbf532163df65fac1d27fafa58a709467370fbb73efa848c3a00c948/rekuest-7.1.0-py3-none-any.whl", hash = "sha256:df5616fdfe8e0d089d7433a6c0fe064573583a911b032c018a3618a9af588661", size = 140638, upload-time = "2026-09-29T22:42:03.105Z" }, ] +[[package]] +name = "reportlab" +version = "4.5.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "charset-normalizer", marker = "python_full_version < '3.14'" }, + { name = "pillow", marker = "python_full_version < '3.14'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/4d/3f/b3861b7e40c9d66f4a04e018958d681d16b948bfd1963c962d43a8c23f66/reportlab-4.5.1.tar.gz", hash = "sha256:9fdf68f4de9171ec66acb4a5feed8f8ca2af43479e707a6fbb0daa75d88e5494", size = 3939748, upload-time = "2026-05-12T10:14:13.663Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a7/45/ea7fad10122440de6e845568d106bffdc456ca0e8a1d8ae10b46016087e4/reportlab-4.5.1-py3-none-any.whl", hash = "sha256:06fce8cb56c83307cfa4909cdf4e6a2ddbb44e5d6ef4d2edca896d7e9769f091", size = 1957812, upload-time = "2026-05-12T10:14:10.622Z" }, +] + [[package]] name = "requests" version = "2.32.5" From 1f2561e121457db62d25e9c98f790e9c3ea2d190 Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Mon, 16 Nov 2026 14:47:34 +0100 Subject: [PATCH 05/10] updates HIL test suite and improve documentation --- imswitch/imcontrol/_test/hil/README.md | 147 ++++---- imswitch/imcontrol/_test/hil/__main__.py | 75 ++-- imswitch/imcontrol/_test/hil/conftest.py | 49 ++- imswitch/imcontrol/_test/hil/firmware_sync.py | 10 +- imswitch/imcontrol/_test/hil/hil_client.py | 12 +- imswitch/imcontrol/_test/hil/hil_pdf.py | 332 ++++++++++++------ imswitch/imcontrol/_test/hil/hil_report.py | 213 +++++------ imswitch/imcontrol/_test/hil/pytest.ini | 4 + .../imcontrol/_test/hil/test_board_link.py | 9 +- .../_test/hil/test_camera_capture.py | 10 +- .../_test/hil/test_firmware_server.py | 9 +- .../_test/hil/test_frame_calibration.py | 160 +++++---- .../imcontrol/_test/hil/test_ledmatrix.py | 15 +- .../_test/hil/test_ledmatrix_single.py | 25 +- .../imcontrol/_test/hil/test_lightsource.py | 15 +- .../_test/hil/test_motor_axis_move.py | 79 +++++ .../_test/unit/test_hil_reporting.py | 171 +++++---- 17 files changed, 826 insertions(+), 509 deletions(-) create mode 100644 imswitch/imcontrol/_test/hil/test_motor_axis_move.py diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md index b02ef2756..53c3dccf2 100644 --- a/imswitch/imcontrol/_test/hil/README.md +++ b/imswitch/imcontrol/_test/hil/README.md @@ -1,31 +1,41 @@ # Hardware-in-the-loop (HIL) tests -Tests of a running ImSwitch on a real microscope, through its HTTP API only. They sit next to -`../unit/` (no server) and `../api/` (headless server), but never import ImSwitch: they need only -`pytest`, `requests`, `pillow`, `numpy`, `reportlab` and `pypdf`. +Tests of a running ImSwitch on a real microscope, through its HTTP API only. +They sit next to `../unit/` (no server) and `../api/` (headless server), but never import ImSwitch: they need only `pytest`, `requests`, `pillow`, `numpy`, `reportlab` and `pypdf`. -**They move the stage and switch light.** Each test file says in its first line what it does. +**They move the stage and switch light.** +Each test file says at the top of its docstring what it checks and what it does to the rig. | Test | Checks | Hardware | |---|---|---| -| `board_link` | the UC2 board is connected and runs the CANopen master firmware | reads | -| `firmware_server` | the firmware server has images; every board runs its version | reads | -| `camera_capture` | every camera returns a frame at its resolution | reads | -| `lightsource` | lasers/LEDs switch; every LED reaches the cameras | **light** | -| `ledmatrix` | the LED matrix reaches the cameras | **light** | -| `ledmatrix_single` | one LED lights alone (`setLEDs`) and is dimmer than every LED | **light** | -| `frame_calibration` | the one-button FRAME calibration runs through; needs the calibration target in the holder | **moves** (homes, turret), **light**, **writes the setup** (backup: `setup_before_frame_calibration.json`) | +| `board_link` | ImSwitch talks to the UC2 board, and the board runs the master firmware | reads | +| `firmware_server` | the firmware server has firmware files, and each board runs the server's version | reads | +| `camera_capture` | each camera takes a picture as large as its sensor | reads | +| `motor_axis_move` | each axis moves 10 µm and back; then each axis with homing switched on homes: Z, X, Y, then the turret | **moves** (10 µm, then to the end stops) | +| `lightsource` | each laser and LED switches on and off; the cameras see each LED | **light** | +| `ledmatrix` | the cameras see the LED matrix | **light** | +| `ledmatrix_single` | one LED lights on its own (`setLEDs`) and is dimmer than the whole matrix | **light** | +| `frame_calibration` | the FRAME calibration runs from start to end; needs the calibration target in the holder | **moves** (homes, turret), **light**, **writes the setup** (backup: `setup_before_frame_calibration.json`) | + +Hardware a setup does not have skips its tests. +Hardware that is there but does not work fails. + +They run in the order of the table: the boards, the cameras, the motors, the lights, then the calibration. +The stage is homed before the lights are tested, so the slide holder is out of the light path. +The order is the list `ORDER` in `conftest.py`. -Hardware a setup does not have skips its tests. Hardware that is there but does not work fails. +Some tests do not start after a failure; they are skipped and say which test failed. +The table is `NEEDS` in `conftest.py`: -They run in the order of the table: the boards, the cameras, the lights, then the calibration. -The order is the list `ORDER` in `conftest.py`. +- `frame_calibration` needs `board_link`, `camera_capture`, `motor_axis_move` and the three light tests. + It does not need `firmware_server`: a board on another firmware version fails that test, but can still be calibrated. -The calibration is the test of the motors. It homes Z, X, Y and the turret, reads the position -back after every move, follows X and Y in the observation camera, focuses with Z and switches -the objective. It is attempted even when an earlier test failed; its own preflight and busy checks -decide whether it can proceed. Earlier failures still fail the overall run. A step the calibration skips (e.g. the second objective on a rig with -one) is listed in the test's output as not tested. +`motor_axis_move` first steps every axis, then homes them, one case per axis. +When a step failed or an axis did not home, the axes after it are skipped. +The homing cannot see whether an end stop was found: `homeAxis` does not return it. +It fails when ImSwitch answers with an error or not at all. +The calibration homes again and checks every axis, reads the position back after every move, follows X and Y in the observation camera, focuses with Z and switches the objective. +A step the calibration skips (e.g. the second objective on a rig with one) is listed in the test's output as not tested. ## Run @@ -41,17 +51,27 @@ python -m imswitch.imcontrol._test.hil out --sync-firmware # FLASHES `TEST` is the name from the table: `board_link` runs `test_board_link.py`. -It waits until ImSwitch answers and its setup is readable. Camera startup errors are recorded -without preventing the tests or calibration. It then runs the tests and writes `junit.xml`, `report.html` (results, output and photos in one file) -and `summary.md` to `REPORT_DIR`. `hil-report.pdf` contains the test summary, diagnostics and -photos followed by the original PDF of this run's calibration (`calibration-report.pdf`). -A failed or unstarted calibration is explicitly identified; an older report is never substituted. A test may leave further files there; it finds the folder in -the environment variable `HIL_REPORT_DIR`. Both reports name the setup file the rig ran with. Exit code: `0` all passed, `1` a test failed, `2` the tests -could not run (not ready, firmware sync failed, unknown test, everything skipped). +It waits until ImSwitch answers and its setup is readable. +A camera that does not start is a problem in the report; the tests run anyway. +`REPORT_DIR` receives: + +| File | Holds | +|---|---| +| `hil-report.pdf` | the report to read: what was tested, one line per test, then every test with what failed, its notes, its cases and its photos, then the PDFs the tests appended (the calibration's own report) | +| `summary.md` | the setup, the counts, one line per failure and the notes of the tests, for the CI run's page | +| `setup_before_frame_calibration.json` | the setup as it was before the calibration; only when the calibration ran | + +Both reports name the setup file the rig ran with. +A test finds the folder in the environment variable `HIL_REPORT_DIR`. +Use a new folder for every run: the two reports are replaced, but a file a test saved there in an older run stays. + +While the tests run, the log shows one line per test with the number of tests done (`[12/31]`). +The calibration takes minutes and prints a line when each of its steps starts and ends (`calibration 4/10 First objective: ...`). + +Exit code: `0` all passed, `1` a test failed, `2` the tests could not run (not ready, firmware sync failed, unknown test, everything skipped, the PDF could not be written). The test rig (os-rpi, `.github/hil/`) runs exactly this command inside the ImSwitch container. -That one line is all the two repositories share, so the tests always belong to the ImSwitch -version under test. +That one line is all the two repositories share, so the tests always belong to the ImSwitch version under test. From a laptop against a rig, without ImSwitch installed: @@ -68,26 +88,27 @@ IMSWITCH_URL=http:///imswitch pytest test_camera_capture.py -s ## Files -Every `test_*.py` is one test and stands on its own: its settings are at its top, its helper -functions below them. No test imports another one. Deleting a test is deleting its file. +Every `test_*.py` is one test and stands on its own: its settings are at its top, its helper functions below them. +No test imports another one. +Deleting a test is deleting its file. What the tests share has nothing to do with what they check: | File | Holds | |---|---| | `hil_client.py` | HTTP (`get_json`, `post_json`, `wait_until`), `setup()`, `parametrize_from_rig` | -| `hil_report.py` | `attach(label, image)` and the HTML/Markdown report | -| `conftest.py` | the order of the tests (`ORDER`); runs calibration last even after failures; marks the tests `hardware`; skips everything when ImSwitch is not reachable | +| `hil_report.py` | `attach(label, image)`, `note(text)`, `append_pdf(title, data)`, the results of the run, `summary.md` | +| `hil_pdf.py` | `hil-report.pdf` | +| `conftest.py` | the order of the tests (`ORDER`); which test needs which (`NEEDS`); `live`; marks the tests `hardware`; skips everything when ImSwitch is not reachable | | `__main__.py` | the command above | | `firmware_sync.py` | `--sync-firmware` | ## Which hardware a test uses -There is no list of the rig's hardware here. The tests read it from the setup file ImSwitch -runs with: `ImSwitchConfig/imcontrol_setups/.json`, where `` is the `setupFileName` -in `ImSwitchConfig/config/imcontrol_options.json`. `client.setup_file()` returns the name, -`client.setup()` the content as a dict. ImSwitch parses the file before it answers, so a field -the file leaves out comes back with ImSwitch's default (e.g. `"forAcquisition": false`). +There is no list of the rig's hardware here. +The tests read it from the setup file ImSwitch runs with: `ImSwitchConfig/imcontrol_setups/.json`, where `` is the `setupFileName` in `ImSwitchConfig/config/imcontrol_options.json`. +`client.setup_file()` returns the name, `client.setup()` the content as a dict. +ImSwitch parses the file before it answers, so a field the file leaves out comes back with ImSwitch's default (e.g. `"forAcquisition": false`). | Setup | Used for | |---|---| @@ -101,33 +122,37 @@ So a rig with other hardware needs another setup file in ImSwitch, not other tes ## Writing a test -Copy the test that is closest to the new one, rename it `test_.py`, and change it. It -runs with the others from then on, after the tests listed in `ORDER` (`conftest.py`); add its -name there to give it another place. A test file has: +Copy the test that is closest to the new one, rename it `test_.py`, and change it. +It runs with the others from then on, after the tests listed in `ORDER` (`conftest.py`); add its name there to give it another place. +A test file has: -1. a first line saying what it checks and what it does to the rig; +1. a docstring: first a paragraph saying in plain words what it checks, then what it does to the rig (MOVES REAL HARDWARE, SWITCHES LIGHT, Only reads) and anything else worth knowing; 2. its settings, as constants; 3. its helper functions and fixtures; 4. the tests, whose steps read top to bottom. - Call ImSwitch with `client.get_json("/Controller/method", {"param": value})`. -- Take what the rig has from `client.setup()`, and thresholds, distances and timeouts from the - constants at the top of the file. -- Add a photo to the report with `attach("label", image)`. -- Whatever a test switches on or moves, it puts back, also when it fails (`try/finally`, or a - fixture with `yield`). -- Code that a second test needs is copied, not shared: a test must stay readable and removable - by itself. - -## Combined report and retained calibration - -The suite waits for the calibration thread to finish cleanup before exporting its PDF through -`getFrameCalibrationReportPdf`. It checks the run's `startedAt` before and after export. -Calibration results remain in the instrument's setup, even after os-rpi restores the deployment. -A failed calibration may have written partial changes; the setup backup is for manual recovery. -No automatic rollback is performed. Cleanup/export failures are reported as errors. - -Optional `HIL_TARGET` and `HIL_RUN_URL` identify the tested image/pallet and Actions run in the -PDF. os-rpi supplies these; laptop runs show that the target was not supplied. -ReportLab renders the test pages; pypdf appends the original calibration PDF. Full captured -output remains in HTML. A PDF generation failure preserves HTML/Markdown and fails the run. +- Take what the rig has from `client.setup()`, and thresholds, distances and timeouts from the constants at the top of the file. +- Add to the test's part of the report with `attach("label", image)` for a photo and `hil_report.note("...")` for a line of text. + `hil_report.append_pdf("title", data)` puts a whole PDF behind the pages of the tests. + The report code knows no test by name. +- The first paragraph of the docstring is what the report shows under "What it checks" (`hil_report.py`). + Write it as you would say it to a colleague. +- A test that runs for minutes takes the fixture `live` and prints its progress with `live("step 4/10 ...")`; a plain `print` only shows when the test fails. +- Whatever a test switches on or moves, it puts back, also when it fails (`try/finally`, or a fixture with `yield`). +- Code that a second test needs is copied, not shared: a test must stay readable and removable by itself. + +## The calibration in the report + +The test waits until the calibration's thread has ended, then fetches its PDF with `getFrameCalibrationReportPdf` and checks the run's `startedAt` before and after, so the report of another run is never taken. +The PDF is appended to `hil-report.pdf` as ImSwitch wrote it (`hil_report.append_pdf`). +When it cannot be fetched, the `frame_calibration` part of the report shows that as an error. + +The fixtures of `test_frame_calibration.py` put the rig back, each on its own: the calibration is stopped, the light goes off (the calibration leaves it on), the settings go back, and then the report is collected. + +The calibration's result stays in the instrument's setup, also after os-rpi has restored the deployment. +A calibration that fails may have written a part of it; `setup_before_frame_calibration.json` is there to go back by hand. +Nothing is rolled back automatically. + +os-rpi passes three environment variables that the report shows: `HIL_TARGET` (the image or pallet under test), `HIL_PALLET` (the pallet and every image in it) and `HIL_RUN_URL` (the Actions run). +A run from a laptop has none of them. diff --git a/imswitch/imcontrol/_test/hil/__main__.py b/imswitch/imcontrol/_test/hil/__main__.py index 930354683..0a91c01bb 100644 --- a/imswitch/imcontrol/_test/hil/__main__.py +++ b/imswitch/imcontrol/_test/hil/__main__.py @@ -8,8 +8,10 @@ TEST is the name of a test file without "test_" and ".py": board_link is test_board_link.py. Without TEST every test runs, which MOVES THE STAGE AND SWITCHES LIGHT. -REPORT_DIR receives junit.xml, report.html and summary.md; both reports name the ImSwitch -setup file (ImSwitchConfig/imcontrol_setups/.json) the rig ran with. +REPORT_DIR receives hil-report.pdf and summary.md; +both name the ImSwitch setup file (ImSwitchConfig/imcontrol_setups/.json) the rig ran with. +Use a new folder for every run: only these two files are replaced, +a file a test saved there in an older run stays. Exit code: 0 all passed, 1 a test failed, 2 the tests could not run. The test rig (os-rpi) runs exactly this command inside the ImSwitch container. @@ -41,25 +43,24 @@ def can_snap(detector, for_acquisition): if for_acquisition: return client.get("/RecordingController/snapNumpyToFastAPI", params={ "detectorName": detector, "resizeFactor": 0.1}).status_code == 200 - # 400: no observation camera is connected. Waiting does not change that, and the - # tests that need it skip. + # 400: no observation camera is connected. + # Waiting does not change that, and the tests that need it skip. return client.post("/ExperimentController/snapOverviewImage", timeout=30, params={ "slot_id": "1", "camera_name": "hil_ready_check"}).status_code in (200, 400) except requests.RequestException: return False -def why_not_ready(): - """Wait for ImSwitch and a readable setup. Returns None, or what is missing.""" - if not client.wait_until(client.reachable, READY_API_TIMEOUT, interval=5): - return f"ImSwitch did not answer at {client.IMSWITCH_URL} within {READY_API_TIMEOUT}s" - client.setup() # A readable setup is needed to collect the tests. - return None +def wait_for_imswitch(): + """Wait until ImSwitch answers and its setup can be read; the tests are collected from it.""" + assert client.wait_until(client.reachable, READY_API_TIMEOUT, interval=5), ( + f"ImSwitch did not answer at {client.IMSWITCH_URL} within {READY_API_TIMEOUT}s") + client.setup() def prepare_cameras(): - """Give cameras time to start; record failures without blocking calibration.""" - problems = [] + """Give the cameras time to start. Returns {camera: what went wrong}, empty when all run.""" + problems = {} for name, detector in client.setup()["detectors"].items(): try: acquisition = detector["forAcquisition"] @@ -70,14 +71,21 @@ def prepare_cameras(): assert client.wait_until(lambda: can_snap(name, acquisition), READY_DETECTOR_TIMEOUT, interval=5), "no frame before timeout" except (requests.RequestException, AssertionError) as error: - problems.append(f"{name}: {error}") + problems[name] = str(error) return problems +def give_up(report_dir, problem): + """Write a report that only says why the tests did not run.""" + print(f"[hil] not running the tests: {problem}") + hil_report.record_problem("startup", problem) + hil_report.write_reports(report_dir, "unavailable") + return COULD_NOT_RUN + def main(): parser = argparse.ArgumentParser(prog="python -m imswitch.imcontrol._test.hil") - parser.add_argument("report_dir", help="folder for junit.xml, report.html and summary.md") + parser.add_argument("report_dir", help="folder for hil-report.pdf and summary.md") parser.add_argument("tests", nargs="*", help="tests, e.g. board_link camera_capture; default all") parser.add_argument("--sync-firmware", action="store_true", @@ -88,50 +96,43 @@ def main(): report_dir.mkdir(parents=True, exist_ok=True) os.environ["HIL_REPORT_DIR"] = str(report_dir.resolve()) hil_report.reset() - # A reused local report directory must not expose artifacts from an older run. - for name in ("hil-report.pdf", "test-report.pdf", "calibration-report.pdf", - "calibration-status.json", "setup_before_frame_calibration.json", "report-error.txt", - "report.html", "summary.md", "junit.xml"): + # A run that dies must not leave the report of an older run behind. + for name in ("hil-report.pdf", "summary.md"): (report_dir / name).unlink(missing_ok=True) + # The rig (os-rpi) passes the pallet and images it swapped in; a laptop run has none. + if os.environ.get("HIL_PALLET"): + print(f"[hil] pallet under test:\n{os.environ['HIL_PALLET']}", flush=True) files = [HERE / f"test_{name}.py" for name in args.tests] unknown = [name for name, file in zip(args.tests, files) if not file.is_file()] if unknown: known = " ".join(sorted(file.stem[len("test_"):] for file in HERE.glob("test_*.py"))) - problem = f"no such test: {' '.join(unknown)}. There are: {known}" - hil_report.record_problem("startup", problem) - hil_report.write_reports(report_dir, "unavailable") - return COULD_NOT_RUN + return give_up(report_dir, f"no such test: {' '.join(unknown)}. There are: {known}") try: - problem = why_not_ready() - if problem is None: - print(f"[hil] setup: {client.setup_file()}", flush=True) - if problem is None and args.sync_firmware: + wait_for_imswitch() + print(f"[hil] setup: {client.setup_file()}", flush=True) + if args.sync_firmware: firmware_sync.sync() except (requests.RequestException, AssertionError, firmware_sync.SyncFailed) as error: - problem = str(error) - if problem: - print(f"[hil] not running the tests: {problem}") - hil_report.record_problem("startup", problem) - hil_report.write_reports(report_dir, "unavailable") - return COULD_NOT_RUN + return give_up(report_dir, str(error)) - for problem in prepare_cameras(): - hil_report.record_problem(f"camera preparation: {problem.split(':', 1)[0]}", problem) + # A camera that does not start is a problem in the report; the tests run anyway. + for name, error in prepare_cameras().items(): + hil_report.record_problem(f"camera preparation: {name}", error) code = pytest.main( [*[str(file) for file in files or [HERE]], - "-c", str(HERE / "pytest.ini"), "-ra", f"--junitxml={report_dir / 'junit.xml'}"], + "-c", str(HERE / "pytest.ini"), "-ra"], plugins=[hil_report.ReportPlugin(report_dir, client.setup_file())]) counts = hil_report.counts() print("[hil] " + " · ".join(f"{n} {status}" for status, n in counts.items())) if hil_report.report_error: return COULD_NOT_RUN - if code == pytest.ExitCode.TESTS_FAILED or counts["failed"] or counts["error"]: + if counts["failed"] or counts["error"]: return FAILED if code != pytest.ExitCode.OK: - return COULD_NOT_RUN + return COULD_NOT_RUN # e.g. a test file that does not import if not counts["passed"]: print("[hil] every test skipped: nothing on this rig was actually tested") return COULD_NOT_RUN diff --git a/imswitch/imcontrol/_test/hil/conftest.py b/imswitch/imcontrol/_test/hil/conftest.py index 393d99644..3bfef8805 100644 --- a/imswitch/imcontrol/_test/hil/conftest.py +++ b/imswitch/imcontrol/_test/hil/conftest.py @@ -12,9 +12,20 @@ ORDER = [ "board_link", "firmware_server", # 1. the boards and their firmware versions "camera_capture", # 2. the cameras - "lightsource", "ledmatrix", "ledmatrix_single", # 3. the lights - "frame_calibration", # 4. the calibration: moves every motor + "motor_axis_move", # 3. the motors, then homing: the stage is + # out of the light path for the tests below + "lightsource", "ledmatrix", "ledmatrix_single", # 4. the lights + "frame_calibration", # 5. the calibration ] +# A test does not start when one of these failed before it. firmware_server is in no list: +# a board on another firmware version fails that test, but can still move and be calibrated. +NEEDS = { + "frame_calibration": ["board_link", "motor_axis_move", "camera_capture", + "lightsource", "ledmatrix", "ledmatrix_single"], +} + +_failed = [] # the names of the tests that failed so far in this run + def name_of(item_or_report): """ "board_link" for a test of test_board_link.py.""" @@ -28,15 +39,45 @@ def pytest_collection_modifyitems(items): The mark lets ``pytest -m "not hardware"`` leave the suite out. """ # The sort keeps the order of the tests inside a file. - items.sort(key=lambda item: (name_of(item) == "frame_calibration", - ORDER.index(name_of(item)) if name_of(item) in ORDER else len(ORDER))) + items.sort(key=lambda item: ORDER.index(name_of(item)) if name_of(item) in ORDER + else len(ORDER)) for item in items: if Path(__file__).parent in Path(item.fspath).parents: item.add_marker(pytest.mark.hardware) +def pytest_runtest_logreport(report): + """Called with every test's result: remember the tests that failed.""" + if report.failed: + _failed.append(name_of(report)) + + +def pytest_runtest_setup(item): + """Called before a test and its fixtures start: skip it when a test it needs failed.""" + failed = [name for name in NEEDS.get(name_of(item), []) if name in _failed] + if failed: + pytest.skip(f"not started, because {failed[0]} failed") + + @pytest.fixture(scope="session", autouse=True) def imswitch_reachable(): """Without a server the whole suite skips.""" if not client.reachable(): pytest.skip(f"ImSwitch not reachable at {client.IMSWITCH_URL}") + + +@pytest.fixture(scope="session") +def live(request): + """``live("step 4/10 ...")`` prints a line at once, for a test that runs for minutes. + + pytest keeps what a test prints and shows it only when the test fails. + This switches that off for the one line. + """ + capture = request.config.pluginmanager.getplugin("capturemanager") + reporter = request.config.pluginmanager.getplugin("terminalreporter") + + def show(text): + with capture.global_and_fixture_disabled(): + reporter.ensure_newline() # pytest has written the test's name without a line end + reporter.write_line(text) + return show diff --git a/imswitch/imcontrol/_test/hil/firmware_sync.py b/imswitch/imcontrol/_test/hil/firmware_sync.py index 68735714b..f93c37b36 100644 --- a/imswitch/imcontrol/_test/hil/firmware_sync.py +++ b/imswitch/imcontrol/_test/hil/firmware_sync.py @@ -1,8 +1,10 @@ -"""Bring every board to the firmware server's version. FLASHES FIRMWARE. +"""Bring every board to the firmware server's version. -A sync, not an update: a board with a newer developer build is flashed back as well. The -flashing itself is ImSwitch's own firmware update (startFirmwareUpdate), which checks every -image and counts a board as done only when it reports the new version. +FLASHES FIRMWARE. + +A sync, not an update: a board with a newer developer build is flashed back as well. +The flashing itself is ImSwitch's own firmware update (startFirmwareUpdate), +which checks every image and counts a board as done only when it reports the new version. """ import time diff --git a/imswitch/imcontrol/_test/hil/hil_client.py b/imswitch/imcontrol/_test/hil/hil_client.py index d55b7be1c..d4dc12e44 100644 --- a/imswitch/imcontrol/_test/hil/hil_client.py +++ b/imswitch/imcontrol/_test/hil/hil_client.py @@ -68,10 +68,10 @@ def setup_file(): def setup(): """The content of setup_file(), as a dict. - ImSwitch parses the file before it answers, so a field the file leaves out comes back with - ImSwitch's default (e.g. "forAcquisition": false). The sections the tests use are - "detectors", "lasers", "LEDMatrixs", "positioners" and "objective". A section the rig does - not have is empty or None. + ImSwitch parses the file before it answers. + So a field the file leaves out comes back with ImSwitch's default ("forAcquisition": false). + The tests use "detectors", "lasers", "LEDMatrixs", "positioners" and "objective". + A section the rig does not have is empty or None. """ return get_json("/UC2ConfigController/readSetupFile", {"setupFileName": setup_file()}) @@ -89,8 +89,8 @@ def wait_until(check, timeout, interval=0.1): def parametrize_from_rig(argnames, fetch, reason): """``pytest.mark.parametrize(argnames, fetch())`` for values the rig reports, e.g. its axes. - pytest reads the values while it collects the tests, where an error would stop the whole - run. So without a server, or with nothing to test, the test is skipped with ``reason``. + pytest reads the values while it collects the tests, where an error would stop the whole run. + So without a server, or with nothing to test, the test is skipped with ``reason``. """ try: values = fetch() diff --git a/imswitch/imcontrol/_test/hil/hil_pdf.py b/imswitch/imcontrol/_test/hil/hil_pdf.py index 2ae128aeb..8416e9159 100644 --- a/imswitch/imcontrol/_test/hil/hil_pdf.py +++ b/imswitch/imcontrol/_test/hil/hil_pdf.py @@ -1,111 +1,245 @@ -"""Printable HIL results followed by the server's original calibration PDF.""" -import base64 +"""hil-report.pdf: the results of the run, then the PDFs the tests appended. + +The first pages are drawn here with ReportLab. +They show what was tested and one line per test file. +Then comes each test file with what failed, its notes, its cases and its photos. +pypdf appends the PDFs of ``hil_report.append_pdf`` as they are. +""" import io import os -from datetime import datetime, timezone +import time from xml.sax.saxutils import escape from pypdf import PdfReader, PdfWriter from reportlab.lib import colors from reportlab.lib.pagesizes import A4 -from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet +from reportlab.lib.styles import ParagraphStyle from reportlab.lib.utils import ImageReader from reportlab.platypus import ( - SimpleDocTemplate, Paragraph, Spacer, Table, TableStyle, Image, PageBreak, KeepTogether, + Flowable, Image, Indenter, KeepTogether, Paragraph, SimpleDocTemplate, Spacer, Table, + TableStyle, ) +from reportlab.platypus.doctemplate import LayoutError + +MARGIN = 42 +PADDING = 6 # points ReportLab's page frame keeps free inside the margins, on each side +WIDTH = A4[0] - 2 * (MARGIN + PADDING) # of the text +INDENT = 14 # of a test's part under its heading +INK = colors.HexColor("#24515e") # the headings +HEAD_ROW = colors.HexColor("#ececec") # behind the column names of a table +COLOUR = {"passed": colors.HexColor("#2e9c3f"), "failed": colors.HexColor("#d0312d"), + "error": colors.HexColor("#d0312d"), "skipped": colors.HexColor("#8a8a8a")} +OUTPUT_LINES = 12 # of a failure's traceback that go into the report +PHOTO_HEIGHT = 285 # points; a photo is scaled down to this + +BODY = ParagraphStyle("body", fontName="Times-Roman", fontSize=9, leading=11.5, + splitLongWords=True) +LABEL = ParagraphStyle("label", parent=BODY, fontName="Times-Bold") +CELLS = TableStyle([("VALIGN", (0, 0), (-1, -1), "TOP"), + ("LEFTPADDING", (0, 0), (-1, -1), 0), + ("TOPPADDING", (0, 0), (-1, -1), 1.5), + ("BOTTOMPADDING", (0, 0), (-1, -1), 1.5)]) + + +def draw_verdict(canvas, x, y, radius, status): + """A small square with round corners at (x, y): green with a tick, red with a cross, + grey with a dash.""" + canvas.setFillColor(COLOUR[status]) + canvas.roundRect(x - radius, y - radius, 2 * radius, 2 * radius, radius * 0.35, + stroke=0, fill=1) + canvas.setStrokeColor(colors.white) + canvas.setLineWidth(radius * 0.3) + d = radius * 0.45 + if status == "passed": + canvas.line(x - d, y, x - d * 0.3, y - d) + canvas.line(x - d * 0.3, y - d, x + d, y + d) + elif status == "skipped": + canvas.line(x - d, y, x + d, y) + else: + canvas.line(x - d, y - d, x + d, y + d) + canvas.line(x - d, y + d, x + d, y - d) + + +class Verdict(Flowable): + """The sign of draw_verdict, to put into a table.""" + + def __init__(self, status, size=9): + super().__init__() + self.status, self.size = status, size + + def wrap(self, available_width, available_height): + return self.size, self.size + + def draw(self): + draw_verdict(self.canv, self.size / 2, self.size / 2, self.size / 2, self.status) + + +class Heading(Flowable): + """A title on a thin line; with ``status``, its sign in front.""" + + def __init__(self, text, size, status=None): + super().__init__() + self.text, self.size, self.status = text, size, status + self.keepWithNext = True + self.spaceBefore, self.spaceAfter = size, 4 + + def wrap(self, available_width, available_height): + self.width = available_width + return available_width, self.size + 7 + + def draw(self): + x = 0 + if self.status: + radius = self.size * 0.5 + draw_verdict(self.canv, radius, 5 + self.size * 0.35, radius, self.status) + x = self.size + 5 + self.canv.setFillColor(INK) + self.canv.setFont("Helvetica-Bold", self.size) + self.canv.drawString(x, 5, self.text) + self.canv.setStrokeColor(INK) + self.canv.setLineWidth(0.5) + self.canv.line(0, 0, self.width, 0) + + +def text(value, style=BODY): + return Paragraph(escape(str(value)).replace("\n", "
"), style) + + +def rows(pairs, width): + """A table of (label, value): the label bold on the left, as in the head of the report.""" + table = Table([[text(label, LABEL), value if isinstance(value, Flowable) else text(value)] + for label, value in pairs], colWidths=[90, width - 90], hAlign="LEFT") + table.setStyle(CELLS) + return table + + +def grid(head, body, widths): + """A table with a line of column names, in bold on light grey.""" + table = Table([[text(name, LABEL) for name in head]] + body, colWidths=widths, repeatRows=1, + hAlign="LEFT") + table.setStyle(CELLS) + table.setStyle(TableStyle([("BACKGROUND", (0, 0), (-1, 0), HEAD_ROW), + ("LEFTPADDING", (0, 0), (0, -1), 3)])) + return table + + +def verdict_of(statuses): + """One status for several: failed when one failed, passed when one ran, else skipped.""" + if "failed" in statuses or "error" in statuses: + return "failed" + return "passed" if "passed" in statuses else "skipped" + + +def by_file(results): + """``{"test_board_link.py": {"test_uc2_board_connected": result, ...}, ...}``, in run order. + + A problem outside the tests (``hil_report.record_problem``) is an entry without cases. + """ + files = {} + for test, result in results.items(): + file, _, case = test.partition("::") + files.setdefault(file, {})[case] = result + return files + + +def failure_lines(details): + """The lines of a pytest traceback that say what went wrong: its "E ..." lines.""" + lines = details.strip().splitlines() + errors = [line[1:].strip() for line in lines if line.startswith("E ")] + return (errors or lines)[-OUTPUT_LINES:] + + +def name_of(file): + """ "board_link" for "test_board_link.py"; a problem outside the tests keeps its name.""" + return file[len("test_"):-len(".py")] if file.endswith(".py") else file + + +def test_part(number, file, cases, description, notes, photos): + """The flowables of one test file: its heading, what it checks, output, cases and photos.""" + name = name_of(file) + width = WIDTH - INDENT + output = [] + for case, result in cases.items(): + if result["status"] in ("failed", "error"): + output.append(f"{case or name} {result['status']}:") + output.extend(failure_lines(result["details"])) + elif result["status"] == "skipped": + output.append(f"{case} skipped: {result['details']}") + output.extend(notes) + pairs = [("What it checks", description)] if description else [] + if output: + pairs.append(("Output", "\n".join(output))) + part = [Heading(f"{number}. {name}", 11, verdict_of([r["status"] for r in cases.values()])), + Indenter(left=INDENT), rows(pairs, width)] + if any(cases): + body = [[text(case), text(result["status"]), text(f"{result['duration']:.1f} s")] + for case, result in cases.items()] + part += [Spacer(1, 4), text("Cases", LABEL), + grid(["Case", "Result", "Time"], body, [width - 130, 70, 60])] + for case in cases: + for label, png in photos.get(f"{file}::{case}", []): + image_width, image_height = ImageReader(io.BytesIO(png)).getSize() + scale = min(width / image_width, PHOTO_HEIGHT / image_height) + part.append(KeepTogether([Spacer(1, 6), text(label), Image( + io.BytesIO(png), width=image_width * scale, height=image_height * scale, + hAlign="LEFT")])) + return part + [Indenter(left=-INDENT)] + + +def test_pages(setup, started, results, descriptions, photos, notes): + """The pages drawn here, as the bytes of a PDF.""" + files = by_file(results) + statuses = [result["status"] for result in results.values()] + counted = ", ".join(f"{statuses.count(status)} {status}" + for status in ("passed", "failed", "error", "skipped") + if status in statuses) + head = [("Started", time.strftime("%Y-%m-%d %H:%M UTC", time.gmtime(started))), + ("Duration", f"{(time.time() - started) / 60:.0f} min"), + ("Result", counted or "no test ran"), + ("Tested target", os.environ.get("HIL_TARGET")), + ("Run", os.environ.get("HIL_RUN_URL")), + ("Pallet", os.environ.get("HIL_PALLET"))] + summary = [] + for number, (file, cases) in enumerate(files.items(), 1): + summary.append([text(number), Verdict(verdict_of([r["status"] for r in cases.values()])), + text(name_of(file)), text(descriptions.get(file, "")), + text(f"{sum(r['duration'] for r in cases.values()):.0f} s")]) + story = [Heading(f"Hardware test: {setup}", 14, verdict_of(statuses)), + rows([pair for pair in head if pair[1]], WIDTH), + Spacer(1, 6), text("Summary", LABEL), + grid(["No.", "Result", "Test", "What it checks", "Time"], summary, + [28, 42, 100, WIDTH - 215, 45]), + Heading("Tests", 13)] + for number, (file, cases) in enumerate(files.items(), 1): + story += test_part(number, file, cases, descriptions.get(file, ""), + notes.get(file, []), photos) + + def page_number(canvas, document): + canvas.setFont("Times-Roman", 8) + canvas.drawRightString(A4[0] - MARGIN, 24, str(document.page)) + + pages = io.BytesIO() + SimpleDocTemplate(pages, pagesize=A4, leftMargin=MARGIN, rightMargin=MARGIN, topMargin=MARGIN, + bottomMargin=MARGIN, title=f"Hardware test: {setup}").build( + story, onFirstPage=page_number, onLaterPages=page_number) + return pages.getvalue() + + +def write_pdf(target, setup, started, results, descriptions, photos, notes, appended): + """Write the report to the file ``target``. -INK = colors.HexColor("#16324f") -MUTED = colors.HexColor("#526579") -STATUS = {"passed": "#187448", "failed": "#b42332", "error": "#a34a12", "skipped": "#526579"} - - -def write_pdf(folder, setup, results, photos, calibration, started): - """Only an explicitly collected, current-run PDF may be appended.""" - styles = getSampleStyleSheet() - styles.add(ParagraphStyle("TitleHIL", fontName="Helvetica-Bold", fontSize=25, - leading=30, textColor=INK, spaceAfter=15)) - styles.add(ParagraphStyle("SectionHIL", fontName="Helvetica-Bold", fontSize=15, - leading=20, textColor=INK, spaceBefore=14, spaceAfter=9, - keepWithNext=True)) - styles.add(ParagraphStyle("BodyHIL", fontSize=9, leading=13, textColor=INK, - spaceAfter=7, splitLongWords=True)) - styles.add(ParagraphStyle("SmallHIL", parent=styles["BodyHIL"], fontSize=8, - leading=11, textColor=MUTED)) - - def p(text, style="BodyHIL"): - return Paragraph(escape(str(text)).replace("\n", "
"), styles[style]) - - def footer(canvas, doc): - canvas.setStrokeColor(colors.HexColor("#dce4ec")) - canvas.line(42, 37, A4[0] - 42, 37) - canvas.setFont("Helvetica", 8) - canvas.setFillColor(MUTED) - canvas.drawString(42, 24, "openUC2 | Hardware tests and FRAME calibration") - canvas.drawRightString(A4[0] - 42, 24, f"Tests / {doc.page}") - - story = [p("Hardware tests\n& FRAME calibration", "TitleHIL")] - totals = {state: sum(r["status"] == state for r in results.values()) for state in STATUS} - outcome = "FAILED" if totals["failed"] or totals["error"] else "PASSED" if totals["passed"] else "NOT RUN" - story += [p(f"TEST RESULT: {outcome}", "SectionHIL"), - p(" | ".join(f"{n} {state}" for state, n in totals.items()))] - metadata = [("Started (UTC)", datetime.fromtimestamp(started, timezone.utc).isoformat(timespec="seconds")), - ("Setup", setup), ("Tested target", os.environ.get("HIL_TARGET", "Not supplied")), - ("Run", os.environ.get("HIL_RUN_URL", "Local run")), - ("Calibration", calibration.get("state", "not started"))] - table = Table([[p(k, "SmallHIL"), p(v)] for k, v in metadata], colWidths=[100, A4[0] - 184]) - table.setStyle(TableStyle([("VALIGN", (0, 0), (-1, -1), "TOP"), - ("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#f0f4f8")), - ("LEFTPADDING", (0, 0), (-1, -1), 9), - ("TOPPADDING", (0, 0), (-1, -1), 6)])) - story += [table, Spacer(1, 12), p("Calibration results are retained on the instrument. " - "Deployment restoration does not roll back the setup. A failed calibration may have written partial changes."), - p("The pre-calibration setup backup and full diagnostic output are included in the report artifacts.", "SmallHIL"), - p("Test overview", "SectionHIL")] - rows = [[p("Test", "SmallHIL"), p("Result", "SmallHIL"), p("Time", "SmallHIL")]] - for name, r in results.items(): - rows.append([p(name, "SmallHIL"), Paragraph(f'{r["status"].upper()}', styles["SmallHIL"]), p(f"{r['duration']:.1f}s", "SmallHIL")]) - table = Table(rows, colWidths=[A4[0] - 220, 80, 56], repeatRows=1, hAlign="LEFT") - table.setStyle(TableStyle([("VALIGN", (0, 0), (-1, -1), "TOP"), - ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#e2ebf3")), - ("LINEBELOW", (0, 0), (-1, -1), .3, colors.HexColor("#dce4ec")), - ("TOPPADDING", (0, 0), (-1, -1), 7), - ("BOTTOMPADDING", (0, 0), (-1, -1), 7)])) - story.append(table) - if results: - story.append(PageBreak()) - for name, r in results.items(): - story += [p(name, "SectionHIL"), p(f"{r['status'].upper()} | {r['duration']:.1f} seconds")] - if r["details"]: - # Individual paragraphs let even a very long traceback paginate. - story.extend(p(line, "SmallHIL") for line in r["details"].splitlines()) - # The calibration PDF contains its full-size figures; do not duplicate them here. - if "test_frame_calibration.py" not in name: - for label, data in photos.get(name, []): - raw = io.BytesIO(base64.b64decode(data)) - width, height = ImageReader(raw).getSize() - scale = min((A4[0] - 84) / width, 285 / height) - story += [KeepTogether([p(label), Image(raw, width=width * scale, height=height * scale)]), Spacer(1, 12)] - if not calibration.get("pdf") or calibration.get("error"): - story += [PageBreak(), p("FRAME calibration", "TitleHIL"), - p(f"State: {calibration.get('state', 'not started')}", "SectionHIL"), - p(calibration.get("message", "Calibration was not selected or could not start. See test results."))] - if calibration.get("error"): - story += [p("Calibration / report collection error", "SectionHIL"), p(calibration["error"])] - if not calibration.get("pdf"): - story.append(p("No calibration PDF from this run is available. No historical report has been substituted.")) - front = folder / "test-report.pdf" - SimpleDocTemplate(str(front), pagesize=A4, rightMargin=42, leftMargin=42, - topMargin=42, bottomMargin=50, title="Hardware tests and FRAME calibration").build( - story, onFirstPage=footer, onLaterPages=footer) + ``appended`` holds the (title, PDF bytes) the tests gave to ``hil_report.append_pdf``. + """ + try: + pages = test_pages(setup, started, results, descriptions, photos, notes) + except LayoutError as error: + raise ValueError(f"the report does not fit on its pages: {error}") from error with PdfWriter() as writer: - writer.append(str(front), outline_item="Hardware tests") - if calibration.get("pdf"): - reader = PdfReader(calibration["pdf"]) - if not len(reader.pages): - raise ValueError("Calibration PDF contains no pages") - writer.append(reader, outline_item="FRAME calibration (original report)") - writer.add_metadata({"/Title": "Hardware tests and FRAME calibration", "/Author": "openUC2"}) - target = folder / "hil-report.pdf" - temporary = folder / "hil-report.pending.pdf" - writer.write(str(temporary)) - temporary.replace(target) + writer.append(io.BytesIO(pages), outline_item="Hardware tests") + for title, data in appended: + writer.append(PdfReader(io.BytesIO(data)), outline_item=title) + writer.add_metadata({"/Title": f"Hardware test: {setup}", "/Author": "openUC2"}) + # Written under another name first, so a run that dies here leaves no half report. + pending = target.with_suffix(".pending") + writer.write(str(pending)) + pending.replace(target) diff --git a/imswitch/imcontrol/_test/hil/hil_report.py b/imswitch/imcontrol/_test/hil/hil_report.py index 3a21284ed..0ee8f6844 100644 --- a/imswitch/imcontrol/_test/hil/hil_report.py +++ b/imswitch/imcontrol/_test/hil/hil_report.py @@ -1,11 +1,15 @@ -"""The report of a run: report.html (results, output and photos in one file) and summary.md. +"""The report of a run: hil-report.pdf (results, photos, PDFs of the tests) and summary.md. -A test adds a photo with ``attach("dark", image)``. ``__main__.py`` passes ``ReportPlugin`` to -pytest, which collects every result and writes the two files at the end. Under plain pytest -nothing is written. +A test adds to its part of the report with: + + attach("dark", image) a photo + note("The calibration ended as ...") a line of text + append_pdf("FRAME calibration", data) a whole PDF, after the pages of the tests + +``__main__.py`` passes ``ReportPlugin`` to pytest, +which collects every result and writes the two files at the end. +Under plain pytest nothing is written. """ -import base64 -import html import io import os import time @@ -15,54 +19,37 @@ from PIL import Image PHOTO_WIDTH = 640 # photos are scaled down to this, so a report with dozens of them stays small -STATUSES = ["failed", "error", "skipped", "passed"] # the order in the report +STATUSES = ["failed", "error", "skipped", "passed"] # the order in the summary _started = time.time() -_photos = {} # test id -> [(label, base64 PNG)] -_results = {} # test id -> {"status", "duration", "details", "output"} - -calibration = {} -report_error = None +_results = {} # test id -> {"status", "duration", "details"} +_descriptions = {} # test file -> the first paragraph of its docstring: what it checks +_photos = {} # test id -> [(label, PNG bytes)] +_notes = {} # test file -> [lines of text] +_appended = [] # [(title, PDF bytes)] +report_error = None # why hil-report.pdf could not be written def reset(): global _started, report_error _started = time.time() report_error = None - _photos.clear() _results.clear() - calibration.clear() - - -def record_problem(name, message): - _results[name] = {"status": "error", "duration": 0.0, "details": str(message), "output": ""} + _descriptions.clear() + _photos.clear() + _notes.clear() + _appended.clear() -def write_reports(report_dir, setup_file): - global report_error - report_dir.mkdir(parents=True, exist_ok=True) - if not calibration: - skipped = [r["details"] for name, r in _results.items() - if "test_frame_calibration.py" in name and r["details"]] - calibration.update(state="not started", message="; ".join(skipped) or - "Calibration was not selected or the suite could not start.") - (report_dir / "hil-report.pdf").unlink(missing_ok=True) - (report_dir / "report-error.txt").unlink(missing_ok=True) - try: - from hil_pdf import write_pdf - write_pdf(report_dir, setup_file, _results, _photos, calibration, _started) - except Exception as error: - report_error = str(error) - record_problem("PDF generation", report_error) - (report_dir / "report-error.txt").write_text(report_error, encoding="utf-8") - print(f"[hil] PDF generation failed: {error}", flush=True) - (report_dir / "summary.md").write_text(summary(setup_file), encoding="utf-8") - (report_dir / "report.html").write_text(page(setup_file), encoding="utf-8") +def current_test(): + """The id of the test that runs now, "test_x.py::test_y[cam]"; None outside pytest.""" + test = os.environ.get("PYTEST_CURRENT_TEST") # "test_x.py::test_y[cam] (call)" + return test.rsplit(" (", 1)[0] if test else None def attach(label, image): """Add a photo to the test that is running. ``image`` is a PIL image or a numpy array.""" - test = os.environ.get("PYTEST_CURRENT_TEST") # "camera/test_x.py::test_y[cam] (call)" + test = current_test() if not test: return if isinstance(image, np.ndarray): @@ -73,8 +60,24 @@ def attach(label, image): image = image.resize((PHOTO_WIDTH, round(image.height * PHOTO_WIDTH / image.width))) buffer = io.BytesIO() image.save(buffer, format="PNG", optimize=True) - photo = base64.b64encode(buffer.getvalue()).decode("ascii") - _photos.setdefault(test.rsplit(" (", 1)[0], []).append((str(label), photo)) + _photos.setdefault(test, []).append((str(label), buffer.getvalue())) + + +def note(text): + """Add a line of text to the part of the test file that is running.""" + test = current_test() + if test: + _notes.setdefault(test.split("::")[0], []).append(str(text)) + + +def append_pdf(title, data): + """Append a PDF (its bytes) to the report, after the pages of the tests.""" + _appended.append((str(title), data)) + + +def record_problem(name, message): + """Add a problem outside the tests to the results, e.g. a camera that did not start.""" + _results[name] = {"status": "error", "duration": 0.0, "details": str(message)} def counts(): @@ -83,6 +86,36 @@ def counts(): return {status: statuses.count(status) for status in STATUSES} +def summary(setup_file): + """Markdown, short enough for a CI step summary: the setup, the counts, one line per failure.""" + totals = " · ".join(f"{n} {status}" for status, n in counts().items()) + lines = ["### HIL report", "", f"setup `{setup_file}`", "", totals, "", + "Report: `hil-report.pdf` in the artifact `hil-report`.", ""] + for test, result in _results.items(): + if result["status"] in ("failed", "error"): + last_line = (result["details"].strip().splitlines() or [""])[-1] + lines.append(f"- **{result['status']}** `{test}`: {last_line[:300]}") + for file, notes in _notes.items(): + for text in notes: + lines.append(f"- `{file}`: {text}") + return "\n".join(lines) + "\n" + + +def write_reports(report_dir, setup_file): + """Write hil-report.pdf and summary.md. A PDF that fails is a problem in the summary.""" + global report_error + try: + # Imported here, so that a missing ReportLab also ends as a problem in the summary. + from hil_pdf import write_pdf + write_pdf(report_dir / "hil-report.pdf", setup_file, _started, _results, _descriptions, + _photos, _notes, _appended) + except Exception as error: + report_error = str(error) + record_problem("PDF generation", report_error) + print(f"[hil] PDF generation failed: {error}", flush=True) + (report_dir / "summary.md").write_text(summary(setup_file), encoding="utf-8") + + class ReportPlugin: """Collects the results while pytest runs and writes the report files into ``report_dir``. @@ -93,12 +126,20 @@ def __init__(self, report_dir, setup_file): self.report_dir = Path(report_dir) self.setup_file = setup_file + def pytest_itemcollected(self, item): + """Called for every test pytest finds: keep what its file says it checks. + + That is the first paragraph of the file's docstring, its lines joined into one. + """ + file = item.nodeid.split("::")[0] + first_paragraph = (item.module.__doc__ or "").strip().split("\n\n")[0] + _descriptions[file] = " ".join(first_paragraph.split()) + def pytest_runtest_logreport(self, report): """Called three times per test: for its setup, the test itself (call) and its teardown.""" result = _results.setdefault(report.nodeid, { - "status": "passed", "duration": 0.0, "details": "", "output": ""}) + "status": "passed", "duration": 0.0, "details": ""}) result["duration"] += report.duration - result["output"] = report.capstdout or result["output"] if report.failed and result["status"] != "failed": # A failure outside the test itself is a broken fixture, not a failed assertion. result["status"] = "failed" if report.when == "call" else "error" @@ -109,89 +150,3 @@ def pytest_runtest_logreport(self, report): def pytest_sessionfinish(self): write_reports(self.report_dir, self.setup_file) - - -def summary(setup_file): - """Markdown, short enough for a CI step summary: the setup, the counts, one line per failure.""" - totals = " · ".join(f"{n} {status}" for status, n in counts().items()) - lines = ["### HIL report", "", f"setup `{setup_file}`", "", totals, "", - f"Calibration: **{calibration.get('state', 'not started')}**. Results retained on the instrument.", - "", "Combined PDF: `hil-report.pdf` (artifact: `hil-report-pdf`).", ""] - for test, result in _results.items(): - if result["status"] in ("failed", "error"): - last_line = (result["details"].strip().splitlines() or [""])[-1] - lines.append(f"- **{result['status']}** `{test}`: {last_line[:300]}") - return "\n".join(lines) + "\n" - - -def page(setup_file): - """The HTML report: failures first, then skips, then passes.""" - tests = sorted(_results.items(), key=lambda item: STATUSES.index(item[1]["status"])) - started = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(_started)) - totals = "".join(f'{n} {status}' - for status, n in counts().items()) - return PAGE.format(css=CSS, setup=html.escape(setup_file), started=started, - took=time.time() - _started, totals=totals, - tests="\n".join(card(test, result) for test, result in tests)) - - -def card(test, result): - photos = "".join(PHOTO.format(label=html.escape(label), data=data) - for label, data in _photos.get(test, [])) - details = f"
{html.escape(result['details'])}
" if result["details"] else "" - output = OUTPUT.format(output=html.escape(result["output"])) if result["output"].strip() else "" - return CARD.format(status=result["status"], test=html.escape(test), details=details, - duration=result["duration"], photos=photos, output=output) - - -PAGE = """ - - -HIL report -

HIL report

-

Download combined test and calibration PDF

-
setup {setup} · started {started} · took {took:.0f} s
-
{totals}
-{tests} - -""" - -CARD = """
-

{status}{test} -{duration:.1f} s

-{details} -
{photos}
-{output} -
""" - -PHOTO = ('
{label}' - '
{label}
') - -OUTPUT = "
output
{output}
" - -CSS = """ -:root { --bg:#fff; --fg:#1d1d1f; --muted:#6e6e73; --card:#f5f5f7; --line:#d2d2d7; - --passed:#1a7f37; --failed:#cf222e; --error:#bc4c00; --skipped:#6e6e73; } -@media (prefers-color-scheme: dark) { - :root { --bg:#161618; --fg:#f5f5f7; --muted:#a1a1a6; --card:#222225; --line:#3a3a3d; - --passed:#3fb950; --failed:#f85149; --error:#db6d28; --skipped:#a1a1a6; } } -body { background:var(--bg); color:var(--fg); margin:0 auto; max-width:1100px; - padding:24px 16px; font:15px/1.5 system-ui, sans-serif; } -h1 { font-size:22px; margin:0 0 4px; } -.meta { color:var(--muted); margin-bottom:16px; } -.counts span { margin-right:16px; font-weight:600; } -.test { background:var(--card); border:1px solid var(--line); border-left-width:6px; - border-radius:8px; padding:12px 16px; margin:12px 0; } -.test h2 { font-size:15px; margin:0; word-break:break-all; } -.badge { display:inline-block; min-width:64px; font-size:12px; font-weight:700; - text-transform:uppercase; margin-right:8px; } -.duration { color:var(--muted); font-weight:400; margin-left:8px; } -pre { background:var(--bg); border:1px solid var(--line); border-radius:6px; padding:8px; - overflow-x:auto; font-size:12.5px; white-space:pre-wrap; } -summary { cursor:pointer; color:var(--muted); margin-top:8px; } -.photos { display:flex; flex-wrap:wrap; gap:12px; margin-top:10px; } -figure { margin:0; max-width:100%; } -figure img { max-width:min(100%, 480px); border:1px solid var(--line); border-radius:4px; - display:block; } -figcaption { color:var(--muted); font-size:13px; } -""" diff --git a/imswitch/imcontrol/_test/hil/pytest.ini b/imswitch/imcontrol/_test/hil/pytest.ini index dd89cfc19..a7ab0175d 100644 --- a/imswitch/imcontrol/_test/hil/pytest.ini +++ b/imswitch/imcontrol/_test/hil/pytest.ini @@ -1,5 +1,9 @@ [pytest] # The HIL suite is its own pytest project, so pytest does not import the ImSwitch packages above. +# console_output_style = count shows "[12/31]" after each test, the number of tests done. +# The default is a percentage, which reads as time. +# That misleads here: the calibration is the last 2 tests and most of the run. addopts = -p no:arkitekt_next -p no:cacheprovider -v --tb=short +console_output_style = count markers = hardware: needs a real rig; conftest.py sets it on every HIL test diff --git a/imswitch/imcontrol/_test/hil/test_board_link.py b/imswitch/imcontrol/_test/hil/test_board_link.py index b29515b7a..8177ead92 100644 --- a/imswitch/imcontrol/_test/hil/test_board_link.py +++ b/imswitch/imcontrol/_test/hil/test_board_link.py @@ -1,4 +1,8 @@ -"""The UC2 board is connected and runs the CANopen master firmware. Only reads.""" +"""ImSwitch talks to the UC2 board over USB, and the board runs the master firmware, +the one that passes commands on to the motor and LED boards over the CAN bus. + +Only reads. +""" import hil_client as client @@ -11,5 +15,4 @@ def test_correct_esp32_firmware(): info = client.get_json("/UC2ConfigController/getFirmwareInfo", timeout=5) print(f"\nESP32 firmware: {info}") assert info.get("connected") is True, f"ESP32 not connected: {info}" - assert info.get("isMaster") is True, f"ESP32 is not the CANopen master: {info}" - assert info.get("pindef") == "UC2_canopen_master", f"wrong firmware type: {info.get('pindef')}" + assert info.get("isMaster") is True, f"ESP32 does not run the master firmware: {info}" diff --git a/imswitch/imcontrol/_test/hil/test_camera_capture.py b/imswitch/imcontrol/_test/hil/test_camera_capture.py index db8f34f1f..fc91c498e 100644 --- a/imswitch/imcontrol/_test/hil/test_camera_capture.py +++ b/imswitch/imcontrol/_test/hil/test_camera_capture.py @@ -1,9 +1,11 @@ -"""Every configured camera returns a frame, at the resolution it reports. Only reads. +"""Each camera takes a picture, and the picture is as large as the camera says its sensor is. + +Only reads. ImSwitch reads the two kinds of camera in different ways: -- an acquisition detector ("forAcquisition": true in the setup) with snapNumpyToFastAPI, which - only works while its live view runs; the runner (__main__.py) has started it; -- the observation camera ("forAcquisition": false) with snapOverviewImage, at any time. +- An acquisition detector ("forAcquisition": true in the setup) with snapNumpyToFastAPI. + That only works while its live view runs; the runner (__main__.py) has started it. +- The observation camera ("forAcquisition": false) with snapOverviewImage, at any time. """ import base64 import io diff --git a/imswitch/imcontrol/_test/hil/test_firmware_server.py b/imswitch/imcontrol/_test/hil/test_firmware_server.py index c93333f7d..e0ec80b11 100644 --- a/imswitch/imcontrol/_test/hil/test_firmware_server.py +++ b/imswitch/imcontrol/_test/hil/test_firmware_server.py @@ -1,7 +1,10 @@ -"""The firmware server is usable and every board runs its version. Only reads, flashes nothing. +"""The firmware server can be reached and has firmware files on it, +and each board on the CAN bus runs the version the server has for it. -checkFirmwareUpdates is ImSwitch's own comparison of the server's version.json with what each -board reports. To flash before the tests, start the suite with --sync-firmware. +Only reads, flashes nothing. + +checkFirmwareUpdates is how ImSwitch compares the server's version.json with each board. +To flash before the tests, start the suite with --sync-firmware. """ import pytest diff --git a/imswitch/imcontrol/_test/hil/test_frame_calibration.py b/imswitch/imcontrol/_test/hil/test_frame_calibration.py index 92d1e5133..d9013bb9e 100644 --- a/imswitch/imcontrol/_test/hil/test_frame_calibration.py +++ b/imswitch/imcontrol/_test/hil/test_frame_calibration.py @@ -1,10 +1,13 @@ -"""The one-button FRAME calibration runs through on the calibration target in the holder. +"""The FRAME calibration runs from start to end with the calibration target in the holder, +and none of its steps fails. -MOVES REAL HARDWARE: homes X, Y, Z and the turret, moves the stage across the target, focuses, -switches the objective. SWITCHES LIGHT. WRITES THE SETUP: the calibration stores its result -(stage offset, objective offsets, pixel calibration) in the setup file the rig runs with. That -result stays, it is what the calibration is for; the setup as it was before is saved as -setup_before_frame_calibration.json in the report folder, to go back to by hand. +MOVES REAL HARDWARE: homes X, Y, Z and the turret, scans the target, focuses, changes objective. +SWITCHES LIGHT. +WRITES THE SETUP: the calibration stores its result in the setup file the rig runs with. +The result is the stage offset, the objective offsets and the pixel calibration. +It stays, it is what the calibration is for. +To go back by hand, the old setup is saved in the report folder +as setup_before_frame_calibration.json. The calibration target (plate or pinhole slides, setting "target") must be in the holder. Afterwards the settings this test changed are back and every light is off. @@ -16,19 +19,18 @@ from pathlib import Path import pytest -from PIL import Image +from pypdf import PdfReader import hil_client as client import hil_report -from hil_report import attach RUN_TIMEOUT = 1800 # seconds the whole calibration may take POLL_S = 2 # seconds between two status requests STOP_TIMEOUT = 60 # seconds a stopped calibration may take to end # Without a focus the calibration would wait for someone to focus by hand and press Continue. # Nobody is there in a test, so the run fails instead. -# The light value is set, not kept ("illuminationValue" 0 = keep its current value): the -# teardown turns every light to 0, so a kept value would be 0 in the next run - a black camera. +# The light value is set, not kept ("illuminationValue" 0 would keep its current value). +# The teardown turns every light to 0, so a kept value would be 0 in the next run: a black camera. TEST_SETTINGS = {"manualFocusFallback": False, "illuminationValue": 500} BACKUP_NAME = "setup_before_frame_calibration.json" ENDED = ("finished", "failed", "aborted") @@ -40,10 +42,6 @@ def status(): return client.get_json("/FrameCalibrationController/getFrameCalibrationStatus") -def settings(): - return client.get_json("/FrameCalibrationController/getFrameCalibrationSettings") - - def set_settings(values): return client.post_json("/FrameCalibrationController/setFrameCalibrationSettings", json=values) @@ -64,47 +62,57 @@ def stop_and_wait(): def collect_report(run): - """Export only the completed calibration started by this test, never an older one.""" + """Put the calibration's own PDF into the report; never the one of an older run.""" assert not running(), "cannot export while calibration still runs" current = status() assert run.get("startedAt") and current["startedAt"] == run["startedAt"], ( "calibration identity changed; refusing to attach another run's report") - hil_report.calibration.update(state=current["state"], message=current["message"], - startedAt=current["startedAt"]) - folder = Path(os.environ.get("HIL_REPORT_DIR", ".")) - folder.mkdir(parents=True, exist_ok=True) - (folder / "calibration-status.json").write_text(json.dumps(current, indent=2), encoding="utf-8") + hil_report.note(f"The calibration ended as {current['state']}: {current['message']}") response = client.get("/FrameCalibrationController/getFrameCalibrationReportPdf", timeout=120) assert response.status_code == 200 and response.content.startswith(b"%PDF-"), ( f"calibration PDF export failed: HTTP {response.status_code}") - # Recheck after export because the endpoint returns the running/last report. + # Checked again, because the endpoint gives the report of whatever run is the last one now. assert status()["startedAt"] == run["startedAt"], "calibration changed during PDF export" - from pypdf import PdfReader assert len(PdfReader(io.BytesIO(response.content)).pages), "calibration PDF has no pages" - path = folder / "calibration-report.pdf" - path.write_bytes(response.content) - hil_report.calibration["pdf"] = str(path) + hil_report.append_pdf("FRAME calibration (original report)", response.content) + hil_report.note("Its own report follows on the last pages.") + + +def show_progress(steps, shown, live): + """Print what changed since the last call: a line when a step starts, one when it ends. + calibration 4/10 First objective: find via, focus, affine ... + calibration 4/10 ok (212 s) objective 0: 0.598 x 0.598 um/px -def run_calibration(run): + ``shown`` remembers the lines already printed, as (step name, "start" or "end"). + """ + for number, step in enumerate(steps, 1): + head = f"calibration {number:>2}/{len(steps)} " + if step["status"] != "pending" and (step["name"], "start") not in shown: + shown.add((step["name"], "start")) + live(f"{head}{step['title']} ...") + if step["status"] not in ("pending", "running") and (step["name"], "end") not in shown: + shown.add((step["name"], "end")) + took = f" ({step['seconds']:.0f} s)" if step["seconds"] is not None else "" + live(f"{head}{step['status']}{took} {step['detail']}") + for warning in step["warnings"]: + live(f"{' ' * len(head)}warning: {warning}") + + +def run_calibration(run, live): """Start the calibration and follow it to its end; returns the last status. - Every step's change is printed once, so the output reads as the calibration's log. + ``live`` prints the progress at once (conftest.py), so the log shows which step runs. """ started = client.post_json("/FrameCalibrationController/startFrameCalibration") assert started.get("success"), f"startFrameCalibration refused: {started}" run["accepted"] = True - hil_report.calibration.update(state="running", message="Calibration accepted") run["startedAt"] = status()["startedAt"] - printed = {} + shown = set() deadline = time.monotonic() + RUN_TIMEOUT while True: current = status() - for step in current["steps"]: - line = (step["status"], step["detail"], len(step["warnings"])) - if printed.get(step["name"]) != line and step["status"] != "pending": - printed[step["name"]] = line - print(f"[{step['status']}] {step['title']}: {step['detail']}", flush=True) + show_progress(current["steps"], shown, live) assert current["startedAt"] == run["startedAt"], "calibration replaced during polling" if current["state"] in ENDED and not running(): return current @@ -116,20 +124,10 @@ def run_calibration(run): time.sleep(POLL_S) -def attach_figures(run): - """Every report figure of the run (yellow = expected, green = measured) into the report.""" - assert not running() and status()["startedAt"] == run.get("startedAt"), "not this run's completed figures" - for figure in client.get_json("/FrameCalibrationController/getFrameCalibrationFigures"): - response = client.get("/FrameCalibrationController/getFrameCalibrationFigure", - params={"figureId": figure["id"]}) - if response.headers.get("content-type", "").startswith("image/"): - mark = "" if figure.get("ok") in (True, None) else " (NOT OK)" - attach(f"{figure['title']}{mark}", Image.open(io.BytesIO(response.content))) - - # --- the rig before and after ----------------------------------------------------------------- def all_lights_off(): + """Every laser, LED and the LED matrix off. One that fails does not stop the others.""" actions = [] for name in client.setup()["lasers"]: actions.extend([ @@ -149,21 +147,37 @@ def all_lights_off(): def save_setup_backup(): - """Write the setup as it is now into the report folder; returns the file.""" + """Write the setup as it is now into the report folder.""" folder = Path(os.environ.get("HIL_REPORT_DIR", ".")) folder.mkdir(parents=True, exist_ok=True) file = folder / BACKUP_NAME backup = {"setupFile": client.setup_file(), "setup": client.setup()} file.write_text(json.dumps(backup, indent=2), encoding="utf-8") print(f"\nsetup before the calibration saved to {file.resolve()}") - return file + hil_report.note("The calibration writes its result into the setup. The setup as it was " + f"before is saved as {BACKUP_NAME}.") + + +# pytest ends these fixtures in the reverse order of the arguments of ``calibration``: +# first the light goes off, then the settings go back, then the report is collected. +# Each of them runs also when the one before it failed. + +@pytest.fixture(scope="module") +def run(): + """What is known of the calibration this test starts: "accepted" and "startedAt". + + Afterwards its PDF goes into the report, also when the calibration failed. + """ + run = {} + yield run + if run.get("accepted"): + collect_report(run) @pytest.fixture(scope="module") -def calibration(): - """Run the calibration once; returns its last status. Puts the settings and light back.""" - setup = client.setup() - if not setup["positioners"]: +def settings_for_the_test(): + """Skip when there is nothing to calibrate; else set TEST_SETTINGS, and put them back.""" + if not client.setup()["positioners"]: pytest.skip("the setup has no stage") response = client.get("/FrameCalibrationController/getFrameCalibrationSettings") if response.status_code == 404: @@ -174,35 +188,27 @@ def calibration(): save_setup_backup() print(f"target {original['target']!r}, settings changed for the test: {TEST_SETTINGS}") - run, errors = {}, [] - result = None - hil_report.calibration.update(state="not started", message="Calibration start not yet accepted") + set_settings(TEST_SETTINGS) + yield + set_settings({key: original[key] for key in TEST_SETTINGS}) + + +@pytest.fixture(scope="module") +def lights_off_afterwards(): + """The calibration leaves its light on when it ends.""" + yield + all_lights_off() + + +@pytest.fixture(scope="module") +def calibration(live, run, settings_for_the_test, lights_off_afterwards): + """Run the calibration once; returns its last status.""" try: - set_settings(TEST_SETTINGS) - result = run_calibration(run) - except Exception as error: - errors.append(("calibration", error)) + result = run_calibration(run, live) finally: - actions = [] - if run.get("accepted"): - actions.append(("stop/wait", stop_and_wait)) - actions.extend([ - ("restore settings", lambda: set_settings({key: original[key] for key in TEST_SETTINGS})), - ("lights off", all_lights_off), - ]) if run.get("accepted"): - actions.extend([("export PDF", lambda: collect_report(run)), - ("attach figures", lambda: attach_figures(run))]) - for label, action in actions: - try: - action() - except Exception as error: - errors.append((label, error)) - if errors: - detail = "; ".join(f"{label}: {error}" for label, error in errors) - hil_report.calibration["error"] = detail - raise RuntimeError(detail) from errors[0][1] - print(f"\n{result['state']}: {result['message']}") + stop_and_wait() + live(f"calibration {result['state']}: {result['message']}") return result diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix.py b/imswitch/imcontrol/_test/hil/test_ledmatrix.py index 54fb7c6cd..bb4c7aa8e 100644 --- a/imswitch/imcontrol/_test/hil/test_ledmatrix.py +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix.py @@ -1,4 +1,6 @@ -"""The LED matrix answers, and its light reaches the cameras. SWITCHES LIGHT. +"""The LED matrix can be switched on, and the cameras see its light. + +SWITCHES LIGHT. The matrix counts as visible when it changes the image by more than the camera's own noise: take a few dark frames, measure how much they differ, then compare a dark and a lit frame. @@ -38,8 +40,8 @@ def all_lights_off(): # --- cameras ---------------------------------------------------------------------------------- -# An acquisition detector ("forAcquisition": true in the setup) gives frames only while its -# live view runs. The observation camera ("forAcquisition": false) gives them at any time. +# An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. +# The observation camera ("forAcquisition": false) gives them at any time. def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] @@ -127,8 +129,8 @@ def led_matrix(): def camera(request): """A camera that is ready to take frames; with it a test runs once per kind of camera. - The exposure is set once, in the dark, so that the dark and the lit frames share it. The - observation camera is left alone: it has no live view for the auto exposure to act on. + The exposure is set once, in the dark, so that the dark and the lit frames share it. + The observation camera is left alone: it has no live view for the auto exposure to act on. """ wanted = request.param == "observation" names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] @@ -162,8 +164,7 @@ def dark(): # --- tests ------------------------------------------------------------------------------------ def test_all_leds_off_is_accepted(): - response = client.get("/LEDMatrixController/setAllLEDOff", timeout=5) - assert response.status_code == 200, f"setAllLEDOff -> {response.status_code}: {response.text}" + client.get_json("/LEDMatrixController/setAllLEDOff", timeout=5) def test_led_matrix_is_visible_to_camera(camera, dark): diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py index 02c014d15..af0c50636 100644 --- a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py @@ -1,9 +1,14 @@ -"""One LED of the matrix lights alone, and the cameras see it. SWITCHES LIGHT. +"""One LED of the matrix can be lit on its own. +The cameras see it, and it is dimmer than the whole matrix. -setLEDs lights exactly the LEDs it is given. One LED must change the image by more than the -camera's own noise, and the whole matrix must give a brighter image than that one LED. -The LED is the one closest to the optical axis (from the DPC LED layout), so that it lights the -sample in brightfield; without the DPC controller it is the centre of the setup's Nx x Ny grid. +SWITCHES LIGHT. + +setLEDs lights exactly the LEDs it is given. +One LED must change the image by more than the camera's own noise, +and the whole matrix must give a brighter image than that one LED. +The LED is the one closest to the optical axis (from the DPC LED layout), +so that it lights the sample in brightfield; +without the DPC controller it is the centre of the setup's Nx x Ny grid. """ import base64 import contextlib @@ -43,9 +48,9 @@ def all_lights_off(): def central_led(): """Chain index of the LED closest to the optical axis. - The DPC controller knows every LED's illumination NA; the smallest NA is the most central - LED. Without it, the middle of the Nx x Ny grid the setup declares (ImSwitch's default - layout) is taken; its chain order is not known here, so that LED may lie off centre. + The DPC controller knows every LED's illumination NA; the smallest NA is the most central LED. + Without it, the LED in the middle of the setup's Nx x Ny grid is taken. + The order of the LEDs in the chain is not known here, so that LED may lie off centre. """ response = client.get("/DPCController/get_led_layout") if response.status_code == 200: @@ -60,8 +65,8 @@ def central_led(): # --- cameras ---------------------------------------------------------------------------------- -# An acquisition detector ("forAcquisition": true in the setup) gives frames only while its -# live view runs. The observation camera ("forAcquisition": false) gives them at any time. +# An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. +# The observation camera ("forAcquisition": false) gives them at any time. def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] diff --git a/imswitch/imcontrol/_test/hil/test_lightsource.py b/imswitch/imcontrol/_test/hil/test_lightsource.py index 2990611d7..82f9c2d11 100644 --- a/imswitch/imcontrol/_test/hil/test_lightsource.py +++ b/imswitch/imcontrol/_test/hil/test_lightsource.py @@ -1,4 +1,6 @@ -"""Every laser/LED switches through the API, and every LED reaches the cameras. SWITCHES LIGHT. +"""Each laser and LED can be switched on and off, and the cameras see the light of each LED. + +SWITCHES LIGHT. A light counts as visible when it changes the image by more than the camera's own noise: take a few dark frames, measure how much they differ, then compare a dark and a lit frame. @@ -33,7 +35,8 @@ def light_sources(): def leds(): - """Names of the LEDs. The lasers are left out: on these rigs their beam misses the sensor. + """Names of the LEDs. + The lasers are left out: on these rigs their beam misses the sensor. The setup lists lasers and LEDs alike under "lasers", so only the name tells them apart. """ @@ -60,8 +63,8 @@ def all_lights_off(): # --- cameras ---------------------------------------------------------------------------------- -# An acquisition detector ("forAcquisition": true in the setup) gives frames only while its -# live view runs. The observation camera ("forAcquisition": false) gives them at any time. +# An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. +# The observation camera ("forAcquisition": false) gives them at any time. def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] @@ -143,8 +146,8 @@ def auto_expose(detector): def camera(request): """A camera that is ready to take frames; with it a test runs once per kind of camera. - The exposure is set once, in the dark, so that the dark and the lit frames share it. The - observation camera is left alone: it has no live view for the auto exposure to act on. + The exposure is set once, in the dark, so that the dark and the lit frames share it. + The observation camera is left alone: it has no live view for the auto exposure to act on. """ wanted = request.param == "observation" names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] diff --git a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py new file mode 100644 index 000000000..8b2301a69 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py @@ -0,0 +1,79 @@ +"""Each motor axis moves 10 µm and back, and ImSwitch reports the position it moved to. +After that the stage drives to its home position. + +MOVES REAL HARDWARE (10 µm, then to the end stops). + +Every axis with homing switched on homes, Z first. +So the objective is away from the sample before X and Y move. +The stage stays at home, where the slide holder is out of the light path for the light tests. +When a test of this file failed, the axes after it do not home. + +homeAxis does not say whether the end stop was found. +So the homing only fails when ImSwitch answers with an error or not at all. +The FRAME calibration homes again and checks each axis. +""" +import time + +import pytest + +import hil_client as client + +STEP_UM = 10 +SETTLE_S = 0.5 # wait before reading the position back +HOME_ORDER = "ZXYA" +HOME_EXTRA_S = 30 # seconds homeAxis may take longer than the axis's homeTimeout in the setup + + +def axes(): + """Every (positioner, axis) pair of the setup, e.g. ("ESP32Stage", "X").""" + return [(name, axis) for name, positioner in client.setup()["positioners"].items() + if positioner["forPositioning"] for axis in positioner["axes"]] + + +def axes_to_home(): + """Every (positioner, axis) with homing switched on, in HOME_ORDER.""" + found = [] + for name, positioner in client.setup()["positioners"].items(): + properties = positioner["managerProperties"] + for axis in HOME_ORDER: + # as ESP32StageManager decides it: an end stop, or a fixed number of steps + homes = properties.get(f"home{axis}enabled") or properties.get(f"homeSteps{axis}") + if axis in positioner["axes"] and homes: + found.append((name, axis)) + return found + + +def position(positioner, axis): + return client.get_json("/PositionerController/getPositionerPositions")[positioner][axis] + + +@pytest.fixture(scope="module", autouse=True) +def failures_before(request): + """How many tests of the run had failed when this file started.""" + return request.session.testsfailed # pytest counts the failures of the run + + +@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") +def test_axis_moves_by_step(positioner, axis): + step = {"positionerName": positioner, "axis": axis, "dist": STEP_UM} + back = {"positionerName": positioner, "axis": axis, "dist": -STEP_UM} + + before = position(positioner, axis) + try: + client.get_json("/PositionerController/movePositioner", step) + time.sleep(SETTLE_S) + after = position(positioner, axis) + assert after == pytest.approx(before + STEP_UM, abs=0.1), ( + f"{positioner} {axis}: {before} -> {after}, expected {before + STEP_UM}") + finally: + client.get_json("/PositionerController/movePositioner", back) + + +@client.parametrize_from_rig("positioner, axis", axes_to_home, "no axis has homing switched on") +def test_axis_homes(positioner, axis, failures_before, request): + if request.session.testsfailed > failures_before: + pytest.skip("not homing: a step or an axis before this one failed") + properties = client.setup()["positioners"][positioner]["managerProperties"] + timeout = properties.get(f"homeTimeout{axis}", 20000) / 1000 + HOME_EXTRA_S + client.get_json("/PositionerController/homeAxis", timeout=timeout, params={ + "positionerName": positioner, "axis": axis, "isBlocking": True}) diff --git a/imswitch/imcontrol/_test/unit/test_hil_reporting.py b/imswitch/imcontrol/_test/unit/test_hil_reporting.py index 2676dec99..1f81786a9 100644 --- a/imswitch/imcontrol/_test/unit/test_hil_reporting.py +++ b/imswitch/imcontrol/_test/unit/test_hil_reporting.py @@ -36,33 +36,43 @@ def pdf_bytes(text="Calibration evidence"): return data.getvalue() -def test_pdf_merge_keeps_original_pages_and_long_failures(tmp_path): - original = tmp_path / "calibration-report.pdf" - original.write_bytes(pdf_bytes()) +def test_pdf_has_the_failure_the_note_and_the_appended_pdf(tmp_path): results = {"test_camera.py::test_capture": { - "status": "failed", "duration": 2., "details": "Diagnostic line\n" * 140 + "LAST ERROR LINE", "output": ""}} - hil_pdf.write_pdf(tmp_path, "FRAME.json", results, {}, - {"state": "finished", "pdf": str(original)}, 0) + "status": "failed", "duration": 2., "details": "Diagnostic line\n" * 140 + "E LAST ERROR LINE"}} + hil_pdf.write_pdf(tmp_path / "hil-report.pdf", "FRAME.json", 0, results, + {"test_camera.py": "Every camera returns a frame."}, {}, + {"test_camera.py": ["A NOTE OF THE TEST"]}, + [("Calibration", pdf_bytes())]) reader = PdfReader(tmp_path / "hil-report.pdf") - assert len(reader.pages) > 3 - text = "\n".join(page.extract_text() for page in reader.pages) - assert "LAST ERROR LINE" in text and "TEST RESULT: FAILED" in text + text = "\n".join(page.extract_text() for page in reader.pages[:-1]) + assert "LAST ERROR LINE" in text and "Every camera returns a frame." in text + assert "A NOTE OF THE TEST" in text + assert "Diagnostic line" not in text # only what went wrong, not the whole traceback assert "Calibration evidence" in reader.pages[-1].extract_text() assert len(reader.outline) == 2 + assert [file.name for file in tmp_path.iterdir()] == ["hil-report.pdf"] -def test_old_pdf_is_not_appended_without_current_run(tmp_path): - (tmp_path / "calibration-report.pdf").write_bytes(pdf_bytes("OLD RUN")) +def test_what_a_test_checks_is_the_whole_first_paragraph_of_its_docstring(): + hil_report.reset() + module = SimpleNamespace(__doc__="Every axis moves 10 um\nand steps back.\n\nMOVES HARDWARE.") + hil_report.ReportPlugin("out", "FRAME.json").pytest_itemcollected( + SimpleNamespace(nodeid="test_motor.py::test_it", module=module)) + assert hil_report._descriptions["test_motor.py"] == "Every axis moves 10 um and steps back." + + +def test_report_without_appended_pdf_has_only_the_test_pages(tmp_path): hil_report.reset() hil_report.record_problem("startup", "server unavailable") hil_report.write_reports(tmp_path, "unavailable") - text = "".join(p.extract_text() for p in PdfReader(tmp_path / "hil-report.pdf").pages) - assert "OLD RUN" not in text and "No calibration PDF" in text + reader = PdfReader(tmp_path / "hil-report.pdf") + assert "server unavailable" in "".join(page.extract_text() for page in reader.pages) + assert len(reader.outline) == 1 + assert sorted(file.name for file in tmp_path.iterdir()) == ["hil-report.pdf", "summary.md"] -def test_pdf_failure_preserves_other_reports_and_removes_stale_pdf(tmp_path, monkeypatch): +def test_pdf_failure_still_writes_the_summary(tmp_path, monkeypatch): hil_report.reset() - (tmp_path / "hil-report.pdf").write_bytes(pdf_bytes("OLD RUN")) def fail(*args): raise ValueError("broken PDF") monkeypatch.setattr(hil_pdf, "write_pdf", fail) @@ -70,7 +80,6 @@ def fail(*args): assert hil_report.report_error == "broken PDF" assert not (tmp_path / "hil-report.pdf").exists() assert "broken PDF" in (tmp_path / "summary.md").read_text() - assert (tmp_path / "report.html").exists() def test_stop_timeout_is_an_error(calibration_module, monkeypatch): @@ -90,7 +99,7 @@ def test_poll_waits_for_thread_after_terminal_status(calibration_module, monkeyp monkeypatch.setattr(m, "running", lambda: next(states)) monkeypatch.setattr(m.time, "sleep", lambda _: None) run = {} - assert m.run_calibration(run)["state"] == "finished" + assert m.run_calibration(run, lambda line: None)["state"] == "finished" assert run == {"accepted": True, "startedAt": "now"} @@ -109,17 +118,36 @@ def test_failed_calibration_pdf_is_collected(calibration_module, monkeypatch, tm monkeypatch.setattr(m, "status", lambda: {"startedAt": "ours", "state": "failed", "message": "no focus"}) monkeypatch.setattr(m.client, "get", lambda *a, **k: SimpleNamespace(status_code=200, content=pdf_bytes())) m.collect_report({"startedAt": "ours"}) - assert hil_report.calibration["state"] == "failed" - assert (tmp_path / "calibration-report.pdf").exists() - - -def test_calibration_is_last_without_failure_guard(): + (title, data), = hil_report._appended + assert data.startswith(b"%PDF-") + (notes,) = hil_report._notes.values() + assert notes[0] == "The calibration ended as failed: no focus" + assert "failed: no focus" in hil_report.summary("FRAME.json") + assert not list(tmp_path.iterdir()) # kept for hil-report.pdf, not written as a file + + +def test_calibration_progress_is_one_line_per_start_and_end(calibration_module): + steps = [{"name": "homing", "title": "Home", "status": "ok", "detail": "homed Z", "seconds": 12.4, + "warnings": ["slow"]}, + {"name": "objective0", "title": "First objective", "status": "running", "detail": "", + "seconds": None, "warnings": []}, + {"name": "save", "title": "Save", "status": "pending", "detail": "", "seconds": None, + "warnings": []}] + lines, shown = [], set() + calibration_module.show_progress(steps, shown, lines.append) + calibration_module.show_progress(steps, shown, lines.append) # nothing changed: no new line + assert lines == ["calibration 1/3 Home ...", "calibration 1/3 ok (12 s) homed Z", + " warning: slow", "calibration 2/3 First objective ..."] + + +def test_tests_run_in_order_and_unlisted_ones_last(): conf = load("hil_hooks", HIL / "conftest.py") items = [SimpleNamespace(nodeid=f"test_{name}.py::test_it", fspath=HIL / f"test_{name}.py", - add_marker=lambda _: None) for name in ("frame_calibration", "new_test", "board_link")] + add_marker=lambda _: None) + for name in ("frame_calibration", "new_test", "motor_axis_move", "board_link")] conf.pytest_collection_modifyitems(items) - assert conf.name_of(items[-1]) == "frame_calibration" - assert not hasattr(conf, "pytest_runtest_setup") + assert [conf.name_of(item) for item in items] == [ + "board_link", "motor_axis_move", "frame_calibration", "new_test"] def test_calibration_summary_overflow_keeps_last_step(tmp_path): @@ -136,8 +164,8 @@ def test_calibration_summary_overflow_keeps_last_step(tmp_path): def test_camera_preparation_failure_does_not_prevent_test_execution(tmp_path, monkeypatch): main = load("hil_main", HIL / "__main__.py") monkeypatch.setattr(sys, "argv", ["hil", str(tmp_path)]) - monkeypatch.setattr(main, "why_not_ready", lambda: None) - monkeypatch.setattr(main, "prepare_cameras", lambda: ["camera A: no frame"]) + monkeypatch.setattr(main, "wait_for_imswitch", lambda: None) + monkeypatch.setattr(main, "prepare_cameras", lambda: {"camera A": "no frame"}) monkeypatch.setattr(main.client, "setup_file", lambda: "FRAME.json") called = [] def tests(*args, **kwargs): @@ -151,51 +179,76 @@ def tests(*args, **kwargs): def test_unreachable_server_still_writes_report(tmp_path, monkeypatch): main = load("hil_main", HIL / "__main__.py") - (tmp_path / "calibration-report.pdf").write_bytes(pdf_bytes("old calibration")) - (tmp_path / "report-error.txt").write_text("old error") + (tmp_path / "hil-report.pdf").write_bytes(pdf_bytes("OLD RUN")) monkeypatch.setattr(sys, "argv", ["hil", str(tmp_path)]) - monkeypatch.setattr(main, "why_not_ready", lambda: "server unavailable") + def unavailable(): + raise AssertionError("server unavailable") + monkeypatch.setattr(main, "wait_for_imswitch", unavailable) assert main.main() == main.COULD_NOT_RUN - assert (tmp_path / "hil-report.pdf").exists() - assert not (tmp_path / "calibration-report.pdf").exists() - assert not (tmp_path / "report-error.txt").exists() + text = "".join(page.extract_text() for page in PdfReader(tmp_path / "hil-report.pdf").pages) + assert "server unavailable" in text and "OLD RUN" not in text -def test_cleanup_error_does_not_prevent_lights_off_or_export(calibration_module, tmp_path, monkeypatch): +def test_failed_calibration_is_stopped_and_its_report_collected(calibration_module, monkeypatch): m = calibration_module - monkeypatch.setenv("HIL_REPORT_DIR", str(tmp_path)) - monkeypatch.setattr(m.client, "setup", lambda: {"positioners": {"stage": {}}, "lasers": {}, "LEDMatrixs": {}}) - monkeypatch.setattr(m.client, "get", lambda *a, **k: SimpleNamespace(status_code=200)) - monkeypatch.setattr(m.client, "json_of", lambda _: {"target": "plate", **m.TEST_SETTINGS}) - monkeypatch.setattr(m, "running", lambda: False) - monkeypatch.setattr(m, "save_setup_backup", lambda: None) - monkeypatch.setattr(m, "set_settings", lambda _: None) called = [] - def run(ctx): - ctx.update(accepted=True, startedAt="ours") + def fails(run, live): + run.update(accepted=True, startedAt="ours") raise AssertionError("original failure") - def stop(): - raise AssertionError("stop timeout") - monkeypatch.setattr(m, "run_calibration", run) - monkeypatch.setattr(m, "stop_and_wait", stop) + monkeypatch.setattr(m, "run_calibration", fails) + monkeypatch.setattr(m, "stop_and_wait", lambda: called.append("stop")) + monkeypatch.setattr(m, "collect_report", lambda run: called.append("pdf")) monkeypatch.setattr(m, "all_lights_off", lambda: called.append("off")) - monkeypatch.setattr(m, "collect_report", lambda _: called.append("pdf")) - monkeypatch.setattr(m, "attach_figures", lambda _: called.append("figures")) - with pytest.raises(RuntimeError, match="original failure.*stop timeout"): - m.calibration.__wrapped__() - assert called == ["off", "pdf", "figures"] - -def test_pytest_continues_to_calibration_after_failure(tmp_path): + # As pytest does it: the fixtures start in the order of ``calibration``'s arguments, + # and end in the reverse order. + run_fixture = m.run.__wrapped__() + lights_fixture = m.lights_off_afterwards.__wrapped__() + run = next(run_fixture) + next(lights_fixture) + with pytest.raises(AssertionError, match="original failure"): + m.calibration.__wrapped__(lambda line: None, run, None, None) + for fixture in (lights_fixture, run_fixture): + with pytest.raises(StopIteration): + next(fixture) + assert called == ["stop", "off", "pdf"] + + +def test_a_refused_calibration_is_not_stopped_and_gives_no_report(calibration_module, monkeypatch): + m = calibration_module + def refused(run, live): + raise AssertionError("startFrameCalibration refused") + monkeypatch.setattr(m, "run_calibration", refused) + monkeypatch.setattr(m, "stop_and_wait", lambda: pytest.fail("stopped another run")) + monkeypatch.setattr(m, "collect_report", lambda run: pytest.fail("took another run's report")) + run_fixture = m.run.__wrapped__() + run = next(run_fixture) + with pytest.raises(AssertionError, match="refused"): + m.calibration.__wrapped__(lambda line: None, run, None, None) + with pytest.raises(StopIteration): + next(run_fixture) + + +@pytest.mark.parametrize("failing, watched, runs", [ + ("firmware_server", "frame_calibration", True), # another firmware version can still calibrate + ("board_link", "frame_calibration", False), + ("motor_axis_move", "frame_calibration", False), +]) +def test_a_test_does_not_start_after_a_failure_it_depends_on(tmp_path, failing, watched, runs): import os import subprocess conf = (HIL / "conftest.py").read_text() (tmp_path / "conftest.py").write_text(conf + "\nclient.reachable = lambda: True\n") - (tmp_path / "test_board_link.py").write_text("def test_board():\n assert False, 'offline simulated failure'\n") - (tmp_path / "test_frame_calibration.py").write_text( - "from pathlib import Path\ndef test_calibration():\n Path(__file__).with_suffix('.ran').touch()\n") + (tmp_path / f"test_{failing}.py").write_text("def test_it():\n assert False, 'offline simulated failure'\n") + (tmp_path / f"test_{watched}.py").write_text( + "from pathlib import Path\ndef test_it(live):\n live('LIVE LINE')\n" + " Path(__file__).with_suffix('.ran').touch()\n") env = dict(os.environ, PYTHONPATH=str(HIL), PYTEST_DISABLE_PLUGIN_AUTOLOAD="1") - result = subprocess.run([sys.executable, "-m", "pytest", str(tmp_path), "--confcutdir", str(tmp_path), "-q"], + result = subprocess.run([sys.executable, "-m", "pytest", str(tmp_path), "--confcutdir", str(tmp_path), "-q", "-rs"], env=env, capture_output=True, text=True, timeout=60) assert result.returncode == 1, result.stdout + result.stderr - assert (tmp_path / "test_frame_calibration.ran").exists() + assert (tmp_path / f"test_{watched}.ran").exists() == runs + # live() prints although pytest captures the output of a passing test + assert ("LIVE LINE" in result.stdout) == runs + if not runs: + assert f"not started, because {failing} failed" in result.stdout From d0c67382b60742eea85345227b8d7e987761a93c Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Mon, 16 Nov 2026 17:19:39 +0100 Subject: [PATCH 06/10] Refactor LED matrix and light source tests to ensure visibility across all cameras --- imswitch/imcontrol/_test/hil/README.md | 36 ++- imswitch/imcontrol/_test/hil/__main__.py | 3 - imswitch/imcontrol/_test/hil/conftest.py | 20 +- imswitch/imcontrol/_test/hil/hil_pdf.py | 49 ++- imswitch/imcontrol/_test/hil/hil_report.py | 47 ++- .../_test/hil/test_frame_calibration.py | 7 +- .../imcontrol/_test/hil/test_ledmatrix.py | 151 ++++++--- .../_test/hil/test_ledmatrix_single.py | 172 ++++++---- .../imcontrol/_test/hil/test_lightsource.py | 127 +++++--- .../_test/hil/test_motor_axis_move.py | 59 +--- .../_test/hil/test_motor_motion_camera.py | 302 ++++++++++++++++++ .../imcontrol/_test/hil/test_stage_homing.py | 71 ++++ .../_test/unit/test_hil_reporting.py | 36 ++- 13 files changed, 813 insertions(+), 267 deletions(-) create mode 100644 imswitch/imcontrol/_test/hil/test_motor_motion_camera.py create mode 100644 imswitch/imcontrol/_test/hil/test_stage_homing.py diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md index 53c3dccf2..17b8f9945 100644 --- a/imswitch/imcontrol/_test/hil/README.md +++ b/imswitch/imcontrol/_test/hil/README.md @@ -11,29 +11,39 @@ Each test file says at the top of its docstring what it checks and what it does | `board_link` | ImSwitch talks to the UC2 board, and the board runs the master firmware | reads | | `firmware_server` | the firmware server has firmware files, and each board runs the server's version | reads | | `camera_capture` | each camera takes a picture as large as its sensor | reads | -| `motor_axis_move` | each axis moves 10 µm and back; then each axis with homing switched on homes: Z, X, Y, then the turret | **moves** (10 µm, then to the end stops) | -| `lightsource` | each laser and LED switches on and off; the cameras see each LED | **light** | -| `ledmatrix` | the cameras see the LED matrix | **light** | -| `ledmatrix_single` | one LED lights on its own (`setLEDs`) and is dimmer than the whole matrix | **light** | +| `motor_axis_move` | each axis moves 10 µm and back, and ImSwitch reports the position it moved to | **moves** (10 µm) | +| `stage_homing` | "Safe Global Homing" (`startFrameHoming`) homes Z, X and Y and reports each as done | **moves** (to the end stops, then to the transport position) | +| `motor_motion_camera` | the observation camera sees every axis move: X and Y shift the image the right way, Z changes its scale | **moves** (transport position, 3 mm per axis), **light** | +| `lightsource` | each laser and LED switches on and off; every camera sees each LED go on and off | **light** | +| `ledmatrix` | every camera sees the LED matrix go on and off | **light** | +| `ledmatrix_single` | one LED lights on its own (`setLEDs`), every camera sees it go on and off, and it is dimmer than the whole matrix | **light** | | `frame_calibration` | the FRAME calibration runs from start to end; needs the calibration target in the holder | **moves** (homes, turret), **light**, **writes the setup** (backup: `setup_before_frame_calibration.json`) | Hardware a setup does not have skips its tests. Hardware that is there but does not work fails. They run in the order of the table: the boards, the cameras, the motors, the lights, then the calibration. -The stage is homed before the lights are tested, so the slide holder is out of the light path. +The homing ends at the transport position, and the motion and light tests run there. The order is the list `ORDER` in `conftest.py`. +A light test has one case per light, not one per camera. +It passes only when every camera of the setup sees the light go on and go off again. +A camera that ImSwitch serves as a mock, or that cannot report its status, is left out and named in the report. + Some tests do not start after a failure; they are skipped and say which test failed. The table is `NEEDS` in `conftest.py`: -- `frame_calibration` needs `board_link`, `camera_capture`, `motor_axis_move` and the three light tests. +- `stage_homing` needs `motor_axis_move`. +- `motor_motion_camera` needs `motor_axis_move` and `stage_homing`: its first move is absolute, so the stage must be homed. +- `frame_calibration` needs `board_link`, `camera_capture`, the three motor tests and the three light tests. It does not need `firmware_server`: a board on another firmware version fails that test, but can still be calibrated. + Only `--sync-firmware` stops every test, when the flashing fails. -`motor_axis_move` first steps every axis, then homes them, one case per axis. -When a step failed or an axis did not home, the axes after it are skipped. -The homing cannot see whether an end stop was found: `homeAxis` does not return it. -It fails when ImSwitch answers with an error or not at all. +`motor_axis_move` compares positions, which are the firmware's step count. +`motor_motion_camera` is what shows that the stage really moved. +`stage_homing` presses the same button as the FRAME settings page and checks the same per-axis "done". +That "done" says that the homing command of the axis returned, not that its end stop was pressed. +The turret (A) is homed by the calibration. The calibration homes again and checks every axis, reads the position back after every move, follows X and Y in the observation camera, focuses with Z and switches the objective. A step the calibration skips (e.g. the second objective on a rig with one) is listed in the test's output as not tested. @@ -58,8 +68,9 @@ A camera that does not start is a problem in the report; the tests run anyway. | File | Holds | |---|---| | `hil-report.pdf` | the report to read: what was tested, one line per test, then every test with what failed, its notes, its cases and its photos, then the PDFs the tests appended (the calibration's own report) | -| `summary.md` | the setup, the counts, one line per failure and the notes of the tests, for the CI run's page | +| `summary.md` | the setup, the counts, a table with one row per test file, one line per failure and the notes of the tests, for the CI run's page | | `setup_before_frame_calibration.json` | the setup as it was before the calibration; only when the calibration ran | +| `frame_calibration.pdf` | the calibration's own report, also appended to `hil-report.pdf`; only when the calibration ran | Both reports name the setup file the rig ran with. A test finds the folder in the environment variable `HIL_REPORT_DIR`. @@ -146,6 +157,7 @@ A test file has: The test waits until the calibration's thread has ended, then fetches its PDF with `getFrameCalibrationReportPdf` and checks the run's `startedAt` before and after, so the report of another run is never taken. The PDF is appended to `hil-report.pdf` as ImSwitch wrote it (`hil_report.append_pdf`). +It is also saved on its own as `frame_calibration.pdf` in the report folder, so it is there even when `hil-report.pdf` could not be written. When it cannot be fetched, the `frame_calibration` part of the report shows that as an error. The fixtures of `test_frame_calibration.py` put the rig back, each on its own: the calibration is stopped, the light goes off (the calibration leaves it on), the settings go back, and then the report is collected. @@ -154,5 +166,5 @@ The calibration's result stays in the instrument's setup, also after os-rpi has A calibration that fails may have written a part of it; `setup_before_frame_calibration.json` is there to go back by hand. Nothing is rolled back automatically. -os-rpi passes three environment variables that the report shows: `HIL_TARGET` (the image or pallet under test), `HIL_PALLET` (the pallet and every image in it) and `HIL_RUN_URL` (the Actions run). +os-rpi passes three environment variables that the report shows: `HIL_TARGET` (the image or pallet under test), `HIL_IMAGES` (every image of the pallet under test, one per line) and `HIL_RUN_URL` (the Actions run). A run from a laptop has none of them. diff --git a/imswitch/imcontrol/_test/hil/__main__.py b/imswitch/imcontrol/_test/hil/__main__.py index 0a91c01bb..da51144b0 100644 --- a/imswitch/imcontrol/_test/hil/__main__.py +++ b/imswitch/imcontrol/_test/hil/__main__.py @@ -99,9 +99,6 @@ def main(): # A run that dies must not leave the report of an older run behind. for name in ("hil-report.pdf", "summary.md"): (report_dir / name).unlink(missing_ok=True) - # The rig (os-rpi) passes the pallet and images it swapped in; a laptop run has none. - if os.environ.get("HIL_PALLET"): - print(f"[hil] pallet under test:\n{os.environ['HIL_PALLET']}", flush=True) files = [HERE / f"test_{name}.py" for name in args.tests] unknown = [name for name, file in zip(args.tests, files) if not file.is_file()] if unknown: diff --git a/imswitch/imcontrol/_test/hil/conftest.py b/imswitch/imcontrol/_test/hil/conftest.py index 3bfef8805..4135ab61f 100644 --- a/imswitch/imcontrol/_test/hil/conftest.py +++ b/imswitch/imcontrol/_test/hil/conftest.py @@ -12,16 +12,22 @@ ORDER = [ "board_link", "firmware_server", # 1. the boards and their firmware versions "camera_capture", # 2. the cameras - "motor_axis_move", # 3. the motors, then homing: the stage is - # out of the light path for the tests below - "lightsource", "ledmatrix", "ledmatrix_single", # 4. the lights + "motor_axis_move", # 3. the motors: 10 µm steps, + "stage_homing", # homing, ending at the transport position, + "motor_motion_camera", # then moves the camera sees + "lightsource", "ledmatrix", "ledmatrix_single", # 4. the lights, at the transport position "frame_calibration", # 5. the calibration ] -# A test does not start when one of these failed before it. firmware_server is in no list: -# a board on another firmware version fails that test, but can still move and be calibrated. +# A test does not start when one of these failed before it. +# firmware_server is in no list: a board on another firmware version fails that test, +# but can still move and be calibrated. +# Only --sync-firmware stops every test, when flashing fails (__main__.py). NEEDS = { - "frame_calibration": ["board_link", "motor_axis_move", "camera_capture", - "lightsource", "ledmatrix", "ledmatrix_single"], + "stage_homing": ["motor_axis_move"], + # Its first move is absolute, so the stage must be homed. + "motor_motion_camera": ["motor_axis_move", "stage_homing"], + "frame_calibration": ["board_link", "camera_capture", "motor_axis_move", "stage_homing", + "motor_motion_camera", "lightsource", "ledmatrix", "ledmatrix_single"], } _failed = [] # the names of the tests that failed so far in this run diff --git a/imswitch/imcontrol/_test/hil/hil_pdf.py b/imswitch/imcontrol/_test/hil/hil_pdf.py index 8416e9159..4f21b1226 100644 --- a/imswitch/imcontrol/_test/hil/hil_pdf.py +++ b/imswitch/imcontrol/_test/hil/hil_pdf.py @@ -21,6 +21,8 @@ ) from reportlab.platypus.doctemplate import LayoutError +from hil_report import by_file, name_of, verdict_of + MARGIN = 42 PADDING = 6 # points ReportLab's page frame keeps free inside the margins, on each side WIDTH = A4[0] - 2 * (MARGIN + PADDING) # of the text @@ -123,25 +125,6 @@ def grid(head, body, widths): return table -def verdict_of(statuses): - """One status for several: failed when one failed, passed when one ran, else skipped.""" - if "failed" in statuses or "error" in statuses: - return "failed" - return "passed" if "passed" in statuses else "skipped" - - -def by_file(results): - """``{"test_board_link.py": {"test_uc2_board_connected": result, ...}, ...}``, in run order. - - A problem outside the tests (``hil_report.record_problem``) is an entry without cases. - """ - files = {} - for test, result in results.items(): - file, _, case = test.partition("::") - files.setdefault(file, {})[case] = result - return files - - def failure_lines(details): """The lines of a pytest traceback that say what went wrong: its "E ..." lines.""" lines = details.strip().splitlines() @@ -149,11 +132,6 @@ def failure_lines(details): return (errors or lines)[-OUTPUT_LINES:] -def name_of(file): - """ "board_link" for "test_board_link.py"; a problem outside the tests keeps its name.""" - return file[len("test_"):-len(".py")] if file.endswith(".py") else file - - def test_part(number, file, cases, description, notes, photos): """The flowables of one test file: its heading, what it checks, output, cases and photos.""" name = name_of(file) @@ -167,10 +145,14 @@ def test_part(number, file, cases, description, notes, photos): output.append(f"{case} skipped: {result['details']}") output.extend(notes) pairs = [("What it checks", description)] if description else [] - if output: - pairs.append(("Output", "\n".join(output))) + # One line per row, labelled once: a table splits onto the next page only between rows. + pairs += [("Output" if index == 0 else "", line) for index, line in enumerate(output)] part = [Heading(f"{number}. {name}", 11, verdict_of([r["status"] for r in cases.values()])), - Indenter(left=INDENT), rows(pairs, width)] + Indenter(left=INDENT)] + # A file without docstring that passed has nothing to say. + # ReportLab refuses a table without rows. + if pairs: + part.append(rows(pairs, width)) if any(cases): body = [[text(case), text(result["status"]), text(f"{result['duration']:.1f} s")] for case, result in cases.items()] @@ -197,8 +179,7 @@ def test_pages(setup, started, results, descriptions, photos, notes): ("Duration", f"{(time.time() - started) / 60:.0f} min"), ("Result", counted or "no test ran"), ("Tested target", os.environ.get("HIL_TARGET")), - ("Run", os.environ.get("HIL_RUN_URL")), - ("Pallet", os.environ.get("HIL_PALLET"))] + ("Run", os.environ.get("HIL_RUN_URL"))] summary = [] for number, (file, cases) in enumerate(files.items(), 1): summary.append([text(number), Verdict(verdict_of([r["status"] for r in cases.values()])), @@ -208,8 +189,14 @@ def test_pages(setup, started, results, descriptions, photos, notes): rows([pair for pair in head if pair[1]], WIDTH), Spacer(1, 6), text("Summary", LABEL), grid(["No.", "Result", "Test", "What it checks", "Time"], summary, - [28, 42, 100, WIDTH - 215, 45]), - Heading("Tests", 13)] + [28, 42, 100, WIDTH - 215, 45])] + # The rig (os-rpi) passes the images of the pallet under test, one per line. + # One image per row: a table splits between its rows onto the next page, never inside a row. + images = os.environ.get("HIL_IMAGES", "").split() + if images: + story += [Spacer(1, 6), text("Images under test", LABEL), + grid(["Image"], [[text(image)] for image in images], [WIDTH])] + story.append(Heading("Tests", 13)) for number, (file, cases) in enumerate(files.items(), 1): story += test_part(number, file, cases, descriptions.get(file, ""), notes.get(file, []), photos) diff --git a/imswitch/imcontrol/_test/hil/hil_report.py b/imswitch/imcontrol/_test/hil/hil_report.py index 0ee8f6844..153cfdce8 100644 --- a/imswitch/imcontrol/_test/hil/hil_report.py +++ b/imswitch/imcontrol/_test/hil/hil_report.py @@ -1,5 +1,7 @@ """The report of a run: hil-report.pdf (results, photos, PDFs of the tests) and summary.md. +summary.md is the short form for the CI step summary: a table with one row per test file. + A test adds to its part of the report with: attach("dark", image) a photo @@ -86,11 +88,50 @@ def counts(): return {status: statuses.count(status) for status in STATUSES} +def by_file(results): + """``{"test_board_link.py": {"test_uc2_board_connected": result, ...}, ...}``, in run order. + + A problem outside the tests (``record_problem``) is an entry without cases. + """ + files = {} + for test, result in results.items(): + file, _, case = test.partition("::") + files.setdefault(file, {})[case] = result + return files + + +def verdict_of(statuses): + """One status for several: failed when one failed, passed when one ran, else skipped.""" + if "failed" in statuses or "error" in statuses: + return "failed" + return "passed" if "passed" in statuses else "skipped" + + +def name_of(file): + """ "board_link" for "test_board_link.py"; a problem outside the tests keeps its name.""" + return file[len("test_"):-len(".py")] if file.endswith(".py") else file + + def summary(setup_file): - """Markdown, short enough for a CI step summary: the setup, the counts, one line per failure.""" + """Markdown for the CI step summary: one row per test file, then one line per failure.""" totals = " · ".join(f"{n} {status}" for status, n in counts().items()) - lines = ["### HIL report", "", f"setup `{setup_file}`", "", totals, "", - "Report: `hil-report.pdf` in the artifact `hil-report`.", ""] + if report_error: + report = f"The PDF was not written: {report_error}" + else: + report = "Report: `hil-report.pdf` in the artifact `hil-report`." + lines = ["### Hardware tests", "", f"setup `{setup_file}` · {totals}", "", report, "", + "| No. | Test | Result | Cases | Time |", "|---|---|---|---|---|"] + for number, (file, cases) in enumerate(by_file(_results).items(), 1): + statuses = [result["status"] for result in cases.values()] + cases_counted = ", ".join(f"{statuses.count(status)} {status}" + for status in STATUSES if status in statuses) + verdict = verdict_of(statuses) + if verdict == "failed": + verdict = f"**{verdict}**" # bold, so a failure stands out in the table + seconds = sum(result["duration"] for result in cases.values()) + lines.append(f"| {number} | {name_of(file)} | {verdict} | {cases_counted} | " + f"{seconds:.0f} s |") + lines.append("") for test, result in _results.items(): if result["status"] in ("failed", "error"): last_line = (result["details"].strip().splitlines() or [""])[-1] diff --git a/imswitch/imcontrol/_test/hil/test_frame_calibration.py b/imswitch/imcontrol/_test/hil/test_frame_calibration.py index d9013bb9e..52a9abd75 100644 --- a/imswitch/imcontrol/_test/hil/test_frame_calibration.py +++ b/imswitch/imcontrol/_test/hil/test_frame_calibration.py @@ -33,6 +33,7 @@ # The teardown turns every light to 0, so a kept value would be 0 in the next run: a black camera. TEST_SETTINGS = {"manualFocusFallback": False, "illuminationValue": 500} BACKUP_NAME = "setup_before_frame_calibration.json" +CALIBRATION_PDF = "frame_calibration.pdf" # the calibration's own report, in the report folder ENDED = ("finished", "failed", "aborted") @@ -75,7 +76,11 @@ def collect_report(run): assert status()["startedAt"] == run["startedAt"], "calibration changed during PDF export" assert len(PdfReader(io.BytesIO(response.content)).pages), "calibration PDF has no pages" hil_report.append_pdf("FRAME calibration (original report)", response.content) - hil_report.note("Its own report follows on the last pages.") + # Also on its own, so it is in the report folder even when hil-report.pdf cannot be written. + folder = Path(os.environ.get("HIL_REPORT_DIR", ".")) + folder.mkdir(parents=True, exist_ok=True) + (folder / CALIBRATION_PDF).write_bytes(response.content) + hil_report.note(f"Its own report follows on the last pages, and is saved as {CALIBRATION_PDF}.") def show_progress(steps, shown, live): diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix.py b/imswitch/imcontrol/_test/hil/test_ledmatrix.py index bb4c7aa8e..823a5a405 100644 --- a/imswitch/imcontrol/_test/hil/test_ledmatrix.py +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix.py @@ -1,9 +1,11 @@ -"""The LED matrix can be switched on, and the cameras see its light. +"""The LED matrix can be switched on and off, and every camera sees it go on and off. SWITCHES LIGHT. -The matrix counts as visible when it changes the image by more than the camera's own noise: -take a few dark frames, measure how much they differ, then compare a dark and a lit frame. +It passes only when every camera of the setup sees both switches. +On: the image changes by more than the camera's own noise. +Off: the image is back to dark, within that noise. +The noise: take a few dark frames and measure how much they differ. """ import base64 import contextlib @@ -14,7 +16,7 @@ from PIL import Image, ImageChops, ImageStat import hil_client as client -from hil_report import attach +from hil_report import attach, note MATRIX_INTENSITY = 500 # per colour, of setAllLED LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it @@ -39,6 +41,17 @@ def all_lights_off(): time.sleep(LIGHT_SETTLE_S) +def set_matrix(on): + """Every LED of the matrix on at MATRIX_INTENSITY, or off.""" + if on: + client.get_json("/LEDMatrixController/setAllLED", { + "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, + "intensity_b": MATRIX_INTENSITY}) + else: + client.get_json("/LEDMatrixController/setAllLEDOff") + time.sleep(LIGHT_SETTLE_S) + + # --- cameras ---------------------------------------------------------------------------------- # An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. # The observation camera ("forAcquisition": false) gives them at any time. @@ -47,6 +60,22 @@ def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] +def cameras(): + """The cameras that give real frames. + A camera ImSwitch serves as a mock, or cannot report on, is left out and named in the report. + """ + found = [] + for detector in client.setup()["detectors"]: + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in status or status.get("status") == "error": + note(f"{detector} left out: getCameraStatus failed: {status.get('error')}") + elif status.get("isMock") or str(status.get("model", "")).lower() == "mock": + note(f"{detector} left out: ImSwitch served a mock camera") + else: + found.append(detector) + return found + + def take_image(detector): """One small greyscale frame (PIL) of either kind of camera.""" if is_observation_camera(detector): @@ -70,10 +99,23 @@ def image_difference(first, second): return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] +def brightness(image): + """Mean grey value of a frame.""" + return ImageStat.Stat(image).mean[0] + + +def exposure_and_gain(detector): + """ "exposure 20, gain 0" as the camera reports them; None for a value it does not report.""" + values = [client.get_json("/SettingsController/getDetectorParameter", + {"detectorName": detector, "parameterName": name}) + for name in ("exposure", "gain")] + return f"exposure {values[0]}, gain {values[1]}" + + def dark_baseline(detector): """Measure the camera noise with the scene unchanged. - Returns (last frame, noise floor, change the matrix must exceed). + Returns (last frame, noise floor, change a light must exceed). """ previous = take_image(detector) drifts = [] @@ -117,40 +159,57 @@ def auto_expose(detector): time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) -# --- fixtures --------------------------------------------------------------------------------- +@contextlib.contextmanager +def ready(detector): + """The camera ready to take frames inside a ``with`` block. -@pytest.fixture(scope="module", autouse=True) -def led_matrix(): - if not client.setup()["LEDMatrixs"]: - pytest.skip("the setup has no LED matrix") + An acquisition detector streams, and its exposure is set once, in the dark, + so that the dark, the lit and the switched-off frames share it. + The observation camera is left alone: it has no live view for the auto exposure to act on. + """ + if is_observation_camera(detector): + yield + return + with live_view(detector): + auto_expose(detector) + yield -@pytest.fixture(scope="module", params=["acquisition", "observation"]) -def camera(request): - """A camera that is ready to take frames; with it a test runs once per kind of camera. +def sees_switching(detector, switch): + """Switch the light on and off in front of one camera; ``switch(on)`` switches it. - The exposure is set once, in the dark, so that the dark and the lit frames share it. - The observation camera is left alone: it has no live view for the auto exposure to act on. + Returns what the camera did not see, as lines; empty when it saw both. """ - wanted = request.param == "observation" - names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] - if not names: - pytest.skip(f"the setup has no {request.param} camera") - detector = names[0] - status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) - if "error" in status or status.get("status") == "error": - pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") - if status.get("isMock") or str(status.get("model", "")).lower() == "mock": - pytest.skip(f"{detector}: ImSwitch served a mock camera") + with ready(detector): + dark, noise_floor, required = dark_baseline(detector) + switch(True) + lit = take_image(detector) + switch(False) + off = take_image(detector) + settings = exposure_and_gain(detector) + attach(f"{detector}: dark", dark) + attach(f"{detector}: on", lit) + attach(f"{detector}: off again", off) + on_change, off_change = image_difference(dark, lit), image_difference(dark, off) + print(f"\n{detector}: on changed {on_change:.2f}, off is {off_change:.2f} from dark, " + f"noise floor {noise_floor:.2f}, required {required:.2f}; brightness dark " + f"{brightness(dark):.2f}, on {brightness(lit):.2f}; {settings}") + missed = [] + if on_change < required: + missed.append(f"{detector}: on changed the image only by {on_change:.2f}, " + f"need >= {required:.2f} (noise floor {noise_floor:.2f}; {settings})") + if off_change >= required: + missed.append(f"{detector}: off is still {off_change:.2f} from dark, " + f"need < {required:.2f}") + return missed - all_lights_off() - if wanted: - yield detector - else: - with live_view(detector): - auto_expose(detector) - yield detector - all_lights_off() + +# --- fixtures --------------------------------------------------------------------------------- + +@pytest.fixture(scope="module", autouse=True) +def led_matrix(): + if not client.setup()["LEDMatrixs"]: + pytest.skip("the setup has no LED matrix") @pytest.fixture @@ -167,20 +226,12 @@ def test_all_leds_off_is_accepted(): client.get_json("/LEDMatrixController/setAllLEDOff", timeout=5) -def test_led_matrix_is_visible_to_camera(camera, dark): - unlit, noise_floor, required = dark_baseline(camera) - - client.get_json("/LEDMatrixController/setAllLED", { - "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, - "intensity_b": MATRIX_INTENSITY}) - time.sleep(LIGHT_SETTLE_S) - lit = take_image(camera) - - attach("dark", unlit) - attach("bright", lit) - change = image_difference(unlit, lit) - print(f"\nLED matrix @ {MATRIX_INTENSITY}: pixel_change={change:.2f} " - f"noise_floor={noise_floor:.2f} required={required:.2f}") - assert lit.getextrema()[1] > 0, "the LED matrix is on but every pixel is still 0" - assert change >= required, (f"LED matrix: image changed only by {change:.2f}; camera noise " - f"floor is {noise_floor:.2f}, need >= {required:.2f}") +def test_every_camera_sees_the_matrix_switch_on_and_off(dark): + found = cameras() + if not found: + pytest.skip("the setup has no camera that gives real frames") + missed = [] + # Every camera is measured before the verdict, so the report has the photos of all of them. + for detector in found: + missed += sees_switching(detector, set_matrix) + assert not missed, f"LED matrix @ {MATRIX_INTENSITY}:\n" + "\n".join(missed) diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py index af0c50636..32e4e4a23 100644 --- a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py @@ -1,11 +1,13 @@ -"""One LED of the matrix can be lit on its own. -The cameras see it, and it is dimmer than the whole matrix. +"""One LED of the matrix can be lit on its own, and every camera sees it go on and off. +It is dimmer than the whole matrix. SWITCHES LIGHT. +It passes only when every camera of the setup sees both switches. setLEDs lights exactly the LEDs it is given. -One LED must change the image by more than the camera's own noise, -and the whole matrix must give a brighter image than that one LED. +On: one LED changes the image by more than the camera's own noise. +Off: the image is back to dark, within that noise. +The whole matrix must give a brighter image than that one LED. The LED is the one closest to the optical axis (from the DPC LED layout), so that it lights the sample in brightfield; without the DPC controller it is the centre of the setup's Nx x Ny grid. @@ -19,7 +21,7 @@ from PIL import Image, ImageChops, ImageStat import hil_client as client -from hil_report import attach +from hil_report import attach, note SINGLE_INTENSITY = 255 # per colour, of setLEDs (0..255) MATRIX_INTENSITY = 255 # per colour, of setAllLED, the same as one LED @@ -45,6 +47,21 @@ def all_lights_off(): time.sleep(LIGHT_SETTLE_S) +def every_led_on(): + client.get_json("/LEDMatrixController/setAllLED", { + "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, + "intensity_b": MATRIX_INTENSITY}) + time.sleep(LIGHT_SETTLE_S) + + +def only_led_on(led): + """Only ``led`` on: setLEDs switches every other LED off.""" + client.get_json("/LEDMatrixController/setLEDs", { + "ledIds": str(led), "intensity_r": SINGLE_INTENSITY, "intensity_g": SINGLE_INTENSITY, + "intensity_b": SINGLE_INTENSITY}) + time.sleep(LIGHT_SETTLE_S) + + def central_led(): """Chain index of the LED closest to the optical axis. @@ -72,6 +89,22 @@ def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] +def cameras(): + """The cameras that give real frames. + A camera ImSwitch serves as a mock, or cannot report on, is left out and named in the report. + """ + found = [] + for detector in client.setup()["detectors"]: + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in status or status.get("status") == "error": + note(f"{detector} left out: getCameraStatus failed: {status.get('error')}") + elif status.get("isMock") or str(status.get("model", "")).lower() == "mock": + note(f"{detector} left out: ImSwitch served a mock camera") + else: + found.append(detector) + return found + + def take_image(detector): """One small greyscale frame (PIL) of either kind of camera.""" if is_observation_camera(detector): @@ -100,10 +133,18 @@ def brightness(image): return ImageStat.Stat(image).mean[0] +def exposure_and_gain(detector): + """ "exposure 20, gain 0" as the camera reports them; None for a value it does not report.""" + values = [client.get_json("/SettingsController/getDetectorParameter", + {"detectorName": detector, "parameterName": name}) + for name in ("exposure", "gain")] + return f"exposure {values[0]}, gain {values[1]}" + + def dark_baseline(detector): """Measure the camera noise with the scene unchanged. - Returns (last frame, noise floor, change one LED must exceed). + Returns (last frame, noise floor, change a light must exceed). """ previous = take_image(detector) drifts = [] @@ -147,6 +188,52 @@ def auto_expose(detector): time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) +def sees_one_led(detector, led): + """Every LED, then dark, then the one LED on and off, in front of one camera. + + The exposure is set on every LED, the brightest scene, so that no frame saturates; + all frames of the camera share it. + The observation camera has no live view for the auto exposure to act on. + Returns what the camera did not see, as lines; empty when it saw everything. + """ + observation = is_observation_camera(detector) + with contextlib.nullcontext() if observation else live_view(detector): + every_led_on() + if not observation: + auto_expose(detector) + every = take_image(detector) + all_lights_off() + dark, noise_floor, required = dark_baseline(detector) + only_led_on(led) + single = take_image(detector) + all_lights_off() + off = take_image(detector) + settings = exposure_and_gain(detector) + attach(f"{detector}: dark", dark) + attach(f"{detector}: LED {led} alone", single) + attach(f"{detector}: off again", off) + attach(f"{detector}: every LED", every) + on_change, off_change = image_difference(dark, single), image_difference(dark, off) + print(f"\n{detector}: LED {led} on changed {on_change:.2f}, " + f"off is {off_change:.2f} from dark, " + f"noise floor {noise_floor:.2f}, required {required:.2f}; brightness dark " + f"{brightness(dark):.2f}, single {brightness(single):.2f}, " + f"all {brightness(every):.2f}; {settings}") + missed = [] + if on_change < required: + missed.append(f"{detector}: LED {led} alone changed the image only by {on_change:.2f}, " + f"need >= {required:.2f} (noise floor {noise_floor:.2f}; {settings}) " + f"- setLEDs may not have lit it") + if off_change >= required: + missed.append(f"{detector}: off is still {off_change:.2f} from dark, " + f"need < {required:.2f}") + if brightness(every) <= brightness(single): + missed.append(f"{detector}: every LED ({brightness(every):.2f}) is not brighter than " + f"LED {led} alone ({brightness(single):.2f}) - setLEDs may have lit more " + f"than one LED, or the camera saturates") + return missed + + # --- fixtures --------------------------------------------------------------------------------- @pytest.fixture(scope="module", autouse=True) @@ -157,32 +244,6 @@ def led_matrix(): pytest.skip("this ImSwitch has no LEDMatrixController/setLEDs") -@pytest.fixture(scope="module", params=["acquisition", "observation"]) -def camera(request): - """A camera that is ready to take frames; with it a test runs once per kind of camera. - - The test sets the exposure itself, with every LED on, so that no frame saturates. - """ - wanted = request.param == "observation" - names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] - if not names: - pytest.skip(f"the setup has no {request.param} camera") - detector = names[0] - status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) - if "error" in status or status.get("status") == "error": - pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") - if status.get("isMock") or str(status.get("model", "")).lower() == "mock": - pytest.skip(f"{detector}: ImSwitch served a mock camera") - - all_lights_off() - if wanted: - yield detector - else: - with live_view(detector): - yield detector - all_lights_off() - - @pytest.fixture def dark(): """Every light off before and after the test.""" @@ -193,41 +254,14 @@ def dark(): # --- tests ------------------------------------------------------------------------------------ -def test_single_led_is_visible_and_dimmer_than_all(camera, dark): +def test_every_camera_sees_one_led_switch_on_and_off(dark): + found = cameras() + if not found: + pytest.skip("the setup has no camera that gives real frames") led, why = central_led() - - # 1. Every LED on; the exposure is set on this, the brightest scene, so nothing saturates. - # The observation camera has no live view for the auto exposure to act on. - client.get_json("/LEDMatrixController/setAllLED", { - "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, - "intensity_b": MATRIX_INTENSITY}) - time.sleep(LIGHT_SETTLE_S) - if not is_observation_camera(camera): - auto_expose(camera) - every = take_image(camera) - - # 2. Only the one LED: setLEDs switches every other LED off. - client.get_json("/LEDMatrixController/setLEDs", { - "ledIds": str(led), "intensity_r": SINGLE_INTENSITY, "intensity_g": SINGLE_INTENSITY, - "intensity_b": SINGLE_INTENSITY}) - time.sleep(LIGHT_SETTLE_S) - single = take_image(camera) - - # 3. Dark, at the same exposure: the noise the single LED must exceed. - all_lights_off() - unlit, noise_floor, required = dark_baseline(camera) - - attach("dark", unlit) - attach(f"LED {led} alone", single) - attach("every LED", every) - change = image_difference(unlit, single) - print(f"\nLED {led} ({why}): pixel_change={change:.2f} noise_floor={noise_floor:.2f} " - f"required={required:.2f}; brightness dark={brightness(unlit):.2f} " - f"single={brightness(single):.2f} all={brightness(every):.2f}") - assert change >= required, ( - f"LED {led} alone changed the image only by {change:.2f}; camera noise floor is " - f"{noise_floor:.2f}, need >= {required:.2f} - setLEDs may not have lit it") - assert brightness(every) > brightness(single), ( - f"every LED ({brightness(every):.2f}) is not brighter than LED {led} alone " - f"({brightness(single):.2f}) - setLEDs may have lit more than one LED, or the camera " - f"saturates") + note(f"LED {led}: {why}") + missed = [] + # Every camera is measured before the verdict, so the report has the photos of all of them. + for detector in found: + missed += sees_one_led(detector, led) + assert not missed, "\n".join(missed) diff --git a/imswitch/imcontrol/_test/hil/test_lightsource.py b/imswitch/imcontrol/_test/hil/test_lightsource.py index 82f9c2d11..3531bfcb7 100644 --- a/imswitch/imcontrol/_test/hil/test_lightsource.py +++ b/imswitch/imcontrol/_test/hil/test_lightsource.py @@ -1,9 +1,11 @@ -"""Each laser and LED can be switched on and off, and the cameras see the light of each LED. +"""Each laser and LED can be switched on and off, and every camera sees each LED go on and off. SWITCHES LIGHT. -A light counts as visible when it changes the image by more than the camera's own noise: -take a few dark frames, measure how much they differ, then compare a dark and a lit frame. +One case per LED; it passes only when every camera of the setup sees both switches. +On: the image changes by more than the camera's own noise. +Off: the image is back to dark, within that noise. +The noise: take a few dark frames and measure how much they differ. """ import base64 import contextlib @@ -14,7 +16,7 @@ from PIL import Image, ImageChops, ImageStat import hil_client as client -from hil_report import attach +from hil_report import attach, note LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time @@ -70,6 +72,22 @@ def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] +def cameras(): + """The cameras that give real frames. + A camera ImSwitch serves as a mock, or cannot report on, is left out and named in the report. + """ + found = [] + for detector in client.setup()["detectors"]: + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) + if "error" in status or status.get("status") == "error": + note(f"{detector} left out: getCameraStatus failed: {status.get('error')}") + elif status.get("isMock") or str(status.get("model", "")).lower() == "mock": + note(f"{detector} left out: ImSwitch served a mock camera") + else: + found.append(detector) + return found + + def take_image(detector): """One small greyscale frame (PIL) of either kind of camera.""" if is_observation_camera(detector): @@ -93,6 +111,19 @@ def image_difference(first, second): return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] +def brightness(image): + """Mean grey value of a frame.""" + return ImageStat.Stat(image).mean[0] + + +def exposure_and_gain(detector): + """ "exposure 20, gain 0" as the camera reports them; None for a value it does not report.""" + values = [client.get_json("/SettingsController/getDetectorParameter", + {"detectorName": detector, "parameterName": name}) + for name in ("exposure", "gain")] + return f"exposure {values[0]}, gain {values[1]}" + + def dark_baseline(detector): """Measure the camera noise with the scene unchanged. @@ -140,35 +171,52 @@ def auto_expose(detector): time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) -# --- fixtures --------------------------------------------------------------------------------- - -@pytest.fixture(scope="module", params=["acquisition", "observation"]) -def camera(request): - """A camera that is ready to take frames; with it a test runs once per kind of camera. +@contextlib.contextmanager +def ready(detector): + """The camera ready to take frames inside a ``with`` block. - The exposure is set once, in the dark, so that the dark and the lit frames share it. + An acquisition detector streams, and its exposure is set once, in the dark, + so that the dark, the lit and the switched-off frames share it. The observation camera is left alone: it has no live view for the auto exposure to act on. """ - wanted = request.param == "observation" - names = [name for name in client.setup()["detectors"] if is_observation_camera(name) == wanted] - if not names: - pytest.skip(f"the setup has no {request.param} camera") - detector = names[0] - status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) - if "error" in status or status.get("status") == "error": - pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") - if status.get("isMock") or str(status.get("model", "")).lower() == "mock": - pytest.skip(f"{detector}: ImSwitch served a mock camera") + if is_observation_camera(detector): + yield + return + with live_view(detector): + auto_expose(detector) + yield - all_lights_off() - if wanted: - yield detector - else: - with live_view(detector): - auto_expose(detector) - yield detector - all_lights_off() +def sees_switching(detector, switch): + """Switch the light on and off in front of one camera; ``switch(on)`` switches it. + + Returns what the camera did not see, as lines; empty when it saw both. + """ + with ready(detector): + dark, noise_floor, required = dark_baseline(detector) + switch(True) + lit = take_image(detector) + switch(False) + off = take_image(detector) + settings = exposure_and_gain(detector) + attach(f"{detector}: dark", dark) + attach(f"{detector}: on", lit) + attach(f"{detector}: off again", off) + on_change, off_change = image_difference(dark, lit), image_difference(dark, off) + print(f"\n{detector}: on changed {on_change:.2f}, off is {off_change:.2f} from dark, " + f"noise floor {noise_floor:.2f}, required {required:.2f}; brightness dark " + f"{brightness(dark):.2f}, on {brightness(lit):.2f}; {settings}") + missed = [] + if on_change < required: + missed.append(f"{detector}: on changed the image only by {on_change:.2f}, " + f"need >= {required:.2f} (noise floor {noise_floor:.2f}; {settings})") + if off_change >= required: + missed.append(f"{detector}: off is still {off_change:.2f} from dark, " + f"need < {required:.2f}") + return missed + + +# --- fixtures --------------------------------------------------------------------------------- @pytest.fixture def dark(): @@ -199,17 +247,12 @@ def test_lightsource_reports_active(name): @client.parametrize_from_rig("name", leds, "no LED among the light sources of the setup") -def test_light_source_is_visible_to_camera(name, camera, dark): - unlit, noise_floor, required = dark_baseline(camera) - - set_light(name, True) - lit = take_image(camera) - - attach("dark", unlit) - attach("bright", lit) - change = image_difference(unlit, lit) - print(f"\n{name}: pixel_change={change:.2f} noise_floor={noise_floor:.2f} " - f"required={required:.2f}") - assert lit.getextrema()[1] > 0, f"{name} is on but every pixel is still 0" - assert change >= required, (f"{name}: image changed only by {change:.2f}; camera noise floor " - f"is {noise_floor:.2f}, need >= {required:.2f}") +def test_every_camera_sees_the_led_switch_on_and_off(name, dark): + found = cameras() + if not found: + pytest.skip("the setup has no camera that gives real frames") + missed = [] + # Every camera is measured before the verdict, so the report has the photos of all of them. + for detector in found: + missed += sees_switching(detector, lambda on: set_light(name, on)) + assert not missed, f"{name}:\n" + "\n".join(missed) diff --git a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py index 8b2301a69..b6bda04ce 100644 --- a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py +++ b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py @@ -1,27 +1,17 @@ """Each motor axis moves 10 µm and back, and ImSwitch reports the position it moved to. -After that the stage drives to its home position. -MOVES REAL HARDWARE (10 µm, then to the end stops). +MOVES REAL HARDWARE (10 µm). -Every axis with homing switched on homes, Z first. -So the objective is away from the sample before X and Y move. -The stage stays at home, where the slide holder is out of the light path for the light tests. -When a test of this file failed, the axes after it do not home. - -homeAxis does not say whether the end stop was found. -So the homing only fails when ImSwitch answers with an error or not at all. -The FRAME calibration homes again and checks each axis. +The position is the step count of the firmware, not a measurement. +So this only shows that ImSwitch, the board and its bookkeeping follow the command. +motor_motion_camera shows in the camera that the stage really moved. """ -import time - import pytest import hil_client as client STEP_UM = 10 -SETTLE_S = 0.5 # wait before reading the position back -HOME_ORDER = "ZXYA" -HOME_EXTRA_S = 30 # seconds homeAxis may take longer than the axis's homeTimeout in the setup +MOVE_TIMEOUT = 60 # seconds a blocking 10 µm move may take def axes(): @@ -30,50 +20,23 @@ def axes(): if positioner["forPositioning"] for axis in positioner["axes"]] -def axes_to_home(): - """Every (positioner, axis) with homing switched on, in HOME_ORDER.""" - found = [] - for name, positioner in client.setup()["positioners"].items(): - properties = positioner["managerProperties"] - for axis in HOME_ORDER: - # as ESP32StageManager decides it: an end stop, or a fixed number of steps - homes = properties.get(f"home{axis}enabled") or properties.get(f"homeSteps{axis}") - if axis in positioner["axes"] and homes: - found.append((name, axis)) - return found - - def position(positioner, axis): return client.get_json("/PositionerController/getPositionerPositions")[positioner][axis] -@pytest.fixture(scope="module", autouse=True) -def failures_before(request): - """How many tests of the run had failed when this file started.""" - return request.session.testsfailed # pytest counts the failures of the run +def move(positioner, axis, distance): + """Move one axis by ``distance`` µm; returns once it has arrived.""" + client.get_json("/PositionerController/movePositioner", timeout=MOVE_TIMEOUT, params={ + "positionerName": positioner, "axis": axis, "dist": distance, "isBlocking": True}) @client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") def test_axis_moves_by_step(positioner, axis): - step = {"positionerName": positioner, "axis": axis, "dist": STEP_UM} - back = {"positionerName": positioner, "axis": axis, "dist": -STEP_UM} - before = position(positioner, axis) try: - client.get_json("/PositionerController/movePositioner", step) - time.sleep(SETTLE_S) + move(positioner, axis, STEP_UM) after = position(positioner, axis) assert after == pytest.approx(before + STEP_UM, abs=0.1), ( f"{positioner} {axis}: {before} -> {after}, expected {before + STEP_UM}") finally: - client.get_json("/PositionerController/movePositioner", back) - - -@client.parametrize_from_rig("positioner, axis", axes_to_home, "no axis has homing switched on") -def test_axis_homes(positioner, axis, failures_before, request): - if request.session.testsfailed > failures_before: - pytest.skip("not homing: a step or an axis before this one failed") - properties = client.setup()["positioners"][positioner]["managerProperties"] - timeout = properties.get(f"homeTimeout{axis}", 20000) / 1000 + HOME_EXTRA_S - client.get_json("/PositionerController/homeAxis", timeout=timeout, params={ - "positionerName": positioner, "axis": axis, "isBlocking": True}) + move(positioner, axis, -STEP_UM) diff --git a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py new file mode 100644 index 000000000..4d43252e4 --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py @@ -0,0 +1,302 @@ +"""The observation camera sees every axis move: X and Y shift the image, Z changes its scale. + +MOVES REAL HARDWARE (to the transport position, then 3 mm per axis and back). +SWITCHES LIGHT. + +It runs after stage_homing, so that its absolute move goes to a referenced position. +At the transport position ImSwitch switches the Z hard limits off, and the turret goes to slot 0. +The LED matrix lights the sample. +Then every axis moves out and back once, and three tests judge that one measurement: + +- test_axis_motion_is_visible (every axis): the image changed more than its noise +- test_axis_motion_direction (X, Y): +X moves the image right, +Y moves it down +- test_z_motion_changes_scale (Z): the image got larger or smaller + +The position ImSwitch reports is only a step count. +This file is what shows that the stage really moved. +""" +import base64 +import functools +import io +import time + +import numpy as np +import pytest +from PIL import Image + +import hil_client as client +from hil_report import attach + +# Distances are in µm, times in seconds. +DISTANCE_UM = 3000 +Z_DISTANCE_UM = 5000 +Z_DIRECTION = -1 # away from Z home: at the transport position the limits are off +SPEED = 15000 +SETTLE_S = 0.5 # wait after a move, before the frame +TRANSPORT_SPEED = 20000 # above 30000 the stage loses steps +TRANSPORT_TIMEOUT = 120 +TURRET_TIMEOUT = 120 +MATRIX_INTENSITY = 255 # the firmware's maximum per colour +MATRIX_SETTLE_S = 3.5 # wait after switching the matrix on, before the first frame + +EXPECTED_DIRECTION = {"X": "right", "Y": "down"} # of the image, when the axis moves by +distance +MIN_RATIO = 1.8 # image change over noise that counts as movement, X and Y +MIN_RATIO_AZ = 1.25 # the same for A and Z, which change the image less +ROI = (150, 355, 150, 340) # X/Y are judged in frame[y1:y2, x1:x2] of the 640x360 image +TOP_CROP_PERCENT = 25 # A/Z are judged below this top share of the image +Z_SCALE_MIN = 0.90 # the image scales that are tried to find the Z zoom +Z_SCALE_MAX = 1.10 +Z_SCALE_STEP = 0.002 +Z_MIN_SCALE_CHANGE = 0.001 +Z_SCALE_NOISE_RATIO = 1.4 + +SNAP = {"slot_id": "1", "camera_name": "hil_motion"} # camera_name: folder ImSwitch saves to + + +# --- stage ------------------------------------------------------------------------------------ + +def axes(): + """Every (positioner, axis) pair of the setup, e.g. ("ESP32Stage", "X").""" + return [(name, axis) for name, positioner in client.setup()["positioners"].items() + if positioner["forPositioning"] for axis in positioner["axes"]] + + +def xy_axes(): + return [pair for pair in axes() if pair[1].upper() in EXPECTED_DIRECTION] + + +def z_axes(): + return [pair for pair in axes() if pair[1].upper() == "Z"] + + +def move(positioner, axis, distance): + """Move one axis by ``distance`` µm and wait until it has arrived and settled.""" + client.get_json("/PositionerController/movePositioner", timeout=60, params={ + "positionerName": positioner, "axis": axis, "dist": distance, + "isBlocking": True, "speed": SPEED}) + time.sleep(SETTLE_S) + + +def wait_until_stopped(): + """The positions once two reads agree; some endpoints answer before the stage has arrived.""" + previous = client.get_json("/PositionerController/getPositionerPositions") + deadline = time.monotonic() + TRANSPORT_TIMEOUT + while time.monotonic() < deadline: + time.sleep(0.5) + current = client.get_json("/PositionerController/getPositionerPositions") + if current == previous: + break + previous = current + return previous + + +def park_at_transport(): + """Move to the transport position and turn the turret to slot 0; returns the positions.""" + client.get_json("/PositionerController/moveToTransportPosition", timeout=TRANSPORT_TIMEOUT, + params={"speed": TRANSPORT_SPEED, "isBlocking": True}) + wait_until_stopped() + if client.setup()["objective"]: + status = client.get_json("/ObjectiveController/getstatus") + if status.get("isActive") and status.get("hasMotor") and status["slotConfigured"][0]: + # skipZ: the turret must not apply the slot's Z offset to the parked stage. + started = client.get_json("/ObjectiveController/moveToObjective", + {"slot": 0, "skipZ": True}) + assert started.get("accepted"), f"the turret refused slot 0: {started}" + + def turned(): + # moveToObjective only starts the move; the status tells when it is done. + now = client.get_json("/ObjectiveController/getstatus") + return (not now.get("isMovingObjective") and + now.get("lastCompletedObjectiveRequestId") == started["requestId"]) + + assert client.wait_until(turned, TURRET_TIMEOUT), ( + f"the turret did not reach slot 0 in {TURRET_TIMEOUT}s") + return wait_until_stopped() + + +# --- observation camera ----------------------------------------------------------------------- + +def frame(): + """One full-size greyscale frame of the observation camera, as a float array.""" + body = client.post_json("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) + image = Image.open(io.BytesIO(base64.b64decode(body["imageBase64"]))).convert("L") + return np.asarray(image, dtype=np.float32) + + +# --- image maths: frames are greyscale float arrays ------------------------------------------- + +def difference(before, after): + """Mean absolute grey-value difference.""" + assert before.shape == after.shape + return float(np.mean(np.abs(after - before))) + + +def roi(image): + """The part of the frame in which X/Y motion is judged (ROI).""" + y1, y2, x1, x2 = ROI + height, width = image.shape + assert 0 <= x1 < x2 <= width, f"invalid ROI x-range {x1}:{x2} for image width {width}" + assert 0 <= y1 < y2 <= height, f"invalid ROI y-range {y1}:{y2} for image height {height}" + return image[y1:y2, x1:x2] + + +def below_top(image): + """The frame without its top TOP_CROP_PERCENT, where A/Z motion is judged.""" + return image[image.shape[0] * TOP_CROP_PERCENT // 100:, :] + + +def shift(before, after): + """How far AFTER is moved against BEFORE: (dx, dy, peak) in pixels, +dx right, +dy down. + + Phase correlation: the peak of the correlation of the two images lies at their shift. + Its height says how clear the match is. + """ + assert before.shape == after.shape + before, after = before.astype(np.float64), after.astype(np.float64) + # Fade the edges out, or the FFT takes the jump from one edge to the other for structure. + window = np.hanning(before.shape[0])[:, None] * np.hanning(before.shape[1])[None, :] + f_before = np.fft.fft2((before - before.mean()) * window) + f_after = np.fft.fft2((after - after.mean()) * window) + cross_power = np.conj(f_before) * f_after + cross_power /= np.maximum(np.abs(cross_power), 1e-12) + correlation = np.fft.fftshift(np.abs(np.fft.ifft2(cross_power))) + peak_y, peak_x = np.unravel_index(np.argmax(correlation), correlation.shape) + dy = peak_y - correlation.shape[0] // 2 + dx = peak_x - correlation.shape[1] // 2 + return float(dx), float(dy), float(correlation[peak_y, peak_x]) + + +def direction(dx, dy, min_shift=2): + """ "right", "left", "down" or "up"; None if the shift is under ``min_shift`` pixels.""" + if np.hypot(dx, dy) < min_shift: + return None + if abs(dx) > abs(dy): + return "right" if dx > 0 else "left" + return "down" if dy > 0 else "up" + + +def scale(before, after): + """The zoom of AFTER against BEFORE; above 1 means the image got larger. + + Tries every scale from Z_SCALE_MIN to Z_SCALE_MAX. + For each, BEFORE is zoomed by it and cut or padded back to the frame size. + The scale whose result matches AFTER best is kept. + """ + height, width = before.shape + image = Image.fromarray(np.ascontiguousarray(before, dtype=np.float32)) + best_scale, best_peak = 1.0, -1.0 + for candidate in np.arange(Z_SCALE_MIN, Z_SCALE_MAX + Z_SCALE_STEP / 2, Z_SCALE_STEP): + zoomed = np.asarray(image.resize((max(1, round(width * candidate)), + max(1, round(height * candidate))), Image.BILINEAR)) + zoomed_height, zoomed_width = zoomed.shape + # Offsets in the zoomed image (when it is larger) and in the frame (when it is smaller). + from_y, to_y = max(0, (zoomed_height - height) // 2), max(0, (height - zoomed_height) // 2) + from_x, to_x = max(0, (zoomed_width - width) // 2), max(0, (width - zoomed_width) // 2) + h, w = min(zoomed_height, height), min(zoomed_width, width) + resized = np.full(before.shape, float(np.median(before)), dtype=np.float32) + resized[to_y:to_y + h, to_x:to_x + w] = zoomed[from_y:from_y + h, from_x:from_x + w] + peak = shift(resized, after)[2] + if peak > best_peak: + best_scale, best_peak = round(float(candidate), 6), peak + return best_scale + + +# --- the measurement and its tests ------------------------------------------------------------ + +@pytest.fixture(scope="module", autouse=True) +def parked_and_lit(): + """Check the camera before anything moves, then park the stage and switch the matrix on.""" + setup = client.setup() + cameras = [name for name, detector in setup["detectors"].items() + if not detector["forAcquisition"]] + if not cameras: + pytest.skip("the setup has no observation camera") + status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": cameras[0]}) + if "error" in status or status.get("status") == "error": + pytest.skip(f"{cameras[0]}: getCameraStatus failed: {status.get('error')}") + if status.get("isMock") or status.get("isConnected") is False: + pytest.skip(f"{cameras[0]} is a mock camera or not connected: {status}") + response = client.post("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) + if response.status_code != 200: + pytest.skip(f"{cameras[0]} cannot deliver an image: {response.text}") + roi(frame()) # fails here if ROI does not fit the image + + print(f"\ntransport position reached: {park_at_transport()}") + has_matrix = bool(setup["LEDMatrixs"]) + if has_matrix: + client.get_json("/LEDMatrixController/setAllLED", { + "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, + "intensity_b": MATRIX_INTENSITY}) + time.sleep(MATRIX_SETTLE_S) + yield + if has_matrix: + client.get_json("/LEDMatrixController/setAllLEDOff") + + +@functools.lru_cache(maxsize=None) # each axis moves once; the tests share the result +def measure(positioner, axis): + """Move one axis out and back, and return what the frames before and after show.""" + is_xy = axis.upper() in EXPECTED_DIRECTION + is_z = axis.upper() == "Z" + distance = Z_DISTANCE_UM * Z_DIRECTION if is_z else DISTANCE_UM + # X and Y shift the image, so they are judged in a region that stays on the sample. + region = roi if is_xy else below_top + + still = frame() + time.sleep(SETTLE_S) + before = frame() + move(positioner, axis, distance) + try: + after = frame() + finally: + move(positioner, axis, -distance) + attach(f"{axis} before", before) + attach(f"{axis} after {distance:+d} um", after) + + noise = difference(region(still), region(before)) + change = difference(region(before), region(after)) + result = {"noise": noise, "change": change, "ratio": change / max(noise, 1e-6)} + if is_xy: + dx, dy, peak = shift(region(before), region(after)) + result["direction"] = direction(dx, dy) + result["shift"] = f"dx={dx:+.1f}px, dy={dy:+.1f}px, peak={peak:.4f}" + if is_z: + result["scale"] = scale(roi(before), roi(after)) + result["scale_change"] = abs(result["scale"] - 1) + result["scale_noise"] = abs(scale(roi(still), roi(before)) - 1) + print(f"\n{positioner} {axis} {distance:+d} um: {result}") + return result + + +@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") +def test_axis_motion_is_visible(positioner, axis): + result = measure(positioner, axis) + required = MIN_RATIO if axis.upper() in EXPECTED_DIRECTION else MIN_RATIO_AZ + assert result["ratio"] >= required, ( + f"{positioner} {axis}: movement was not clearly visible. change={result['change']:.3f}, " + f"noise={result['noise']:.3f}, ratio={result['ratio']:.2f}x, required={required:.2f}x") + + +@client.parametrize_from_rig("positioner, axis", xy_axes, "the setup has no X/Y axes") +def test_axis_motion_direction(positioner, axis): + """Only the wrong direction fails. A shift too small to measure skips.""" + result = measure(positioner, axis) + if result["direction"] is None: + pytest.skip(f"{positioner} {axis}: no clear translation ({result['shift']})") + expected = EXPECTED_DIRECTION[axis.upper()] + assert result["direction"] == expected, ( + f"{positioner} {axis}: image moved {result['direction']}, expected {expected} " + f"({result['shift']})") + + +@client.parametrize_from_rig("positioner, axis", z_axes, "the setup has no Z axis") +def test_z_motion_changes_scale(positioner, axis): + """Larger or smaller does not matter. An unclear scale skips as long as the move was seen.""" + result = measure(positioner, axis) + clear = (result["scale_change"] >= Z_MIN_SCALE_CHANGE + and result["scale_change"] >= result["scale_noise"] * Z_SCALE_NOISE_RATIO) + evidence = (f"scale={result['scale']:.4f}, change={result['scale_change']:.4f}, " + f"noise={result['scale_noise']:.4f}, ratio={result['ratio']:.2f}x") + if not clear and result["ratio"] >= MIN_RATIO_AZ: + pytest.skip(f"{positioner} {axis}: moved, but the scale change is unclear. {evidence}") + assert clear, f"{positioner} {axis}: no scale change and no movement seen. {evidence}" diff --git a/imswitch/imcontrol/_test/hil/test_stage_homing.py b/imswitch/imcontrol/_test/hil/test_stage_homing.py new file mode 100644 index 000000000..94b8b077a --- /dev/null +++ b/imswitch/imcontrol/_test/hil/test_stage_homing.py @@ -0,0 +1,71 @@ +"""The stage homes Z, X and Y as "Safe Global Homing" does, and every axis reports done. + +MOVES REAL HARDWARE: Z, X and Y drive to their end stops. + +This is the button "Start homing" under FRAME settings: the endpoint startFrameHoming. +It homes Z and lifts it clear of the bottom, then homes X and Y. +At the end X and Y go to the transport position, and Z goes back to its height from before. +That is where motor_motion_camera and the light tests find the stage. +The turret (A) is not homed here; the FRAME calibration homes it. + +The test passes when the homing ends as "done" with Z, X and Y "done", as the button shows it. +The positions at the start and at the end are in the report. +""" +import pytest + +import hil_client as client +from hil_report import note + +HOME_ORDER = "ZXY" # the axes startFrameHoming homes, in its order +POLL_S = 0.5 # seconds between two status reads while the stage homes +START_TIMEOUT = 10 # seconds the homing thread may take to start +HOME_EXTRA_S = 120 # seconds the whole homing may take beyond the homeTimeouts of the setup +DEFAULT_HOME_TIMEOUT_MS = 20000 # as ESP32StageManager, when the setup sets no homeTimeout + + +def positioner_to_home(): + """(name, managerProperties) of the first positioner with homing on for Z, X or Y.""" + for name, positioner in client.setup()["positioners"].items(): + properties = positioner["managerProperties"] + if any(properties.get(f"home{axis}enabled") for axis in HOME_ORDER): + return name, properties + return None, None + + +def homing_state(positioner): + return client.get_json("/PositionerController/getFrameHomingState", + {"positionerName": positioner}) + + +def positions(positioner): + return client.get_json("/PositionerController/getPositionerPositions")[positioner] + + +def test_stage_homes_with_safe_global_homing(): + positioner, properties = positioner_to_home() + if positioner is None: + pytest.skip("no positioner has homing switched on for Z, X or Y") + if homing_state(positioner)["active"]: + pytest.skip("a homing is already running") + timeout = HOME_EXTRA_S + sum( + properties.get(f"homeTimeout{axis}", DEFAULT_HOME_TIMEOUT_MS) / 1000 for axis in HOME_ORDER) + + note(f"positions at the start: {positions(positioner)}") + started = client.get_json("/PositionerController/startFrameHoming", + {"positionerName": positioner, "isBlocking": False}) + assert started.get("success"), f"startFrameHoming refused: {started}" + # The homing starts in a thread; until then the state is still the one of the last homing. + assert client.wait_until(lambda: homing_state(positioner)["active"], START_TIMEOUT), ( + f"the homing did not start within {START_TIMEOUT}s") + ended = client.wait_until(lambda: not homing_state(positioner)["active"], timeout, + interval=POLL_S) + state = homing_state(positioner) + if not ended: + client.get_json("/PositionerController/cancelFrameHoming", {"positionerName": positioner}) + pytest.fail(f"the homing did not end within {timeout:.0f}s, in phase " + f"{state['phase']!r}; it was cancelled") + note(f"positions at the end: {positions(positioner)}") + + assert state["phase"] == "done", f"the homing ended as {state['phase']!r}: {state['message']}" + not_done = [axis for axis in HOME_ORDER if state["axes"].get(axis) != "done"] + assert not not_done, f"not homed: {', '.join(not_done)} ({state['axes']})" diff --git a/imswitch/imcontrol/_test/unit/test_hil_reporting.py b/imswitch/imcontrol/_test/unit/test_hil_reporting.py index 1f81786a9..1648f1ad8 100644 --- a/imswitch/imcontrol/_test/unit/test_hil_reporting.py +++ b/imswitch/imcontrol/_test/unit/test_hil_reporting.py @@ -80,6 +80,39 @@ def fail(*args): assert hil_report.report_error == "broken PDF" assert not (tmp_path / "hil-report.pdf").exists() assert "broken PDF" in (tmp_path / "summary.md").read_text() + assert "hil-report.pdf` in the artifact" not in (tmp_path / "summary.md").read_text() + + +def test_a_long_image_list_fits_on_the_pages(tmp_path, monkeypatch): + # Run 43896090621: the pallet text in one table cell was taller than a page (LayoutError). + images = [f"ghcr.io/openuc2/image-{number}:sha-{number:07d}" for number in range(200)] + monkeypatch.setenv("HIL_IMAGES", "\n".join(images)) + results = {"test_board_link.py::test_it": {"status": "passed", "duration": 1., "details": ""}} + hil_pdf.write_pdf(tmp_path / "hil-report.pdf", "FRAME.json", 0, results, {}, {}, {}, []) + text = "".join(page.extract_text() for page in PdfReader(tmp_path / "hil-report.pdf").pages) + assert images[0] in text and images[-1] in text + + +def test_a_long_output_fits_on_the_pages(tmp_path): + # Many failed cases of one file: their lines must not end up in one cell taller than a page. + results = {f"test_motor.py::test_it[{axis}{number}]": { + "status": "failed", "duration": 1., "details": "E moved by 0\n" * 12} + for axis in "XYZA" for number in range(10)} + hil_pdf.write_pdf(tmp_path / "hil-report.pdf", "FRAME.json", 0, results, {}, {}, {}, []) + assert len(PdfReader(tmp_path / "hil-report.pdf").pages) > 2 + + +def test_summary_has_one_row_per_test_file(): + hil_report.reset() + hil_report._results.update({ + "test_board_link.py::test_a": {"status": "passed", "duration": 1., "details": ""}, + "test_lightsource.py::test_a[LED]": {"status": "failed", "duration": 2., + "details": "E LED: not seen"}, + "test_lightsource.py::test_b[LED]": {"status": "passed", "duration": 3., "details": ""}}) + lines = hil_report.summary("FRAME.json").splitlines() + assert "| 1 | board_link | passed | 1 passed | 1 s |" in lines + assert "| 2 | lightsource | **failed** | 1 failed, 1 passed | 5 s |" in lines + assert any("LED: not seen" in line for line in lines) def test_stop_timeout_is_an_error(calibration_module, monkeypatch): @@ -123,7 +156,8 @@ def test_failed_calibration_pdf_is_collected(calibration_module, monkeypatch, tm (notes,) = hil_report._notes.values() assert notes[0] == "The calibration ended as failed: no focus" assert "failed: no focus" in hil_report.summary("FRAME.json") - assert not list(tmp_path.iterdir()) # kept for hil-report.pdf, not written as a file + # Also saved on its own, so it survives a hil-report.pdf that cannot be written. + assert (tmp_path / "frame_calibration.pdf").read_bytes() == data def test_calibration_progress_is_one_line_per_start_and_end(calibration_module): From 1d1b7c0d4736b4f95ab38317031ccabcf54f88dc Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Tue, 17 Nov 2026 09:09:39 +0100 Subject: [PATCH 07/10] refine camera and light source tests, and adjust motion assertions --- imswitch/imcontrol/_test/hil/README.md | 6 +- imswitch/imcontrol/_test/hil/hil_report.py | 7 +- .../imcontrol/_test/hil/test_board_link.py | 3 +- .../_test/hil/test_camera_capture.py | 13 +- .../_test/hil/test_firmware_server.py | 20 +- .../_test/hil/test_frame_calibration.py | 16 +- .../imcontrol/_test/hil/test_ledmatrix.py | 36 +++- .../_test/hil/test_ledmatrix_single.py | 45 +++-- .../imcontrol/_test/hil/test_lightsource.py | 34 +++- .../_test/hil/test_motor_axis_move.py | 3 + .../_test/hil/test_motor_motion_camera.py | 184 +++--------------- 11 files changed, 153 insertions(+), 214 deletions(-) diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md index 17b8f9945..8dc30a495 100644 --- a/imswitch/imcontrol/_test/hil/README.md +++ b/imswitch/imcontrol/_test/hil/README.md @@ -13,7 +13,7 @@ Each test file says at the top of its docstring what it checks and what it does | `camera_capture` | each camera takes a picture as large as its sensor | reads | | `motor_axis_move` | each axis moves 10 µm and back, and ImSwitch reports the position it moved to | **moves** (10 µm) | | `stage_homing` | "Safe Global Homing" (`startFrameHoming`) homes Z, X and Y and reports each as done | **moves** (to the end stops, then to the transport position) | -| `motor_motion_camera` | the observation camera sees every axis move: X and Y shift the image the right way, Z changes its scale | **moves** (transport position, 3 mm per axis), **light** | +| `motor_motion_camera` | the observation camera sees every axis move: the image changes more than its noise | **moves** (transport position, 3 to 5 mm per axis), **light** | | `lightsource` | each laser and LED switches on and off; every camera sees each LED go on and off | **light** | | `ledmatrix` | every camera sees the LED matrix go on and off | **light** | | `ledmatrix_single` | one LED lights on its own (`setLEDs`), every camera sees it go on and off, and it is dimmer than the whole matrix | **light** | @@ -21,6 +21,7 @@ Each test file says at the top of its docstring what it checks and what it does Hardware a setup does not have skips its tests. Hardware that is there but does not work fails. +A camera of the setup that ImSwitch serves as a mock fails `camera_capture`: the real one did not start. They run in the order of the table: the boards, the cameras, the motors, the lights, then the calibration. The homing ends at the transport position, and the motion and light tests run there. @@ -28,7 +29,7 @@ The order is the list `ORDER` in `conftest.py`. A light test has one case per light, not one per camera. It passes only when every camera of the setup sees the light go on and go off again. -A camera that ImSwitch serves as a mock, or that cannot report its status, is left out and named in the report. +A camera that ImSwitch serves as a mock, that cannot report its status or that cannot give frames is left out and named in the report. Some tests do not start after a failure; they are skipped and say which test failed. The table is `NEEDS` in `conftest.py`: @@ -130,6 +131,7 @@ ImSwitch parses the file before it answers, so a field the file leaves out comes | `objective` | whether there is an objective turret | So a rig with other hardware needs another setup file in ImSwitch, not other tests. +The exception is `Z_DIRECTION` in `motor_motion_camera`: which way Z is free is a constant at its top. ## Writing a test diff --git a/imswitch/imcontrol/_test/hil/hil_report.py b/imswitch/imcontrol/_test/hil/hil_report.py index 153cfdce8..0efd351f9 100644 --- a/imswitch/imcontrol/_test/hil/hil_report.py +++ b/imswitch/imcontrol/_test/hil/hil_report.py @@ -134,8 +134,11 @@ def summary(setup_file): lines.append("") for test, result in _results.items(): if result["status"] in ("failed", "error"): - last_line = (result["details"].strip().splitlines() or [""])[-1] - lines.append(f"- **{result['status']}** `{test}`: {last_line[:300]}") + # The first "E ..." line of a pytest traceback is the assertion's message; + # a problem outside the tests has no such line, there the last line says it. + details = result["details"].strip().splitlines() or [""] + errors = [line[1:].strip() for line in details if line.startswith("E ")] + lines.append(f"- **{result['status']}** `{test}`: {(errors or details[-1:])[0][:300]}") for file, notes in _notes.items(): for text in notes: lines.append(f"- `{file}`: {text}") diff --git a/imswitch/imcontrol/_test/hil/test_board_link.py b/imswitch/imcontrol/_test/hil/test_board_link.py index 8177ead92..09eb90b72 100644 --- a/imswitch/imcontrol/_test/hil/test_board_link.py +++ b/imswitch/imcontrol/_test/hil/test_board_link.py @@ -7,7 +7,8 @@ def test_uc2_board_connected(): - connected = client.get_json("/UC2ConfigController/is_connected", timeout=5) + # Not is_connected: that one only says that ImSwitch answers, it is always true. + connected = client.get_json("/UC2ConfigController/uc2_board_is_connected", timeout=5) assert connected is True, "UC2/ESP32 board is not reported as connected" diff --git a/imswitch/imcontrol/_test/hil/test_camera_capture.py b/imswitch/imcontrol/_test/hil/test_camera_capture.py index fc91c498e..2beff4835 100644 --- a/imswitch/imcontrol/_test/hil/test_camera_capture.py +++ b/imswitch/imcontrol/_test/hil/test_camera_capture.py @@ -28,12 +28,15 @@ def is_observation_camera(detector): def camera_status(detector): - """getCameraStatus; skips the test if the camera has an error or is ImSwitch's mock camera.""" + """getCameraStatus; fails the test if the camera has an error or is ImSwitch's mock camera. + + The setup names the camera, so a mock in its place means the real one did not start. + """ status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) - if "error" in status or status.get("status") == "error": - pytest.skip(f"{detector}: getCameraStatus failed: {status.get('error')}") - if status.get("isMock") or str(status.get("model", "")).lower() == "mock": - pytest.skip(f"{detector}: ImSwitch served a mock camera (model={status.get('model')!r})") + assert "error" not in status and status.get("status") != "error", ( + f"{detector}: getCameraStatus failed: {status.get('error')}") + assert not status.get("isMock") and str(status.get("model", "")).lower() != "mock", ( + f"{detector}: ImSwitch served a mock camera (model={status.get('model')!r})") return status diff --git a/imswitch/imcontrol/_test/hil/test_firmware_server.py b/imswitch/imcontrol/_test/hil/test_firmware_server.py index e0ec80b11..c2ceac5dc 100644 --- a/imswitch/imcontrol/_test/hil/test_firmware_server.py +++ b/imswitch/imcontrol/_test/hil/test_firmware_server.py @@ -6,6 +6,8 @@ checkFirmwareUpdates is how ImSwitch compares the server's version.json with each board. To flash before the tests, start the suite with --sync-firmware. """ +import time + import pytest import hil_client as client @@ -28,11 +30,19 @@ def scan_came_back_empty(result): @pytest.fixture(scope="module") def check(): - """The answer of checkFirmwareUpdates, asked once: it scans the CAN bus.""" - result = client.get_json("/UC2ConfigController/checkFirmwareUpdates", - {"timeout": SCAN_TIMEOUT}, timeout=60) - assert not scan_came_back_empty(result), ( - "the CAN scan came back empty: no node listed, the master without canId") + """The answer of checkFirmwareUpdates, kept for the file: every call scans the CAN bus. + + Asked up to three times, because the CAN scan sometimes is empty. + """ + for _ in range(3): + result = client.get_json("/UC2ConfigController/checkFirmwareUpdates", + {"timeout": SCAN_TIMEOUT}, timeout=60) + if not scan_came_back_empty(result): + break + time.sleep(3) + else: + pytest.fail("the CAN scan came back empty three times: " + "no node listed, the master without canId") print() for device in result["devices"]: print(f"{label(device)}: {device.get('installed_version') or 'no version'}, " diff --git a/imswitch/imcontrol/_test/hil/test_frame_calibration.py b/imswitch/imcontrol/_test/hil/test_frame_calibration.py index 52a9abd75..64673ef5f 100644 --- a/imswitch/imcontrol/_test/hil/test_frame_calibration.py +++ b/imswitch/imcontrol/_test/hil/test_frame_calibration.py @@ -227,14 +227,14 @@ def test_calibration_finishes(calibration): def test_every_step_succeeds(calibration): """Optional steps may fail without stopping the calibration; this test lists them.""" - failed = [f"{step['title']}: {step['detail']}" for step in calibration["steps"] - if step["status"] in ("failed", "aborted")] - assert not failed, "steps that failed:\n" + "\n".join(failed) - warned = [f"{step['title']}: {'; '.join(step['warnings'])}" for step in calibration["steps"] - if step["warnings"]] - if warned: - print("\nwarnings:\n" + "\n".join(warned)) + # Notes, not prints: a print only shows when the test fails. + for step in calibration["steps"]: + if step["warnings"]: + hil_report.note(f"Warning in {step['title']}: {'; '.join(step['warnings'])}") # A skipped step did not test its part of the rig, e.g. the turret without a second objective. skipped = [step["title"] for step in calibration["steps"] if step["status"] == "skipped"] if skipped: - print("\nskipped, so not tested:\n" + "\n".join(skipped)) + hil_report.note(f"Skipped by the calibration, so not tested: {', '.join(skipped)}") + failed = [f"{step['title']}: {step['detail']}" for step in calibration["steps"] + if step["status"] in ("failed", "aborted")] + assert not failed, "steps that failed:\n" + "\n".join(failed) diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix.py b/imswitch/imcontrol/_test/hil/test_ledmatrix.py index 823a5a405..049ce695d 100644 --- a/imswitch/imcontrol/_test/hil/test_ledmatrix.py +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix.py @@ -4,7 +4,8 @@ It passes only when every camera of the setup sees both switches. On: the image changes by more than the camera's own noise. -Off: the image is back to dark, within that noise. +Off: the image is closer to dark than to the lit image. +Only differences between frames are judged, never a brightness by itself. The noise: take a few dark frames and measure how much they differ. """ import base64 @@ -18,13 +19,15 @@ import hil_client as client from hil_report import attach, note -MATRIX_INTENSITY = 500 # per colour, of setAllLED -LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it +MATRIX_INTENSITY = 255 # per colour, of setAllLED (0..255) +# Wait after switching a light, before the next frame. +# The observation camera sets its exposure by itself and needs more than a second for it. +LIGHT_SETTLE_S = 1.5 AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time FRAME_RESIZE = 0.25 # the frames are compared at this share of their size # The matrix must change the image by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. # The noise is the largest difference between NOISE_SAMPLES dark frames. -MIN_CHANGE = 1.5 +MIN_CHANGE = 0.5 NOISE_FACTOR = 1.5 NOISE_SAMPLES = 6 NOISE_DELAY_S = 0.5 @@ -56,6 +59,10 @@ def set_matrix(on): # An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. # The observation camera ("forAcquisition": false) gives them at any time. +class LeftOut(Exception): + """A camera that cannot give frames now; the test leaves it out and names it in the report.""" + + def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] @@ -83,7 +90,7 @@ def take_image(detector): response = client.post("/ExperimentController/snapOverviewImage", timeout=60, params={"slot_id": "1", "camera_name": "hil_ledmatrix"}) if response.status_code == 400: - pytest.skip(f"observation camera not connected: {response.text}") + raise LeftOut(f"observation camera not connected: {response.text}") raw = base64.b64decode(client.json_of(response)["imageBase64"]) frame = Image.open(io.BytesIO(raw)).convert("L") return frame.resize((max(1, int(frame.width * FRAME_RESIZE)), @@ -141,7 +148,7 @@ def live_view(detector): status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, timeout=60).get("status") if status == "long_exposure": - pytest.skip(f"{detector}: exposure too long for live view") + raise LeftOut("exposure too long for live view") assert status in ("success", "already_running"), ( f"{detector}: startLiveView answered {status!r}") time.sleep(0.4) @@ -198,9 +205,11 @@ def sees_switching(detector, switch): if on_change < required: missed.append(f"{detector}: on changed the image only by {on_change:.2f}, " f"need >= {required:.2f} (noise floor {noise_floor:.2f}; {settings})") - if off_change >= required: + # Off is judged against on, not against the noise: + # the observation camera's own exposure drifts after a bright light. + if off_change >= on_change / 2: missed.append(f"{detector}: off is still {off_change:.2f} from dark, " - f"need < {required:.2f}") + f"need < {on_change / 2:.2f} (half of what on changed)") return missed @@ -230,8 +239,15 @@ def test_every_camera_sees_the_matrix_switch_on_and_off(dark): found = cameras() if not found: pytest.skip("the setup has no camera that gives real frames") - missed = [] + missed, measured = [], 0 # Every camera is measured before the verdict, so the report has the photos of all of them. for detector in found: - missed += sees_switching(detector, set_matrix) + try: + missed += sees_switching(detector, set_matrix) + measured += 1 + except LeftOut as reason: + note(f"{detector} left out: {reason}") + all_lights_off() assert not missed, f"LED matrix @ {MATRIX_INTENSITY}:\n" + "\n".join(missed) + if not measured: + pytest.skip("no camera of the setup could give frames") diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py index 32e4e4a23..614abad9e 100644 --- a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py +++ b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py @@ -6,8 +6,9 @@ It passes only when every camera of the setup sees both switches. setLEDs lights exactly the LEDs it is given. On: one LED changes the image by more than the camera's own noise. -Off: the image is back to dark, within that noise. -The whole matrix must give a brighter image than that one LED. +Off: the image is closer to dark than to the lit image. +Only differences between frames are judged, never a brightness by itself. +The whole matrix must change the image more than that one LED. The LED is the one closest to the optical axis (from the DPC LED layout), so that it lights the sample in brightfield; without the DPC controller it is the centre of the setup's Nx x Ny grid. @@ -24,13 +25,15 @@ from hil_report import attach, note SINGLE_INTENSITY = 255 # per colour, of setLEDs (0..255) -MATRIX_INTENSITY = 255 # per colour, of setAllLED, the same as one LED -LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it +MATRIX_INTENSITY = 255 # per colour, of setAllLED (0..255), the same as one LED +# Wait after switching a light, before the next frame. +# The observation camera sets its exposure by itself and needs more than a second for it. +LIGHT_SETTLE_S = 1.5 AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time FRAME_RESIZE = 0.25 # the frames are compared at this share of their size # One LED must change the image by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. # The noise is the largest difference between NOISE_SAMPLES dark frames. -MIN_CHANGE = 1.5 +MIN_CHANGE = 0.5 NOISE_FACTOR = 1.5 NOISE_SAMPLES = 6 NOISE_DELAY_S = 0.5 @@ -85,6 +88,10 @@ def central_led(): # An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. # The observation camera ("forAcquisition": false) gives them at any time. +class LeftOut(Exception): + """A camera that cannot give frames now; the test leaves it out and names it in the report.""" + + def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] @@ -112,7 +119,7 @@ def take_image(detector): response = client.post("/ExperimentController/snapOverviewImage", timeout=60, params={"slot_id": "1", "camera_name": "hil_ledmatrix_single"}) if response.status_code == 400: - pytest.skip(f"observation camera not connected: {response.text}") + raise LeftOut(f"observation camera not connected: {response.text}") raw = base64.b64decode(client.json_of(response)["imageBase64"]) frame = Image.open(io.BytesIO(raw)).convert("L") return frame.resize((max(1, int(frame.width * FRAME_RESIZE)), @@ -170,7 +177,7 @@ def live_view(detector): status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, timeout=60).get("status") if status == "long_exposure": - pytest.skip(f"{detector}: exposure too long for live view") + raise LeftOut("exposure too long for live view") assert status in ("success", "already_running"), ( f"{detector}: startLiveView answered {status!r}") time.sleep(0.4) @@ -224,12 +231,15 @@ def sees_one_led(detector, led): missed.append(f"{detector}: LED {led} alone changed the image only by {on_change:.2f}, " f"need >= {required:.2f} (noise floor {noise_floor:.2f}; {settings}) " f"- setLEDs may not have lit it") - if off_change >= required: + # Off is judged against on, not against the noise: + # the observation camera's own exposure drifts after a bright light. + if off_change >= on_change / 2: missed.append(f"{detector}: off is still {off_change:.2f} from dark, " - f"need < {required:.2f}") - if brightness(every) <= brightness(single): - missed.append(f"{detector}: every LED ({brightness(every):.2f}) is not brighter than " - f"LED {led} alone ({brightness(single):.2f}) - setLEDs may have lit more " + f"need < {on_change / 2:.2f} (half of what on changed)") + every_change = image_difference(dark, every) + if every_change <= on_change: + missed.append(f"{detector}: every LED changed the image by {every_change:.2f}, not more " + f"than LED {led} alone ({on_change:.2f}) - setLEDs may have lit more " f"than one LED, or the camera saturates") return missed @@ -260,8 +270,15 @@ def test_every_camera_sees_one_led_switch_on_and_off(dark): pytest.skip("the setup has no camera that gives real frames") led, why = central_led() note(f"LED {led}: {why}") - missed = [] + missed, measured = [], 0 # Every camera is measured before the verdict, so the report has the photos of all of them. for detector in found: - missed += sees_one_led(detector, led) + try: + missed += sees_one_led(detector, led) + measured += 1 + except LeftOut as reason: + note(f"{detector} left out: {reason}") + all_lights_off() assert not missed, "\n".join(missed) + if not measured: + pytest.skip("no camera of the setup could give frames") diff --git a/imswitch/imcontrol/_test/hil/test_lightsource.py b/imswitch/imcontrol/_test/hil/test_lightsource.py index 3531bfcb7..883566072 100644 --- a/imswitch/imcontrol/_test/hil/test_lightsource.py +++ b/imswitch/imcontrol/_test/hil/test_lightsource.py @@ -4,7 +4,8 @@ One case per LED; it passes only when every camera of the setup sees both switches. On: the image changes by more than the camera's own noise. -Off: the image is back to dark, within that noise. +Off: the image is closer to dark than to the lit image. +Only differences between frames are judged, never a brightness by itself. The noise: take a few dark frames and measure how much they differ. """ import base64 @@ -18,12 +19,14 @@ import hil_client as client from hil_report import attach, note -LIGHT_SETTLE_S = 0.5 # wait after switching a light, so the next frame shows it +# Wait after switching a light, before the next frame. +# The observation camera sets its exposure by itself and needs more than a second for it. +LIGHT_SETTLE_S = 1.5 AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time FRAME_RESIZE = 0.25 # the frames are compared at this share of their size # A light must change the image by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. # The noise is the largest difference between NOISE_SAMPLES dark frames. -MIN_CHANGE = 1.5 +MIN_CHANGE = 0.5 NOISE_FACTOR = 1.5 NOISE_SAMPLES = 6 NOISE_DELAY_S = 0.5 @@ -68,6 +71,10 @@ def all_lights_off(): # An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. # The observation camera ("forAcquisition": false) gives them at any time. +class LeftOut(Exception): + """A camera that cannot give frames now; the test leaves it out and names it in the report.""" + + def is_observation_camera(detector): return not client.setup()["detectors"][detector]["forAcquisition"] @@ -95,7 +102,7 @@ def take_image(detector): response = client.post("/ExperimentController/snapOverviewImage", timeout=60, params={"slot_id": "1", "camera_name": "hil_lightsource"}) if response.status_code == 400: - pytest.skip(f"observation camera not connected: {response.text}") + raise LeftOut(f"observation camera not connected: {response.text}") raw = base64.b64decode(client.json_of(response)["imageBase64"]) frame = Image.open(io.BytesIO(raw)).convert("L") return frame.resize((max(1, int(frame.width * FRAME_RESIZE)), @@ -153,7 +160,7 @@ def live_view(detector): status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, timeout=60).get("status") if status == "long_exposure": - pytest.skip(f"{detector}: exposure too long for live view") + raise LeftOut("exposure too long for live view") assert status in ("success", "already_running"), ( f"{detector}: startLiveView answered {status!r}") time.sleep(0.4) @@ -210,9 +217,11 @@ def sees_switching(detector, switch): if on_change < required: missed.append(f"{detector}: on changed the image only by {on_change:.2f}, " f"need >= {required:.2f} (noise floor {noise_floor:.2f}; {settings})") - if off_change >= required: + # Off is judged against on, not against the noise: + # the observation camera's own exposure drifts after a bright light. + if off_change >= on_change / 2: missed.append(f"{detector}: off is still {off_change:.2f} from dark, " - f"need < {required:.2f}") + f"need < {on_change / 2:.2f} (half of what on changed)") return missed @@ -251,8 +260,15 @@ def test_every_camera_sees_the_led_switch_on_and_off(name, dark): found = cameras() if not found: pytest.skip("the setup has no camera that gives real frames") - missed = [] + missed, measured = [], 0 # Every camera is measured before the verdict, so the report has the photos of all of them. for detector in found: - missed += sees_switching(detector, lambda on: set_light(name, on)) + try: + missed += sees_switching(detector, lambda on: set_light(name, on)) + measured += 1 + except LeftOut as reason: + note(f"{detector} left out: {reason}") + all_lights_off() assert not missed, f"{name}:\n" + "\n".join(missed) + if not measured: + pytest.skip("no camera of the setup could give frames") diff --git a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py index b6bda04ce..47031ccc9 100644 --- a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py +++ b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py @@ -40,3 +40,6 @@ def test_axis_moves_by_step(positioner, axis): f"{positioner} {axis}: {before} -> {after}, expected {before + STEP_UM}") finally: move(positioner, axis, -STEP_UM) + back = position(positioner, axis) + assert back == pytest.approx(before, abs=0.1), ( + f"{positioner} {axis}: back at {back}, expected {before}") diff --git a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py index 4d43252e4..8a3bc86c6 100644 --- a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py +++ b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py @@ -1,22 +1,18 @@ -"""The observation camera sees every axis move: X and Y shift the image, Z changes its scale. +"""The observation camera sees every axis move: the image changes more than its own noise. -MOVES REAL HARDWARE (to the transport position, then 3 mm per axis and back). +MOVES REAL HARDWARE (to the transport position, then 3 to 5 mm per axis and back). SWITCHES LIGHT. It runs after stage_homing, so that its absolute move goes to a referenced position. At the transport position ImSwitch switches the Z hard limits off, and the turret goes to slot 0. The LED matrix lights the sample. -Then every axis moves out and back once, and three tests judge that one measurement: - -- test_axis_motion_is_visible (every axis): the image changed more than its noise -- test_axis_motion_direction (X, Y): +X moves the image right, +Y moves it down -- test_z_motion_changes_scale (Z): the image got larger or smaller +Then every axis moves out and back once. +The noise is the difference of two frames with nothing moving; the move must change the image more. The position ImSwitch reports is only a step count. This file is what shows that the stage really moved. """ import base64 -import functools import io import time @@ -28,7 +24,8 @@ from hil_report import attach # Distances are in µm, times in seconds. -DISTANCE_UM = 3000 +DISTANCE_UM = 5000 # X and Y +A_DISTANCE_UM = 3000 Z_DISTANCE_UM = 5000 Z_DIRECTION = -1 # away from Z home: at the transport position the limits are off SPEED = 15000 @@ -36,19 +33,11 @@ TRANSPORT_SPEED = 20000 # above 30000 the stage loses steps TRANSPORT_TIMEOUT = 120 TURRET_TIMEOUT = 120 -MATRIX_INTENSITY = 255 # the firmware's maximum per colour +MATRIX_INTENSITY = 255 # per colour, of setAllLED (0..255) MATRIX_SETTLE_S = 3.5 # wait after switching the matrix on, before the first frame -EXPECTED_DIRECTION = {"X": "right", "Y": "down"} # of the image, when the axis moves by +distance MIN_RATIO = 1.8 # image change over noise that counts as movement, X and Y MIN_RATIO_AZ = 1.25 # the same for A and Z, which change the image less -ROI = (150, 355, 150, 340) # X/Y are judged in frame[y1:y2, x1:x2] of the 640x360 image -TOP_CROP_PERCENT = 25 # A/Z are judged below this top share of the image -Z_SCALE_MIN = 0.90 # the image scales that are tried to find the Z zoom -Z_SCALE_MAX = 1.10 -Z_SCALE_STEP = 0.002 -Z_MIN_SCALE_CHANGE = 0.001 -Z_SCALE_NOISE_RATIO = 1.4 SNAP = {"slot_id": "1", "camera_name": "hil_motion"} # camera_name: folder ImSwitch saves to @@ -61,14 +50,6 @@ def axes(): if positioner["forPositioning"] for axis in positioner["axes"]] -def xy_axes(): - return [pair for pair in axes() if pair[1].upper() in EXPECTED_DIRECTION] - - -def z_axes(): - return [pair for pair in axes() if pair[1].upper() == "Z"] - - def move(positioner, axis, distance): """Move one axis by ``distance`` µm and wait until it has arrived and settled.""" client.get_json("/PositionerController/movePositioner", timeout=60, params={ @@ -85,9 +66,9 @@ def wait_until_stopped(): time.sleep(0.5) current = client.get_json("/PositionerController/getPositionerPositions") if current == previous: - break + return current previous = current - return previous + pytest.fail(f"the stage still moves after {TRANSPORT_TIMEOUT}s: {previous}") def park_at_transport(): @@ -123,85 +104,13 @@ def frame(): return np.asarray(image, dtype=np.float32) -# --- image maths: frames are greyscale float arrays ------------------------------------------- - def difference(before, after): - """Mean absolute grey-value difference.""" + """Mean absolute grey-value difference of two frames.""" assert before.shape == after.shape return float(np.mean(np.abs(after - before))) -def roi(image): - """The part of the frame in which X/Y motion is judged (ROI).""" - y1, y2, x1, x2 = ROI - height, width = image.shape - assert 0 <= x1 < x2 <= width, f"invalid ROI x-range {x1}:{x2} for image width {width}" - assert 0 <= y1 < y2 <= height, f"invalid ROI y-range {y1}:{y2} for image height {height}" - return image[y1:y2, x1:x2] - - -def below_top(image): - """The frame without its top TOP_CROP_PERCENT, where A/Z motion is judged.""" - return image[image.shape[0] * TOP_CROP_PERCENT // 100:, :] - - -def shift(before, after): - """How far AFTER is moved against BEFORE: (dx, dy, peak) in pixels, +dx right, +dy down. - - Phase correlation: the peak of the correlation of the two images lies at their shift. - Its height says how clear the match is. - """ - assert before.shape == after.shape - before, after = before.astype(np.float64), after.astype(np.float64) - # Fade the edges out, or the FFT takes the jump from one edge to the other for structure. - window = np.hanning(before.shape[0])[:, None] * np.hanning(before.shape[1])[None, :] - f_before = np.fft.fft2((before - before.mean()) * window) - f_after = np.fft.fft2((after - after.mean()) * window) - cross_power = np.conj(f_before) * f_after - cross_power /= np.maximum(np.abs(cross_power), 1e-12) - correlation = np.fft.fftshift(np.abs(np.fft.ifft2(cross_power))) - peak_y, peak_x = np.unravel_index(np.argmax(correlation), correlation.shape) - dy = peak_y - correlation.shape[0] // 2 - dx = peak_x - correlation.shape[1] // 2 - return float(dx), float(dy), float(correlation[peak_y, peak_x]) - - -def direction(dx, dy, min_shift=2): - """ "right", "left", "down" or "up"; None if the shift is under ``min_shift`` pixels.""" - if np.hypot(dx, dy) < min_shift: - return None - if abs(dx) > abs(dy): - return "right" if dx > 0 else "left" - return "down" if dy > 0 else "up" - - -def scale(before, after): - """The zoom of AFTER against BEFORE; above 1 means the image got larger. - - Tries every scale from Z_SCALE_MIN to Z_SCALE_MAX. - For each, BEFORE is zoomed by it and cut or padded back to the frame size. - The scale whose result matches AFTER best is kept. - """ - height, width = before.shape - image = Image.fromarray(np.ascontiguousarray(before, dtype=np.float32)) - best_scale, best_peak = 1.0, -1.0 - for candidate in np.arange(Z_SCALE_MIN, Z_SCALE_MAX + Z_SCALE_STEP / 2, Z_SCALE_STEP): - zoomed = np.asarray(image.resize((max(1, round(width * candidate)), - max(1, round(height * candidate))), Image.BILINEAR)) - zoomed_height, zoomed_width = zoomed.shape - # Offsets in the zoomed image (when it is larger) and in the frame (when it is smaller). - from_y, to_y = max(0, (zoomed_height - height) // 2), max(0, (height - zoomed_height) // 2) - from_x, to_x = max(0, (zoomed_width - width) // 2), max(0, (width - zoomed_width) // 2) - h, w = min(zoomed_height, height), min(zoomed_width, width) - resized = np.full(before.shape, float(np.median(before)), dtype=np.float32) - resized[to_y:to_y + h, to_x:to_x + w] = zoomed[from_y:from_y + h, from_x:from_x + w] - peak = shift(resized, after)[2] - if peak > best_peak: - best_scale, best_peak = round(float(candidate), 6), peak - return best_scale - - -# --- the measurement and its tests ------------------------------------------------------------ +# --- the test --------------------------------------------------------------------------------- @pytest.fixture(scope="module", autouse=True) def parked_and_lit(): @@ -219,7 +128,6 @@ def parked_and_lit(): response = client.post("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) if response.status_code != 200: pytest.skip(f"{cameras[0]} cannot deliver an image: {response.text}") - roi(frame()) # fails here if ROI does not fit the image print(f"\ntransport position reached: {park_at_transport()}") has_matrix = bool(setup["LEDMatrixs"]) @@ -233,14 +141,14 @@ def parked_and_lit(): client.get_json("/LEDMatrixController/setAllLEDOff") -@functools.lru_cache(maxsize=None) # each axis moves once; the tests share the result -def measure(positioner, axis): - """Move one axis out and back, and return what the frames before and after show.""" - is_xy = axis.upper() in EXPECTED_DIRECTION - is_z = axis.upper() == "Z" - distance = Z_DISTANCE_UM * Z_DIRECTION if is_z else DISTANCE_UM - # X and Y shift the image, so they are judged in a region that stays on the sample. - region = roi if is_xy else below_top +@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") +def test_axis_motion_is_visible(positioner, axis): + if axis.upper() == "Z": + distance, required = Z_DISTANCE_UM * Z_DIRECTION, MIN_RATIO_AZ + elif axis.upper() in ("X", "Y"): + distance, required = DISTANCE_UM, MIN_RATIO + else: + distance, required = A_DISTANCE_UM, MIN_RATIO_AZ still = frame() time.sleep(SETTLE_S) @@ -253,50 +161,10 @@ def measure(positioner, axis): attach(f"{axis} before", before) attach(f"{axis} after {distance:+d} um", after) - noise = difference(region(still), region(before)) - change = difference(region(before), region(after)) - result = {"noise": noise, "change": change, "ratio": change / max(noise, 1e-6)} - if is_xy: - dx, dy, peak = shift(region(before), region(after)) - result["direction"] = direction(dx, dy) - result["shift"] = f"dx={dx:+.1f}px, dy={dy:+.1f}px, peak={peak:.4f}" - if is_z: - result["scale"] = scale(roi(before), roi(after)) - result["scale_change"] = abs(result["scale"] - 1) - result["scale_noise"] = abs(scale(roi(still), roi(before)) - 1) - print(f"\n{positioner} {axis} {distance:+d} um: {result}") - return result - - -@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") -def test_axis_motion_is_visible(positioner, axis): - result = measure(positioner, axis) - required = MIN_RATIO if axis.upper() in EXPECTED_DIRECTION else MIN_RATIO_AZ - assert result["ratio"] >= required, ( - f"{positioner} {axis}: movement was not clearly visible. change={result['change']:.3f}, " - f"noise={result['noise']:.3f}, ratio={result['ratio']:.2f}x, required={required:.2f}x") - - -@client.parametrize_from_rig("positioner, axis", xy_axes, "the setup has no X/Y axes") -def test_axis_motion_direction(positioner, axis): - """Only the wrong direction fails. A shift too small to measure skips.""" - result = measure(positioner, axis) - if result["direction"] is None: - pytest.skip(f"{positioner} {axis}: no clear translation ({result['shift']})") - expected = EXPECTED_DIRECTION[axis.upper()] - assert result["direction"] == expected, ( - f"{positioner} {axis}: image moved {result['direction']}, expected {expected} " - f"({result['shift']})") - - -@client.parametrize_from_rig("positioner, axis", z_axes, "the setup has no Z axis") -def test_z_motion_changes_scale(positioner, axis): - """Larger or smaller does not matter. An unclear scale skips as long as the move was seen.""" - result = measure(positioner, axis) - clear = (result["scale_change"] >= Z_MIN_SCALE_CHANGE - and result["scale_change"] >= result["scale_noise"] * Z_SCALE_NOISE_RATIO) - evidence = (f"scale={result['scale']:.4f}, change={result['scale_change']:.4f}, " - f"noise={result['scale_noise']:.4f}, ratio={result['ratio']:.2f}x") - if not clear and result["ratio"] >= MIN_RATIO_AZ: - pytest.skip(f"{positioner} {axis}: moved, but the scale change is unclear. {evidence}") - assert clear, f"{positioner} {axis}: no scale change and no movement seen. {evidence}" + noise, change = difference(still, before), difference(before, after) + ratio = change / max(noise, 1e-6) + print(f"\n{positioner} {axis} {distance:+d} um: change {change:.3f}, noise {noise:.3f}, " + f"ratio {ratio:.2f}x") + assert ratio >= required, ( + f"{positioner} {axis}: movement was not clearly visible. change={change:.3f}, " + f"noise={noise:.3f}, ratio={ratio:.2f}x, required={required:.2f}x") From e5299d5806b72af3bc4a9469f29b616bebc49667 Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Tue, 17 Nov 2026 10:34:05 +0100 Subject: [PATCH 08/10] remove motor move tests and single led --- imswitch/imcontrol/_test/hil/README.md | 9 +- imswitch/imcontrol/_test/hil/conftest.py | 7 +- .../_test/hil/test_ledmatrix_single.py | 284 ------------------ .../_test/hil/test_motor_axis_move.py | 1 - .../_test/hil/test_motor_motion_camera.py | 170 ----------- .../imcontrol/_test/hil/test_stage_homing.py | 2 +- 6 files changed, 5 insertions(+), 468 deletions(-) delete mode 100644 imswitch/imcontrol/_test/hil/test_ledmatrix_single.py delete mode 100644 imswitch/imcontrol/_test/hil/test_motor_motion_camera.py diff --git a/imswitch/imcontrol/_test/hil/README.md b/imswitch/imcontrol/_test/hil/README.md index 8dc30a495..9b722e8cf 100644 --- a/imswitch/imcontrol/_test/hil/README.md +++ b/imswitch/imcontrol/_test/hil/README.md @@ -13,10 +13,8 @@ Each test file says at the top of its docstring what it checks and what it does | `camera_capture` | each camera takes a picture as large as its sensor | reads | | `motor_axis_move` | each axis moves 10 µm and back, and ImSwitch reports the position it moved to | **moves** (10 µm) | | `stage_homing` | "Safe Global Homing" (`startFrameHoming`) homes Z, X and Y and reports each as done | **moves** (to the end stops, then to the transport position) | -| `motor_motion_camera` | the observation camera sees every axis move: the image changes more than its noise | **moves** (transport position, 3 to 5 mm per axis), **light** | | `lightsource` | each laser and LED switches on and off; every camera sees each LED go on and off | **light** | | `ledmatrix` | every camera sees the LED matrix go on and off | **light** | -| `ledmatrix_single` | one LED lights on its own (`setLEDs`), every camera sees it go on and off, and it is dimmer than the whole matrix | **light** | | `frame_calibration` | the FRAME calibration runs from start to end; needs the calibration target in the holder | **moves** (homes, turret), **light**, **writes the setup** (backup: `setup_before_frame_calibration.json`) | Hardware a setup does not have skips its tests. @@ -24,7 +22,7 @@ Hardware that is there but does not work fails. A camera of the setup that ImSwitch serves as a mock fails `camera_capture`: the real one did not start. They run in the order of the table: the boards, the cameras, the motors, the lights, then the calibration. -The homing ends at the transport position, and the motion and light tests run there. +The homing ends at the transport position, and the light tests run there. The order is the list `ORDER` in `conftest.py`. A light test has one case per light, not one per camera. @@ -35,13 +33,11 @@ Some tests do not start after a failure; they are skipped and say which test fai The table is `NEEDS` in `conftest.py`: - `stage_homing` needs `motor_axis_move`. -- `motor_motion_camera` needs `motor_axis_move` and `stage_homing`: its first move is absolute, so the stage must be homed. -- `frame_calibration` needs `board_link`, `camera_capture`, the three motor tests and the three light tests. +- `frame_calibration` needs `board_link`, `camera_capture`, the two motor tests and the two light tests. It does not need `firmware_server`: a board on another firmware version fails that test, but can still be calibrated. Only `--sync-firmware` stops every test, when the flashing fails. `motor_axis_move` compares positions, which are the firmware's step count. -`motor_motion_camera` is what shows that the stage really moved. `stage_homing` presses the same button as the FRAME settings page and checks the same per-axis "done". That "done" says that the homing command of the axis returned, not that its end stop was pressed. The turret (A) is homed by the calibration. @@ -131,7 +127,6 @@ ImSwitch parses the file before it answers, so a field the file leaves out comes | `objective` | whether there is an objective turret | So a rig with other hardware needs another setup file in ImSwitch, not other tests. -The exception is `Z_DIRECTION` in `motor_motion_camera`: which way Z is free is a constant at its top. ## Writing a test diff --git a/imswitch/imcontrol/_test/hil/conftest.py b/imswitch/imcontrol/_test/hil/conftest.py index 4135ab61f..579fc20c7 100644 --- a/imswitch/imcontrol/_test/hil/conftest.py +++ b/imswitch/imcontrol/_test/hil/conftest.py @@ -14,8 +14,7 @@ "camera_capture", # 2. the cameras "motor_axis_move", # 3. the motors: 10 µm steps, "stage_homing", # homing, ending at the transport position, - "motor_motion_camera", # then moves the camera sees - "lightsource", "ledmatrix", "ledmatrix_single", # 4. the lights, at the transport position + "lightsource", "ledmatrix", # 4. the lights, at the transport position "frame_calibration", # 5. the calibration ] # A test does not start when one of these failed before it. @@ -24,10 +23,8 @@ # Only --sync-firmware stops every test, when flashing fails (__main__.py). NEEDS = { "stage_homing": ["motor_axis_move"], - # Its first move is absolute, so the stage must be homed. - "motor_motion_camera": ["motor_axis_move", "stage_homing"], "frame_calibration": ["board_link", "camera_capture", "motor_axis_move", "stage_homing", - "motor_motion_camera", "lightsource", "ledmatrix", "ledmatrix_single"], + "lightsource", "ledmatrix"], } _failed = [] # the names of the tests that failed so far in this run diff --git a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py b/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py deleted file mode 100644 index 614abad9e..000000000 --- a/imswitch/imcontrol/_test/hil/test_ledmatrix_single.py +++ /dev/null @@ -1,284 +0,0 @@ -"""One LED of the matrix can be lit on its own, and every camera sees it go on and off. -It is dimmer than the whole matrix. - -SWITCHES LIGHT. - -It passes only when every camera of the setup sees both switches. -setLEDs lights exactly the LEDs it is given. -On: one LED changes the image by more than the camera's own noise. -Off: the image is closer to dark than to the lit image. -Only differences between frames are judged, never a brightness by itself. -The whole matrix must change the image more than that one LED. -The LED is the one closest to the optical axis (from the DPC LED layout), -so that it lights the sample in brightfield; -without the DPC controller it is the centre of the setup's Nx x Ny grid. -""" -import base64 -import contextlib -import io -import time - -import pytest -from PIL import Image, ImageChops, ImageStat - -import hil_client as client -from hil_report import attach, note - -SINGLE_INTENSITY = 255 # per colour, of setLEDs (0..255) -MATRIX_INTENSITY = 255 # per colour, of setAllLED (0..255), the same as one LED -# Wait after switching a light, before the next frame. -# The observation camera sets its exposure by itself and needs more than a second for it. -LIGHT_SETTLE_S = 1.5 -AUTO_EXPOSURE_RESET_MS = 1500 # ImSwitch returns to manual exposure after this time -FRAME_RESIZE = 0.25 # the frames are compared at this share of their size -# One LED must change the image by max(MIN_CHANGE, noise * NOISE_FACTOR) grey values. -# The noise is the largest difference between NOISE_SAMPLES dark frames. -MIN_CHANGE = 0.5 -NOISE_FACTOR = 1.5 -NOISE_SAMPLES = 6 -NOISE_DELAY_S = 0.5 - - -# --- lights ----------------------------------------------------------------------------------- - -def all_lights_off(): - """Every laser, LED and the LED matrix off, so only the matrix changes the image.""" - for name in client.setup()["lasers"]: - client.get_json("/LaserController/setLaserValue", {"laserName": name, "value": 0}) - client.get_json("/LaserController/setLaserActive", {"laserName": name, "active": False}) - client.get_json("/LEDMatrixController/setAllLEDOff") - time.sleep(LIGHT_SETTLE_S) - - -def every_led_on(): - client.get_json("/LEDMatrixController/setAllLED", { - "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, - "intensity_b": MATRIX_INTENSITY}) - time.sleep(LIGHT_SETTLE_S) - - -def only_led_on(led): - """Only ``led`` on: setLEDs switches every other LED off.""" - client.get_json("/LEDMatrixController/setLEDs", { - "ledIds": str(led), "intensity_r": SINGLE_INTENSITY, "intensity_g": SINGLE_INTENSITY, - "intensity_b": SINGLE_INTENSITY}) - time.sleep(LIGHT_SETTLE_S) - - -def central_led(): - """Chain index of the LED closest to the optical axis. - - The DPC controller knows every LED's illumination NA; the smallest NA is the most central LED. - Without it, the LED in the middle of the setup's Nx x Ny grid is taken. - The order of the LEDs in the chain is not known here, so that LED may lie off centre. - """ - response = client.get("/DPCController/get_led_layout") - if response.status_code == 200: - leds = response.json().get("leds") or [] - if leds: - led = min(leds, key=lambda led: led["na_x"] ** 2 + led["na_y"] ** 2) - return led["id"], f"smallest illumination NA ({led['na_x']:.3f}, {led['na_y']:.3f})" - matrix = next(iter(client.setup()["LEDMatrixs"].values())) - props = matrix.get("managerProperties") or {} - nx, ny = int(props.get("Nx", 8)), int(props.get("Ny", 8)) - return (ny // 2) * nx + nx // 2, f"middle of the {nx} x {ny} grid (no DPC layout)" - - -# --- cameras ---------------------------------------------------------------------------------- -# An acquisition detector ("forAcquisition": true) gives frames only while its live view runs. -# The observation camera ("forAcquisition": false) gives them at any time. - -class LeftOut(Exception): - """A camera that cannot give frames now; the test leaves it out and names it in the report.""" - - -def is_observation_camera(detector): - return not client.setup()["detectors"][detector]["forAcquisition"] - - -def cameras(): - """The cameras that give real frames. - A camera ImSwitch serves as a mock, or cannot report on, is left out and named in the report. - """ - found = [] - for detector in client.setup()["detectors"]: - status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": detector}) - if "error" in status or status.get("status") == "error": - note(f"{detector} left out: getCameraStatus failed: {status.get('error')}") - elif status.get("isMock") or str(status.get("model", "")).lower() == "mock": - note(f"{detector} left out: ImSwitch served a mock camera") - else: - found.append(detector) - return found - - -def take_image(detector): - """One small greyscale frame (PIL) of either kind of camera.""" - if is_observation_camera(detector): - # camera_name only names the folder ImSwitch saves the frame to. - response = client.post("/ExperimentController/snapOverviewImage", timeout=60, - params={"slot_id": "1", "camera_name": "hil_ledmatrix_single"}) - if response.status_code == 400: - raise LeftOut(f"observation camera not connected: {response.text}") - raw = base64.b64decode(client.json_of(response)["imageBase64"]) - frame = Image.open(io.BytesIO(raw)).convert("L") - return frame.resize((max(1, int(frame.width * FRAME_RESIZE)), - max(1, int(frame.height * FRAME_RESIZE)))) - response = client.get("/RecordingController/snapNumpyToFastAPI", timeout=60, - params={"detectorName": detector, "resizeFactor": FRAME_RESIZE}) - assert response.status_code == 200, response.text - return Image.open(io.BytesIO(response.content)).convert("L") - - -def image_difference(first, second): - """Mean absolute grey-value difference between two frames.""" - return ImageStat.Stat(ImageChops.difference(first, second)).mean[0] - - -def brightness(image): - """Mean grey value of a frame.""" - return ImageStat.Stat(image).mean[0] - - -def exposure_and_gain(detector): - """ "exposure 20, gain 0" as the camera reports them; None for a value it does not report.""" - values = [client.get_json("/SettingsController/getDetectorParameter", - {"detectorName": detector, "parameterName": name}) - for name in ("exposure", "gain")] - return f"exposure {values[0]}, gain {values[1]}" - - -def dark_baseline(detector): - """Measure the camera noise with the scene unchanged. - - Returns (last frame, noise floor, change a light must exceed). - """ - previous = take_image(detector) - drifts = [] - for _ in range(NOISE_SAMPLES - 1): - time.sleep(NOISE_DELAY_S) - current = take_image(detector) - drifts.append(image_difference(previous, current)) - previous = current - noise_floor = max(drifts) - required = max(MIN_CHANGE, noise_floor * NOISE_FACTOR) - print(f"\n{detector} dark noise: drifts={[round(d, 2) for d in drifts]}, " - f"noise_floor={noise_floor:.2f}, required_change={required:.2f}") - return previous, noise_floor, required - - -@contextlib.contextmanager -def live_view(detector): - """Keep an acquisition detector streaming inside a ``with`` block. - - Only a live view that was started here is stopped again. - """ - # The HTTP status is 200 even when ImSwitch refuses, so only the "status" field tells. - status = client.post_json("/LiveViewController/startLiveView", {"detectorName": detector}, - timeout=60).get("status") - if status == "long_exposure": - raise LeftOut("exposure too long for live view") - assert status in ("success", "already_running"), ( - f"{detector}: startLiveView answered {status!r}") - time.sleep(0.4) - try: - yield - finally: - if status == "success": - client.get_json("/LiveViewController/stopLiveView", {"detectorName": detector}) - - -def auto_expose(detector): - """One auto-exposure pass on the scene as it is now; needs a running live view.""" - client.get_json("/SettingsController/setDetectorExposureOnce", - {"detectorName": detector, "resetDelayMs": AUTO_EXPOSURE_RESET_MS}) - time.sleep(AUTO_EXPOSURE_RESET_MS / 1000 + 0.1) - - -def sees_one_led(detector, led): - """Every LED, then dark, then the one LED on and off, in front of one camera. - - The exposure is set on every LED, the brightest scene, so that no frame saturates; - all frames of the camera share it. - The observation camera has no live view for the auto exposure to act on. - Returns what the camera did not see, as lines; empty when it saw everything. - """ - observation = is_observation_camera(detector) - with contextlib.nullcontext() if observation else live_view(detector): - every_led_on() - if not observation: - auto_expose(detector) - every = take_image(detector) - all_lights_off() - dark, noise_floor, required = dark_baseline(detector) - only_led_on(led) - single = take_image(detector) - all_lights_off() - off = take_image(detector) - settings = exposure_and_gain(detector) - attach(f"{detector}: dark", dark) - attach(f"{detector}: LED {led} alone", single) - attach(f"{detector}: off again", off) - attach(f"{detector}: every LED", every) - on_change, off_change = image_difference(dark, single), image_difference(dark, off) - print(f"\n{detector}: LED {led} on changed {on_change:.2f}, " - f"off is {off_change:.2f} from dark, " - f"noise floor {noise_floor:.2f}, required {required:.2f}; brightness dark " - f"{brightness(dark):.2f}, single {brightness(single):.2f}, " - f"all {brightness(every):.2f}; {settings}") - missed = [] - if on_change < required: - missed.append(f"{detector}: LED {led} alone changed the image only by {on_change:.2f}, " - f"need >= {required:.2f} (noise floor {noise_floor:.2f}; {settings}) " - f"- setLEDs may not have lit it") - # Off is judged against on, not against the noise: - # the observation camera's own exposure drifts after a bright light. - if off_change >= on_change / 2: - missed.append(f"{detector}: off is still {off_change:.2f} from dark, " - f"need < {on_change / 2:.2f} (half of what on changed)") - every_change = image_difference(dark, every) - if every_change <= on_change: - missed.append(f"{detector}: every LED changed the image by {every_change:.2f}, not more " - f"than LED {led} alone ({on_change:.2f}) - setLEDs may have lit more " - f"than one LED, or the camera saturates") - return missed - - -# --- fixtures --------------------------------------------------------------------------------- - -@pytest.fixture(scope="module", autouse=True) -def led_matrix(): - if not client.setup()["LEDMatrixs"]: - pytest.skip("the setup has no LED matrix") - if client.get("/LEDMatrixController/setLEDs", params={"ledIds": ""}).status_code == 404: - pytest.skip("this ImSwitch has no LEDMatrixController/setLEDs") - - -@pytest.fixture -def dark(): - """Every light off before and after the test.""" - all_lights_off() - yield - all_lights_off() - - -# --- tests ------------------------------------------------------------------------------------ - -def test_every_camera_sees_one_led_switch_on_and_off(dark): - found = cameras() - if not found: - pytest.skip("the setup has no camera that gives real frames") - led, why = central_led() - note(f"LED {led}: {why}") - missed, measured = [], 0 - # Every camera is measured before the verdict, so the report has the photos of all of them. - for detector in found: - try: - missed += sees_one_led(detector, led) - measured += 1 - except LeftOut as reason: - note(f"{detector} left out: {reason}") - all_lights_off() - assert not missed, "\n".join(missed) - if not measured: - pytest.skip("no camera of the setup could give frames") diff --git a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py index 47031ccc9..02772c687 100644 --- a/imswitch/imcontrol/_test/hil/test_motor_axis_move.py +++ b/imswitch/imcontrol/_test/hil/test_motor_axis_move.py @@ -4,7 +4,6 @@ The position is the step count of the firmware, not a measurement. So this only shows that ImSwitch, the board and its bookkeeping follow the command. -motor_motion_camera shows in the camera that the stage really moved. """ import pytest diff --git a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py b/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py deleted file mode 100644 index 8a3bc86c6..000000000 --- a/imswitch/imcontrol/_test/hil/test_motor_motion_camera.py +++ /dev/null @@ -1,170 +0,0 @@ -"""The observation camera sees every axis move: the image changes more than its own noise. - -MOVES REAL HARDWARE (to the transport position, then 3 to 5 mm per axis and back). -SWITCHES LIGHT. - -It runs after stage_homing, so that its absolute move goes to a referenced position. -At the transport position ImSwitch switches the Z hard limits off, and the turret goes to slot 0. -The LED matrix lights the sample. -Then every axis moves out and back once. -The noise is the difference of two frames with nothing moving; the move must change the image more. - -The position ImSwitch reports is only a step count. -This file is what shows that the stage really moved. -""" -import base64 -import io -import time - -import numpy as np -import pytest -from PIL import Image - -import hil_client as client -from hil_report import attach - -# Distances are in µm, times in seconds. -DISTANCE_UM = 5000 # X and Y -A_DISTANCE_UM = 3000 -Z_DISTANCE_UM = 5000 -Z_DIRECTION = -1 # away from Z home: at the transport position the limits are off -SPEED = 15000 -SETTLE_S = 0.5 # wait after a move, before the frame -TRANSPORT_SPEED = 20000 # above 30000 the stage loses steps -TRANSPORT_TIMEOUT = 120 -TURRET_TIMEOUT = 120 -MATRIX_INTENSITY = 255 # per colour, of setAllLED (0..255) -MATRIX_SETTLE_S = 3.5 # wait after switching the matrix on, before the first frame - -MIN_RATIO = 1.8 # image change over noise that counts as movement, X and Y -MIN_RATIO_AZ = 1.25 # the same for A and Z, which change the image less - -SNAP = {"slot_id": "1", "camera_name": "hil_motion"} # camera_name: folder ImSwitch saves to - - -# --- stage ------------------------------------------------------------------------------------ - -def axes(): - """Every (positioner, axis) pair of the setup, e.g. ("ESP32Stage", "X").""" - return [(name, axis) for name, positioner in client.setup()["positioners"].items() - if positioner["forPositioning"] for axis in positioner["axes"]] - - -def move(positioner, axis, distance): - """Move one axis by ``distance`` µm and wait until it has arrived and settled.""" - client.get_json("/PositionerController/movePositioner", timeout=60, params={ - "positionerName": positioner, "axis": axis, "dist": distance, - "isBlocking": True, "speed": SPEED}) - time.sleep(SETTLE_S) - - -def wait_until_stopped(): - """The positions once two reads agree; some endpoints answer before the stage has arrived.""" - previous = client.get_json("/PositionerController/getPositionerPositions") - deadline = time.monotonic() + TRANSPORT_TIMEOUT - while time.monotonic() < deadline: - time.sleep(0.5) - current = client.get_json("/PositionerController/getPositionerPositions") - if current == previous: - return current - previous = current - pytest.fail(f"the stage still moves after {TRANSPORT_TIMEOUT}s: {previous}") - - -def park_at_transport(): - """Move to the transport position and turn the turret to slot 0; returns the positions.""" - client.get_json("/PositionerController/moveToTransportPosition", timeout=TRANSPORT_TIMEOUT, - params={"speed": TRANSPORT_SPEED, "isBlocking": True}) - wait_until_stopped() - if client.setup()["objective"]: - status = client.get_json("/ObjectiveController/getstatus") - if status.get("isActive") and status.get("hasMotor") and status["slotConfigured"][0]: - # skipZ: the turret must not apply the slot's Z offset to the parked stage. - started = client.get_json("/ObjectiveController/moveToObjective", - {"slot": 0, "skipZ": True}) - assert started.get("accepted"), f"the turret refused slot 0: {started}" - - def turned(): - # moveToObjective only starts the move; the status tells when it is done. - now = client.get_json("/ObjectiveController/getstatus") - return (not now.get("isMovingObjective") and - now.get("lastCompletedObjectiveRequestId") == started["requestId"]) - - assert client.wait_until(turned, TURRET_TIMEOUT), ( - f"the turret did not reach slot 0 in {TURRET_TIMEOUT}s") - return wait_until_stopped() - - -# --- observation camera ----------------------------------------------------------------------- - -def frame(): - """One full-size greyscale frame of the observation camera, as a float array.""" - body = client.post_json("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) - image = Image.open(io.BytesIO(base64.b64decode(body["imageBase64"]))).convert("L") - return np.asarray(image, dtype=np.float32) - - -def difference(before, after): - """Mean absolute grey-value difference of two frames.""" - assert before.shape == after.shape - return float(np.mean(np.abs(after - before))) - - -# --- the test --------------------------------------------------------------------------------- - -@pytest.fixture(scope="module", autouse=True) -def parked_and_lit(): - """Check the camera before anything moves, then park the stage and switch the matrix on.""" - setup = client.setup() - cameras = [name for name, detector in setup["detectors"].items() - if not detector["forAcquisition"]] - if not cameras: - pytest.skip("the setup has no observation camera") - status = client.get_json("/SettingsController/getCameraStatus", {"detectorName": cameras[0]}) - if "error" in status or status.get("status") == "error": - pytest.skip(f"{cameras[0]}: getCameraStatus failed: {status.get('error')}") - if status.get("isMock") or status.get("isConnected") is False: - pytest.skip(f"{cameras[0]} is a mock camera or not connected: {status}") - response = client.post("/ExperimentController/snapOverviewImage", params=SNAP, timeout=60) - if response.status_code != 200: - pytest.skip(f"{cameras[0]} cannot deliver an image: {response.text}") - - print(f"\ntransport position reached: {park_at_transport()}") - has_matrix = bool(setup["LEDMatrixs"]) - if has_matrix: - client.get_json("/LEDMatrixController/setAllLED", { - "intensity_r": MATRIX_INTENSITY, "intensity_g": MATRIX_INTENSITY, - "intensity_b": MATRIX_INTENSITY}) - time.sleep(MATRIX_SETTLE_S) - yield - if has_matrix: - client.get_json("/LEDMatrixController/setAllLEDOff") - - -@client.parametrize_from_rig("positioner, axis", axes, "the setup has no positioner axes") -def test_axis_motion_is_visible(positioner, axis): - if axis.upper() == "Z": - distance, required = Z_DISTANCE_UM * Z_DIRECTION, MIN_RATIO_AZ - elif axis.upper() in ("X", "Y"): - distance, required = DISTANCE_UM, MIN_RATIO - else: - distance, required = A_DISTANCE_UM, MIN_RATIO_AZ - - still = frame() - time.sleep(SETTLE_S) - before = frame() - move(positioner, axis, distance) - try: - after = frame() - finally: - move(positioner, axis, -distance) - attach(f"{axis} before", before) - attach(f"{axis} after {distance:+d} um", after) - - noise, change = difference(still, before), difference(before, after) - ratio = change / max(noise, 1e-6) - print(f"\n{positioner} {axis} {distance:+d} um: change {change:.3f}, noise {noise:.3f}, " - f"ratio {ratio:.2f}x") - assert ratio >= required, ( - f"{positioner} {axis}: movement was not clearly visible. change={change:.3f}, " - f"noise={noise:.3f}, ratio={ratio:.2f}x, required={required:.2f}x") diff --git a/imswitch/imcontrol/_test/hil/test_stage_homing.py b/imswitch/imcontrol/_test/hil/test_stage_homing.py index 94b8b077a..9d890d7c5 100644 --- a/imswitch/imcontrol/_test/hil/test_stage_homing.py +++ b/imswitch/imcontrol/_test/hil/test_stage_homing.py @@ -5,7 +5,7 @@ This is the button "Start homing" under FRAME settings: the endpoint startFrameHoming. It homes Z and lifts it clear of the bottom, then homes X and Y. At the end X and Y go to the transport position, and Z goes back to its height from before. -That is where motor_motion_camera and the light tests find the stage. +That is where the light tests find the stage. The turret (A) is not homed here; the FRAME calibration homes it. The test passes when the homing ends as "done" with Z, X and Y "done", as the button shows it. From 9cba5d09f70ab8375eda3ca1807e66dc51ab7dba Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Tue, 17 Nov 2026 11:03:38 +0100 Subject: [PATCH 09/10] improve running state handling in frame calibration test --- .../_test/hil/test_frame_calibration.py | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/imswitch/imcontrol/_test/hil/test_frame_calibration.py b/imswitch/imcontrol/_test/hil/test_frame_calibration.py index 64673ef5f..0ea5ff801 100644 --- a/imswitch/imcontrol/_test/hil/test_frame_calibration.py +++ b/imswitch/imcontrol/_test/hil/test_frame_calibration.py @@ -35,6 +35,7 @@ BACKUP_NAME = "setup_before_frame_calibration.json" CALIBRATION_PDF = "frame_calibration.pdf" # the calibration's own report, in the report folder ENDED = ("finished", "failed", "aborted") +ACTIVE = ("running", "waiting") # the states the FRAME calibration app shows as running # --- the calibration -------------------------------------------------------------------------- @@ -49,15 +50,20 @@ def set_settings(values): def running(): - return client.get_json("/FrameCalibrationController/isFrameCalibrationRunning") is True + """Running as the app shows it, from the state of the status. + + The state ends before the calibration thread does. + The thread then only resets the camera and writes its report folder. + It switches no light, moves no motor and leaves the setup file alone. + So nothing this test does afterwards collides with it. + """ + return status()["state"] in ACTIVE def stop_and_wait(): - """The terminal status alone does not mean cleanup/report writing has finished.""" if not running(): return - if status()["state"] not in ENDED: - client.post_json("/FrameCalibrationController/stopFrameCalibration") + client.post_json("/FrameCalibrationController/stopFrameCalibration") assert client.wait_until(lambda: not running(), STOP_TIMEOUT, interval=POLL_S), ( f"calibration thread did not stop within {STOP_TIMEOUT}s") @@ -119,7 +125,7 @@ def run_calibration(run, live): current = status() show_progress(current["steps"], shown, live) assert current["startedAt"] == run["startedAt"], "calibration replaced during polling" - if current["state"] in ENDED and not running(): + if current["state"] in ENDED: return current # The test turned the manual focus off; a wait for the user would never end. assert current["state"] != "waiting", ( From f2ae715b28a9fb660b36cedf399dff4f92dd6635 Mon Sep 17 00:00:00 2001 From: Haiyue Li Date: Tue, 17 Nov 2026 14:06:09 +0100 Subject: [PATCH 10/10] fix: correct stop timeout handling and update polling test for terminal status --- imswitch/imcontrol/_test/unit/test_hil_reporting.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/imswitch/imcontrol/_test/unit/test_hil_reporting.py b/imswitch/imcontrol/_test/unit/test_hil_reporting.py index 1648f1ad8..847c8fe00 100644 --- a/imswitch/imcontrol/_test/unit/test_hil_reporting.py +++ b/imswitch/imcontrol/_test/unit/test_hil_reporting.py @@ -117,19 +117,19 @@ def test_summary_has_one_row_per_test_file(): def test_stop_timeout_is_an_error(calibration_module, monkeypatch): m = calibration_module - monkeypatch.setattr(m, "running", lambda: True) - monkeypatch.setattr(m, "status", lambda: {"state": "finished"}) + monkeypatch.setattr(m, "status", lambda: {"state": "running"}) + sent = [] + monkeypatch.setattr(m.client, "post_json", lambda endpoint, **k: sent.append(endpoint)) monkeypatch.setattr(m.client, "wait_until", lambda *a, **k: False) with pytest.raises(AssertionError, match="thread did not stop"): m.stop_and_wait() + assert sent == ["/FrameCalibrationController/stopFrameCalibration"] -def test_poll_waits_for_thread_after_terminal_status(calibration_module, monkeypatch): +def test_poll_returns_at_terminal_status(calibration_module, monkeypatch): m = calibration_module monkeypatch.setattr(m.client, "post_json", lambda *a, **k: {"success": True}) monkeypatch.setattr(m, "status", lambda: {"state": "finished", "startedAt": "now", "steps": []}) - states = iter([True, False]) - monkeypatch.setattr(m, "running", lambda: next(states)) monkeypatch.setattr(m.time, "sleep", lambda _: None) run = {} assert m.run_calibration(run, lambda line: None)["state"] == "finished"