Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Testing

Components can be tested by connecting them into a small simulation and driving their ports directly. For simple cases this can be done by hand with OutPort/InPort, but most component tests need the same testbench structure:

  1. Create an engine and the device under test (DUT).
  2. Connect driver ports to DUT input ports.
  3. Connect receiver ports to DUT output ports.
  4. Run a sequence of sends, expects, delays, and no-traffic checks.

The build_component_harness! macro will generate the repeated testbench code. It generates the harness struct, Port/Step enums, helper macros, etc.

Harnesses are usually declared inside a small test module. This keeps generated names such as Port, Step, and the helper macros local to the harness and avoids clashes with other harnesses in the same test file.

For example, the harness around a Delay component is created and used below:

#![allow(unused)]
fn main() {
mod delay_harness {
    use std::rc::Rc;

    use gwr_components::build_component_harness;
    use gwr_components::delay::Delay;
    use gwr_engine::test_helpers::start_test;

    build_component_harness! {
        harness DelayHarness<T> {
            component: delay: Rc<Delay<T>>,
            rx ports: {
                Rx<T> => rx,
            },
            tx ports: {
                Tx<T> => tx,
            },
        }
    }

    #[test]
    fn delay_forwards_values() {
        let mut engine = start_test(file!());
        let clock = engine.default_clock();
        let delay = Delay::new_and_register(&engine, &clock, engine.top(), "delay", 5).unwrap();
        let mut harness = DelayHarness::new(engine, delay);

        harness.run_steps([
            send_rx!(10),
            expect_no_traffic!(&[Port::Tx], 4),
            expect_tx!(10),
        ]);
    }
}
}

The macro supports scalar RX/TX ports and RX/TX port arrays. Each port section is optional, so a source-only component can define only tx ports and a sink-only component can define only rx ports.

Step can be a send, expect, delay, no-traffic check, Seq(Vec<Step<...>>) that runs child steps in order, or Par(Vec<Step<...>>) that runs child steps concurrently and waits for all of them before moving on. The generated seq! and par! helper macros build those recursive control structures and record their source location, so tests can express parallel sequences on different ports while keeping error messages tied to the call site.

The harness checks that each step is used on a compatible port; for example, using an expect step on an RX port or a send step on a TX port will fail the test.

Use run_steps([Step<...>]) for fixed test sequences and run_step_generator(iterator) for stateful generators that yield steps as the test progresses.

Use script! for behavior that depends on received values or needs async Rust control flow. Declare the ports it uses, then write an ordinary async block:

harness.run_steps([script! {
    ports { input = Rx, output = Tx }
    async {
        for value in [3, 7] {
            input.put(value)?.await;
            let received = output.get()?.await;
            let next = if received > 5 { 10 } else { 0 };
            input.put(next)?.await;
            assert_eq!(output.get()?.await, next);
        }
        Ok(())
    }
}]);

The aliases are mutable raw ports: RX captures are OutPort drivers and TX captures are InPort receivers. Scripts can use loops, conditionals, early returns, ?, concurrent futures, and any async helper that borrows those ports. There is no body parsing or automatic awaiting. The send_ and expect_ macros remain step constructors for use outside scripts; inside a script use port methods and ordinary async functions. The async body returns SimResult.

Use ports { input = Rx[index], output = Tx[index] } for indexed ports. Selectors are evaluated once when constructing the script. Every declared port is reserved for the whole script, even if a conditional does not use it. A port cannot be captured twice or shared by parallel branches. Capture multiple ports when a script needs to choose between them at runtime. Ports are returned when the script completes, so later steps can use them again.

For custom drivers outside scripts, the generated take_<port>_receiver() and take_<port>_driver() methods can transfer scalar ports to an async task. Harness steps continue to manage the remaining ports; steps that use a transferred port will fail.