grub-fstest

grub-fstest [OPTION...] IMAGE [TEST...]

-d, --debug
    Produce debug output

-h, --help
    Display this message and exit

--locales=DIR
    Use DIR as directory where the locales are installed

--fonts=DIR
    Use DIR as directory where the fonts are installed

--modules=DIR
    Use DIR as directory where the modules are installed

-v, --verbose
    Print verbose messages

--version
    Print the version information and exit

grub-fstest is a utility from the GRUB2 bootloader suite designed to test GRUB's filesystem modules against a specified filesystem image file in userspace.

It simulates GRUB's filesystem access environment, allowing developers and users to verify that modules like ext2, btrfs, fat, xfs, and others correctly read directories, files, symlinks, and metadata from the image.

By default, it runs a comprehensive set of tests including directory listing, file reading, stat operations, and more. Specific tests can be selected via command-line arguments. This is invaluable for GRUB developers adding new filesystem support, troubleshooting boot issues related to filesystems, or validating disk images before creating bootable media.

The tool mounts the image read-only using GRUB's modules (loaded from the standard module path or a custom one) and reports pass/fail results with optional verbose or debug output. It does not modify the image, focusing on read compatibility. Success ensures the image is likely parsable by GRUB at boot time, though it lacks full bootloader context like memory constraints.

Tests are read-only and run in userspace; does not replicate full GRUB boot environment constraints like limited memory or device access. Not all filesystems support all tests.

all (default), dirs, files, symlinks, readdir, stat, read, lstat, utime, mkdir, rmdir, unlink, symlink, chmod

Introduced in GRUB 2.04 (2016) as part of enhanced developer tools; evolved from earlier GRUB2 utilities to aid filesystem module development amid growing support for modern filesystems like Btrfs.

grub-probe(1), grub-mkimage(1), grub-editenv(1)