BUILDING THE FSQA SUITE
_______________________
-Building Linux:
- - cd into the xfstests directory
- - run make
- - run make install
-
-Building IRIX:
- - cd into the xfstests directory
- - set the ROOT and TOOLROOT env variables for IRIX appropriately
- - run ./make_irix
+- cd into the xfstests directory
+- install prerequisite packages
+ For example, for Ubuntu:
+ sudo apt-get install xfslibs-dev uuid-dev libtool-bin \
+ e2fsprogs automake gcc libuuid1 quota attr libattr1-dev make \
+ libacl1-dev libaio-dev xfsprogs libgdbm-dev gawk fio dbench \
+ uuid-runtime python sqlite3 liburing-dev
+ For Fedora, RHEL, or CentOS:
+ yum install acl attr automake bc dbench dump e2fsprogs fio \
+ gawk gcc indent libtool lvm2 make psmisc quota sed \
+ xfsdump xfsprogs \
+ libacl-devel libattr-devel libaio-devel libuuid-devel \
+ xfsprogs-devel btrfs-progs-devel python sqlite liburing-devel
+ (Older distributions may require xfsprogs-qa-devel as well.)
+ (Note that for RHEL and CentOS, you may need the EPEL repo.)
+- run make
+- run make install
+- create fsgqa test user ("sudo useradd -m fsgqa")
+- create fsgqa group ("sudo groupadd fsgqa")
+- create 123456-fsgqa test user ("sudo useradd 123456-fsgqa")
+ this 2nd user creation step can be safely skipped if your system
+ doesn't support names starting with digits, only a handful of tests
+ require it.
+- create fsgqa2 test user ("sudo useradd fsgqa2")
______________________
USING THE FSQA SUITE
______________________
-Preparing system for tests (IRIX and Linux):
+Preparing system for tests:
- compile XFS into your kernel or load XFS modules
- - install user tools including mkfs.xfs, xfs_db & xfs_bmap
- - If you wish to run the udf components of the suite install
- mkfs_udf and udf_db for IRIX and mkudffs for Linux. Also download and
- build the Philips UDF Verification Software from
- http://www.extra.research.philips.com/udf/, then copy the udf_test
+ - install administrative tools specific to the filesystem you wish to test
+ - If you wish to run the udf components of the suite install
+ mkudffs. Also download and build the Philips UDF Verification Software
+ from https://www.lscdweb.com/registered/udf_verifier.html, then copy the udf_test
binary to xfstests/src/. If you wish to disable UDF verification test
set the environment variable DISABLE_UDF_TEST to 1.
-
-
+
- create one or two partitions to use for testing
- one TEST partition
- - format as XFS, mount & optionally populate with
+ - format as XFS, mount & optionally populate with
NON-IMPORTANT stuff
- one SCRATCH partition (optional)
- leave empty and expect this partition to be clobbered
SCRATCH_DEV should be unused by the tester, and for the legacy
support SCRATCH_DEV will be set to the first disk of the
SCRATCH_DEV_POOL by xfstests script.
-
+
- setup your environment
+ Quick start:
+ - copy local.config.example to local.config and edit as needed
+ Or:
- setenv TEST_DEV "device containing TEST PARTITION"
- - setenv TEST_DIR "mount point of TEST PARTITION"
- - optionally:
+ - setenv TEST_DIR "mount point of TEST PARTITION"
+ - optionally:
- setenv SCRATCH_DEV "device containing SCRATCH PARTITION" OR
(btrfs only) setenv SCRATCH_DEV_POOL "to 3 or more SCRATCH disks for
testing btrfs raid concepts"
environment variable set to "yes" will enable their use.
- setenv DIFF_LENGTH "number of diff lines to print from a failed test",
by default 10, set to 0 to print the full diff
+ - setenv FSTYP "the filesystem you want to test", the filesystem
+ type is devised from the TEST_DEV device, but you may want to
+ override it; if unset, the default is 'xfs'
+ - setenv FSSTRESS_AVOID and/or FSX_AVOID, which contain options
+ added to the end of fsstresss and fsx invocations, respectively,
+ in case you wish to exclude certain operational modes from these
+ tests.
+ - set TEST_XFS_REPAIR_REBUILD=1 to have _check_xfs_filesystem
+ run xfs_repair -n to check the filesystem; xfs_repair to rebuild
+ metadata indexes; and xfs_repair -n (a third time) to check the
+ results of the rebuilding.
+ - xfs_scrub, if present, will always check the test and scratch
+ filesystems if they are still online at the end of the test.
+ It is no longer necessary to set TEST_XFS_SCRUB.
+ - setenv LOGWRITES_DEV to a block device to use for power fail
+ testing.
+ - setenv PERF_CONFIGNAME to a arbitrary string to be used for
+ identifying the test setup for running perf tests. This should
+ be different for each type of performance test you wish to run so
+ that relevant results are compared. For example 'spinningrust'
+ for configurations that use spinning disks and 'nvme' for tests
+ using nvme drives.
+ - set USE_KMEMLEAK=yes to scan for memory leaks in the kernel
+ after every test, if the kernel supports kmemleak.
+ - set KEEP_DMESG=yes to keep dmesg log after test
+ - Set TEST_FS_MODULE_RELOAD=1 to unload the module and reload
+ it between test invocations. This assumes that the name of
+ the module is the same as FSTYP.
+
- or add a case to the switch in common/config assigning
these variables based on the hostname of your test
machine
- if testing xfsdump, make sure the tape devices have a
tape which can be overwritten.
-
+
- make sure $TEST_DEV is a mounted XFS partition
- make sure that $SCRATCH_DEV or $SCRATCH_DEV_POOL contains nothing useful
-
+
Running tests:
- cd xfstests
- - By default the tests suite will run xfs tests:
+ - By default the tests suite will run all the tests in the auto group. These
+ are the tests that are expected to function correctly as regression tests,
+ and it excludes tests that exercise conditions known to cause machine
+ failures (i.e. the "dangerous" tests).
- ./check '*/001' '*/002' '*/003'
- ./check '*/06?'
- - You can explicitly specify NFS, otherwise the filesystem type will be
- autodetected from $TEST_DEV:
- ./check -nfs [test(s)]
- Groups of tests maybe ran by: ./check -g [group(s)]
See the 'group' file for details on groups
- - for udf tests: ./check -udf [test(s)]
- Running all the udf tests: ./check -udf -g udf
- - for running nfs tests: ./check -nfs [test(s)]
+ - If you want to run all tests regardless of what group they are in
+ (including dangerous tests), use the "all" group: ./check -g all
- To randomize test order: ./check -r [test(s)]
+ - You can explicitly specify NFS/CIFS/OVERLAY, otherwise
+ the filesystem type will be autodetected from $TEST_DEV:
+ - for running nfs tests: ./check -nfs [test(s)]
+ - for running cifs/smb3 tests: ./check -cifs [test(s)]
+ - for overlay tests: ./check -overlay [test(s)]
+ The TEST and SCRATCH partitions should be pre-formatted
+ with another base fs, where the overlay dirs will be created
+
-
The check script tests the return value of each script, and
compares the output against the expected output. If the output
is not as expected, a diff will be output and an .out.bad file
will be produced for the failing test.
-
+
Unexpected console messages, crashes and hangs may be considered
to be failures but are not necessarily detected by the QA system.
-__________________________
+__________________________
ADDING TO THE FSQA SUITE
__________________________
$TEST_DEV.
(b) mkfs a new XFS filesystem on $SCRATCH_DEV, and mount this
- on $SCRATCH_MNT. Call the the _require_scratch function
+ on $SCRATCH_MNT. Call the the _require_scratch function
on startup if you require use of the scratch partition.
- _require_scratch does some checks on $SCRATCH_DEV &
- $SCRATCH_MNT and makes sure they're unmounted. You should
- cleanup when your test is done, and in particular unmount
+ _require_scratch does some checks on $SCRATCH_DEV &
+ $SCRATCH_MNT and makes sure they're unmounted. You should
+ cleanup when your test is done, and in particular unmount
$SCRATCH_MNT.
Tests can make use of $SCRATCH_LOGDEV and $SCRATCH_RTDEV
for testing external log and realtime volumes - however,
3. By default, tests are run as the same uid as the person
executing the control script "check" that runs the test scripts.
- If you need to be root, add a call to the shell procedure
- _need_to_be_root ... this will do nothing or exit with an
- error message depending on your current uid.
-
4. Some other useful shell procedures:
_get_fqdn - echo the host's fully qualified
- When calling getfacl in a test, pass the "-n" argument so
that numeric rather than symbolic identifiers are used in
the output.
+ - When creating a new test, it is possible to enter a custom name
+ for the file. Filenames are in form NNN-custom-name, where NNN
+ is automatically added by the ./new script as an unique ID,
+ and "custom-name" is the optional string entered into a prompt
+ in the ./new script. It can contain only alphanumeric characters
+ and dash. Note the "NNN-" part is added automatically.
Verified output:
- Each test script has a numerical name, e.g. 007, and an associated
+ Each test script has a name, e.g. 007, and an associated
verified output, e.g. 007.out.
It is important that the verified output is deterministic, and
- variable directory contents
- imprecise numbers, especially sizes and times
- Use the "remake" script to recreate the verified output for one
- or more tests.
-
Pass/failure:
The script "check" may be used to run one or more tests.
The recent pass/fail history is maintained in the file "check.log".
The elapsed time for the most recent pass for each test is kept
in "check.time".
+
+ The compare-failures script in tools/ may be used to compare failures
+ across multiple runs, given files containing stdout from those runs.
+
+__________________
+SUBMITTING PATCHES
+__________________
+
+Send patches to the fstests mailing list at fstests@vger.kernel.org.
projects / xfstests-dev.git / blobdiff