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