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
 124 --Assert macros----------------------------------------------------------------
 125 Used within test registering macros.
 126
 127 First failed assertion throws test failed exception. If another assertions
 128 fail, information about fail conditions and backtrace is cumulated and
 129 presented together with already thrown exception message.
 130
 131 dpl-test-framework
 132   test_runner.h
 133     RUNNER_ASSERT_MSG
 134           Assertion with message with backtrace information appended.
 135     RUNNER_ASSERT_ERRNO_MSG
 136           Assertion with message, error string and backtrace information
 137           appended.
 138     RUNNER_ASSERT_ERRNO
 139           Assertion with error string and backtrace information appended.
 140     RUNNER_FAIL_MSG
 141           Fail with message and backtrace information appended.
 142     RUNNER_ASSERT
 143           Assertion with backtrace information appended.
 144     RUNNER_IGNORED_MSG
 145           Assertion with message classified as ignored.
 146
 147 --Performence macros-----------------------------------------------------------
 148 Used to do the time measurement.
 149
 150 dpl-test-framework
 151   test_runner.h
 152     RUNNER_PERF_TEST_BEGIN
 153           Start time measurement.
 154     RUNNER_PERF_TEST_END
 155           End time measurement.
 156
 157 --Message macros---------------------------------------------------------------
 158 Used to print error messages during test run time.
 159
 160 dpl-test-framework
 161   test_runner.h
 162     RUNNER_ERROR_MSG
 163           Print error message using red color.
 164
 165 --Defer macros-----------------------------------------------------------------
 166 Used to defer throwing TestException exceptions (TestFailed, TestIgnored)
 167 by catching them and rethrowing later. This mechanism can help in breaking
 168 test and passing test result from places where throwing exceptions
 169 is not allowed
 170
 171 dpl-test-framework
 172   test_runner.h
 173     RUNNER_DEFER_TRYCATCH
 174           Catches thrown TestException exceptions and stores them in TestRunner
 175           structures for later use. This macro works only inside deffered scope
 176           defined by RUNNER_DEFER_SCOPE, otherwise it won't catch exceptions
 177     RUNNER_DEFER_SCOPE
 178           Defines deferred scope. All RUNNER_DEFER_TRYCATCH macros used inside
 179           the scope catch and save TestException exceptions. After scope is left
 180           all saved exceptions take part in setting result of test. If there
 181           is no any uncaught exception then additionally first of saved
 182           exceptions is thrown.
 183
 184 --Collectors-------------------------------------------------------------------
 185 Collectors are classes which collect test results. Each class does it differently.
 186 Collectors can be registered by --output parameter (see HOW TO RUN section) but
 187 there is also another collector created to write summary.
 188
 189 dpl-test-framework
 190   test_results_collector_summary.h
 191     SummaryCollector
 192           Collector writing tests summary. Call SummaryCollector::Register() to
 193           register it
 194
 195 --Usage example----------------------------------------------------------------
 196
 197 #include <test_runner.h>
 198 #include <tests_common.h>
 199 #include <summary_collector.h>
 200
 201 #include <sys/stat.h>
 202 #include <unistd.h>
 203 #include <fcntl.h>
 204
 205 RUNNER_TEST_GROUP_INIT(foo_module)
 206
 207 RUNNER_TEST_SMACK(bar_allways_fails)
 208 {
 209     RUNNER_ASSERT(false);
 210 }
 211
 212 RUNNER_TEST(bar_allways_passses)
 213 {
 214     RUNNER_ASSERT(true);
 215 }
 216
 217 RUNNER_TEST(bar_file1)
 218 {
 219     cosnt char *file = "bar_file1";
 220     int fd = TEMP_FAILURE_RETRY(open(file, O_RDONLY));
 221     RUNNER_ASSERT_ERRNO_MSG(fd != -1, "Cannot open " << file << " file");
 222     close(fd);
 223 }
 224
 225 RUNNER_CHILD_TEST_NOSMACK(bar_file2_dropped_root)
 226 {
 227     RUNNER_ASSERT_ERRNO(setgid(5000) == 0);
 228     RUNNER_ASSERT_ERRNO(setuid(5000) == 0);
 229
 230     cosnt char *file = "bar_file2";
 231     int fd = TEMP_FAILURE_RETRY(open(file, O_RDONLY));
 232     if(fd != -1) {
 233         close(fd);
 234         RUNNER_FAIL_MSG("file " << file << "should not be opened");
 235     }
 236     RUNNER_ASSERT_ERRNO_MSG(errno == EACCESS,
 237                             "Wrong errno on opening " << " file");
 238 }
 239
 240 class Env
 241 {
 242 public:
 243     Env() { ... }
 244     void init(const std::string &testName) { ... }
 245     void finish() { ... }
 246     void doEnv() { ... }
 247 };
 248
 249 class Restore
 250 {
 251 public:
 252     Restore() { ... }
 253     void init(const std::string &testName) { ... }
 254     void finish() { ... }
 255     void doRestore() { ... }
 256 };
 257
 258 RUNNER_TEST(bar_optional_args, Env, Restore)
 259 {
 260     std::get<0>(optionalArgsTuple).doEnv();
 261     std::get<1>(optionalArgsTuple).doRestore();
 262 }
 263
 264 int main(int argc, char *argv[])
 265 {
 266     SummaryCollector::Register();
 267     return DPL::Test::TestRunnerSingleton::Instance().ExecTestRunner(argc, argv);
 268 }
 269
 270 --Notes------------------------------------------------------------------------
 271
 272   While changing body of test cases, be sure to remove functions and global
 273 variables if not used by any other tests.
 274   Use const variables instead of #define's.
 275   Use mechanisms already provided in common library.