Eretmochelys imbricata libfiu is a C library for fault injection.

It aims to simplify automated testing of software behaviour at failure scenarios, for software which is supposed to be fault-resistant or at least gracefully cope with failures.

It provides functions to mark "points of failure" inside your code (the core API), and functions to enable/disable the failure of those points (the control API).

The core API is used inside the code wanting to perform failure injection on. The control API is used inside the testing code, in order to control the injection of failures.

It also comes with some tools that can be used to perform fault injection in the POSIX API without having to modify the application's source code, that can help to test failure handling in an easy and reproducible way.

It's in the public domain, completely open source, so you can run the software anywhere, and link the library with whatever you want.

Examples

The fiu-run utility lets you simulate failures in the POSIX API at runtime, without modifying your code. For example, if you want to run "ls" and simulate that all I/O operations fail, you can run it using:
fiu-run -x -c 'enable name=posix/io/*' ls
If you want to simulate failure in your own functions, you can do so with minimal anotations. Let's say you want to test the code you wrote that checks if there's enough free space to fit a given file. You can write:
size_t free_space() {
        fiu_return_on("no_free_space", 0);

        [code to find out how much free space there is]
        return space;
}

bool file_fits(FILE *fd) {
        if (free_space() < file_size(fd)) {
                return false;
        }
        return true;
}
The fiu_return_on() annotation is the only change you need to make to your code to create a point of failure. In your testing code, this enables you to do:
fiu_init();
fiu_enable("no_free_space", 1, NULL, 0);
assert(file_fits("tmpfile") == false);
The first line initializes the library, and the second enables the point of failure. As the point of failure is enabled, the free_space() call will return 0, so you can test how your code behaves under that condition, which was otherwise hard to trigger.

Documentation

Articles

Download

The current version is 1.2 (released on 2023-10-29): You can also browse all released files.

Debian and Ubuntu users can also install it using apt-get install libfiu-dev fiu-utils [python3-fiu] (note it may be an older version).

Patches are welcome. The source code is managed using git. You can browse the repository, or clone it by running:

git clone https://blitiri.com.ar/repos/libfiu

Users