Workflow Test

Testing Changes to ZFS

The code in the ZFS on Linux project is quite complex. A minor error in a change could easily introduce new bugs into the software, causing unforeseeable problems. In an attempt to avoid this, the ZTS (ZFS Test Suite) was developed. This test suite is run against multiple architectures and distributions by the Github system when a PR (Pull Request) is submitted.

A subset of the full test suite can be run by the developer to perform a preliminary verification of the changes in their local repository.

Style Testing

The first part of the testing is to verify that the software meets the project's style guidelines. To verify that the code meets those guidelines, run make checkstyle from the local repository.

Basic Functionality Testing

The second part of the testing is to verify basic functionality. This is to ensure that the changes made don't break previous functionality.

There are a few helper scripts provided in the top-level scripts directory designed to aid developers working with in-tree builds.

• zfs-helper.sh: Certain functionality (i.e. /dev/zvol/) depends on the ZFS provided udev helper scripts being installed on the system. This script can be used to create symlinks on the system from the installation location to the in-tree helper. These links must be in place to successfully run the ZFS Test Suite. The -i and -r options can be used to install and remove the symlinks.

$ sudo ./scripts/zfs-helpers.sh -i

• zfs.sh: The freshly built kernel modules from the local repository can be loaded using zfs.sh. This script will load those modules, even if there are ZFS modules loaded from another location, which could cause long-term problems if any of the non-testing file-systems on the system use ZFS.

This script can latter be used to unload the kernel modules with the -u option.

$ sudo ./scripts/zfs.sh

• zfs-tests.sh: A wrapper which can be used to launch the ZFS Test Suite. Three loopback devices are created on top of sparse files located in /var/tmp/ and used for the regression test. Detailed directions for the running the ZTS can be found in the ZTS Readme file.

WARNING: This script should only be run on a development system. It makes configuration changes to the system to run the tests, and it tries to remove those changes after completion, but the change removal could fail, and dynamic canges of this nature are usually undesirable on a production system. For more information on the changes made, please see the ZTS Readme file.

$ sudo ./scripts/zfs-tests.sh -vx

tip: The delegate tests will be skipped unless group read permission is set on the zfs directory and its parents.

• zloop.sh: A wrapper to run ztest repeatedly with randomized arguments. The ztest command is a user space stress test designed to detect correctness issues by concurrently running a random set of test cases. If a crash is encountered, the ztest logs, any associated vdev files, and core file (if one exists) are collected and moved to the output directory for analysis.

If there are any failures in this test, please see the zloop debugging page.

$ sudo ./scripts/zloop.sh

Change Testing

Finally, it's necessary to verify that the changes made actually do what they were intended to do. The extent of the testing would depend on the complexity of the changes.

After the changes are tested, if the testing can be automated for addition to ZTS, a new test should be created. This test should be part of the PR that resolves the issue or adds the feature. If the festure is split into multiple PRs, some testing should be included in the first, with additions to the test as required.

It should be noted that if the change adds too many lines of code that don't get tested by ZTS, the change will not pass testing.