btrfs-progs: tests: update README.md

Irregular proofreading with adjustments and enhancements.

Signed-off-by: David Sterba <dsterba@suse.com>

diff --git a/tests/README.md b/tests/README.md
index c456018..c6d89a5 100644 (file)
--- 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