README revision d583b39bfb4e2571d3e41097c5c357ffe353ad45
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews# This file and its contents are supplied under the terms of the
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews# Common Development and Distribution License ("CDDL"), version 1.0.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews# You may only use this file in accordance with the terms of version
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews# 1.0 of the CDDL.
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman# A full copy of the text of the CDDL should have accompanied this
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman# source. A copy of the CDDL is also available via the Internet at
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman# Copyright (c) 2012 by Delphix. All rights reserved.
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanZFS Test Suite README
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman1. Building and installing the ZFS Test Suite
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman2. Running the ZFS Test Suite
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman3. Test results
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman--------------------------------------------------------------------------------
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman1. Building and installing the ZFS Test Suite
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanThe ZFS Test Suite runs under the testrunner framework (which can be installed
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanas pkg:/system/test/testrunner). To build both the ZFS Test Suite and the
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramantestrunner without running a full nightly:
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman build_machine$ bldenv [-d] <your_env_file>
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman build_machine$ cd $SRC/test
7e6cf6fc6e700061a1cec3bcf67786706d956fc5Evan Hunt build_machine$ dmake install
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman build_machine$ cd $SRC/pkg
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman build_machine$ dmake install
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanThen set the publisher on the test machine to point to your repository and
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramaninstall the ZFS Test Suite.
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman test_machine# pkg install pkg:/system/test/zfstest
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanNote, the framework will be installed automatically, as the ZFS Test Suite
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramandepends on it.
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman2. Running the ZFS Test Suite
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanThe pre-requisites for running the ZFS Test Suite are:
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman - Three scratch disks
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman - Specify the disks you wish to use in the $DISKS variable, as a
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman space delimited list like this: DISKS='c3t1d0 c3t2d0 c3t3d0'
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman - Use the '-a' option to the zfstest script and all unused disks on
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman the system are eligible. With '-a' specified, $DISKS is ignored.
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman - A non-root user with the full set of basic privileges and the ability
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman to sudo(1M) to root without a password to run the test.
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman - Specify any pools you wish to preserve as a space delimited list in
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman the $KEEP variable. The root pool is added automatically.
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanOnce the pre-requisites are satisfied, simply run the zfstest script:
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman test_machine$ /opt/zfs-tests/bin/zfstest [-aq]
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanWhen the '-q' option is specified, it is passed to run(1) which causes output
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanto be written to the console only for tests that do not pass and the results
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanThe ZFS Test Suite allows the user to specify a subset of the tests via a
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanrunfile. The format of the runfile is explained in run(1), and the files that
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanzfstest uses are available for reference under /opt/zfs-tests/runfiles. To
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanspecify a custom runfile, use the -c option:
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman test_machine$ /opt/zfs-tests/bin/zfstest [-aq] -c my_tests.run
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaraman3. Test results
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund SivaramanWhile the ZFS Test Suite is running, one informational line is printed at the
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanend of each test, and a results summary is printed at the end of the run. The
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanresults summary includes the location of the complete logs, which is of the
b947e1a521c6931f787d6d1b3604d5b138170c3dMukund Sivaramanform /var/tmp/test_results/<ISO 8601 date>.