RDK‐E Testing & Raft Command Model – Technical Requirements Document (TRD) - rdkcentral/rdk-halif-aidl GitHub Wiki
Document Status: Draft
Date Created: 2025-09-05
Author(s): G. Weatherup
Version: 0.1
1. Introduction
1.1 Purpose
This TRD defines the test execution model for RDK-E platforms (rack hardware and vDevice) using Python Raft as the single orchestration layer.
It ensures that:
- The same test suites run unchanged on both rack hardware and vDevice.
- Test authors use a stable Python API, independent of platform details.
- All test stimuli are deterministic, auditable, and versioned.
This document covers the command model, execution flow, and platform abstraction for tests.
It does not define individual vDevice component implementations (covered in the vDevice TRD).
1.2 Background
- RDK-E tests were historically tied to physical rack hardware.
- The vDevice initiative introduces a virtual execution environment.
- Python Raft abstracts hardware details so tests remain platform-agnostic.
1.3 Objectives
- Define a single Python API for all test stimuli.
- Ensure Raft routes commands to either rack controllers or vDevice Control Plane automatically.
- Provide deterministic, auditable execution via YAML logging and replay.
- Guarantee full VTS integration as the pre-commit and release gate.
2. Related Documents
| Type | Name | Link |
|---|---|---|
| TRD | RDK-E vDevice TRD | [link TBD] |
| TRD | VTS Framework TRD | [link TBD] |
| Standard | Documentation in Git | [link TBD] |
| Standard | Doxygen Code Documentation | [link TBD] |
3. Test Execution Model
3.1 Python Raft as Orchestrator
- All tests invoke Python Raft API methods.
- Raft abstracts whether commands target:
- Rack Hardware via drivers (PDU, HDMI robot, IR blaster, network shaper…)
- vDevice via Control Plane commands and VM lifecycle operations.
- Tests must never contain platform-specific logic.
3.2 Command Flow
sequenceDiagram
participant Test as Test Code
participant Raft as Python Raft
participant Rack as Rack Drivers
participant vDev as vDevice Control Plane
Test->>Raft: slot.powerOn()
Raft->>Rack: PDU power ON (if physical)
Raft->>vDev: VM reboot (if vDevice)
Rack-->>Raft: Result + Telemetry
vDev-->>Raft: Result + Telemetry
Raft-->>Test: Pass/Fail outcome
4. Raft Command Model
4.1 Public Test API
- Tests call simple Python methods:
slot.powerOn(),slot.powerOff(),slot.powerCycle()slot.hdmi.plug(),slot.hdmi.unplug()self.ir(KEY_UP),self.ir(KEY_OK)slot.network.throttle(),slot.network.down()slot.usb.plug(),slot.usb.unplug()slot.clock.set()
4.2 Command Mapping
| Domain | Python API (Tests) | Meaning | Rack Mapping | vDevice Mapping |
|---|---|---|---|---|
| Power | slot.powerOn() |
Apply power to DUT | PDU outlet ON | VM boot / relaunch image |
| Power | slot.powerOff() |
Remove power | PDU outlet OFF | VM power-off / stop |
| Power | slot.powerCycle(delay_ms=1000) |
Off→wait→On | PDU OFF→sleep→ON | VM reboot |
| HDMI | slot.hdmi.plug(port=0) |
Simulate cable present | Robot/relay close | Control Plane: hdmi set_hotplug true |
| HDMI | slot.hdmi.unplug(port=0) |
Simulate cable absent | Robot/relay open | Control Plane: hdmi set_hotplug false |
| IR | self.ir(KEY_UP, hold_ms=0) |
Send IR key | IR transmitter | Control Plane: ir send key=KEY_UP |
| Network | slot.network.throttle("wan", 10, 30000) |
Apply link shaping | Lab shaper API | Control Plane: net set_rate |
| Network | slot.network.down("wan") / up("wan") |
Link down/up | Port disable/enable | Control Plane: net set_link |
| Storage | slot.usb.plug("stickA") |
Mount USB | USB relay insert | Control Plane: usb attach |
| Input | self.keyboard("KEY_HOME") |
Linux input event | HID injector | Control Plane: input key |
| Clock | slot.clock.set(offset_ms=…) |
Adjust clock | NTP/PTP action | Control Plane: clock set_offset |
5. Determinism & Versioning
- Deterministic execution: timeouts, retries, and event expectations must be explicit.
- Versioned command schema: changes require minor/major version bumps.
- Record & Replay: identical inputs must produce identical outputs.
6. VTS Integration
- All tests are executed under VTS orchestration.
- Pre-commit VTS testing is mandatory before merging code changes.
- Python Raft integrates with VTS to:
- Run tests on rack hardware or vDevice
- Collect telemetry and logs
- Report pass/fail results consistently
7. Acceptance Criteria
| Area | Acceptance Criteria |
|---|---|
| Test API | Python API stable across rack and vDevice |
| Platform Routing | Raft routes commands correctly without platform conditionals |
| Determinism | Identical inputs → identical results |
| VTS Compliance | All tests pass via VTS pre-commit gates |