Add hardware testing scaffold

[ceej640]

Closes #18.

Summary:

• Add pytest markers and flags for offline hardware tests and opt-in live hardware checks.
• Add a dependency-free MockQueueServerClient and HardwareCondition helpers for hardware-dependent code.
• Add offline contract tests plus a skipped-by-default live device-layer state check.
• Document how to run hardware and live_hardware tests.

Verification:

• .\.venv\Scripts\python.exe -m pytest tests/hardware -q -p no:cacheprovider
• git diff --check

[pskeshu]

This is a bit tricky. The design of a simulation hardware depends on what you are testing. For instance, if you want to test device layer as simulator - it is fairly simple. But if you're testing perception then that's a different simulated microscope altogether - you need to simulate a sample, and then sample time dynamics. So a difficult question to address - but need to ask the meta level of - what needs testing, and how to provide coverage.

…

On Sat, 30 May 2026 at 22:11, ceej640 ***@***.***> wrote: Closes #18 <https://github.com/pskeshu/gently/issues/18>. Summary: - Add pytest markers and flags for offline hardware tests and opt-in live hardware checks. - Add a dependency-free MockQueueServerClient and HardwareCondition helpers for hardware-dependent code. - Add offline contract tests plus a skipped-by-default live device-layer state check. - Document how to run hardware and live_hardware tests. Verification: - .\.venv\Scripts\python.exe -m pytest tests/hardware -q -p no:cacheprovider - git diff --check ------------------------------ You can view, comment on, or merge this pull request online at: https://github.com/pskeshu/gently/pull/28 Commit Summary - 508891b <pskeshu@508891b> Add hardware testing scaffold File Changes (7 files <https://github.com/pskeshu/gently/pull/28/files>) - *A* docs/testing-hardware.md <https://github.com/pskeshu/gently/pull/28/files#diff-f3a82cc6753e0505360a65616e91af20e16d203520212929566c1bf2d189ef4e> (47) - *A* gently/hardware/testing.py <https://github.com/pskeshu/gently/pull/28/files#diff-380c98a1c41deb89a7804d50f87522982b1dadc2f9e64e5a9d78aadc2ba93215> (206) - *M* pyproject.toml <https://github.com/pskeshu/gently/pull/28/files#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711> (5) - *M* tests/conftest.py <https://github.com/pskeshu/gently/pull/28/files#diff-e52e4ddd58b7ef887ab03c04116e676f6280b824ab7469d5d3080e5cba4f2128> (45) - *A* tests/hardware/__init__.py <https://github.com/pskeshu/gently/pull/28/files#diff-1afa1b1718033c618e64ec6ec71925729cce34eef82de5d227e5e66561279971> (1) - *A* tests/hardware/test_live_device_layer.py <https://github.com/pskeshu/gently/pull/28/files#diff-43b0ad51e6211ea9dde1f39d6b347aa9f93685a467b5deeeb3b04e751e7e0500> (24) - *A* tests/hardware/test_testing_helpers.py <https://github.com/pskeshu/gently/pull/28/files#diff-3b5097341cd6c6a0b25fb14324ce81d3251960e5d843ca7f03a1a960cb158f2f> (69) Patch Links: - https://github.com/pskeshu/gently/pull/28.patch - https://github.com/pskeshu/gently/pull/28.diff — Reply to this email directly, view it on GitHub <https://github.com/pskeshu/gently/pull/28?email_source=notifications&email_token=ABVNN4CXCPSCYCKH2WFDM4T45OIERA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF4ZTONZVGM4TGMJWG2THEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVRTG633UMVZF6Y3MNFRWW>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVNN4EZ6DIQM22OLFCGFQD45OIERAVCNFSM6AAAAACZUCMPN2VHI2DSMVQWIX3LMV43ASLTON2WKOZUGU2TMMZQG43DIMY> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- Kesavan

[ceej640]

Agreed. The important distinction is what level of the system the simulator is meant to cover.

This PR is only a first-layer scaffold for device-layer/offline contract tests. It is useful for checking command semantics and safety gates without live hardware, but it is not a simulated microscope.

Before adding richer simulation, I would define a testing coverage matrix with separate layers:

• device command contract tests: fast mocks for API behavior and safety validation
• hardware digital twins: stateful simulations for devices such as stages, cameras, lasers, temperature control, and queue timing
• optical/perception simulation: synthetic sample, image formation, noise, drift, focus, and segmentation/perception outputs
• sample dynamics: biological state over time, development, movement, perturbation, and damage/exposure effects
• end-to-end experiment rehearsal: whether Gently can plan, acquire, react, and recover across those layers

The meta-question should come first: what risk is each test meant to catch, what fidelity is needed, and what is deliberately out of scope. I would keep this PR as the lowest layer and use a follow-up design/test-plan PR for the broader simulation strategy.

[ceej640]

Follow-up implemented from this thread in commit af216c2.

I added a simulation coverage matrix to docs/testing-hardware.md. It distinguishes:

• device command contract tests
• hardware digital twins
• optical/perception simulators
• sample dynamics simulators
• end-to-end experiment rehearsal

The current mock client is now explicitly scoped as the lowest device-command layer, not a full simulated microscope. That keeps this PR useful while making the broader testing strategy clear.

Verification:

• git diff --check