1*eda14cbcSMatt Macy# ZFS Test Suite README 2*eda14cbcSMatt Macy 3*eda14cbcSMatt Macy1) Building and installing the ZFS Test Suite 4*eda14cbcSMatt Macy 5*eda14cbcSMatt MacyThe ZFS Test Suite runs under the test-runner framework. This framework 6*eda14cbcSMatt Macyis built along side the standard ZFS utilities and is included as part of 7*eda14cbcSMatt Macyzfs-test package. The zfs-test package can be built from source as follows: 8*eda14cbcSMatt Macy 9*eda14cbcSMatt Macy $ ./configure 10*eda14cbcSMatt Macy $ make pkg-utils 11*eda14cbcSMatt Macy 12*eda14cbcSMatt MacyThe resulting packages can be installed using the rpm or dpkg command as 13*eda14cbcSMatt Macyappropriate for your distributions. Alternately, if you have installed 14*eda14cbcSMatt MacyZFS from a distributions repository (not from source) the zfs-test package 15*eda14cbcSMatt Macymay be provided for your distribution. 16*eda14cbcSMatt Macy 17*eda14cbcSMatt Macy - Installed from source 18*eda14cbcSMatt Macy $ rpm -ivh ./zfs-test*.rpm, or 19*eda14cbcSMatt Macy $ dpkg -i ./zfs-test*.deb, 20*eda14cbcSMatt Macy 21*eda14cbcSMatt Macy - Installed from package repository 22*eda14cbcSMatt Macy $ yum install zfs-test 23*eda14cbcSMatt Macy $ apt-get install zfs-test 24*eda14cbcSMatt Macy 25*eda14cbcSMatt Macy2) Running the ZFS Test Suite 26*eda14cbcSMatt Macy 27*eda14cbcSMatt MacyThe pre-requisites for running the ZFS Test Suite are: 28*eda14cbcSMatt Macy 29*eda14cbcSMatt Macy * Three scratch disks 30*eda14cbcSMatt Macy * Specify the disks you wish to use in the $DISKS variable, as a 31*eda14cbcSMatt Macy space delimited list like this: DISKS='vdb vdc vdd'. By default 32*eda14cbcSMatt Macy the zfs-tests.sh script will construct three loopback devices to 33*eda14cbcSMatt Macy be used for testing: DISKS='loop0 loop1 loop2'. 34*eda14cbcSMatt Macy * A non-root user with a full set of basic privileges and the ability 35*eda14cbcSMatt Macy to sudo(8) to root without a password to run the test. 36*eda14cbcSMatt Macy * Specify any pools you wish to preserve as a space delimited list in 37*eda14cbcSMatt Macy the $KEEP variable. All pools detected at the start of testing are 38*eda14cbcSMatt Macy added automatically. 39*eda14cbcSMatt Macy * The ZFS Test Suite will add users and groups to test machine to 40*eda14cbcSMatt Macy verify functionality. Therefore it is strongly advised that a 41*eda14cbcSMatt Macy dedicated test machine, which can be a VM, be used for testing. 42*eda14cbcSMatt Macy 43*eda14cbcSMatt MacyOnce the pre-requisites are satisfied simply run the zfs-tests.sh script: 44*eda14cbcSMatt Macy 45*eda14cbcSMatt Macy $ /usr/share/zfs/zfs-tests.sh 46*eda14cbcSMatt Macy 47*eda14cbcSMatt MacyAlternately, the zfs-tests.sh script can be run from the source tree to allow 48*eda14cbcSMatt Macydevelopers to rapidly validate their work. In this mode the ZFS utilities and 49*eda14cbcSMatt Macymodules from the source tree will be used (rather than those installed on the 50*eda14cbcSMatt Macysystem). In order to avoid certain types of failures you will need to ensure 51*eda14cbcSMatt Macythe ZFS udev rules are installed. This can be done manually or by ensuring 52*eda14cbcSMatt Macysome version of ZFS is installed on the system. 53*eda14cbcSMatt Macy 54*eda14cbcSMatt Macy $ ./scripts/zfs-tests.sh 55*eda14cbcSMatt Macy 56*eda14cbcSMatt MacyThe following zfs-tests.sh options are supported: 57*eda14cbcSMatt Macy 58*eda14cbcSMatt Macy -v Verbose zfs-tests.sh output When specified additional 59*eda14cbcSMatt Macy information describing the test environment will be logged 60*eda14cbcSMatt Macy prior to invoking test-runner. This includes the runfile 61*eda14cbcSMatt Macy being used, the DISKS targeted, pools to keep, etc. 62*eda14cbcSMatt Macy 63*eda14cbcSMatt Macy -q Quiet test-runner output. When specified it is passed to 64*eda14cbcSMatt Macy test-runner(1) which causes output to be written to the 65*eda14cbcSMatt Macy console only for tests that do not pass and the results 66*eda14cbcSMatt Macy summary. 67*eda14cbcSMatt Macy 68*eda14cbcSMatt Macy -x Remove all testpools, dm, lo, and files (unsafe). When 69*eda14cbcSMatt Macy specified the script will attempt to remove any leftover 70*eda14cbcSMatt Macy configuration from a previous test run. This includes 71*eda14cbcSMatt Macy destroying any pools named testpool, unused DM devices, 72*eda14cbcSMatt Macy and loopback devices backed by file-vdevs. This operation 73*eda14cbcSMatt Macy can be DANGEROUS because it is possible that the script 74*eda14cbcSMatt Macy will mistakenly remove a resource not related to the testing. 75*eda14cbcSMatt Macy 76*eda14cbcSMatt Macy -k Disable cleanup after test failure. When specified the 77*eda14cbcSMatt Macy zfs-tests.sh script will not perform any additional cleanup 78*eda14cbcSMatt Macy when test-runner exists. This is useful when the results of 79*eda14cbcSMatt Macy a specific test need to be preserved for further analysis. 80*eda14cbcSMatt Macy 81*eda14cbcSMatt Macy -f Use sparse files directly instead of loopback devices for 82*eda14cbcSMatt Macy the testing. When running in this mode certain tests will 83*eda14cbcSMatt Macy be skipped which depend on real block devices. 84*eda14cbcSMatt Macy 85*eda14cbcSMatt Macy -c Only create and populate constrained path 86*eda14cbcSMatt Macy 87*eda14cbcSMatt Macy -I NUM Number of iterations 88*eda14cbcSMatt Macy 89*eda14cbcSMatt Macy -d DIR Create sparse files for vdevs in the DIR directory. By 90*eda14cbcSMatt Macy default these files are created under /var/tmp/. 91*eda14cbcSMatt Macy 92*eda14cbcSMatt Macy -s SIZE Use vdevs of SIZE (default: 4G) 93*eda14cbcSMatt Macy 94*eda14cbcSMatt Macy -r RUNFILES Run tests in RUNFILES (default: common.run,linux.run) 95*eda14cbcSMatt Macy 96*eda14cbcSMatt Macy -t PATH Run single test at PATH relative to test suite 97*eda14cbcSMatt Macy 98*eda14cbcSMatt Macy -T TAGS Comma separated list of tags (default: 'functional') 99*eda14cbcSMatt Macy 100*eda14cbcSMatt Macy -u USER Run single test as USER (default: root) 101*eda14cbcSMatt Macy 102*eda14cbcSMatt Macy 103*eda14cbcSMatt MacyThe ZFS Test Suite allows the user to specify a subset of the tests via a 104*eda14cbcSMatt Macyrunfile or list of tags. 105*eda14cbcSMatt Macy 106*eda14cbcSMatt MacyThe format of the runfile is explained in test-runner(1), and 107*eda14cbcSMatt Macythe files that zfs-tests.sh uses are available for reference under 108*eda14cbcSMatt Macy/usr/share/zfs/runfiles. To specify a custom runfile, use the -r option: 109*eda14cbcSMatt Macy 110*eda14cbcSMatt Macy $ /usr/share/zfs/zfs-tests.sh -r my_tests.run 111*eda14cbcSMatt Macy 112*eda14cbcSMatt MacyOtherwise user can set needed tags to run only specific tests. 113*eda14cbcSMatt Macy 114*eda14cbcSMatt Macy3) Test results 115*eda14cbcSMatt Macy 116*eda14cbcSMatt MacyWhile the ZFS Test Suite is running, one informational line is printed at the 117*eda14cbcSMatt Macyend of each test, and a results summary is printed at the end of the run. The 118*eda14cbcSMatt Macyresults summary includes the location of the complete logs, which is logged in 119*eda14cbcSMatt Macythe form `/var/tmp/test_results/[ISO 8601 date]`. A normal test run launched 120*eda14cbcSMatt Macywith the `zfs-tests.sh` wrapper script will look something like this: 121*eda14cbcSMatt Macy 122*eda14cbcSMatt Macy $ /usr/share/zfs/zfs-tests.sh -v -d /tmp/test 123*eda14cbcSMatt Macy 124*eda14cbcSMatt Macy --- Configuration --- 125*eda14cbcSMatt Macy Runfile: /usr/share/zfs/runfiles/linux.run 126*eda14cbcSMatt Macy STF_TOOLS: /usr/share/zfs/test-runner 127*eda14cbcSMatt Macy STF_SUITE: /usr/share/zfs/zfs-tests 128*eda14cbcSMatt Macy STF_PATH: /var/tmp/constrained_path.G0Sf 129*eda14cbcSMatt Macy FILEDIR: /tmp/test 130*eda14cbcSMatt Macy FILES: /tmp/test/file-vdev0 /tmp/test/file-vdev1 /tmp/test/file-vdev2 131*eda14cbcSMatt Macy LOOPBACKS: /dev/loop0 /dev/loop1 /dev/loop2 132*eda14cbcSMatt Macy DISKS: loop0 loop1 loop2 133*eda14cbcSMatt Macy NUM_DISKS: 3 134*eda14cbcSMatt Macy FILESIZE: 4G 135*eda14cbcSMatt Macy ITERATIONS: 1 136*eda14cbcSMatt Macy TAGS: functional 137*eda14cbcSMatt Macy Keep pool(s): rpool 138*eda14cbcSMatt Macy 139*eda14cbcSMatt Macy 140*eda14cbcSMatt Macy /usr/share/zfs/test-runner/bin/test-runner.py -c /usr/share/zfs/runfiles/linux.run \ 141*eda14cbcSMatt Macy -T functional -i /usr/share/zfs/zfs-tests -I 1 142*eda14cbcSMatt Macy Test: /usr/share/zfs/zfs-tests/tests/functional/arc/setup (run as root) [00:00] [PASS] 143*eda14cbcSMatt Macy ...more than 1100 additional tests... 144*eda14cbcSMatt Macy Test: /usr/share/zfs/zfs-tests/tests/functional/zvol/zvol_swap/cleanup (run as root) [00:00] [PASS] 145*eda14cbcSMatt Macy 146*eda14cbcSMatt Macy Results Summary 147*eda14cbcSMatt Macy SKIP 52 148*eda14cbcSMatt Macy PASS 1129 149*eda14cbcSMatt Macy 150*eda14cbcSMatt Macy Running Time: 02:35:33 151*eda14cbcSMatt Macy Percent passed: 95.6% 152*eda14cbcSMatt Macy Log directory: /var/tmp/test_results/20180515T054509 153