contrib/kyua/doc/test-isolation.mdoc

   1 .\" Copyright 2014 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 The test programs and test cases run by
  29 .Nm
  30 are all executed in a deterministic environment.
  31 This known, clean environment serves to make the test execution as
  32 reproducible as possible and also to prevent clashes between tests that may,
  33 for example, create auxiliary files with overlapping names.
  34 .Pp
  35 For plain test programs and for TAP test programs, the whole test program
  36 is run under a single instance of the environment described in this page.
  37 For ATF test programs (see
  38 .Xr atf 7 ) ,
  39 each individual test case
  40 .Em and
  41 test cleanup routine are executed in separate environments.
  42 .Bl -tag -width XX
  43 .It Process space
  44 Each test is executed in an independent processes.
  45 Corollary: the test can do whatever it wants to the current process (such
  46 as modify global variables) without having to undo such changes.
  47 .It Session and process group
  48 The test is executed in its own session and its own process group.
  49 There is no controlling terminal attached to the session.
  50 .Pp
  51 Should the test spawn any children, the children should maintain the same
  52 session and process group.
  53 Modifying any of these settings prevents
  54 .Nm
  55 from being able to kill any stray subprocess as part of the cleanup phase.
  56 If modifying these settings is necessary, or if any subprocess started by
  57 the test decides to use a different process group or session, it is the
  58 responsibility of the test to ensure those subprocesses are forcibly
  59 terminated during cleanup.
  60 .It Work directory
  61 The test is executed in a temporary directory automatically created by the
  62 runtime engine.
  63 Corollary: the test can write to its current directory
  64 without needing to clean any files and/or directories it creates.
  65 The runtime engine takes care to recursively delete the temporary directories
  66 after the execution of a test case.
  67 Any file systems mounted within the temporary directory are also unmounted.
  68 .It Home directory
  69 The
  70 .Va HOME
  71 environment variable is set to the absolute path of the work directory.
  72 .It Umask
  73 The value of the umask is set to 0022.
  74 .It Environment
  75 The
  76 .Va LANG ,
  77 .Va LC_ALL ,
  78 .Va LC_COLLATE ,
  79 .Va LC_CTYPE ,
  80 .Va LC_MESSAGES ,
  81 .Va LC_MONETARY ,
  82 .Va LC_NUMERIC
  83 and
  84 .Va LC_TIME
  85 variables are unset.
  86 .Pp
  87 The
  88 .Va TZ
  89 variable is set to
  90 .Sq UTC .
  91 .Pp
  92 The
  93 .Va TMPDIR
  94 variable is set to the absolute path of the work directory.
  95 This is to prevent the test from mistakenly using a temporary directory
  96 outside of the automatically-managed work directory, should the test use the
  97 .Xr mktemp 3
  98 familiy of functions.
  99 .It Process limits
 100 The maximum soft core size limit is raised to its corresponding hard limit.
 101 This is a simple, best-effort attempt at allowing tests to dump core for
 102 further diagnostic purposes.
 103 .It Configuration varibles
 104 The test engine may pass run-time configuration variables to the test program
 105 via the environment.
 106 The name of the configuration variable is prefixed with
 107 .Sq TEST_ENV_
 108 so that a configuration variable of the form
 109 .Sq foo=bar
 110 becomes accessible in the environment as
 111 .Sq TEST_ENV_foo=bar .
 112 .El