fstests: check for filesystem FS_IOC_FSSETXATTR support
[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) Filesystem capability requirements.
16
17         _require_chattr <letters>
18         _require_exportfs
19
20  (3) System call requirements.
21
22         _require_statx
23
24  (4) Device mapper requirement.
25
26         _require_dm_target
27         _require_log_writes
28
29 ====================
30 GENERAL REQUIREMENTS
31 ====================
32
33 _require_command "$NAME_PROG" name
34
35      The test requires an external command, called 'name' be present on the
36      system and that '$VAR' should be set with the path to that command.  $VAR
37      should then be used to refer to the command when executing it.  For
38      example:
39
40         _require_command "KILLALL_PROG" killall
41
42      to locate the killall command and then:
43
44         $KILLALL_PROG -q $FSSTRESS_PROG
45
46      to make use of it.
47
48
49 _require_test
50
51      The test requires that the block device specified by $TEST_DEV be mounted
52      on $TEST_DIR.
53
54
55 _require_test_program <name>
56
57      The test requires a program by the name of 'name' be present and built in
58      the src/ directory.  For example:
59
60         _require_test_program "stat_test"
61
62      requires that src/stat_test be built.
63
64
65 _require_xfs_io_command <name> [<switch>]
66
67      The test requires that the xfs_io command be available, that it supports
68      command <name> and, optionally, that that command supports the specified
69      switch.  For example:
70
71         _require_xfs_io_command "falloc"
72         _require_xfs_io_command "chattr" "x"
73
74      The first requires that xfs_io support the falloc command and the second
75      that it supports the chattr command and that the chattr command supports
76      the +x and -x arguments (DAX attribute).
77
78
79 ==================================
80 FILESYSTEM CAPABILITY REQUIREMENTS
81 ==================================
82
83 _require_chattr <letters>
84
85      The test requires that the filesystem attribute set by the chattr command
86      with +<letters> as an argument be available and supported by the $TEST_DEV
87      filesystem.  No check is made of the scratch filesystem.  For example:
88
89         _require_chattr ai
90
91      tests to see if setting the append-only and immutable attributes on a file
92      (chattr +a +i) is supported.
93
94 _require_exportfs
95
96      The test requires that the $TEST_DEV filesystem supports NFS export.
97      The test also requires the use of the open_by_handle_at() system call and
98      will be skipped if it isn't available in the kernel.
99
100
101 ========================
102 SYSTEM CALL REQUIREMENTS
103 ========================
104
105 _require_statx
106
107      The test requires the use of the statx() system call and will be skipped
108      if it isn't available in the kernel.
109
110
111 ==========================
112 DEVICE MAPPER REQUIREMENTS
113 ==========================
114
115 _require_dm_target <name>
116
117      The test requires the use of the device mapper target and will be skipped
118      if it isn't available in the kernel.
119
120 _require_log_writes
121
122      The test requires the use of the device mapper target log-writes.
123      The test also requires the test program log-writes/replay-log is built
124      and will be skipped if either isn't available.
125
126 ======================
127 PERF TEST REQUIREMENTS
128 ======================
129
130 _require_fio_results
131
132      This test requires the supporting tools for saving and comparing fio based
133      perf test results.