Documentation/what-is-xfstests.md

# What is xfstests?

As the name might imply, xfstests is a file system regression test
suite which was originally developed by Silicon Graphics (SGI) for the
XFS file system.  Originally, xfstests, like XFS was only supported on
the SGI's Irix operating system.  When XFS was ported to Linux, so was
xfstests, and now xfstests is only supported on Linux.

Today, xfstests is used as a file system regression test suite for all
of Linux's major file systems: xfs, ext2, ext4, cifs, btrfs, f2fs,
reiserfs, gfs, jfs, udf, nfs, and tmpfs.  Many file system maintainers
will run a full set of xfstests before sending patches to Linus, and
will require that any major changes be tested using xfstests before
they are submitted for integration.

## Individual tests in xfstests

Tests in xfstests were originally named using a three digit number.
In 2013 the tests were moved into different classes, depending on
whether the test was file system specific, "generic" (meaning it was
was file system independent), or "shared" (meaning that test was not
truly generic, but which was useful on a handful of file systems).  In
this scheme, tests would have names such as:

* btrfs/126
* generic/013
* ext4/271
* shared/051
* xfs/090

Tests can be belong to multiple groups, such as "auto", "quick",
"aio", "prealloc", "ioctl", and "dangerous".  Membership in a group
can indicate something about the nature of the test.  The "auto" group
indicates those tests best suited for automatic test spinners.  Tests
in the "quick" group should completely quickly, and running the quick
group is good for a smoke test for the file system.  The "dangerous"
group are tests that can crash the kernel, and so they should be run
with care.

Other times, the group membership can indicate file system
functionality which is exercised by the test.  Examples of this would
include groups such as "aio", "prealloc", and "ioctl".

## Test devices

The xfstests test suite uses one or two block devices; one is named
TEST and must be present, and the other is named SCRATCH, and is
optional.  Most tests use either the TEST or the SCRATCH device,
although there are a few tests that use both devices.

The SCRATCH device is reformatted by tests which need to use the
SCRATCH device.  Individual tests may not assume that there is a valid
file system on the SCRATCH device.  In contrast, the TEST device is
never formatted by xfstests, and is intended to be a long lived,
"aged" file system.

For most ext4 file systems configurations, the TEST and SCRATCH device
should be 5GB.  Smaller, and some tests may not run correctly.
Larger, and the tests will take a long time to run --- especially
those tests that need to fill the file system to test ENOSPC handling.
There are a few file system configurations for ext4 (most notable,
bigalloc_4k) which require a 20GB test and scratch device.

For this reason, kvm-xfstests uses five file system devices, /dev/vdb,
/dev/vdc, /dev/vdd, /dev/vde, and /dev/vdf.  (/dev/vda is used for the
root file system, and /dev/vdg is used for the /results file system.)
The first two test devices, /dev/vdb and /dev/vdc, are used for TEST
and SCRATCH, respectively, for the standard, default 4k file system
configuration.  The /dev/vdd device is used for file system
configurations which are not compatible with the default 4k block ext4
file system --- for example, a 1k block file system.  Since we want to
keep the /dev/vdb as a long-term file system test file system aging,
we use /dev/vdd instead for the 1k block file system, and the test
runner will run mke2fs to format /dev/vdd before starting the xfstests
run for that file system configuration.  For this reason, /dev/vdd is
sometimes called the TEST-1K device -- although there are many other
file system configurations which will use /dev/vdd.

The /dev/vde and /dev/vdf file systems are the BIGTEST and BIGSCRATCH
disks, and are used for those file system configurations which require
a 20GB TEST and SCRATCH device.  Like the TEST-1K device, the BIGTEST
device will be reformatted using mke2fs at the beginning of an xfstests
run for that file system configuration.

The gce-xfstests uses the same set of block devices, although instead
of individual virtio devices, gce-xfstests uses Logical Volumes using
LVM stored on a GCE Local SSD.  Unfortunately, this means that the
TEST-4K device is reformatted each time the gce-xfstests VM is
started; and so we don't get the benefits of testing the file system
against a device suffering from long-term aging.