README

   1 README for security-tests project
   2
   3 ==WHAT IS======================================================================
   4
   5 security-tests is repository for testing packages from domain Security.
   6
   7 ==WHAT FOR=====================================================================
   8
   9 The security-tests repository is designed for testing packages mentioned below
  10 with binaries provided for testing them:
  11
  12 libsmack
  13   libsmack-test
  14 security-manager
  15   security-manager-tests
  16 cynara
  17   cynara-test
  18 ode
  19   ode-tests
  20
  21 There are also inner-tests for testing complex security-tests framework
  22 mechanisms with binary:
  23   security-tests-inner-test
  24
  25 ==HOW TO RUN===================================================================
  26
  27 Each test suite may be run with options:
  28   --output=<output type> --output=<output type> ...
  29         --output=xml
  30       example:
  31         test-binary --output=text --output=xml --file=output.xml
  32   --only-from-xml=<xml file>    Run only testcases specified in XML file
  33   --regexp='regexp'             Only selected tests which names match regexp run
  34   --start=<test id>             Start from concrete test id
  35   --group=<group name>          Run tests only from one group
  36   --runignored                  Run also ignored tests
  37   --list                        Show a list of Test IDs
  38   --listgroups                  Show a list of Test Group names
  39   --only-from-xml=<xml file>    Run only testcases specified in XML file
  40         XML name is taken from attribute id="part1_part2" as whole.
  41         If part1 is not found (no _) then it is implicitily set according to
  42         suite part1 from binary tests
  43   --listingroup=<group name>    Show a list of Test IDS in one group
  44   --allowchildlogs              Allow to print logs from child process on screen.
  45         When active child process will be able to print logs on stdout and
  46         stderr. Both descriptors will be closed after test.
  47   --help                        Print help
  48
  49 They can be run also by scripts:
  50   security-tests.sh
  51   security-tests-all.sh
  52
  53 Each test can end with one of three possible statuses:
  54   FAILED
  55   OK
  56   IGNORED
  57
  58 ==HOW TO WRITE=================================================================
  59
  60 security-tests is based on extended dpl framework providing different macros.
  61 Below are categories with macros listed as below:
  62 library
  63   include
  64     macro
  65           description
  66
  67 --Test group registering macro-------------------------------------------------
  68
  69 dpl-test-framework
  70   test_runner.h
  71     RUNNER_TEST_GROUP_INIT
  72           Registers group of tests. Test are registered under this group until
  73           another group registering macro is called.
  74
  75 --Test registering macros------------------------------------------------------
  76 Adding/removing those macro calls will add/remove test cases they provide. To
  77 change tests, change body of those macro calls. Registered tests are run within
  78 group alphabetically.
  79 Those macros allow additional arguments which are classes with mandatory
  80 methods:
  81 * (constructor) ()
  82     Called while registering test.
  83     Should not throw any exceptions
  84 * init(const std::string &testName)
  85     Called before test case function in order of classes passed to macro.
  86     Should not be forked.
  87     testName argument is name of the test (first macro argument).
  88 * finish(void)
  89     called after test case function in reversed order of classes passed to
  90     macro.
  91     Should not be forked.
  92 Created instances of those classes may be accessed from within test case body
  93 as argument of test case funtion is
  94   std::tuple<ClassesPassed> &optionalArgsTuple
  95
  96 dpl-test-framework
  97   test_runner.h
  98     RUNNER_TEST
  99           Function registered by this macro will be run in the same process as
 100           framework. No forking allowed unless forked process does not throw
 101           any exception.
 102   test_runner_child.h
 103     RUNNER_CHILD_TEST
 104           Function registered by this macro will be run in child process. No
 105           forking allowed unless forked process does not throw any exception.
 106   test_runner_multiprocess.h
 107     RUNNER_MULTIPROCESS_TEST
 108           Function registered by this macro will be run in the same process as
 109           framework. Forking allowed. Exception of every process will be
 110           registered.
 111 tests-common
 112   tests_common.h
 113     RUNNER_TEST_SMACK
 114           Same as RUNNER_TEST but run only with smack enabled.
 115     RUNNER_TEST_NOSMACK
 116           Same as RUNNER_TEST but run only with smack disabled.
 117     RUNNER_CHILD_TEST_SMACK
 118           Same as RUNNER_TEST_CHILD but run only with smack enabled.
 119     RUNNER_CHILD_TEST_NOSMACK
 120           Same as RUNNER_TEST_CHILD but run only with smack disabled.
 121     RUNNER_MULTIPROCESS_TEST_SMACK
 122           Same as RUNNER_TEST_MULTIPROCESS but run only with smack enabled.
 123     RUNNER_MULTIPROCESS_TEST_NOSMACK
 124           Same as RUNNER_TEST_MULTIPROCESS but run only with smack disabled.
 125
 126 --Assert macros----------------------------------------------------------------
 127 Used within test registering macros.
 128
 129 First failed assertion throws test failed exception. If another assertions
 130 fail, information about fail conditions and backtrace is cumulated and
 131 presented together with already thrown exception message.
 132
 133 dpl-test-framework
 134   test_runner.h
 135     RUNNER_ASSERT_MSG
 136           Assertion with message with backtrace information appended.
 137     RUNNER_ASSERT_ERRNO_MSG
 138           Assertion with message, error string and backtrace information
 139           appended.
 140     RUNNER_ASSERT_ERRNO
 141           Assertion with error string and backtrace information appended.
 142     RUNNER_FAIL_MSG
 143           Fail with message and backtrace information appended.
 144     RUNNER_ASSERT
 145           Assertion with backtrace information appended.
 146     RUNNER_IGNORED_MSG
 147           Assertion with message classified as ignored.
 148
 149 --Performence macros-----------------------------------------------------------
 150 Used to do the time measurement.
 151
 152 dpl-test-framework
 153   test_runner.h
 154     RUNNER_PERF_TEST_BEGIN
 155           Start time measurement.
 156     RUNNER_PERF_TEST_END
 157           End time measurement.
 158
 159 --Message macros---------------------------------------------------------------
 160 Used to print error messages during test run time.
 161
 162 dpl-test-framework
 163   test_runner.h
 164     RUNNER_ERROR_MSG
 165           Print error message using red color.
 166
 167 --Defer macros-----------------------------------------------------------------
 168 Used to defer throwing TestException exceptions (TestFailed, TestIgnored)
 169 by catching them and rethrowing later. This mechanism can help in breaking
 170 test and passing test result from places where throwing exceptions
 171 is not allowed
 172
 173 dpl-test-framework
 174   test_runner.h
 175     RUNNER_DEFER_TRYCATCH
 176           Catches thrown TestException exceptions and stores them in TestRunner
 177           structures for later use. This macro works only inside deffered scope
 178           defined by RUNNER_DEFER_SCOPE, otherwise it won't catch exceptions
 179     RUNNER_DEFER_SCOPE
 180           Defines deferred scope. All RUNNER_DEFER_TRYCATCH macros used inside
 181           the scope catch and save TestException exceptions. After scope is left
 182           all saved exceptions take part in setting result of test. If there
 183           is no any uncaught exception then additionally first of saved
 184           exceptions is thrown.
 185
 186 --Collectors-------------------------------------------------------------------
 187 Collectors are classes which collect test results. Each class does it differently.
 188 Collectors can be registered by --output parameter (see HOW TO RUN section) but
 189 there is also another collector created to write summary.
 190
 191 dpl-test-framework
 192   test_results_collector_summary.h
 193     SummaryCollector
 194           Collector writing tests summary. Call SummaryCollector::Register() to
 195           register it
 196
 197 --Usage example----------------------------------------------------------------
 198
 199 #include <test_runner.h>
 200 #include <tests_common.h>
 201 #include <summary_collector.h>
 202
 203 #include <sys/stat.h>
 204 #include <unistd.h>
 205 #include <fcntl.h>
 206
 207 RUNNER_TEST_GROUP_INIT(foo_module)
 208
 209 RUNNER_TEST_SMACK(bar_allways_fails)
 210 {
 211     RUNNER_ASSERT(false);
 212 }
 213
 214 RUNNER_TEST(bar_allways_passses)
 215 {
 216     RUNNER_ASSERT(true);
 217 }
 218
 219 RUNNER_TEST(bar_file1)
 220 {
 221     cosnt char *file = "bar_file1";
 222     int fd = TEMP_FAILURE_RETRY(open(file, O_RDONLY));
 223     RUNNER_ASSERT_ERRNO_MSG(fd != -1, "Cannot open " << file << " file");
 224     close(fd);
 225 }
 226
 227 RUNNER_CHILD_TEST_NOSMACK(bar_file2_dropped_root)
 228 {
 229     RUNNER_ASSERT_ERRNO(setgid(5000) == 0);
 230     RUNNER_ASSERT_ERRNO(setuid(5000) == 0);
 231
 232     cosnt char *file = "bar_file2";
 233     int fd = TEMP_FAILURE_RETRY(open(file, O_RDONLY));
 234     if(fd != -1) {
 235         close(fd);
 236         RUNNER_FAIL_MSG("file " << file << "should not be opened");
 237     }
 238     RUNNER_ASSERT_ERRNO_MSG(errno == EACCESS,
 239                             "Wrong errno on opening " << " file");
 240 }
 241
 242 class Env
 243 {
 244 public:
 245     Env() { ... }
 246     void init(const std::string &testName) { ... }
 247     void finish() { ... }
 248     void doEnv() { ... }
 249 };
 250
 251 class Restore
 252 {
 253 public:
 254     Restore() { ... }
 255     void init(const std::string &testName) { ... }
 256     void finish() { ... }
 257     void doRestore() { ... }
 258 };
 259
 260 RUNNER_TEST(bar_optional_args, Env, Restore)
 261 {
 262     std::get<0>(optionalArgsTuple).doEnv();
 263     std::get<1>(optionalArgsTuple).doRestore();
 264 }
 265
 266 int main(int argc, char *argv[])
 267 {
 268     SummaryCollector::Register();
 269     return DPL::Test::TestRunnerSingleton::Instance().ExecTestRunner(argc, argv);
 270 }
 271
 272 --Notes------------------------------------------------------------------------
 273
 274   While changing body of test cases, be sure to remove functions and global
 275 variables if not used by any other tests.
 276   Use const variables instead of #define's.
 277   Use mechanisms already provided in common library.