uCTest: unit test framework

[Sebastian K. (seplog)]

Hallo,

ich würde gerne einmal ein kleines Projekt von mir vorstellen. Dazu ein 
wenig zur Vorgeschichte.

AVR entwickel ich schon länger. Habe aber immer wieder Probleme mit 
automatischen Tests gehabt. Irgendwann bin ich dann auf das google-test 
gestoßen und habe dann einfach meine Libs (welche nicht 
prozessorspezifisch waren) dagegen automatisch getestet. Jedoch ist mir 
dann aufgefallen, dass ein wenig inline Assembler manchmal ziemliche 
Performance-Vorteile bringen kann. ^^
Dann war es leider vorbei mit gtest...

Dann habe ich mich wieder ein wenig auf die Suche gemacht und auch was 
gefunden... Wie uCUnit. Aber... gtest gefiel mir von dem Overhead 
ziemlich gut. Also hab ich mich versucht. ;)

Nun einmal ein kleines Bsp.
Um eine Tests zu definieren ist eine Suite nötig und dann kann schon der 
Test kommen.

#include <uCTest/uCTest.h>

TESTSUITE( Simple );

TEST( Simple, add ) {
    EXPECT_EQ( ( 2 + 2 ), 4 );
    EXPECT_EQ( ( 1 + 1 ), 2 );
}

Das kann dann übersetzt und (bisher) in simulavr ausgeführt werden.

$ avr-gcc -o simple.elf simple.c -L ./uctest-master/build -l uCTest -I ./uctest-master/include -mmcu=atmega328
$ simulavr -d atmega328 -f simple.elf -W 0x20,- -e 0x21 ; echo $?
Running main
[==========] Running 1 tests from 1 test suites.
[----------] 1 tests from Simple
[ RUN      ] Simple.add
[       OK ] Simple.add (55 cycles)
[----------] 1 tests from Simple (55 cycles)

[==========] 1 tests from 1 test suites ran. (55 cycles total)
[  PASSED  ] 1 tests.
0

Mehr ist eigentlich nicht nötig.
Ein bisschen mehr zu den Features.
Es kann ein system setup und teardown implementiert werden. In den 
Tests. dazu muss uctest_system_setup/teardown implementiert werden. 
Diese sind schwach (weak) gebunden.

Es werden Fixture tests zur Verfügung gestellt. Dazu muss TEST_F genutzt 
werden. Dort ist es dann erforderlich SETUP(suite) und TEARDOWN(suite) 
zu implementieren.

Wenn die lib mit CONFIG_COUNT_CYCLES übersetzt wird, werden die Takte 
"gezählt". Dies geschieht über den 16 bit Timer.

Ansonsten...
Die ASSERT und EXPECT sind noch ausbaufähig. Dort habe ich bisher 
getestet mit ASSERT_EQ und ASSERT_NEAR. Mehr ist dort noch nicht 
implementiert. Das steht aber auch noch ganz groß auf meiner ToDo.

Weiterhin auf der ToDo steht auch noch ein JSON output, welcher dann 
nach XML konvertiert werden kann um JUNIT-Kompatible outputs zu 
erzeugen.

Guckt euch das gerne einmal an. Ich habe dort viel Freude beim 
implementieren gehabt und hoffe es ist vielleicht nützlich für einige! 
;)

Viele Grüße
Sebastian

[Testi (Gast)]

In dem Zusammenhang evtl. für den einen oder anderen noch von Interesse:
https://colinholzman.xyz/2020/08/22/unit-testing-embedded-c

[Sebastian K. (seplog)]

Hallo Testi,

vielen Dank für den guten Link. So in der Art habe ich das auch mit dem 
gtest jeweils versucht. Prozessorspezifische Register lassen sich noch 
recht gut abstrahieren.

Mir ging es dann aber später um Optimierungen von lib Funktionen.
Als Bsp.

#ifndef __AVR__
#undef __flash
#define __flash
#include <gtest/gtest.h>
#include <signal/filter/filter_bq.c>
#else
#include <uCTest/uCTest.h>
TESTSUITE( FilterBqTest );
#endif
#include <fmath/signal/filter.h>

TEST( FilterBqTest, filterBessel ) {
    static const __flash struct filter_bq_cfg f_cfg = { .neg_a = { 10232, -3426 },
                                                        .b = { 5462, -10925, 5462 } };

    static const __flash int16_t data[] = {
        120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120,
        0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
    };
    static const __flash int16_t res[] = {
        80, 20, -8, -18, -19, -16, -12, -8, -5, -3, -2, -1, 0, 0, 0,
        -80, -20, 8, 18, 19, 16, 12, 8, 5, 3, 2, 1, 0, 0, 0
    };
    filter_bq_t filter;

    filter_bq_init( &filter, &f_cfg );

    int16_t y;
    int i;
    for( i = 0; i < ( int ) ( sizeof( data ) / sizeof( int16_t ) ); i++ ) {
        int16_t x = data[ i ];
        y = filter_bq_compute( &filter, x );
        ASSERT_EQ( y, res[ i ] );
    }

    EXPECT_NEAR( y, 0, 5 );
}

Dieser Filter greift auf eine ShiftRoundAdd Funktion zu. Diese kann man 
einmal generisch implementieren. Dann läuft das auch alles und ich kann 
das auch wieder auf x86 testen und kann das gegen gtest linken lassen. 
Jedoch habe ich mit einer Asm-Implementierung einige hundert Takte 
sparen können.
Pro filter_bq_compute... ...
Das ist dann schon ein enormer performance-Vorteil. Dort sollte dann 
natürlich auch getestet werden. ;)

Die generische implementierung

[----------] 1 tests from FilterBqTest
[ RUN      ] FilterBqTest.filterBessel
[       OK ] FilterBqTest.filterBessel (47240 cycles)
[----------] 1 tests from FilterBqTest (47240 cycles)

Per inline Asm optimiertes ShiftRoundAdd

[----------] 1 tests from FilterBqTest
[ RUN      ] FilterBqTest.filterBessel
[       OK ] FilterBqTest.filterBessel (19190 cycles)
[----------] 1 tests from FilterBqTest (19190 cycles)

Aso. Noch eine Kleinigkeit zu dem Beispiel oben. Das hat den Vorteil, 
dass dies mit dem gtest übersetzt werden kann, und auch mit dem uCTest, 
sodass es auf dem Controller lauffähig ist ;)

Noch ein Nachtrag:
Ein Grund für die Entwicklung vom uCTest war unter anderem auch, dass 
ich nicht jeden Test neu implementieren muss. Sondern das ich auf 
bestehende Tests vom gtest zurück greifen kann.

Viele Grüße
Sebastian

[Sebastian K. (seplog)]

Hallo,

ich habe einmal ein kleines Update. Ein ToDo auf meiner Liste war ja 
noch die Erweiterung der Assertions. Das war ein wenig Fleißarbeit und 
das habe ich einmal getan.
Es stehen nun weiterhin ASSERT_LT, _LE, _GT, GE zur Verfügung. Weiter 
habe ich mich auch um ein ASSERT_DEATH gekümmert. Also dass eine 
Assertion vom Programm aus Fehl schlägt. Dazu muss dann aber die 
verwendete Lib ohne NDEBUG übersetzt werden, sodass die asserts aus der 
assert.h auch mit übersetzt werden.
Wichtig bei dem ASSERT_DEATH ist noch zu sagen... Ich prüfe dort bisher 
nur, ob ein abort aufgerufen wird. Dann wird die Ausführung abgebrochen 
für die Funktion. Es wird aber bisher nicht die Meldung geprüft!

Ich habe einmal ein kleines Bsp. mit einer Sqrt-Implementierung, welche 
ich auch hier aus dem Forum habe. Leider finde ich den Thread gerade 
nicht mehr.

Aber hier einmal ein wenig Code als Bsp:

#include <assert.h>
#include <stdint.h>

#include <uCTest/uCTest.h>

#define maxRes( msk ) ( ( ( msk << 1 ) - 1 ) * ( ( msk << 1 ) - 1 ) )

uint8_t sqrt_msk( uint16_t x, const uint8_t msk ) {
    assert( x <= maxRes( msk ) );

    uint8_t res = 0;
    uint8_t tmp_msk = msk;

    do {
        res += tmp_msk;
        if( res * res > x ) {
            res -= tmp_msk;
        }
    } while( tmp_msk >>= 1 );
    return res;
}

static inline uint8_t sqrt_u16( uint16_t x ) {
    return sqrt_msk( x, ( 1 << 7 ) );
}

TESTSUITE( SqrtTest );

TEST( SqrtTest, results ) {
    EXPECT_EQ( sqrt_u16( 25 ), 5 );
    EXPECT_EQ( sqrt_u16( 24 ), 4 );
    EXPECT_EQ( sqrt_u16( 9 ), 3 );
    EXPECT_EQ( sqrt_u16( 7 ), 2 );
    EXPECT_EQ( sqrt_u16( 65025 ), 255 );
}

TEST( SqrtTest, assertFail ) {
    ASSERT_DEATH( sqrt_msk( 65025, ( 1 << 6 ) ), ".*x <= maxRes.*failed." );
    EXPECT_LT( sqrt_u16( 24 ), 5 );
}

$ avr-gcc -Os -std=gnu99 -o simple.elf simple.c -L ./uctest-master/build -l uCTest -I ./uctest-master/include -mmcu=atmega328
$ simulavr -d atmega328 -f simple.elf -W 0x20,- -e 0x21 ; echo $?
Running main
[==========] Running 2 tests from 1 test suites.
[----------] 2 tests from SqrtTest
[ RUN      ] SqrtTest.results
[       OK ] SqrtTest.results (729 cycles)
[ RUN      ] SqrtTest.assertFail
[       OK ] SqrtTest.assertFail (274 cycles)
[----------] 2 tests from SqrtTest (1003 cycles)

[==========] 1 tests from 2 test suites ran. (1003 cycles total)
[  PASSED  ] 2 tests.

[Sebastian K. (seplog)]

Hallo,

ich habe einmal ein wenig weiter gemacht und mich um ein JSON output 
gekümmert. Dies klappt nun auch. Man kann das in der Makefile mit 
anschalten indem man CONFIG_OUTPUT_JSON als Symbol definiert. Auch ein 
CONFIG_OUTPUT_NONE ist mit dazu gekommen. Dort kommt dann halt kein 
output.
Um das dann noch ein wenig abzurunden gibt es unter tools ein kleines 
Python-Script, welches das JSON in ein JUNIT-kompatibles XML wandelt.

Auch habe ich einen bug beim ASSERT_DEATH behoben. Dort muss natürlich 
komplett der Kontext gesichert werden. Denn wenn ein assert aus der libc 
das abort aufruft, wird ja an ein Label gesprungen. Dort müssen 
natürlich der Stack und auch alle Register wiederhergestellt werden.

Viel Spaß und viele Grüße
Sebastian

[Sebastian K. (seplog)]

Hallo,

ich habe einmal wieder an meinem Test-Framework weiter gearbeitet.
Zuerst einmal gab es ein paar kleinere Bugfixes und Verbesserungen.
 * Aus den Headern ist nun die Abhängigkeit zur avr/io.h verschwunden.
 * Die Nachrichten werden nun nicht mehr via stdout gesendet sondern 
haben ein eigenes FILE bekommen
 * Wenn bei einem FAIL kein format-String angegeben ist, dann stürzt der 
Controller auch nicht mehr ab.

Weiterhin kam dann noch ein recht gutes Feature dazu.
Ich nutze nun ein Simulator und habe dafür ein Frontend entwickelt. Als 
Simulator nutze ich buserror/simavr. Das Frontend sucht nach einer 
AVR-ELF-Datei mit dem gleichen Namen und führt diese aus. Weiterhin ist 
das Frontend soweit zu GTest kompatibel, dass man es nun in VSCode im 
Testexplorer nutzen kann.
Weiterhin können einzelne Tests ausgeführt werden und die Tests gelistet 
werden.

$ ./test/build/testSuite.avr --mcu atmega328p --freq 11059200 --list-tests
Loaded 11348 .text at address 0x0
Loaded 1608 .data
SqrtTest.
  calculations_u16
  calculations_u24
  assertDeaths
BCDTest.
  init
FilterBqTest.
  filterBessel
DivTest.
  int
  fixpt
SinTest.
  sin
SqrtTest.
  calculations_u16
  calculations_u24
  assertDeaths
BCDTest.
  init
FilterBqTest.
  filterBessel
DivTest.
  int
  fixpt
SinTest.
  sin

Auch lassen sich über einen Filter nur bestimmte Tests ausführen.

$ ./test/build/testSuite.avr --mcu atmega328p --freq 11059200 --filter=FilterBqTest.filterBessel
Loaded 11348 .text at address 0x0
Loaded 1608 .data
Running main
[==========] Running 1 tests from 1 test suites.
[----------] 1 tests from FilterBqTest
[ RUN      ] FilterBqTest.filterBessel
[       OK ] FilterBqTest.filterBessel (2 ms)
[----------] 1 tests from FilterBqTest (2 ms total)

[==========] 1 tests from 1 test suites ran. (2 ms total)
[  PASSED  ] 1 tests.

Warum simavr... ...
Ein hauptgrund war, dass das Framework recht einfach ist und er recht 
gut erweiterbar ist. Auch habe ich dann in den Beispielen zu dem 
Simulator gefunden, dass man dort auch Hardware simulieren kann. Ganz so 
schwierig ist das auch nicht. Sobald der Simulator initialisiert ist, 
gibt es einen Hook welchen man nutzen kann um die Hardware zu 
simulieren.
Dazu überschreibt man den test_init_hook und linkt sein Objekt gegen die 
libtestRunner.so.

void test_init_hook( avr_t *avr );
void test_start_hook( avr_t *avr, char *name );

Die zweite Funktion ist ein Hook, welcher aufgerufen wird wenn ein Test 
startet. Der Name des Tests wird dann in name übergeben.

Ich wünsche viel Freude und ich würde mich über Nachfragen und Beiträge 
freuen.

Viele Grüße
Sebastian

[Sebastian K. (seplog)]

Hallo,

ich habe einmal wieder ein Update parat. Mein Ziel war es nun das 
Framework auf andere Architekturen zu portieren. Die einfachste war nun 
erst einmal die x86-Architektur. Dort ist mir aber ein Problem bei dem 
Konzept aufgefallen.

Beim AVR habe ich die Tests via der .init7 auf den Stack gepusht beim 
registrieren. Das ist weder bei x86 ordentlich möglich noch bei RISC-V 
(zweiter port)... Aus dem Grund bin ich nun einmal an die Linkerfile 
ran. Dort habe ich nun für den test eine extra Section eingeführt. Das 
funktioniert nun bei x86 sehr gut (dort kann man Sections einfügen) bei 
AVR und RISC-V hab ich das noch nicht ganz so schön hinbekommen.. -.-
Sei es drum, dort stelle ich eine gepatchte Linkerfile mit zur 
Verfügung.

Lauffähig ist das Framework nun auf
  - AVR
  - x86
  - RISC-V (picolibc)

Beim Simulator-Frontend für den AVR habe ich noch einen 
Use-After-Free-Bug behoben wenn FIXTURE-Tests ausgeführt werden. 
Weiterhin habe ich nun noch ein wenig mehr dokumentiert und auch in der 
README nun zwei kleine Beispiele drin. Für AVR und für RISC-V.

Das war es nun aber ;)

Viele Grüße
Sebastian