tests/README.md

   1 # Btrfs-progs tests
   2
   3 A testsuite covering functionality of btrfs-progs, ie. the checker, image, mkfs
   4 and similar tools. There are no special requirements on kernel features, the
   5 tests build on top of the core functionality like snapshots and device
   6 management. In some cases optional features are turned on by mkfs and the
   7 filesystem image could be mounted, such tests might fail if there's lack of
   8 support.
   9
  10 ## Quick start
  11
  12 Run the tests from the top directory:
  13
  14 ```shell
  15 $ make test
  16 $ make test-fsck
  17 $ make test-convert
  18 ```
  19
  20 or selectively from the `tests/` directory:
  21
  22 ```shell
  23 $ ./fsck-tests.sh
  24 $ ./misc-tests.sh
  25 ```
  26
  27 The verbose output of the tests is logged into a file named after the test
  28 category, eg. `fsck-tests-results.txt`.
  29
  30 ## Selective testing
  31
  32 The test are prefixed by a number for ordering and uniqueness. To run a
  33 particular test use:
  34
  35 ```shell
  36 $ make TEST=MASK test
  37 ```
  38
  39 where `MASK` is a glob expression that will execute only tests
  40 that match the MASK. Here the test number comes handy:
  41
  42 ```shell
  43 $ make TEST=001\* test-fsck
  44 $ TEST=001\* ./fsck-tests.sh
  45 ```
  46
  47 will run the first test in fsck-tests subdirectory.
  48
  49
  50 ## Test structure
  51
  52 *tests/fsck-tests/:*
  53
  54   * tests targeted at bugs that are fixable by fsck
  55
  56 *tests/convert-tests/:*
  57
  58   * coverage tests of ext2/3/4 and btrfs-convert options
  59
  60 *tests/fuzz-tests/:*
  61
  62   * collection of fuzzed or crafted images
  63   * tests that are supposed to run various utilities on the images and not
  64     crash
  65
  66 *tests/cli-tests/:*
  67
  68   * tests for command line interface, option coverage, weird option combinations that should not work
  69   * not necessary to do any functional testing, could be rather lightweight
  70   * functional tests should go to to other test dirs
  71   * the driver script will only execute `./test.sh` in the test directory
  72
  73 *tests/misc-tests/:*
  74
  75   * anything that does not fit to the above, the test driver script will only
  76     execute `./test.sh` in the test directory
  77
  78 *tests/common:*
  79 *tests/common.convert:*
  80
  81   * script with shell helpers, separated by functionality
  82
  83 *tests/test.img:*
  84
  85   * default testing image, the file is never deleted by the scripts but
  86     truncated to 0 bytes, so it keeps it's permissions. It's eg. possible to
  87     host it on NFS, make it `chmod a+w` for root.
  88
  89
  90 ## Other tuning, environment variables
  91
  92 ### Instrumentation
  93
  94 It's possible to wrap the tested commands to utilities that might do more
  95 checking or catch failures at runtime. This can be done by setting the
  96 `INSTRUMENT` environment variable:
  97
  98 ```shell
  99 INSTRUMENT=valgrind ./fuzz-tests.sh    # in tests/
 100 make INSTRUMENT=valgrind test-fuzz     # in the top directory
 101 ```
 102
 103 The variable is prepended to the command *unquoted*, all sorts of shell tricks
 104 are possible.
 105
 106 Note: instrumentation is not applied to privileged commands (anything that uses
 107 the root helper).
 108
 109 ### Verbosity
 110
 111 * `TEST_LOG=tty` -- setting the variable will print all commands executed by
 112   some of the wrappers (`run_check` etc), other commands are not printed to the
 113   terminal (but the full output is in the log)
 114
 115 * `TEST_LOG=dump` -- dump the entire testing log when a test fails
 116
 117 Multiple values can be separated by `,`.
 118
 119 ### Permissions
 120
 121 Some commands require root privileges (to mount/umount, access loop devices).
 122 It is assumed that `sudo` will work in some way (no password, password asked
 123 and cached). Note that instrumentation is not applied in this case, for safety
 124 reasons. You need to modify the test script instead.
 125
 126 ### Cleanup
 127
 128 The tests are supposed to cleanup after themselves if they pass. In case of
 129 failure, the rest of the tests are skipped and intermediate files, mounts and
 130 loop devices are kept. This should help to investigate the test failure but at
 131 least the mounts and loop devices need to be cleaned before the next run.
 132
 133 This is partially done by the script `clean-tests.sh`, you may want to check
 134 the loop devices as they are managed on a per-test basis.
 135
 136 ### Prototyping tests, quick tests
 137
 138 There's a script `test-console.sh` that will run shell commands in a loop and
 139 logs the output with the testing environment set up.
 140
 141 ## New test
 142
 143 1. Pick the category for the new test or fallback to `misc-tests` if not sure. For
 144 an easy start copy an existing `test.sh` script from some test that might be
 145 close to the purpose of your new test. The environment setup includes the
 146 common scripts and/or prepares the test devices. Other scripts contain examples
 147 how to do mkfs, mount, unmount, check, etc.
 148
 149 2. Use the highest unused number in the sequence, write a short descriptive title
 150 and join by dashes `-`. This will become the directory name, eg. `012-subvolume-sync-must-wait`.
 151
 152 3. Write a short description of the bug and how it's tested to the comment at the
 153 begining of `test.sh`. You don't need to add the file to git yet.
 154
 155 4. Write the test commands, comment anything that's not obvious.
 156
 157 5. Test your test. Use the `TEST` variable to jump right to your test:
 158 ```shell
 159 $ make TEST=012\* tests-misc           # from top directory
 160 $ TEST=012\* ./misc-tests.sh           # from tests/
 161 ```
 162
 163 6. The commit changelog should reference a commit that either introduced or
 164   fixed the bug (or both). Subject line of the shall mention the name of the
 165   new directory for ease of search, eg. `btrfs-progs: tests: add 012-subvolume-sync-must-wait`
 166
 167 ### Crafted/fuzzed images
 168
 169 Images that are create by fuzzing or specially crafted to trigger some error
 170 conditions should be added to the directory *fuzz-tests/images*, accompanied by
 171 a textual description of the source (bugzilla, mail), the reporter, brief
 172 description of the problem or the stack trace.
 173
 174 If you have a fix for the problem, please submit it prior to the test image, so
 175 the fuzz tests always succeed when run on random checked out. This helps
 176 bisectability.