contrib/kyua/doc/kyuafile.5.in

   1 .\" Copyright 2012 The Kyua Authors.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions are
   6 .\" met:
   7 .\"
   8 .\" * Redistributions of source code must retain the above copyright
   9 .\"   notice, this list of conditions and the following disclaimer.
  10 .\" * Redistributions in binary form must reproduce the above copyright
  11 .\"   notice, this list of conditions and the following disclaimer in the
  12 .\"   documentation and/or other materials provided with the distribution.
  13 .\" * Neither the name of Google Inc. nor the names of its contributors
  14 .\"   may be used to endorse or promote products derived from this software
  15 .\"   without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .Dd July 3, 2015
  29 .Dt KYUAFILE 5
  30 .Os
  31 .Sh NAME
  32 .Nm Kyuafile
  33 .Nd Test suite description files
  34 .Sh SYNOPSIS
  35 .Fn atf_test_program "string name" "[string metadata]"
  36 .Fn current_kyuafile
  37 .Fn fs.basename "string path"
  38 .Fn fs.dirname "string path"
  39 .Fn fs.exists "string path"
  40 .Fn fs.files "string path"
  41 .Fn fs.is_absolute "string path"
  42 .Fn fs.join "string path" "string path"
  43 .Fn include "string path"
  44 .Fn plain_test_program "string name" "[string metadata]"
  45 .Fn syntax "int version"
  46 .Fn tap_test_program "string name" "[string metadata]"
  47 .Fn test_suite "string name"
  48 .Sh DESCRIPTION
  49 A test suite is a collection of test programs and is represented by a
  50 hierarchical layout of test binaries on the file system.
  51 Any subtree of the file system can represent a test suite, provided that it
  52 includes one or more
  53 .Nm Ns s ,
  54 which are the test suite definition files.
  55 .Pp
  56 A
  57 .Nm
  58 is a Lua script whose purpose is to describe the structure of the test
  59 suite it belongs to.
  60 To do so, the script has access to a collection of special functions provided
  61 by
  62 .Xr kyua 1
  63 as described in
  64 .Sx Helper functions .
  65 .Ss File versioning
  66 Every
  67 .Nm
  68 file starts with a call to
  69 .Fn syntax "int version" .
  70 This call determines the specific schema used by the file so that future
  71 backwards-incompatible modifications to the file can be introduced.
  72 .Pp
  73 Any new
  74 .Nm
  75 file should set
  76 .Fa version
  77 to
  78 .Sq 2 .
  79 .Ss Test suite definition
  80 If the
  81 .Nm
  82 registers any test programs,
  83 the
  84 .Nm
  85 must define the name of the test suite the test programs belong to by using the
  86 .Fn test_suite
  87 function at the very beginning of the file.
  88 .Pp
  89 The test suite name provided in the
  90 .Fn test_suite
  91 call tells
  92 .Xr kyua 1
  93 which set of configuration variables from
  94 .Xr kyua.conf 5
  95 to pass to the test programs at run time.
  96 .Ss Test program registration
  97 A
  98 .Nm
  99 can register test programs by means of a variety of
 100 .Fn *_test_program
 101 functions, all of which take the name of a test program and a set of
 102 optional metadata properties that describe such test program.
 103 .Pp
 104 The test programs to be registered must live in the current directory; in
 105 other words, the various
 106 .Fn *_test_program
 107 calls cannot reference test programs in other directories.
 108 The rationale for this is to force all
 109 .Nm
 110 files to be self-contained, and to simplify their internal representation.
 111 .Pp
 112 .Em ATF test programs
 113 are those that use the
 114 .Xr atf 7
 115 libraries.
 116 They can be registered with the
 117 .Fn atf_test_program
 118 table constructor.
 119 This function takes the
 120 .Fa name
 121 of the test program and a collection of optional metadata settings for all
 122 the test cases in the test program.
 123 Any metadata properties defined by the test cases themselves override the
 124 metadata values defined here.
 125 .Pp
 126 .Em Plain test programs
 127 are those that return 0 on success and non-0 on failure; in general, most test
 128 programs (even those that use fancy unit-testing libraries) behave this way and
 129 thus also qualify as plain test programs.
 130 They can be registered with the
 131 .Fn plain_test_program
 132 table constructor.
 133 This function takes the
 134 .Fa name
 135 of the test program, an optional
 136 .Fa test_suite
 137 name that overrides the global test suite name, and a collection of optional
 138 metadata settings for the test program.
 139 .Pp
 140 .Em TAP test programs
 141 are those that implement the Test Anything Protocol.
 142 They can be registered with the
 143 .Fn tap_test_program
 144 table constructor.
 145 This function takes the
 146 .Fa name
 147 of the test program and a collection of optional metadata settings for the
 148 test program.
 149 .Pp
 150 The following metadata properties can be passed to any test program definition:
 151 .Bl -tag -width XX -offset indent
 152 .It Va allowed_architectures
 153 Whitespace-separated list of machine architecture names allowed by the test.
 154 If empty or not defined, the test is allowed to run on any machine
 155 architecture.
 156 .It Va allowed_platforms
 157 Whitespace-separated list of machine platform names allowed by the test.
 158 If empty or not defined, the test is allowed to run on any machine
 159 platform.
 160 .It Va custom.NAME
 161 Custom variable defined by the test where
 162 .Sq NAME
 163 denotes the name of the variable.
 164 These variables are useful to tag your tests with information specific to
 165 your project.
 166 The values of such variables are propagated all the way from the tests to the
 167 results files and later to any generated reports.
 168 .Pp
 169 Note that if the name happens to have dashes or any other special characters
 170 in it, you will have to use a special Lua syntax to define the property.
 171 Refer to the
 172 .Sx EXAMPLES
 173 section below for clarification.
 174 .It Va description
 175 Textual description of the test.
 176 .It Va is_exclusive
 177 If true, indicates that this test program cannot be executed along any other
 178 programs at the same time.
 179 Test programs that affect global system state, such as those that modify the
 180 value of a
 181 .Xr sysctl 8
 182 setting, must set themselves as exclusive to prevent failures due to race
 183 conditions.
 184 Defaults to false.
 185 .It Va required_configs
 186 Whitespace-separated list of configuration variables that the test requires
 187 to be defined before it can run.
 188 .It Va required_disk_space
 189 Amount of available disk space that the test needs to run successfully.
 190 .It Va required_files
 191 Whitespace-separated list of paths that the test requires to exist before
 192 it can run.
 193 .It Va required_memory
 194 Amount of physical memory that the test needs to run successfully.
 195 .It Va required_programs
 196 Whitespace-separated list of basenames or absolute paths pointing to executable
 197 binaries that the test requires to exist before it can run.
 198 .It Va required_user
 199 If empty, the test has no restrictions on the calling user for it to run.
 200 If set to
 201 .Sq unprivileged ,
 202 the test needs to not run as root.
 203 If set to
 204 .Sq root ,
 205 the test must run as root.
 206 .It Va timeout
 207 Amount of seconds that the test is allowed to execute before being killed.
 208 .El
 209 .Ss Recursion
 210 To reference test programs in another subdirectory, a different
 211 .Nm
 212 must be created in that directory and it must be included into the original
 213 .Nm
 214 by means of the
 215 .Fn include
 216 function.
 217 .Pp
 218 .Fn include
 219 may only be called with a relative path and with at most one directory
 220 component.
 221 This is by design: Kyua uses the file system structure as the layout of the
 222 test suite definition.
 223 Therefore, each subdirectory in a test suite must include its own
 224 .Nm
 225 and each
 226 .Nm
 227 can only descend into the
 228 .Nm Ns s
 229 of immediate subdirectories.
 230 .Pp
 231 If you need to source a
 232 .Nm
 233 located in disjoint parts of your file system namespace, you will have to
 234 create a
 235 .Sq shadow tree
 236 using symbolic links and possibly helper
 237 .Nm Ns s
 238 to plug the various subdirectories together.
 239 See the
 240 .Sx EXAMPLES
 241 section below for details.
 242 .Pp
 243 Note that each file is processed in its own Lua environment: there is no
 244 mechanism to pass state from one file to the other.
 245 The reason for this is that there is no such thing as a
 246 .Dq top-level
 247 .Nm
 248 in a test suite: the user has to be able to run the test suite from any
 249 directory in a given hierarchy, and this execution must not depend on files
 250 that live in parent directories.
 251 .Ss Top-level Kyuafile
 252 Every system has a top directory into which test suites get installed.
 253 The default is
 254 .Pa __TESTSDIR__ .
 255 Within this directory live test suites, each of which is in an independent
 256 subdirectory.
 257 Each subdirectory can be provided separately by independent third-party
 258 packages.
 259 .Pp
 260 Kyua allows running all the installed test suites at once in order to
 261 provide comprehensive cross-component reports.
 262 In order to do this, there is a special file in the top directory that knows
 263 how to inspect the subdirectories in search for other Kyuafiles and include
 264 them.
 265 .Pp
 266 The
 267 .Sx FILES
 268 section includes more details on where this file lives.
 269 .Ss Helper functions
 270 The
 271 .Sq base ,
 272 .Sq string ,
 273 and
 274 .Sq table
 275 Lua modules are fully available in the context of a
 276 .Nm .
 277 .Pp
 278 The following extra functions are provided by Kyua:
 279 .Bl -tag -width XX -offset indent
 280 .It Ft string Fn current_kyuafile
 281 Returns the absolute path to the current
 282 .Nm .
 283 .It Ft string Fn fs.basename "string path"
 284 Returns the last component of the given path.
 285 .It Ft string Fn fs.dirname "string path"
 286 Returns the given path without its last component or a dot if the path has
 287 a single component.
 288 .It Ft bool Fn fs.exists "string path"
 289 Checks if the given path exists.
 290 If the path is not absolute, it is relative to the directory containing the
 291 .Nm
 292 in which the call to this function occurs.
 293 .It Ft iterator Fn fs.files "string path"
 294 Opens a directory for scanning of its entries.
 295 The returned iterator yields an entry on each call, and the entry is simply
 296 the filename.
 297 If the path is not absolute, it is relative to the directory containing the
 298 .Nm
 299 in which the call to this function occurs.
 300 .It Ft is_absolute Fn fs.is_absolute "string path"
 301 Returns true if the given path is absolute; false otherwise.
 302 .It Ft join Fn fs.join "string path" "string path"
 303 Concatenates the two paths.
 304 The second path cannot be absolute.
 305 .El
 306 .Sh FILES
 307 .Bl -tag -width XX
 308 .It Pa __TESTSDIR__/Kyuafile .
 309 Top-level
 310 .Nm
 311 for the current system.
 312 .It Pa __EGDIR__/Kyuafile.top .
 313 Sample file to serve as a top-level
 314 .Nm .
 315 .El
 316 .Sh EXAMPLES
 317 The following
 318 .Nm
 319 is the simplest you can define.
 320 It provides a test suite definition and registers a couple of different test
 321 programs using different interfaces:
 322 .Bd -literal -offset indent
 323 syntax(2)
 324
 325 test_suite('first')
 326
 327 atf_test_program{name='integration_test'}
 328 plain_test_program{name='legacy_test'}
 329 .Ed
 330 .Pp
 331 The following example is a bit more elaborate.
 332 It introduces some metadata properties to the test program definitions and
 333 recurses into a couple of subdirectories:
 334 .Bd -literal -offset indent
 335 syntax(2)
 336
 337 test_suite('second')
 338
 339 plain_test_program{name='legacy_test',
 340                    allowed_architectures='amd64 i386',
 341                    required_files='/bin/ls',
 342                    timeout=30}
 343
 344 tap_test_program{name='privileged_test',
 345                  required_user='root'}
 346
 347 include('module-1/Kyuafile')
 348 include('module-2/Kyuafile')
 349 .Ed
 350 .Pp
 351 The syntax to define custom properties may be not obvious if their names
 352 have any characters that make the property name not be a valid Lua identifier.
 353 Dashes are just one example.
 354 To set such properties, do something like this:
 355 .Bd -literal -offset indent
 356 syntax(2)
 357
 358 test_suite('FreeBSD')
 359
 360 plain_test_program{name='the_test',
 361                    ['custom.FreeBSD-Bug-Id']='category/12345'}
 362 .Ed
 363 .Ss Connecting disjoint test suites
 364 Now suppose you had various test suites on your file system and you would
 365 like to connect them together so that they could be executed and treated as
 366 a single unit.
 367 The test suites we would like to connect live under
 368 .Pa /usr/tests ,
 369 .Pa /usr/local/tests
 370 and
 371 .Pa ~/local/tests .
 372 .Pp
 373 We cannot create a
 374 .Nm
 375 that references these because the
 376 .Fn include
 377 directive does not support absolute paths.
 378 Instead, what we can do is create a shadow tree using symbolic links:
 379 .Bd -literal -offset indent
 380 $ mkdir ~/everything
 381 $ ln -s /usr/tests ~/everything/system-tests
 382 $ ln -s /usr/local/tests ~/everything/local-tests
 383 $ ln -s ~/local/tests ~/everything/home-tests
 384 .Ed
 385 .Pp
 386 And then we create an
 387 .Pa ~/everything/Kyuafile
 388 file to drive the execution of the integrated test suite:
 389 .Bd -literal -offset indent
 390 syntax(2)
 391
 392 test_suite('test-all-the-things')
 393
 394 include('system-tests/Kyuafile')
 395 include('local-tests/Kyuafile')
 396 include('home-tests/Kyuafile')
 397 .Ed
 398 .Pp
 399 Or, simply, you could reuse the sample top-level
 400 .Nm
 401 to avoid having to manually craft the list of directories into which to
 402 recurse:
 403 .Bd -literal -offset indent
 404 $ cp __EGDIR__/Kyuafile.top ~/everything/Kyuafile
 405 .Ed
 406 .Sh SEE ALSO
 407 .Xr kyua 1