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