3 A testsuite covering functionality of btrfs-progs, ie. the checker, image, mkfs
4 and similar tools. There are no additional requirements on kernel features
5 (other than `CONFIG_BTRFS_FS` built-in or module), the
6 tests build on top of the core functionality like snapshots and device
7 management. In some cases optional features are turned on by mkfs and the
8 filesystem image could be mounted, such tests might fail if there's lack of
13 Run the tests from the top directory:
21 or selectively from the `tests/` directory:
28 The verbose output of the tests is logged into a file named after the test
29 category, eg. `fsck-tests-results.txt`.
33 The test are prefixed by a number for ordering and uniqueness. To run a
40 where `MASK` is a glob expression that will execute only tests
41 that match the MASK. Here the test number comes handy:
44 $ make TEST=001\* test-fsck
45 $ TEST=001\* ./fsck-tests.sh
48 will run the first test in fsck-tests subdirectory.
55 * tests targeted at bugs that are fixable by fsck
57 *tests/convert-tests/:*
59 * coverage tests of ext2/3/4 and btrfs-convert options
63 * collection of fuzzed or crafted images
64 * tests that are supposed to run various utilities on the images and not
69 * tests for command line interface, option coverage, weird option combinations that should not work
70 * not necessary to do any functional testing, could be rather lightweight
71 * functional tests should go to to other test dirs
72 * the driver script will only execute `./test.sh` in the test directory
76 * anything that does not fit to the above, the test driver script will only
77 execute `./test.sh` in the test directory
80 *tests/common.convert:*
82 * script with shell helpers, separated by functionality
86 * default testing image, the file is never deleted by the scripts but
87 truncated to 0 bytes, so it keeps it's permissions. It's eg. possible to
88 host it on NFS, make it `chmod a+w` for root.
91 ## Other tuning, environment variables
95 It's possible to wrap the tested commands to utilities that might do more
96 checking or catch failures at runtime. This can be done by setting the
97 `INSTRUMENT` environment variable:
100 INSTRUMENT=valgrind ./fuzz-tests.sh # in tests/
101 make INSTRUMENT=valgrind test-fuzz # in the top directory
104 The variable is prepended to the command *unquoted*, all sorts of shell tricks
107 Note: instrumentation is not applied to privileged commands (anything that uses
110 ### Verbosity, test tuning
112 * `TEST_LOG=tty` -- setting the variable will print all commands executed by
113 some of the wrappers (`run_check` etc), other commands are not printed to the
114 terminal (but the full output is in the log)
116 * `TEST_LOG=dump` -- dump the entire testing log when a test fails
118 * `TEST_ENABLE_OVERRIDE` -- defined either as make arguments or via
119 `tests/common.local` to enable additional arguments to some commands, using
120 the variable(s) below (default: false, enable by setting to 'true')
122 * `TEST_ARGS_CHECK` -- user-defined arguments to `btrfs check`, before the
123 test-specific arguments
125 Multiple values can be separated by `,`.
129 Some commands require root privileges (to mount/umount, access loop devices).
130 It is assumed that `sudo` will work in some way (no password, password asked
131 and cached). Note that instrumentation is not applied in this case, for safety
132 reasons. You need to modify the test script instead.
136 The tests are supposed to cleanup after themselves if they pass. In case of
137 failure, the rest of the tests are skipped and intermediate files, mounts and
138 loop devices are kept. This should help to investigate the test failure but at
139 least the mounts and loop devices need to be cleaned before the next run.
141 This is partially done by the script `clean-tests.sh`, you may want to check
142 the loop devices as they are managed on a per-test basis.
144 ### Prototyping tests, quick tests
146 There's a script `test-console.sh` that will run shell commands in a loop and
147 logs the output with the testing environment set up.
151 1. Pick the category for the new test or fallback to `misc-tests` if not sure. For
152 an easy start copy an existing `test.sh` script from some test that might be
153 close to the purpose of your new test. The environment setup includes the
154 common scripts and/or prepares the test devices. Other scripts contain examples
155 how to do mkfs, mount, unmount, check, etc.
157 2. Use the highest unused number in the sequence, write a short descriptive title
158 and join by dashes `-`. This will become the directory name, eg. `012-subvolume-sync-must-wait`.
160 3. Write a short description of the bug and how it's tested to the comment at the
161 begining of `test.sh`. You don't need to add the file to git yet.
163 4. Write the test commands, comment anything that's not obvious.
165 5. Test your test. Use the `TEST` variable to jump right to your test:
167 $ make TEST=012\* tests-misc # from top directory
168 $ TEST=012\* ./misc-tests.sh # from tests/
171 6. The commit changelog should reference a commit that either introduced or
172 fixed the bug (or both). Subject line of the shall mention the name of the
173 new directory for ease of search, eg. `btrfs-progs: tests: add 012-subvolume-sync-must-wait`
175 ### Crafted/fuzzed images
177 Images that are create by fuzzing or specially crafted to trigger some error
178 conditions should be added to the directory *fuzz-tests/images*, accompanied by
179 a textual description of the source (bugzilla, mail), the reporter, brief
180 description of the problem or the stack trace.
182 If you have a fix for the problem, please submit it prior to the test image, so
183 the fuzz tests always succeed when run on random checked out. This helps