9ns: Remove the old mnt cache
[akaros.git] / Documentation / testing.txt
1 Automated Testing 
2 ----------------------------
3 This document outlines our plans for automated testing with Akaros.
4 When completed, the testing framework will be used to both verify successful
5 compilation of akaros (and its supporting user libraries and cross compiler),
6 as well as perform automated tests of these.
7
8 Currently, our testing is done in a very ad-hoc manner.  For kernel tests, we
9 simply add a function to the file 'kern/src/testing.c' and run it periodically
10 from the kernel monitor to verify that it still works. For user tests, we
11 create a new file in 'tests/' and run 'make tests' followed by 'make fill-kfs'
12 to make and install the tests so akaros can run them once booted.  We then just
13 peridically run them when we think we might have broken something.
14
15 We obviously need something better.
16
17 At a minimum we need a framework that can automate the following on every commit:
18         - Verify successful kernel compilation
19         - Verify successful compilation of our user libraries
20         - Verify successful compilation of the cross compiler for all supported
21           archs on commits that touch a file in the cross compiler
22         - Compile and run a suite of kernel and user tests and verify their success
23
24 The framework should support easily adding/removing tests, as well as a way to
25 easily turn them on and off, without actually removing them. We should also
26 have a way of notifying us if something breaks, and a way to turn off
27 notifications for individual tests, if things start to get too noisy.
28 Independent of how we do notifications, we should have a dashboard indicating
29 the current state of what's passing/failing, and a way to look through the
30 history of this for every commit.
31
32 An example of such a dashboard can be found at: http://build.golang.org/
33 Our's does not need to be this sophisticated at first.  A simple text file with
34 all the relevant information will suffice, and it's history can be kept track
35 of by versioning it in a git repo.
36
37
38 Unorganized stuff
39 ----------------------------
40 Use configure variables integrated with KBuild for kernel test on/off
41 Mention difficulty of running some tests.
42         - Need specific kernel configs
43         - Specific timing between injecting inputs for some tests
44 Mention technologies we are considering using
45         - Junit like framework for writing tests
46         - Autotest? https://github.com/autotest/autotest
47 Send email notification if cross compiler needs a rebuild
48
49
50 Links 
51 ----------------------------
52 - Converting VirtualBox VDI image to Xen:
53   https://www.serverstack.com/blog/2012/11/20/converting-virtualbox-vm-to-a-xen-hypervisor-virtual-machine/
54
55
56 ================================================================================
57 ======================== W.I.P. OF ACTUAL DOCUMENTATION ========================
58 ================================================================================
59
60 testing.txt
61 Alfonso Gomez Jordana and Kevin Klues
62
63 This document explains how the AKAROS testing framework works: It contains both
64 straight-to-the-point instructions on where & how to set up a new unit test, to
65 a detailed and thorough explanation of how all the components work together 
66 under the hood to make tests run.
67
68 Part 1: Overview
69 Part 2: Instructions for adding a new test
70 Part 3: How to run tests
71 Part 4: Kernel testing internals
72 Part 5: Userspace testing internals
73 Part 6: Continuous integration server
74
75
76 Revision History:
77 2014-02-26 - Initial version
78
79 Part 1: Overview 
80 =====================================
81
82 The AKAROS testing framework consists on an automated Continuous Integration
83 server that runs several kinds of test whenever a new commit is pushed to the
84 master branch in the repository, and generates reports with the results.
85
86 Some or all of the following things will be tested when a new commit is pushed
87 to the server, depending on the parts of the code that are modified:
88 * Cross-compiler compiles without errors
89 * Kernel compiles without errors
90 * Userspace libs compile without errors
91 * Userspace programs compile without errors
92 * Kernel tests pass without errors (this includes during-boot kernel tests and
93   post-boot kernel ones)
94 * Userspace tests pass without errors
95
96
97
98 Part 2: How to add a test
99 =====================================
100
101 2.1 Determining the type of test to create
102 ------------------------------------------------------------------
103 There are three different types of tests that you can create now in Akaros:
104 * Unit tests in kernel space that run at some specific point during boot.
105 * Unit tests in kernel space that run after boot.
106 * Unit tests in user space that run after boot.
107
108 (These may be extended in the future to include, for example, cross-compiler 
109 unit tests.)
110
111 The reasons for choosing one or another would be: 
112 TODO: Add reasons
113
114 2.2 During-boot kernel unit tests
115 ------------------------------------------------------------------
116 TODO: Write
117
118 2.3 Post-boot kernel unit tests
119 ------------------------------------------------------------------
120         1. Go to akaros/kern/src/tests_pb_kernel.c
121         2. Create a new function for the test. Follow the following pattern:
122                 bool test_[NAME](void)
123                 {
124                         [CODE]
125                         return true;
126                 }
127         3. Inside the [CODE] section, use the following assertion functions:
128                 * KT_ASSERT(boolean-expression): runs the expression and, if it fails, 
129                   it finishes the full unit test with a result of FAILED.
130                 * KT_ASSERT_M(message, boolean-expression): like KT_ASSERT but, in case
131                   of failure, the message gets printed as cause of failure.
132         4. Go to akaros/kern/src/tests.c
133         5. Add inside the pb_kernel_tests array a line like the following:
134                 PB_K_TEST_REG([NAME], true), 
135                 (Optionally, disable temporarily the test by setting the second arg to
136                 false).
137
138                 If you'd like a test to be ran only in a given architecture, surround
139                 it here by #ifdefine CONFIG_[ARCH] ... #endif tags.
140
141 2.4 Userspace unit tests
142 ------------------------------------------------------------------
143 TODO: Write
144
145
146
147 Part 3: How to run a suite of tests
148 =====================================
149
150 By default, tests are not run automatically. Tests have to be enabled somehow 
151 during compilation.
152
153 The easiest way to activate tests is to activate them all by running 
154         make ARCH=XXX deftestconfig
155
156 If you need more specific control about which tests to activate, you can run
157         make ARCH=XXX menuconfig
158 and then select, from the Testing submenu, which tests to run.
159
160 Once you activate the tests you want, you will just need to compile kernel, 
161 userspace tests... and then boot akaros, and they'll run automatically and 
162 output to console :)
163
164 Additionally, every time a new commit is pushed to master in the github repo, 
165 the Continuous Integration server (see part 6) will automatically run relevant
166 tests and report on them.
167
168
169
170 Part 4: Kernel testing internals
171 =====================================
172
173 4.1 During-boot testing
174 ------------------------------------------------------------------
175 TODO: Write
176
177 4.2 Post-boot testing
178 ------------------------------------------------------------------
179 To accomplish post-boot testing, the following files are involved:
180         akaros/kern/src/manager.c
181         akaros/kern/src/tests.c
182         akaros/kern/src/tests_pb_kernel.c
183         akaros/include/test_infrastructure.h
184
185 test_infrastructure.h:
186         This file defines macros used for assertions, as well as data structures,
187         variables and a macro for registering postboot tests.
188
189 tests_pb_kernel.c:
190         This file contains the implementation of all the tests in this category.
191
192 tests.c:
193         This file is where all test names are registered for them to be ran.
194
195 manager.c:
196         In this file, via the function postboot_kernel_tests(), all tests are
197         executed after the kernel has loaded. This function is in charge of printing
198         all test results too.
199
200 4.3 Userspace testing
201 ------------------------------------------------------------------
202 TODO: Write
203
204 4.4 Enabling / disabling tests
205 ------------------------------------------------------------------
206 For enabling and disabling tests, we use CONFIG variables. In particular, the
207 following are the variables used:
208         * CONFIG_POSTBOOT_KERNEL_TESTING
209         * TODO: Fill this in once we have more.
210
211 These variables are defined in the akaros/KConfig file.
212
213 TODO: Speak here about deftestconfig once we have set it up
214
215
216
217 TODO: Write rest of sections