crucihil scaffold

Synopsis

crucihil scaffold [--rig <path>] [--example <name>] [--adapter <type>] [options]

Description

crucihil scaffold generates boilerplate so you can start writing tests immediately. It has three modes:

Mode	Flag	What it creates
Test project	`--rig`	Full test project tailored to your rig’s hardware
Example	`--example`	Self-contained runnable example with DBC, rig TOML, and test
Adapter	`--adapter`	Custom backend stub implementing the relevant ABC

Options

path

Path to a rig TOML. Reads the TOML and generates suites/smoke.yaml, suites/regression.yaml, tests/smoke.py, and tests/regression.py tailored to the detected hardware (CAN buses, ECUs, power rails). Short form: -r.

string

Drop a self-contained runnable example. Available names: hello_world, can_signals, fault_injection. Short form: -e.

string

Generate a custom backend adapter stub. Available types: can, power, gpio, doip, someip, udp, uds. Short form: -a.

string

Class name for an adapter stub. Example: --adapter can --name RelayBoard generates a RelayBoardBackend class. Defaults to Custom<Type>. Short form: -n.

path

default:"."

Directory to write generated files into. Short form: -d.

Test project from a rig TOML

crucihil scaffold --rig rigs/bench_01.toml

Reads bench_01.toml and generates:

suites/
├── smoke.yaml         # smoke suite — fast, critical path
└── regression.yaml    # full regression suite
tests/
├── __init__.py
├── smoke.py           # stub functions for smoke tests
└── regression.py      # stub functions for regression tests

The generated YAML manifests reference the signals and ECUs from your rig TOML. For example, if your TOML has [rig.ecus.engine_ecu] and [rig.can.powertrain], the scaffold creates test stubs that reference those. After scaffolding, fill in the pass stubs with real assertions:

crucihil run --suite suites/smoke.yaml --rig rigs/virtual.toml

The stubs pass immediately (they contain pass), giving you a working baseline to build from.

Examples

hello_world

A minimal three-test suite with a virtual rig and sample DBC:

crucihil scaffold --example hello_world

Creates:

hello_world/
├── rigs/virtual.toml
├── defs/vehicle_can.dbc
├── suites/hello_world.yaml
└── tests/hello_world.py

Run it immediately:

cd hello_world
crucihil run --suite suites/hello_world.yaml --rig rigs/virtual.toml

can_signals

Demonstrates rig.can.send, rig.can.expect, rig.sim.set, and rig.sim.override:

crucihil scaffold --example can_signals

fault_injection

Demonstrates the fault injection API — rig.fault.can_dropout, rig.fault.power_cycle, rig.fault.gpio_stuck:

crucihil scaffold --example fault_injection

Custom backend adapters

If you have a proprietary CAN adapter, power supply, or GPIO board, you can implement it as a Python class and load it via backend = "myorg.my_module" in the rig TOML. The scaffold generates the correct boilerplate:

CAN adapter stub

crucihil scaffold --adapter can --name RelayBoard

Generates relay_board_backend.py:

"""RelayBoard custom CAN backend.

Load with:
    backend = "relay_board_backend.RelayBoardBackend"
in [rig.can.<name>] in your rig TOML.
"""
from crucihil.hal.backends.base import AbstractCANBackend
from crucihil.hal.models.frames import CANFrame


class RelayBoardBackend(AbstractCANBackend):
    async def connect(self) -> None:
        # TODO: open connection to hardware
        pass

    async def disconnect(self) -> None:
        # TODO: close connection
        pass

    async def send(self, arb_id: int, data: bytes) -> None:
        # TODO: send frame
        pass

    async def receive(self, timeout: float = 1.0) -> CANFrame:
        # TODO: receive frame
        raise NotImplementedError

    async def set_bitrate(self, bitrate: int) -> None:
        pass

Power backend stub

crucihil scaffold --adapter power --name BenchPSU

GPIO backend stub

crucihil scaffold --adapter gpio --name USBRelay

Stub generation (crucihil stub)

After adding new test IDs to a YAML manifest, run crucihil stub to generate the missing Python function stubs:

crucihil stub --suite suites/regression.yaml

This appends typed async def test_* stubs for every test function that is declared in the YAML but missing from the corresponding Python module. Use --dry-run to preview what would be written:

crucihil stub --suite suites/regression.yaml --dry-run

CLI Reference

crucihil scaffold

Synopsis

Description

Options

Test project from a rig TOML

Examples

hello_world

can_signals

fault_injection

Custom backend adapters

CAN adapter stub

Power backend stub

GPIO backend stub

Stub generation (crucihil stub)

See also

​Synopsis

​Description

​Options

​Test project from a rig TOML

​Examples

​hello_world

​can_signals

​fault_injection

​Custom backend adapters

​CAN adapter stub

​Power backend stub

​GPIO backend stub

​Stub generation (crucihil stub)

​See also

Synopsis

Description

Options

Test project from a rig TOML

Examples

hello_world

can_signals

fault_injection

Custom backend adapters

CAN adapter stub

Power backend stub

GPIO backend stub

Stub generation (crucihil stub)

See also