f3fc9f49eba2a61bbac9a158406eec3437713c94
[xfstests-dev.git] / doc / requirement-checking.txt
1                    ========================================
2                    TESTING FOR REQUIREMENTS IN TEST SCRIPTS
3                    ========================================
4
5 Test scripts need to indicate to the infrastructure what sorts of requirements
6 they have.  This is done with _require_<xxx> macros, which may take parameters.
7
8  (1) General requirements.
9
10         _require_command "$<NAME_PROG>" <name>
11         _require_test
12         _require_test_program <name>
13         _require_xfs_io_command <name> [<switch>]
14
15  (2) System call requirements.
16
17         _require_statx
18
19
20 ====================
21 GENERAL REQUIREMENTS
22 ====================
23
24 _require_command "$NAME_PROG" name
25
26      The test requires an external command, called 'name' be present on the
27      system and that '$VAR' should be set with the path to that command.  $VAR
28      should then be used to refer to the command when executing it.  For
29      example:
30
31         _require_command "KILLALL_PROG" killall
32
33      to locate the killall command and then:
34
35         $KILLALL_PROG -q $FSSTRESS_PROG
36
37      to make use of it.
38
39
40 _require_test
41
42      The test requires that the block device specified by $TEST_DEV be mounted
43      on $TEST_DIR.
44
45
46 _require_test_program <name>
47
48      The test requires a program by the name of 'name' be present and built in
49      the src/ directory.  For example:
50
51         _require_test_program "stat_test"
52
53      requires that src/stat_test be built.
54
55
56 _require_xfs_io_command <name> [<switch>]
57
58      The test requires that the xfs_io command be available, that it supports
59      command <name> and, optionally, that that command supports the specified
60      switch.  For example:
61
62         _require_xfs_io_command "falloc"
63         _require_xfs_io_command "chattr" "+/-x"
64
65      The first requires that xfs_io support the falloc command and the second
66      that it supports the chattr command and that the chattr command supports
67      the +x and -x arguments (DAX attribute).
68
69
70 ========================
71 SYSTEM CALL REQUIREMENTS
72 ========================
73
74 _require_statx
75
76      The test requires the use of the statx() system call and will be skipped
77      if it isn't available in the kernel.