Add defer macros
[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 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.