#avr #test #framework #microcontroller #simavr

nightly avr-tester

Functional testing framework for AVR binaries

1 unstable release

Uses new Rust 2021

0.1.0 Jun 11, 2022

#368 in Testing

MIT license

41KB
967 lines

avr-tester

Functional testing framework for AVR binaries, powered by simavr.

tl;dr get your microcontroller's firmware black-box-tested in seconds!

Status: alpha; work in progress.

Getting Started

First, create a separate crate, dedicated only to your project's tests:

$ cargo new yourproject-tests --lib

... then add avr-tester as its dependency:

# yourproject-tests/Cargo.toml

[dependencies]
avr-tester = "0.1"

... and, just like that, you can start writing tests:

// yourproject-tests/src/lib.rs

use avr_tester::AvrTester;

fn avr() -> AvrTester {
    AvrTester::atmega328p()
        .with_clock_of_16_mhz()
        .load("../../yourproject/target/atmega328p/release/your-project.elf")
}

// Assuming `your-project` is a ROT-13 encoder, one could write tests such as
// those:

#[test]
fn short_text() {
    let mut avr = avr();

    // Let's give our AVR a moment to initialize itself and UART:
    avr.run_for_ms(1);

    // Now, let's send the string:
    avr.uart0().send("Hello, World!");

    // ... give the AVR a moment to retrieve it & send back, encoded:
    avr.run_for_ms(1);

    // ... and, finally, assert the outcome:
    assert_eq!("Uryyb, Jbeyq!", avr.uart0().recv::<String>());
}

#[test]
fn long_text() {
    let mut avr = avr();

    avr.run_for_ms(1);
    avr.uart0().send("Lorem ipsum dolor sit amet, consectetur adipiscing elit");
    avr.run_for_ms(1);

    assert_eq!(
        "Yberz vcfhz qbybe fvg nzrg, pbafrpgrghe nqvcvfpvat ryvg",
        avr.uart0().recv::<String>(),
    );
}

... having the tests ready (and requirements met!), just run cargo test inside yourproject-tests :-)

Note that because AvrTester simulates an actual AVR, you don't have to modify yourproject at all - it's free to use timers, GPIOs etc. and everything should just work.

In fact, yourproject doesn't even have to be written in Rust - you can create Rust-based tests for a firmware written in C, Zig or anything else!

Usage

Requirements & supported platforms

See: simavr-ffi.

Roadmap

Following features seem to be supported by simavr, but haven't been yet exposed in AvrTester:

(i.e. your firmware can use those features, but you won't be able to test them.)

Caveats

  • Triggering AVR's sleep mode will cause the Rust code to gracefully panic!(), because the only way to wake an AVR is to trigger an interrupt and those are not yet supported.

Contributing

Pull requests are very much welcome!

Tests

AvrTester's integration tests lay in avr-tester/tests - you can run them with:

$ cd avr-tester
$ cargo test

Note that for those tests to work, you might need some additional dependencies:

... on Nix

$ nix-shell
# and then `cargo test`

... on Ubuntu

$ sudo apt install avr-libc gcc-avr
# and then `cargo test`

License

Copyright (c) 2022, Patryk Wychowaniec pwychowaniec@pm.me.
Licensed under the MIT license.

Dependencies

~3.5–5MB
~52K SLoC