1# 2# This file and its contents are supplied under the terms of the 3# Common Development and Distribution License ("CDDL"), version 1.0. 4# You may only use this file in accordance with the terms of version 5# 1.0 of the CDDL. 6# 7# A full copy of the text of the CDDL should have accompanied this 8# source. A copy of the CDDL is also available via the Internet at 9# http://www.illumos.org/license/CDDL. 10# 11 12# 13# Copyright (c) 2013 by Delphix. All rights reserved. 14# 15 16ZFS Test Suite README 17 181. Building and installing the ZFS Test Suite 192. Running the ZFS Test Suite 203. Test results 21 22-------------------------------------------------------------------------------- 23 241. Building and installing the ZFS Test Suite 25 26The ZFS Test Suite runs under the testrunner framework (which can be installed 27as pkg:/system/test/testrunner). To build both the ZFS Test Suite and the 28testrunner without running a full nightly: 29 30 build_machine$ bldenv [-d] <your_env_file> 31 build_machine$ cd $SRC/test 32 build_machine$ dmake install 33 build_machine$ cd $SRC/pkg 34 build_machine$ dmake install 35 36Then set the publisher on the test machine to point to your repository and 37install the ZFS Test Suite. 38 39 test_machine# pkg install pkg:/system/test/zfstest 40 41Note, the framework will be installed automatically, as the ZFS Test Suite 42depends on it. 43 442. Running the ZFS Test Suite 45 46The pre-requisites for running the ZFS Test Suite are: 47 - root pool about 100GB (some test data is using /var/tmp) 48 - about 8GB RAM 49 - Three scratch disks, all the same size. The minimum disk size is 50 determined by the system's crash dump size (roughly equal to RAM), 51 plus a small overhead. The zfstest script enforces a floor of 10GB. 52 For example, a system with 8GB RAM needs disks of at least 10GB; 53 a system with 16GB RAM needs disks of at least 16GB. Tests with ufs 54 require 512B native or 512e sector disks. Disks of differing sizes 55 will cause mirror-related tests (e.g. zpool_scrub, zpool_resilver, 56 zpool_trim) to fail with "device is too small". All disks should 57 present the same block size or some tests will fail. 58 - Specify the disks you wish to use in the $DISKS variable, as a 59 space delimited list like this: DISKS='c3t1d0 c3t2d0 c3t3d0' 60 - Use the '-a' option to the zfstest script and all unused disks on 61 the system are eligible. With '-a' specified, $DISKS is ignored. 62 - A non-root user with the full set of basic privileges and the ability 63 to sudo(8) to root without a password to run the test. 64 - Specify any pools you wish to preserve as a space delimited list in 65 the $KEEP variable. The root pool is added automatically. 66 67Once the pre-requisites are satisfied, simply run the zfstest script: 68 69 test_machine$ /opt/zfs-tests/bin/zfstest [-aq] 70 71When the '-q' option is specified, it is passed to run(1) which causes output 72to be written to the console only for tests that do not pass and the results 73summary. 74 75The ZFS Test Suite allows the user to specify a subset of the tests via a 76runfile. The format of the runfile is explained in run(1), and the files that 77zfstest uses are available for reference under /opt/zfs-tests/runfiles. To 78specify a custom runfile, use the -c option: 79 80 test_machine$ /opt/zfs-tests/bin/zfstest [-aq] -c my_tests.run 81 823. Test results 83 84While the ZFS Test Suite is running, one informational line is printed at the 85end of each test, and a results summary is printed at the end of the run. The 86results summary includes the location of the complete logs, which is of the 87form /var/tmp/test_results/<ISO 8601 date>. 88