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         _require_sgid_inheritance
  20         _require_use_local_uidgid
  21         _require_unix_perm_checking
  22
  23  (3) System call requirements.
  24
  25         _require_statx
  26
  27  (4) Device mapper requirement.
  28
  29         _require_dm_target
  30         _require_log_writes
  31
  32 ====================
  33 GENERAL REQUIREMENTS
  34 ====================
  35
  36 _require_command "$NAME_PROG" name
  37
  38      The test requires an external command, called 'name' be present on the
  39      system and that '$VAR' should be set with the path to that command.  $VAR
  40      should then be used to refer to the command when executing it.  For
  41      example:
  42
  43         _require_command "KILLALL_PROG" killall
  44
  45      to locate the killall command and then:
  46
  47         $KILLALL_PROG -q $FSSTRESS_PROG
  48
  49      to make use of it.
  50
  51
  52 _require_test
  53
  54      The test requires that the block device specified by $TEST_DEV be mounted
  55      on $TEST_DIR.
  56
  57
  58 _require_test_program <name>
  59
  60      The test requires a program by the name of 'name' be present and built in
  61      the src/ directory.  For example:
  62
  63         _require_test_program "stat_test"
  64
  65      requires that src/stat_test be built.
  66
  67
  68 _require_xfs_io_command <name> [<switch>]
  69
  70      The test requires that the xfs_io command be available, that it supports
  71      command <name> and, optionally, that that command supports the specified
  72      switch.  For example:
  73
  74         _require_xfs_io_command "falloc"
  75         _require_xfs_io_command "chattr" "x"
  76
  77      The first requires that xfs_io support the falloc command and the second
  78      that it supports the chattr command and that the chattr command supports
  79      the +x and -x arguments (DAX attribute).
  80
  81
  82 ==================================
  83 FILESYSTEM CAPABILITY REQUIREMENTS
  84 ==================================
  85
  86 _require_chattr <letters>
  87
  88      The test requires that the filesystem attribute set by the chattr command
  89      with +<letters> as an argument be available and supported by the $TEST_DEV
  90      filesystem.  No check is made of the scratch filesystem.  For example:
  91
  92         _require_chattr ai
  93
  94      tests to see if setting the append-only and immutable attributes on a file
  95      (chattr +a +i) is supported.
  96
  97 _require_exportfs
  98
  99      The test requires that the $TEST_DEV filesystem supports NFS export.
 100      The test also requires the use of the open_by_handle_at() system call and
 101      will be skipped if it isn't available in the kernel.
 102
 103 _require_sgid_inheritance
 104
 105      The test required that the $TEST_DEV filesystem supports the inheritance
 106      of the SGID bit and the GID from a marked directory.  The test will be
 107      skipped if not supported.
 108
 109 _require_use_local_uidgid
 110
 111      The test requires that the $TEST_DEV filesystem sets the uid and gid of a
 112      newly created file to the creating process's fsuid and fsgid.  Remote
 113      filesystems, for example, may choose other settings or not even have these
 114      concepts available.  The test will be skipped if not supported.
 115
 116 _require_unix_perm_checking
 117
 118      The test requires that the $TEST_DEV filesystem performs traditional UNIX
 119      file permissions checking.  A remote filesystem, for example, might use
 120      some alternative distributed permissions model involving authentication
 121      tokens rather than the local fsuid/fsgid.
 122
 123
 124 ========================
 125 SYSTEM CALL REQUIREMENTS
 126 ========================
 127
 128 _require_statx
 129
 130      The test requires the use of the statx() system call and will be skipped
 131      if it isn't available in the kernel.
 132
 133
 134 ==========================
 135 DEVICE MAPPER REQUIREMENTS
 136 ==========================
 137
 138 _require_dm_target <name>
 139
 140      The test requires the use of the device mapper target and will be skipped
 141      if it isn't available in the kernel.
 142
 143 _require_log_writes
 144
 145      The test requires the use of the device mapper target log-writes.
 146      The test also requires the test program log-writes/replay-log is built
 147      and will be skipped if either isn't available.
 148
 149 ======================
 150 PERF TEST REQUIREMENTS
 151 ======================
 152
 153 _require_fio_results
 154
 155      This test requires the supporting tools for saving and comparing fio based
 156      perf test results.