Testing Lustre Code

We recommend a "test early, test often" approach to testing.

• If you are developing a new feature for Lustre, designing tests to exercise the new feature early in the development process will allow you to test your code as you develop it.

• If you are fixing a bug in Lustre, creating a regression test up front will ensure that you can reproduce the reported problem and then verify that it has been fixed. And it will save you the effort of testing the fix manually and then creating a separate regression test later to submit with your bug fix.

We provide several tools to help with testing Lustre code:

• Acceptance test suite. This Lustre testing framework from which a suite of acceptance tests called acceptance-small can be run is described in the next section Using the Lustre Testing Framework.
• (Optional) POSIX compliance test suite. Instructions for using the POSIX Compliance Test Suite for testing the Lustre file system is described in POSIX Testing.

Using the Lustre Testing Framework

Before you submit code, it must pass the acceptance-small Lustre acceptance test suite. We recommend you run the test suite often so that you can find out as soon as possible if your code changes result in a regression.

The acceptance-small test suite is run using the script acceptance-small.sh, which is located in the lustre/tests directory of a compiled Lustre tree. For more details, see Acceptance Small (acc-sm) Testing on Lustre

Note: When Submitting Patches, set the "acc-sm passed" flag on the attachment for each individual branch that was tested in Bugzilla to indicate that it passed.

Creating a Test Case

The first step in fixing a bug is to create or find a test case that causes the bug to be reproduced, then fix the bug, and finally verify that the code containing the bug passes the test.

Often if a defect is found in Lustre, it is because a test script in the Lustre acceptance test suite is not testing the failing code. Before starting work on a bug, first check if a test script reproduces the bug. If not, you will need to create a new test and add it to the test suite as a scripted sub-test of one of these tests:

sanity.sh	tests that verify operation under normal operating conditions
sanityN.sh	tests that verify operations from two clients under normal operating conditions
liblustre/tests/sanity	runs a test linked to a liblustre client library
recovery-small.sh	tests that verify RPC replay after communications failure (message loss)
replay-single.sh	tests that verify recovery after MDS failure
replay-dual.sh	tests that verify recovery from two clients after server failure
replay-ost-single.sh	tests that verify recovery after OST failure
lfscktest.sh	tests e2fsck and lfsck to detect and fix filesystem corruption
insanity.sh	tests multiple concurrent failure conditions

Bypassing Failures

If one or more tests in acceptance-small are regularly failing due to an issue not related to the bug you are fixing, you may want to bypass these tests so that you can test your bug fix. Complete these steps:

1. Check to see if a bug has been logged for the failure and file a new bug if one has not yet been opened.

2. Set environment variables to skip these specific tests until you or someone else fixes them. For example, to skip sanity.sh subtest 36g and 65, replay-single.sh subtest 42, and all of insanity.sh, set in your environment:

 
export SANITY_EXCEPT="36g 65"
export REPLAY_SINGLE_EXCEPT=42
export INSANITY=no

You can also skip these tests using a command. For example, when running acceptance-small, enter:

 
SANITY_EXCEPT="36g 65" REPLAY_SINGLE_EXCEPT=42 INSANITY=no ./acceptance-small.sh

The test framework is very flexible and provides an easy "hands-off" way of running tests while you are doing other things like coding. By running the entire test suite regularly, you will soon know whether your code has introduced a new bug or revived an old one.

Note: Questions or problems with the test framework should be emailed to the lustre-discuss mailing list so that all Lustre users can benefit from the solution.

Test Framework Options

The examples below show how to run a full test or sub-tests from the acceptance-small suite.

• Run all tests including "standard" tests (sanity*, liblustre) with lov.sh setup; recovery*.sh; and replay*.sh.

$ cd lustre/tests
$ sh acceptance-small.sh

• Run only the recovery-small.sh, replay-single.sh, and conf-sanity.sh tests.

$ ACC_SM_ONLY="recovery-small replay-single conf-sanity" sh acceptance-small.sh

• Run acceptance-small with a different configuration (expects myth.sh to generate myth.xml).

$ CONFIGS="myth" sh acceptance-small.sh
</nowiki>

• Run only tests 1, 3, 4, 6, 9 in sanity.sh with the lov.sh configuration.

$ ONLY="1 3 4 6 9" NAME=lov sh sanity.sh

• Skip tests 1 ... 30 and run remaining tests in sanity.sh.

$ EXCEPT="`seq 1 30`" sh sanity.sh

• Clean up after a lov.sh test failure (normally the system is left mounted for debugging after a failure).

 
$ NAME=lov sh llmountcleanup.sh
</nowiki>

• Clean up replay-single.sh after a test failure (normally the system is left mounted for debugging after a failure).

 
$ ONLY=cleanup sh replay-single.sh

Adding New Tests

• Adding a test to one of the above scripts is easy, and failures can be injected directly into the Lustre kernel code via OBD_FAIL_CHECK(), OBD_FAIL_RACE(), OBD_FAIL_TIMEOUT(), and sysctl -w lustre.fail_loc

Note: You can use the OBD_FAIL_CHECK() or OBD_FAIL_TIMEOUT() hooks in Lustre to monitor failures.