730c7accb8e17deeb733220379a3cf83d1b6e3c1
[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
19  (3) System call requirements.
20
21         _require_statx
22
23
24 ====================
25 GENERAL REQUIREMENTS
26 ====================
27
28 _require_command "$NAME_PROG" name
29
30      The test requires an external command, called 'name' be present on the
31      system and that '$VAR' should be set with the path to that command.  $VAR
32      should then be used to refer to the command when executing it.  For
33      example:
34
35         _require_command "KILLALL_PROG" killall
36
37      to locate the killall command and then:
38
39         $KILLALL_PROG -q $FSSTRESS_PROG
40
41      to make use of it.
42
43
44 _require_test
45
46      The test requires that the block device specified by $TEST_DEV be mounted
47      on $TEST_DIR.
48
49
50 _require_test_program <name>
51
52      The test requires a program by the name of 'name' be present and built in
53      the src/ directory.  For example:
54
55         _require_test_program "stat_test"
56
57      requires that src/stat_test be built.
58
59
60 _require_xfs_io_command <name> [<switch>]
61
62      The test requires that the xfs_io command be available, that it supports
63      command <name> and, optionally, that that command supports the specified
64      switch.  For example:
65
66         _require_xfs_io_command "falloc"
67         _require_xfs_io_command "chattr" "+/-x"
68
69      The first requires that xfs_io support the falloc command and the second
70      that it supports the chattr command and that the chattr command supports
71      the +x and -x arguments (DAX attribute).
72
73
74 ==================================
75 FILESYSTEM CAPABILITY REQUIREMENTS
76 ==================================
77
78 _require_chattr <letters>
79
80      The test requires that the filesystem attribute set by the chattr command
81      with +<letters> as an argument be available and supported by the $TEST_DEV
82      filesystem.  No check is made of the scratch filesystem.  For example:
83
84         _require_chattr ai
85
86      tests to see if setting the append-only and immutable attributes on a file
87      (chattr +a +i) is supported.
88
89
90 ========================
91 SYSTEM CALL REQUIREMENTS
92 ========================
93
94 _require_statx
95
96      The test requires the use of the statx() system call and will be skipped
97      if it isn't available in the kernel.