tool-mock/docs/GUIDELINES.md

---
type: default
---
# Mock and fixture guidelines

## 1. Fixtures publish the real contract
- A fixture emits the **real topic with the real payload schema**. `yukart/gnss/fix`
  from a replayed track must be indistinguishable, at the bus, from a real fix.  
- A fixture that invents its own topic or shape is worse than no fixture: it defers
  the integration work instead of removing it.

## 2. Never stub our own services
- Stub the **car** and the **hardware**. Never stub `svc-gw`, `svc-nav` or anything
  else we wrote.  
- A stub of our own service is a second implementation of our own contract, and it
  will drift from the first. Run the real service against fake inputs instead —
  none of our services touch hardware, so they all run on x86 unmodified.

## 3. Prefer upstream tools, wrap rather than rewrite
- `vcan`, `canplayer` and ICSim already solve the CAN problem. This repo holds the
  scripts that drive them, not reimplementations of them.

## 4. Recorded logs are data, not source
- `candump` logs and GPX tracks are artifacts. Reference them, do not commit them.

## 5. To be added