Difference between revisions of "Writing Torture Tests"

From SambaWiki
Jump to: navigation, search
(Latest Windows)
(Use Test Suites)
Line 43: Line 43:
  
 
All new tests should be added under a sub-level test suite.  For instance when adding a new locking test to the ''raw'' directory it should be added in the lock.c file with an entry in the '''torture_raw_lock()''' initialization function.  This allows users of smbtorture to run individual tests such as '''RAW-LOCK-ASYNC'''.  New tests <font color="red">should not</font> be added to the upper level suites such as '''RAW''' or '''BASE'''.
 
All new tests should be added under a sub-level test suite.  For instance when adding a new locking test to the ''raw'' directory it should be added in the lock.c file with an entry in the '''torture_raw_lock()''' initialization function.  This allows users of smbtorture to run individual tests such as '''RAW-LOCK-ASYNC'''.  New tests <font color="red">should not</font> be added to the upper level suites such as '''RAW''' or '''BASE'''.
 +
 +
==Specifying Target Behavior==
 +
 +
Not all servers support every aspect of all Windows protocols.  It's important for the test suite to be flexible enough to still offer the maximum amount of test coverage while still allowing for variation in behavior of the target server.  For cases where a target server does not support a documented feature a configuration parameter can be specified which changes the error checking of a test based off that feature support. 
 +
 +
For example not all servers support System Access Control Lists.  The parametric option ''torture:sacl_support'' has been defined in the ''source4/torture/smbtorture.h'' file.  Because parametric configuration is used by comparing string names, the definition of this parameter is only a comment.
 +
 +
<pre>
 +
/* torture:sacl_support
 +
*
 +
* This parameter specifies whether the server supports the setting and
 +
* retrieval of System Access Control Lists.  This includes whether the server
 +
* supports the use of the SEC_FLAG_SYSTEM_SECURITY bit in the open access
 +
* mask.*/
 +
</pre>
 +
 +
Target servers which do not support this parameter then define this parameter to false in ''source4/torture/smbtorture.c'':
 +
 +
<pre>
 +
        } else if (strcmp(target, "onefs") == 0) {
 +
                lp_set_cmdline(cmdline_lp_ctx, "torture:sacl_support", "false");
 +
        }
 +
</pre>
 +
 +
Then in tests where the outcome is different based on the servers support for this feature the parameter is checked.  Such as in ''source4/torture/basic/denytest.c'':
 +
 +
<pre>
 +
        /* Skip all SACL related tests. */
 +
        if ((!torture_setting_bool(tctx, "sacl_support", true)) &&
 +
            ((cxd->cxd_access1 & SEC_FLAG_SYSTEM_SECURITY) ||
 +
            (cxd->cxd_access2 & SEC_FLAG_SYSTEM_SECURITY)))
 +
                goto done;
 +
</pre>
  
 
=Test Verification=
 
=Test Verification=

Revision as of 00:35, 4 December 2009

The smbtorture framework provided in Samba is an extremely powerful tool for exercising obscure parts of Windows protocols and determining how different server implementations, Windows among them, respond. Writing torture tests is an invaluable way to determine a server's behavior in odd scenarios. Before the release of the Microsoft protocol documentation smbtorture was the only way to determine how a Windows server would behave to packets that were legal but would not be sent by the existing Windows client.

This page attempts to layout some guidelines for development of new torture tests. Primarily this page focuses on adding tests to the source4/torture collection.

Source Layout

The source4/torture directory contains the following sub-directories:

  • basic - this directory primarily contains the original SMB tests that were ported from the source/torture test directory. These tests use the smbcli_*() wrapper functions which provide an abstracted API to the SMB protocol behavior. These tests primarily deal with older aspects of the SMBv1 protocol and should be considered legacy. If possible, new tests should not be added to this directory.
  • raw - this directory contains SMBv1 tests that exercise most aspects of the file sharing protocol by tweaking the raw bits sent in every packet. Most new SMBv1 correctness tests are added to this directory.
  • smb2 - this directory contains correctness tests for the SMBv2 file sharing protocol. Like the raw directory these tests specify each individual bits in each packet. New SMBv2 tests should be added to this directory.

Best Practices

When adding new tests to smbtorture, it's easiest to copy-n-paste an existing test and modify it to behave differently. However, there are several best practices that should be followed for all newly written tests, even if they go against the existing code structure of that file.

Printing Comments

The printf() function should not be used. Instead the torture_comment() function can be used for printing messages in a torture test. Different front ends to torture, including the Samba build farm, may want to format or ignore text coming from the torture tests. Using the torture_comment function allows for this.

Similarly torture_warning() can be used to display warning messages.

Checking Failure

Older tests simply returned false to indicate that a test failed. Torture now keeps a torture_result state for each test which should be set to one of

enum torture_result {
        TORTURE_OK=0,
        TORTURE_FAIL=1,
        TORTURE_ERROR=2,
        TORTURE_SKIP=3
};

The easiest way to set this state is by using the torture_assert_*() macros provided in lib/torture/torture.h.

These assert macros will set the torture_result state and return from the function. Often a test wants to do some cleanup on failure, such as delete test files. In these cases there are special torture_assert_*_goto() macros which will jump to a label instead of returning from a function. Some tests also have their own CHECK_*()' macros which wrap the torture_result() function. Either of these methods is acceptable.

Use Test Suites

All new tests should be added under a sub-level test suite. For instance when adding a new locking test to the raw directory it should be added in the lock.c file with an entry in the torture_raw_lock() initialization function. This allows users of smbtorture to run individual tests such as RAW-LOCK-ASYNC. New tests should not be added to the upper level suites such as RAW or BASE.

Specifying Target Behavior

Not all servers support every aspect of all Windows protocols. It's important for the test suite to be flexible enough to still offer the maximum amount of test coverage while still allowing for variation in behavior of the target server. For cases where a target server does not support a documented feature a configuration parameter can be specified which changes the error checking of a test based off that feature support.

For example not all servers support System Access Control Lists. The parametric option torture:sacl_support has been defined in the source4/torture/smbtorture.h file. Because parametric configuration is used by comparing string names, the definition of this parameter is only a comment.

/* torture:sacl_support
 *
 * This parameter specifies whether the server supports the setting and
 * retrieval of System Access Control Lists.  This includes whether the server
 * supports the use of the SEC_FLAG_SYSTEM_SECURITY bit in the open access
 * mask.*/

Target servers which do not support this parameter then define this parameter to false in source4/torture/smbtorture.c:

        } else if (strcmp(target, "onefs") == 0) {
                lp_set_cmdline(cmdline_lp_ctx, "torture:sacl_support", "false");
        }

Then in tests where the outcome is different based on the servers support for this feature the parameter is checked. Such as in source4/torture/basic/denytest.c:

        /* Skip all SACL related tests. */
        if ((!torture_setting_bool(tctx, "sacl_support", true)) &&
            ((cxd->cxd_access1 & SEC_FLAG_SYSTEM_SECURITY) ||
             (cxd->cxd_access2 & SEC_FLAG_SYSTEM_SECURITY)))
                goto done;

Test Verification

Latest Windows

All new tests should first be run against the latest two versions of a Windows server. At the time of this writing that is Windows 2008 Server R2 / Windows 7 and Windows 2008 Server / Windows Vista. Tests should pass against both of these servers before being committed.

The behavior of the Windows server should at first be considered the correct implementation. Windows servers do have bugs and often do the wrong thing, thus some parameterization may be necessary to check for correctness based off whether the server is Windows or another target. This is covered in Specifying Target Behavior.