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