tests/README.md

   1 # Btrfs-progs tests
   2
   3 Run the tests from the top directory:
   4
   5 ```shell
   6 $ make test
   7 $ make test-fsck
   8 $ make test-convert
   9 ```
  10
  11 or selectively from the `tests/` directory:
  12
  13 ```shell
  14 $ ./fsck-tests.sh
  15 $ ./misc-tests.sh
  16 ```
  17
  18 The verbose output of the tests is logged into a file named after the test
  19 category, eg. `fsck-tests-results.txt`.
  20
  21 ## Selective testing
  22
  23 The test are prefixed by a number for ordering and uniquenes. To run a
  24 particular test use:
  25
  26 ```shell
  27 $ make TEST=MASK test
  28 ```
  29
  30 where `MASK` is a glob expression that will execute only tests
  31 that match the MASK. Here the test number comes handy:
  32
  33 ```shell
  34 $ make TEST=001\* test-fsck
  35 $ TEST=001\* ./fsck-tests.sh
  36 ```
  37
  38 will run the first test in fsck-tests subdirectory.
  39
  40
  41 ## Test structure
  42
  43 *tests/fsck-tests/:*
  44
  45   * tests targeted at bugs that are fixable by fsck
  46
  47 *tests/convert-tests/:*
  48
  49   * coverage tests of ext2/3/4 and btrfs-convert options
  50
  51 *tests/fuzz-tests/:*
  52
  53   * collection of fuzzed or crafted images
  54   * tests that are supposed to run various utilities on the images and not
  55     crash
  56
  57 *tests/misc-tests/:*
  58
  59   * anything that does not fit to the above, the test driver script will only
  60     execute `./test.sh` in the test directory
  61
  62 *tests/common:*
  63
  64   * script with helpers
  65
  66 *tests/test.img:*
  67
  68   * default testing image, the file is never deleted by the scripts but
  69     truncated to 0 bytes, so it keeps it's permissions. It's eg. possible to
  70     host it on NFS, make it `chmod a+w` for root.
  71
  72
  73 ## Other tuning, environment variables
  74
  75 ### Instrumentation
  76
  77 It's possible to wrap the tested commands to utilities that might do more
  78 checking or catch failures at runtime. This can be done by setting the
  79 `INSTRUMENT` environment variable:
  80
  81 ```shell
  82 INSTRUMENT=valgrind ./fuzz-tests.sh    # in tests/
  83 make INSTRUMENT=valgrind test-fuzz     # in the top directory
  84 ```
  85
  86 The variable is prepended to the command *unquoted*, all sorts of shell tricks
  87 are possible.
  88
  89 Note: instrumentation is not applied to privileged commands (anything that uses
  90 the root helper).
  91
  92 ### Verbosity
  93
  94 Setting the variable `TEST_LOG=tty` will print all commands executed by some of
  95 the wrappers (`run_check` etc), other commands are silent.
  96
  97 ### Permissions
  98
  99 Some commands require root privileges (to mount/umount, access loop devices).
 100 It is assumed that `sudo` will work in some way (no password, password asked
 101 and cached). Note that instrumentation is not applied in this case, for safety
 102 reasons. You need to modify the test script instead.
 103
 104 ### Cleanup
 105
 106 The tests are supposed to cleanup after themselves if they pass. In case of
 107 failure, the rest of the tests are skipped and intermediate files, mounts and
 108 loop devices are kept. This should help to investigate the test failure but at
 109 least the mounts and loop devices need to be cleaned before the next run.
 110
 111 This is partially done by the script `clean-tests.sh`, you may want to check
 112 the loop devices as they are managed on a per-test basis.
 113
 114 ## New test
 115
 116 1. Pick the category for the new test or fallback to `misc-tests` if not sure. For
 117 an easy start copy an existing `test.sh` script from some test that might be
 118 close to the purpose of your new test.
 119
 120 * Use the highest unused number in the sequence, write a short descriptive title
 121 and join by dashes `-`.
 122
 123 * Write a short description of the bug and how it's teste to the comment at the
 124 begining of `test.sh`.
 125
 126 * Write the test commands, comment anything that's not obvious.
 127
 128 * Test your test. Use the `TEST` variable to jump right to your test:
 129 ```shell
 130 $ make TEST=012\* tests-misc           # from top directory
 131 $ TEST=012\* ./misc-tests.sh           # from tests/
 132 ```
 133
 134 * The commit changelog should reference a commit that either introduced or
 135   fixed the bug (or both). Subject line of the shall mention the name of the
 136   new directory for ease of search, eg. `btrfs-progs: tests: add 012-subvolume-sync-must-wait`