From 328de85a28ec94300298dd461ef650a87f92a30d Mon Sep 17 00:00:00 2001 From: Peter Ashford Date: Mon, 28 May 2018 00:26:51 -0700 Subject: [PATCH] Initial content for page added --- Workflow-Test.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++ Workflow/Test.md | 0 2 files changed, 59 insertions(+) create mode 100644 Workflow-Test.md delete mode 100644 Workflow/Test.md diff --git a/Workflow-Test.md b/Workflow-Test.md new file mode 100644 index 0000000..4e46dc7 --- /dev/null +++ b/Workflow-Test.md @@ -0,0 +1,59 @@ +# 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][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][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][W-zloop] 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][W-create-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. + +[zts-readme]: https://github.com/zfsonlinux/zfs/tree/master/tests +[W-zloop]: https://github.com/zfsonlinux/zfs/wiki/Workflow-Zloop-Debugging +[W-create-test]: https://github.com/zfsonlinux/zfs/wiki/Workflow-Create-Test \ No newline at end of file diff --git a/Workflow/Test.md b/Workflow/Test.md deleted file mode 100644 index e69de29..0000000