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 additional requirements on kernel features
   5 (other than `CONFIG_BTRFS_FS` built-in or module), the
   6 tests build on top of the core functionality like snapshots and device
   7 management. In some cases optional features are turned on by mkfs and the
   8 filesystem image could be mounted, such tests might fail if there's lack of
   9 support.
  10
  11 ## Quick start
  12
  13 Run the tests from the top directory:
  14
  15 ```shell
  16 $ make test
  17 $ make test-fsck
  18 $ make test-convert
  19 ```
  20
  21 or selectively from the `tests/` directory:
  22
  23 ```shell
  24 $ ./fsck-tests.sh
  25 $ ./misc-tests.sh
  26 ```
  27
  28 The verbose output of the tests is logged into a file named after the test
  29 category, eg. `fsck-tests-results.txt`.
  30
  31 ## Selective testing
  32
  33 The tests are prefixed by a number for ordering and uniqueness. To run a
  34 particular test use:
  35
  36 ```shell
  37 $ make TEST=MASK test
  38 ```
  39
  40 where `MASK` is a glob expression that will execute only tests
  41 that match the MASK. Here the test number comes handy:
  42
  43 ```shell
  44 $ make TEST=001\* test-fsck
  45 $ TEST=001\* ./fsck-tests.sh
  46 ```
  47
  48 will run the first test in fsck-tests subdirectory. If the test directories
  49 follow a good naming scheme, it's possible to select a subset eg. like the
  50 convert tests for ext[234] filesystems.
  51
  52
  53 ## Test structure
  54
  55 *tests/fsck-tests/*
  56
  57   * tests targeted at bugs that are fixable by fsck, the test directory can
  58     contain images that will get fixed, or a custom script `./test.sh` that
  59     will be run if present
  60
  61 *tests/convert-tests/*
  62
  63   * coverage tests of ext2/3/4 or reiserfs and btrfs-convert options
  64
  65 *tests/fuzz-tests/*
  66
  67   * collection of fuzzed or crafted images
  68   * tests that are supposed to run various utilities on the images and not
  69     crash
  70
  71 *tests/cli-tests/*
  72
  73   * tests for command line interface, option coverage, weird option combinations that should not work
  74   * not necessary to do any functional testing, could be rather lightweight
  75   * functional tests should go to to other test dirs
  76   * the driver script will only execute `./test.sh` in the test directory
  77
  78 *tests/misc-tests/*
  79
  80   * anything that does not fit to the above, the test driver script will only
  81     execute `./test.sh` in the test directory
  82
  83 *tests/common, tests/common.convert*
  84
  85   * scripts with shell helpers, separated by functionality
  86
  87 *tests/test.img*
  88
  89   * default testing image, available as `TEST_DEV` variable, the file is never
  90     deleted by the scripts but truncated to 0 bytes, so it keeps it's
  91     permissions. It's eg. possible to host it on NFS, make it `chmod a+w` for
  92     root.
  93
  94
  95 ## Other tuning, environment variables
  96
  97 ### Instrumentation
  98
  99 It's possible to wrap the tested commands to utilities that might do more
 100 checking or catch failures at runtime. This can be done by setting the
 101 `INSTRUMENT` environment variable:
 102
 103 ```shell
 104 INSTRUMENT=valgrind ./fuzz-tests.sh    # in tests/
 105 make INSTRUMENT=valgrind test-fuzz     # in the top directory
 106 ```
 107
 108 The variable is prepended to the command *unquoted*, all sorts of shell tricks
 109 are possible.
 110
 111 Note: instrumentation is not applied to privileged commands (anything that uses
 112 the root helper).
 113
 114 ### Verbosity, test tuning
 115
 116 * `TEST_LOG=tty` -- setting the variable will print all commands executed by
 117   some of the wrappers (`run_check` etc), other commands are not printed to the
 118   terminal (but the full output is in the log)
 119
 120 * `TEST_LOG=dump` -- dump the entire testing log when a test fails
 121
 122 * `TEST_ENABLE_OVERRIDE` -- defined either as make arguments or via
 123   `tests/common.local` to enable additional arguments to some commands, using
 124   the variable(s) below (default: false, enable by setting to 'true')
 125
 126 * `TEST_ARGS_CHECK` -- user-defined arguments to `btrfs check`, before the
 127   test-specific arguments
 128
 129 Multiple values can be separated by `,`.
 130
 131 ### Permissions
 132
 133 Some commands require root privileges (to mount/umount, access loop devices or
 134 call privileged ioctls).  It is assumed that `sudo` will work in some way (no
 135 password, password asked and cached). Note that instrumentation is not applied
 136 in this case, for safety reasons. You need to modify the test script instead.
 137
 138 ### Cleanup
 139
 140 The tests are supposed to cleanup after themselves if they pass. In case of
 141 failure, the rest of the tests are skipped and intermediate files, mounts and
 142 loop devices are kept. This should help to investigate the test failure but at
 143 least the mounts and loop devices need to be cleaned before the next run.
 144
 145 This is partially done by the script `clean-tests.sh`, you may want to check
 146 the loop devices as they are managed on a per-test basis.
 147
 148 ### Prototyping tests, quick tests
 149
 150 There's a script `test-console.sh` that will run shell commands in a loop and
 151 logs the output with the testing environment set up. It sources the common
 152 helper scripts so the shell functions are available.
 153
 154 ### Runtime dependencies
 155
 156 The tests use some common system utilities like `find`, `rm`, `dd`. Additionally,
 157 specific tests need the following packages installed: `acl`, `attr`,
 158 `e2fsprogs`, `reiserfsprogs`.
 159
 160
 161 ## New test
 162
 163 1. Pick the category for the new test or fallback to `misc-tests` if not sure. For
 164 an easy start copy an existing `test.sh` script from some test that might be
 165 close to the purpose of your new test. The environment setup includes the
 166 common scripts and/or prepares the test devices. Other scripts contain examples
 167 how to do mkfs, mount, unmount, check, loop device management etc.
 168
 169 2. Use the highest unused number in the sequence, write a short descriptive title
 170 and join by dashes `-`. This will become the directory name, eg. `012-subvolume-sync-must-wait`.
 171
 172 3. Write a short description of the bug and how it's tested to the comment at the
 173 begining of `test.sh`. You don't need to add the file to git yet. Don't forget
 174 to make the file executable, otherwise it's not going to be executed by the
 175 infrastructure.
 176
 177 4. Write the test commands, comment anything that's not obvious.
 178
 179 5. **Test your test.** Use the `TEST` variable to jump right to your test:
 180 ```shell
 181 $ make TEST=012\* tests-misc           # from top directory
 182 $ TEST=012\* ./misc-tests.sh           # from tests/
 183 ```
 184
 185 6. The commit changelog should reference a commit that either introduced or
 186   fixed the bug (or both). Subject line of the shall mention the name of the
 187   new directory for ease of search, eg. `btrfs-progs: tests: add 012-subvolume-sync-must-wait`
 188
 189 7. A commit that fixes a bug should be applied before the test that verifies
 190   the fix. This is to keep the git history bisectable.
 191
 192 ### Crafted/fuzzed images
 193
 194 Images that are created by fuzzing or specially crafted to trigger some error
 195 conditions should be added to the directory *fuzz-tests/images*, accompanied by
 196 a textual description of the source (bugzilla, mail), the reporter, brief
 197 description of the problem or the stack trace.
 198
 199 If you have a fix for the problem, please submit it prior to the test image, so
 200 the fuzz tests always succeed when run on random checked out. This helps
 201 bisectability.
 202
 203
 204 # Exported testsuite
 205
 206 The tests are typically run from git on binaries built from the git sources. It
 207 is possible to extract only the testsuite files and run it independently. Use
 208
 209 ```shell
 210 $ make testsuite
 211 ```
 212
 213 This will gather scripts and generate `tests/btrfs-progs-tests.tar.gz`. The
 214 files inside the tar are in the top level directory, make sure you extract
 215 the contents to an empty directory. From there you can start the tests as
 216 described above (the non-make variant).
 217
 218 By default the binaries found in `$PATH` are used, this will normally mean the
 219 system binaries. You can also override the `$TOP` shell variable and this
 220 path will be used as prefix for all btrfs binaries inside the tests.
 221
 222 There are some utilities that are not distributed but are necessary for the
 223 tests. They are in the top level directory of the testsuite and their path
 224 cannot be set.
 225
 226 The tests assume write acesss to their directories.
 227
 228
 229 # Coding style, best practices
 230
 231 ## do
 232
 233 * quote all variables by default, any path, even the TOP could need that, and
 234   we use it everywhere
 235   * there are exceptions:
 236     * `$SUDO_HELPER` as it might be intentionally unset
 237     * the variable is obviously set to a value that does not require it
 238 * use `#!/bin/bash` explicitly
 239 * check for all external dependencies (`check_prereq_global`)
 240 * check for internal dependencies (`check_prereq`), though the basic set is
 241   always built when the tests are started through make
 242 * use functions instead of repeating code
 243   * generic helpers could be factored to the `common` script
 244 * cleanup files an intermediate state (mount, loop devices, device mapper
 245   devices) a after successful test
 246 * use common helpers and variables where possible
 247
 248 ## do not
 249
 250 * pull external dependencies if we can find a way to replace them: example is
 251   `xfs_io` that's conveniently used in fstests but we'd require `xfsprogs`,
 252   so use `dd` instead
 253 * throw away (redirect to */dev/null*) output of commands unless it's justified
 254   (ie. really too much text, unnecessary slowdown) -- the test output log is
 255   regenerated all the time and we need to be able to analyze test failures or
 256   just observe how the tests progress
 257 * cleanup after failed test -- the testsuite stops on first failure and the
 258   developer can eg. access the environment that the test created and do further
 259   debugging
 260   * this might change in the future so the tests cover as much as possible, but
 261     this would require to enhance all tests with a cleanup phase