Tutorial: Engineer's First Project #
Welcome to Litmus! This tutorial takes you from your first test to a production-ready test suite. Each step builds on the previous one, introducing one concept at a time.
Learning Path #
| Step | Goal | What You'll Learn |
|---|---|---|
| 0. Quick Start | Smallest end-to-end loop | install, run, see results |
| 1. First Test | Run something | pytest, project structure |
| 2. Running Without Hardware | Use mock mode | --mock-instruments, mock_config (station-config block of canned return values used when --mock-instruments is on) |
| 3. pytest-native tests | Log measurements | the core per-test Litmus fixtures — context is the ambient run/DUT/station/vector state (always available; carries sweep params when present, observations always), verify records the measurement row AND raises on FAIL, logger.measure records the row without raising (plus ~17 other public fixtures the plugin exposes — see litmus-fixtures) |
| 4. Add Limits | Pass/fail criteria | Limit, Measurement, Outcome |
| 5. Test Configuration | Configure in YAML | sidecar (YAML next to a test file carrying vectors and limits) |
| 6. Product Specifications | Define products | products/*.yaml, characteristics |
| 7. Real Instruments | Talk to hardware | stations/*.yaml, VISA, simulation |
| 8. Capability Matching | Find compatible stations | direction flip, matching API |
| 9. Production Ready | Full traceability | fixtures, test classes, sidecar |
| 10. Live Monitoring | Monitor in real time | sessions, events, channels |
Prerequisites #
- Python 3.11 or later
- Basic familiarity with pytest
- Litmus installed (
uv syncorpip install -e .)
Time Commitment #
Each step takes 10-15 minutes. You can complete the entire tutorial in about 2 hours, or work through it over several sessions.
What You'll Build #
By the end of this tutorial, you'll have:
- A working test suite for a voltage converter
- YAML-based configuration for limits and test parameters
- Tests that run with real instruments OR in simulation mode
- Automatic station matching based on required capabilities
- Full traceability from requirements to results
- Live monitoring of test sessions with event queries
Quick Start #
If you just want to see working code:
litmus init quick_start --starter && cd quick_start
pytestThen come back here to understand how it works.