README
1<!---
2 Copyright 2017, Data61
3 Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4 ABN 41 687 119 230.
5
6 This software may be distributed and modified according to the terms of
7 the BSD 2-Clause license. Note that NO WARRANTY is provided.
8 See "LICENSE_BSD2.txt" for details.
9
10 @TAG(DATA61_BSD)
11-->
12
13This library is for running tests and generating test output in either
14human readable or xml format.
15
16SETTING UP LIBSEL4TEST WITH YOUR PROJECT
17
18Choose the appropriate options for your build. If you are testing as
19a human, you probably want both of those options disabled. If you are
20testing as bamboo, you definitely want both turned on.
21
22CONFIG_PRINT_XML
23
24Bamboo requires XML. Humans can choose.
25
26Stdout will be buffered to avoid corrupting the xml as JUnit output
27requires that stdout be wrapped in an xml element, which is
28what the above option does. Turn that option off (in Kconfig) whilst
29debugging your test suite. This buffering will currently only apply to
30printf.
31
32USING LIBSEL4TEST
33
34To use libsel4test:
35
361. Provide a definition for struct env before including <sel4test/test.h>.
372. Write tests with the prototype int (*test)(env_t env, void *args). Follow each test with the DEFINE_TEST macro.
383. Provide a run_test function int (*run_test)(struct test_case *t) and call sel4test_run_tests.
394. That's it. Each test will run in alphabetical order based on the test name. Tests will run forward and backward.
40
41Example code:
42
43struct env {
44 vka_t *vka;
45}
46
47#include <sel4test/test.h>
48
49static env_t env;
50
51env_t sel4test_get_env(void) {
52 return env;
53}
54
55static int
56a_test(env_t env, void *args)
57{
58 printf("Hello world");
59 test_check(0 == 0);
60}
61DEFINE_TEST(TEST000, "An example test", a_test)
62
63int main(void) {
64
65 /* allocator set up */
66 env->vka = init_allocator();
67
68 /* sel4test_basic_run_test just runs each test and passes in
69 env returned by sel4test_get_env.
70 You can define your own version of this if you need custom
71 setup/teardown
72 */
73 sel4test_run_tests("my test name", sel4test_basic_run_test);
74
75}
76
77CAVEATS
78
79There is a tool for sanitizing the xml in tools/extract_results.py.
80
81A NOTE ON ASSERT
82
83When writing tests with this library you should usually avoid using assert and
84always use 'sel4test_check' etc, which will test the case and report a test failure
85without crashing the build. This permits other tests to keep running.
86
87Use test_assert_fatal if your tests have reached a state where continuing the
88test run is useless and you do not want to parse any test results from
89the build at all.
90
91It is good practice for failing tests to not break the build, but sometimes
92it is necessary.
93