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 dpl-test-framework
 118   test_runner.h
 119     RUNNER_ASSERT_MSG
 120           Assertion with message with backtrace information appended.
 121     RUNNER_ASSERT_ERRNO_MSG
 122           Assertion with message, error string and backtrace information
 123           appended.
 124     RUNNER_ASSERT_ERRNO
 125           Assertion with error string and backtrace information appended.
 126     RUNNER_FAIL_MSG
 127           Fail with message and backtrace information appended.
 128     RUNNER_ASSERT
 129           Assertion with backtrace information appended.
 130     RUNNER_IGNORED_MSG
 131           Assertion with message classified as ignored.
 132
 133 --Performence macros-----------------------------------------------------------
 134 Used to do the time measurement.
 135
 136 dpl-test-framework
 137   test_runner.h
 138     RUNNER_PERF_TEST_BEGIN
 139           Start time measurement.
 140     RUNNER_PERF_TEST_END
 141           End time measurement.
 142
 143 --Message macros---------------------------------------------------------------
 144 Used to print error messages during test run time.
 145
 146 dpl-test-framework
 147   test_runner.h
 148     RUNNER_ERROR_MSG
 149           Print error message using red color.
 150
 151 --Collectors-------------------------------------------------------------------
 152 Collectors are classes which collect test results. Each class does it differently.
 153 Collectors can be registered by --output parameter (see HOW TO RUN section) but
 154 there is also another collector created to write summary.
 155
 156 dpl-test-framework
 157   test_results_collector_summary.h
 158     SummaryCollector
 159           Collector writing tests summary. Call SummaryCollector::Register() to
 160           register it
 161
 162 --Usage example----------------------------------------------------------------
 163
 164 #include <test_runner.h>
 165 #include <tests_common.h>
 166 #include <summary_collector.h>
 167
 168 #include <sys/stat.h>
 169 #include <unistd.h>
 170 #include <fcntl.h>
 171
 172 RUNNER_TEST_GROUP_INIT(foo_module)
 173
 174 RUNNER_TEST_SMACK(bar_allways_fails)
 175 {
 176     RUNNER_ASSERT(false);
 177 }
 178
 179 RUNNER_TEST(bar_allways_passses)
 180 {
 181     RUNNER_ASSERT(true);
 182 }
 183
 184 RUNNER_TEST(bar_file1)
 185 {
 186     cosnt char *file = "bar_file1";
 187     int fd = TEMP_FAILURE_RETRY(open(file, O_RDONLY));
 188     RUNNER_ASSERT_ERRNO_MSG(fd != -1, "Cannot open " << file << " file");
 189     close(fd);
 190 }
 191
 192 RUNNER_CHILD_TEST_NOSMACK(bar_file2_dropped_root)
 193 {
 194     RUNNER_ASSERT_ERRNO(setgid(5000) == 0);
 195     RUNNER_ASSERT_ERRNO(setuid(5000) == 0);
 196
 197     cosnt char *file = "bar_file2";
 198     int fd = TEMP_FAILURE_RETRY(open(file, O_RDONLY));
 199     if(fd != -1) {
 200         close(fd);
 201         RUNNER_FAIL_MSG("file " << file << "should not be opened");
 202     }
 203     RUNNER_ASSERT_ERRNO_MSG(errno == EACCESS,
 204                             "Wrong errno on opening " << " file");
 205 }
 206
 207 int main(int argc, char *argv[])
 208 {
 209     SummaryCollector::Register();
 210     return DPL::Test::TestRunnerSingleton::Instance().ExecTestRunner(argc, argv);
 211 }
 212
 213 --Notes------------------------------------------------------------------------
 214
 215   While changing body of test cases, be sure to remove functions and global
 216 variables if not used by any other tests.
 217   Use const variables instead of #define's.
 218   Use mechanisms already provided in common library.