From dd11901dae6c11387ffce0c769718b22ca8128f0 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Thu, 8 Feb 2018 17:40:34 +0100 Subject: btrfs-progs: tests: update README.md Irregular proofreading with adjustments and enhancements. Signed-off-by: David Sterba --- tests/README.md | 57 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/tests/README.md b/tests/README.md index c4560185..c6d89a5c 100644 --- a/tests/README.md +++ b/tests/README.md @@ -45,46 +45,51 @@ $ make TEST=001\* test-fsck $ TEST=001\* ./fsck-tests.sh ``` -will run the first test in fsck-tests subdirectory. +will run the first test in fsck-tests subdirectory. If the test directories +follow a good naming scheme, it's possible to select a subset eg. like the +convert tests for ext[234] filesystems. ## Test structure -*tests/fsck-tests/:* +*tests/fsck-tests/* - * tests targeted at bugs that are fixable by fsck + * tests targeted at bugs that are fixable by fsck, the test directory can + contain images that will get fixed, or a custom script `./test.sh` that + will be run if present -*tests/convert-tests/:* +*tests/convert-tests/* - * coverage tests of ext2/3/4 and btrfs-convert options + * coverage tests of ext2/3/4 or reiserfs and btrfs-convert options -*tests/fuzz-tests/:* +*tests/fuzz-tests/* * collection of fuzzed or crafted images * tests that are supposed to run various utilities on the images and not crash -*tests/cli-tests/:* +*tests/cli-tests/* * tests for command line interface, option coverage, weird option combinations that should not work * not necessary to do any functional testing, could be rather lightweight * functional tests should go to to other test dirs * the driver script will only execute `./test.sh` in the test directory -*tests/misc-tests/:* +*tests/misc-tests/* * anything that does not fit to the above, the test driver script will only execute `./test.sh` in the test directory -*tests/common, tests/common.convert:* +*tests/common, tests/common.convert* - * script with shell helpers, separated by functionality + * scripts with shell helpers, separated by functionality -*tests/test.img:* +*tests/test.img* - * default testing image, the file is never deleted by the scripts but - truncated to 0 bytes, so it keeps it's permissions. It's eg. possible to - host it on NFS, make it `chmod a+w` for root. + * default testing image, available as `TEST_DEV` variable, the file is never + deleted by the scripts but truncated to 0 bytes, so it keeps it's + permissions. It's eg. possible to host it on NFS, make it `chmod a+w` for + root. ## Other tuning, environment variables @@ -125,10 +130,10 @@ Multiple values can be separated by `,`. ### Permissions -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. +Some commands require root privileges (to mount/umount, access loop devices or +call privileged ioctls). 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. ### Cleanup @@ -143,13 +148,14 @@ the loop devices as they are managed on a per-test basis. ### Prototyping tests, quick tests 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. +logs the output with the testing environment set up. It sources the common +helper scripts so the shell functions are available. ### Runtime dependencies The tests use some common system utilities like `find`, `rm`, `dd`. Additionally, specific tests need the following packages installed: `acl`, `attr`, -`e2fsprogs`, `reiserfsprogs` +`e2fsprogs`, `reiserfsprogs`. ## New test @@ -158,7 +164,7 @@ specific tests need the following packages installed: `acl`, `attr`, 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. +how to do mkfs, mount, unmount, check, loop device management etc. 2. 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`. @@ -180,10 +186,12 @@ $ TEST=012\* ./misc-tests.sh # from tests/ fixed the bug (or both). Subject line of the shall mention the name of the new directory for ease of search, eg. `btrfs-progs: tests: add 012-subvolume-sync-must-wait` +7. A commit that fixes a bug should be applied before the test that verifies + the fix. This is to keep the git history bisectable. ### Crafted/fuzzed images -Images that are create by fuzzing or specially crafted to trigger some error +Images that are created 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. @@ -208,8 +216,9 @@ bisectability. always built when the tests are started through make * use functions instead of repeating code * generic helpers could be factored to the `common` script -* cleanup after successful test -* use common helpers and variables +* cleanup files an intermediate state (mount, loop devices, device mapper + devices) a after successful test +* use common helpers and variables where possible ## do not -- cgit v1.2.3