external/bsd/kyua-testers/dist/kyua-tester-list.5

   1 .\" Copyright 2012 Google Inc.
   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 December 26, 2012
  29 .Dt KYUA-TESTER-LIST 5
  30 .Os
  31 .Sh NAME
  32 .Nm kyua-tester-list
  33 .Nd The test cases list printed by the Kyua testers
  34 .Sh SYNOPSIS
  35 .Fn test_case properties_table
  36 .Sh DESCRIPTION
  37 The
  38 .Sq list
  39 subcommand of the various Kyua testers outputs the list of tests cases within a
  40 given test program.  The format of the list of test cases is a Lua script in
  41 which every line invokes the
  42 .Fn test_case
  43 function to define a test case.  The
  44 .Xr kyua 1
  45 runtime engine reads this list in order to determine what tests can be run.
  46 .Pp
  47 The
  48 .Fn test_case
  49 function takes a table as its only argument, and the table contains the
  50 definition of the metadata properties of the test case.  A typical invocation of
  51 this function looks like this:
  52 .Bd -literal -indent
  53 test_case{name='THE-NAME', ...}
  54 .Ed
  55 .Pp
  56 Where
  57 .Sq ...
  58 denote optional metadata values attached to the test case.  The supported
  59 metadata properties are the following:
  60 .Bl -tag -width allowedXarchitecturesXX
  61 .It allowed_architectures
  62 Whitespace-separated list of machine architecture names allowed by the test
  63 case.  If empty or not defined, the test case is allowed to run on any machine
  64 architecture.
  65 .It allowed_platforms
  66 Whitespace-separated list of machine platform names allowed by the test case.
  67 If empty or not defined, the test case is allowed to run on any machine
  68 platform.
  69 .It description
  70 Textual description of the test case.
  71 .It has_cleanup
  72 If
  73 .Sq true ,
  74 denotes that the test case has a cleanup routine.
  75 .It required_configs
  76 Whitespace-separated list of configuration variables that the test case requires
  77 to be defined before it can run.
  78 .It required_files
  79 Whitespace-separated list of paths that the test case requires to exist before
  80 it can run.
  81 .It required_memory
  82 Amount of physical memory that the test case needs to run successfully.
  83 .It required_programs
  84 Whitespace-separated list of basenames or absolute paths pointing to executable
  85 binaries that the test case requires to exist before it can run.
  86 .It required_user
  87 If empty, the test case has no restrictions on the calling user for it to run.
  88 If set to
  89 .Sq unprivileged ,
  90 the test case needs to not run as root.
  91 If set to
  92 .Sq root ,
  93 the test case must run as root.
  94 .It timeout
  95 Amount of seconds that the test case is allowed to execute before being killed.
  96 .It X-NAME
  97 Custom variable defined by the test case, where
  98 .Sq NAME
  99 denotes the name of the variable.
 100 .El
 101 .Sh SEE ALSO
 102 .Xr kyua-atf-tester 1 ,
 103 .Xr kyua-plain-tester 1