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 uniqueness. 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/cli-tests/:*
  58
  59   * tests for command line interface, option coverage, weird optin combinations that should not work
  60   * not necessary to do any functional testing, could be rather lightweight
  61   * functional tests should go to to other test dirs
  62   * the driver script will only execute `./test.sh` in the test directory
  63
  64 *tests/misc-tests/:*
  65
  66   * anything that does not fit to the above, the test driver script will only
  67     execute `./test.sh` in the test directory
  68
  69 *tests/common:*
  70
  71   * script with helpers
  72
  73 *tests/test.img:*
  74
  75   * default testing image, the file is never deleted by the scripts but
  76     truncated to 0 bytes, so it keeps it's permissions. It's eg. possible to
  77     host it on NFS, make it `chmod a+w` for root.
  78
  79
  80 ## Other tuning, environment variables
  81
  82 ### Instrumentation
  83
  84 It's possible to wrap the tested commands to utilities that might do more
  85 checking or catch failures at runtime. This can be done by setting the
  86 `INSTRUMENT` environment variable:
  87
  88 ```shell
  89 INSTRUMENT=valgrind ./fuzz-tests.sh    # in tests/
  90 make INSTRUMENT=valgrind test-fuzz     # in the top directory
  91 ```
  92
  93 The variable is prepended to the command *unquoted*, all sorts of shell tricks
  94 are possible.
  95
  96 Note: instrumentation is not applied to privileged commands (anything that uses
  97 the root helper).
  98
  99 ### Verbosity
 100
 101 Setting the variable `TEST_LOG=tty` will print all commands executed by some of
 102 the wrappers (`run_check` etc), other commands are silent.
 103
 104 ### Permissions
 105
 106 Some commands require root privileges (to mount/umount, access loop devices).
 107 It is assumed that `sudo` will work in some way (no password, password asked
 108 and cached). Note that instrumentation is not applied in this case, for safety
 109 reasons. You need to modify the test script instead.
 110
 111 ### Cleanup
 112
 113 The tests are supposed to cleanup after themselves if they pass. In case of
 114 failure, the rest of the tests are skipped and intermediate files, mounts and
 115 loop devices are kept. This should help to investigate the test failure but at
 116 least the mounts and loop devices need to be cleaned before the next run.
 117
 118 This is partially done by the script `clean-tests.sh`, you may want to check
 119 the loop devices as they are managed on a per-test basis.
 120
 121 ## New test
 122
 123 1. Pick the category for the new test or fallback to `misc-tests` if not sure. For
 124 an easy start copy an existing `test.sh` script from some test that might be
 125 close to the purpose of your new test.
 126
 127 * Use the highest unused number in the sequence, write a short descriptive title
 128 and join by dashes `-`.
 129
 130 * Write a short description of the bug and how it's tested to the comment at the
 131 begining of `test.sh`.
 132
 133 * Write the test commands, comment anything that's not obvious.
 134
 135 * Test your test. Use the `TEST` variable to jump right to your test:
 136 ```shell
 137 $ make TEST=012\* tests-misc           # from top directory
 138 $ TEST=012\* ./misc-tests.sh           # from tests/
 139 ```
 140
 141 * The commit changelog should reference a commit that either introduced or
 142   fixed the bug (or both). Subject line of the shall mention the name of the
 143   new directory for ease of search, eg. `btrfs-progs: tests: add 012-subvolume-sync-must-wait`