A testsuite covering functionality of btrfs-progs, ie. the checker, image, mkfs and similar tools. There are no additional requirements on kernel features (other than CONFIG_BTRFS_FS
built-in or module), the tests build on top of the core functionality like snapshots and device management. In some cases optional features are turned on by mkfs and the filesystem image could be mounted, such tests might fail if there's lack of support.
Run the tests from the top directory:
$ make test $ make test-fsck $ make test-convert
or selectively from the tests/
directory:
$ ./fsck-tests.sh $ ./misc-tests.sh
The verbose output of the tests is logged into a file named after the test category, eg. fsck-tests-results.txt
.
The test are prefixed by a number for ordering and uniqueness. To run a particular test use:
$ make TEST=MASK test
where MASK
is a glob expression that will execute only tests that match the MASK. Here the test number comes handy:
$ make TEST=001\* test-fsck $ TEST=001\* ./fsck-tests.sh
will run the first test in fsck-tests subdirectory.
tests/fsck-tests/:
tests/convert-tests/:
tests/fuzz-tests/:
tests/cli-tests/:
./test.sh
in the test directorytests/misc-tests/:
./test.sh
in the test directorytests/common: tests/common.convert:
tests/test.img:
chmod a+w
for root.It's possible to wrap the tested commands to utilities that might do more checking or catch failures at runtime. This can be done by setting the INSTRUMENT
environment variable:
INSTRUMENT=valgrind ./fuzz-tests.sh # in tests/ make INSTRUMENT=valgrind test-fuzz # in the top directory
The variable is prepended to the command unquoted, all sorts of shell tricks are possible.
Note: instrumentation is not applied to privileged commands (anything that uses the root helper).
TEST_LOG=tty
-- setting the variable will print all commands executed by some of the wrappers (run_check
etc), other commands are not printed to the terminal (but the full output is in the log)
TEST_LOG=dump
-- dump the entire testing log when a test fails
TEST_ENABLE_OVERRIDE
-- defined either as make arguments or via tests/common.local
to enable additional arguments to some commands, using the variable(s) below (default: false, enable by setting to ‘true’)
TEST_ARGS_CHECK
-- user-defined arguments to btrfs check
, before the test-specific arguments
Multiple values can be separated by ,
.
Some commands require root privileges (to mount/umount, access loop devices). It is assumed that sudo
will work in some way (no password, password asked and cached). Note that instrumentation is not applied in this case, for safety reasons. You need to modify the test script instead.
The tests are supposed to cleanup after themselves if they pass. In case of failure, the rest of the tests are skipped and intermediate files, mounts and loop devices are kept. This should help to investigate the test failure but at least the mounts and loop devices need to be cleaned before the next run.
This is partially done by the script clean-tests.sh
, you may want to check the loop devices as they are managed on a per-test basis.
There's a script test-console.sh
that will run shell commands in a loop and logs the output with the testing environment set up.
Pick the category for the new test or fallback to misc-tests
if not sure. For an easy start copy an existing test.sh
script from some test that might be close to the purpose of your new test. The environment setup includes the common scripts and/or prepares the test devices. Other scripts contain examples how to do mkfs, mount, unmount, check, etc.
Use the highest unused number in the sequence, write a short descriptive title and join by dashes -
. This will become the directory name, eg. 012-subvolume-sync-must-wait
.
Write a short description of the bug and how it‘s tested to the comment at the begining of test.sh
. You don’t need to add the file to git yet.
Write the test commands, comment anything that's not obvious.
Test your test. Use the TEST
variable to jump right to your test:
$ make TEST=012\* tests-misc # from top directory $ TEST=012\* ./misc-tests.sh # from tests/
btrfs-progs: tests: add 012-subvolume-sync-must-wait
Images that are create by fuzzing or specially crafted to trigger some error conditions should be added to the directory fuzz-tests/images, accompanied by a textual description of the source (bugzilla, mail), the reporter, brief description of the problem or the stack trace.
If you have a fix for the problem, please submit it prior to the test image, so the fuzz tests always succeed when run on random checked out. This helps bisectability.
$SUDO_HELPER
as it might be intentionally unset#!/bin/bash
explicitlycheck_prereq_global
)check_prereq
), though the basic set is always built when the tests are started through makecommon
scriptxfs_io
that‘s conveniently used in fstests but we’d require xfsprogs
, so use dd
instead