Initial commit for the ODE API unit tests
[platform/core/test/security-tests.git] / 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.