diff options
author | Christian Grothoff <christian@grothoff.org> | 2012-12-21 15:09:51 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2012-12-21 15:09:51 +0000 |
commit | 33a5d276ff045e45d05264a0c17a545ecd277548 (patch) | |
tree | 1c4e99feb6b73a77157f94e1a21af87d595dd07f /src/include/gnunet_testing_lib.h | |
parent | 999ab7de8d21c8bbcaac15d8fa9d1e2360f4b567 (diff) | |
download | gnunet-33a5d276ff045e45d05264a0c17a545ecd277548.tar.gz gnunet-33a5d276ff045e45d05264a0c17a545ecd277548.zip |
-renaming testing-new.h to testing.h, bumping library versions
Diffstat (limited to 'src/include/gnunet_testing_lib.h')
-rw-r--r-- | src/include/gnunet_testing_lib.h | 372 |
1 files changed, 372 insertions, 0 deletions
diff --git a/src/include/gnunet_testing_lib.h b/src/include/gnunet_testing_lib.h new file mode 100644 index 000000000..c34166b2e --- /dev/null +++ b/src/include/gnunet_testing_lib.h | |||
@@ -0,0 +1,372 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 3, or (at your | ||
8 | option) any later version. | ||
9 | |||
10 | GNUnet is distributed in the hope that it will be useful, but | ||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file include/gnunet_testing_lib.h | ||
23 | * @brief convenience API for writing testcases for GNUnet; | ||
24 | * can start/stop one or more peers on a system; | ||
25 | * testing is responsible for managing private keys, | ||
26 | * ports and paths; it is a low-level library that | ||
27 | * does not support higher-level functions such as | ||
28 | * P2P connection, topology management or distributed | ||
29 | * testbed maintenance (those are in gnunet_testbed_service.h) | ||
30 | * @author Christian Grothoff | ||
31 | */ | ||
32 | |||
33 | #ifndef GNUNET_TESTING_LIB_H | ||
34 | #define GNUNET_TESTING_LIB_H | ||
35 | |||
36 | #include "gnunet_util_lib.h" | ||
37 | #include "gnunet_statistics_service.h" | ||
38 | |||
39 | #ifdef __cplusplus | ||
40 | extern "C" | ||
41 | { | ||
42 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
43 | } | ||
44 | #endif | ||
45 | #endif | ||
46 | |||
47 | #define GNUNET_TESTING_HOSTKEYFILESIZE 914 | ||
48 | |||
49 | /** | ||
50 | * Handle for a system on which GNUnet peers are executed; | ||
51 | * a system is used for reserving unique paths and ports. | ||
52 | */ | ||
53 | struct GNUNET_TESTING_System; | ||
54 | |||
55 | |||
56 | /** | ||
57 | * Handle for a GNUnet peer controlled by testing. | ||
58 | */ | ||
59 | struct GNUNET_TESTING_Peer; | ||
60 | |||
61 | |||
62 | /** | ||
63 | * Create a system handle. There must only be one system handle per operating | ||
64 | * system. Uses a default range for allowed ports. Ports are still tested for | ||
65 | * availability. | ||
66 | * | ||
67 | * @param testdir only the directory name without any path. This is used for all | ||
68 | * service homes; the directory will be created in a temporary location | ||
69 | * depending on the underlying OS | ||
70 | * @param trusted_ip the ip address which will be set as TRUSTED HOST in all | ||
71 | * service configurations generated to allow control connections from | ||
72 | * this ip. This can either be a single ip address or a network address | ||
73 | * in CIDR notation. | ||
74 | * @param hostname the hostname of the system we are using for testing; NULL for | ||
75 | * localhost | ||
76 | * @return handle to this system, NULL on error | ||
77 | */ | ||
78 | struct GNUNET_TESTING_System * | ||
79 | GNUNET_TESTING_system_create (const char *testdir, | ||
80 | const char *trusted_ip, | ||
81 | const char *hostname); | ||
82 | |||
83 | |||
84 | /** | ||
85 | * Create a system handle. There must only be one system | ||
86 | * handle per operating system. Use this function directly | ||
87 | * if multiple system objects are created for the same host | ||
88 | * (only really useful when testing --- or to make the port | ||
89 | * range configureable). | ||
90 | * | ||
91 | * @param testdir only the directory name without any path. This is used for | ||
92 | * all service homes; the directory will be created in a temporary | ||
93 | * location depending on the underlying OS | ||
94 | * @param trusted_ip the ip address which will be set as TRUSTED HOST in all | ||
95 | * service configurations generated to allow control connections from | ||
96 | * this ip. This can either be a single ip address or a network address | ||
97 | * in CIDR notation. | ||
98 | * @param controller hostname of the controlling host, | ||
99 | * service configurations are modified to allow | ||
100 | * control connections from this host; can be NULL | ||
101 | * @param hostname the hostname of the system we are using for testing; NULL for | ||
102 | * localhost | ||
103 | * @param lowport lowest port number this system is allowed to allocate (inclusive) | ||
104 | * @param highport highest port number this system is allowed to allocate (exclusive) | ||
105 | * @return handle to this system, NULL on error | ||
106 | */ | ||
107 | struct GNUNET_TESTING_System * | ||
108 | GNUNET_TESTING_system_create_with_portrange (const char *testdir, | ||
109 | const char *trusted_ip, | ||
110 | const char *hostname, | ||
111 | uint16_t lowport, | ||
112 | uint16_t highport); | ||
113 | |||
114 | |||
115 | /** | ||
116 | * Free system resources. | ||
117 | * | ||
118 | * @param system system to be freed | ||
119 | * @param remove_paths should the 'testdir' and all subdirectories | ||
120 | * be removed (clean up on shutdown)? | ||
121 | */ | ||
122 | void | ||
123 | GNUNET_TESTING_system_destroy (struct GNUNET_TESTING_System *system, | ||
124 | int remove_paths); | ||
125 | |||
126 | |||
127 | /** | ||
128 | * Testing includes a number of pre-created hostkeys for | ||
129 | * faster peer startup. This function can be used to | ||
130 | * access the n-th key of those pre-created hostkeys; note | ||
131 | * that these keys are ONLY useful for testing and not | ||
132 | * secure as the private keys are part of the public | ||
133 | * GNUnet source code. | ||
134 | * | ||
135 | * This is primarily a helper function used internally | ||
136 | * by 'GNUNET_TESTING_peer_configure'. | ||
137 | * | ||
138 | * @param system the testing system handle | ||
139 | * @param key_number desired pre-created hostkey to obtain | ||
140 | * @param id set to the peer's identity (hash of the public | ||
141 | * key; if NULL, GNUNET_SYSERR is returned immediately | ||
142 | * @return NULL on error (not enough keys) | ||
143 | */ | ||
144 | struct GNUNET_CRYPTO_RsaPrivateKey * | ||
145 | GNUNET_TESTING_hostkey_get (const struct GNUNET_TESTING_System *system, | ||
146 | uint32_t key_number, | ||
147 | struct GNUNET_PeerIdentity *id); | ||
148 | |||
149 | |||
150 | /** | ||
151 | * Reserve a TCP or UDP port for a peer. | ||
152 | * | ||
153 | * @param system system to use for reservation tracking | ||
154 | * @param is_tcp GNUNET_YES for TCP ports, GNUNET_NO for UDP | ||
155 | * @return 0 if no free port was available | ||
156 | */ | ||
157 | uint16_t | ||
158 | GNUNET_TESTING_reserve_port (struct GNUNET_TESTING_System *system, | ||
159 | int is_tcp); | ||
160 | |||
161 | |||
162 | /** | ||
163 | * Release reservation of a TCP or UDP port for a peer | ||
164 | * (used during GNUNET_TESTING_peer_destroy). | ||
165 | * | ||
166 | * @param system system to use for reservation tracking | ||
167 | * @param is_tcp GNUNET_YES for TCP ports, GNUNET_NO for UDP | ||
168 | * @param port reserved port to release | ||
169 | */ | ||
170 | void | ||
171 | GNUNET_TESTING_release_port (struct GNUNET_TESTING_System *system, | ||
172 | int is_tcp, | ||
173 | uint16_t port); | ||
174 | |||
175 | |||
176 | /** | ||
177 | * Create a new configuration using the given configuration as a template; | ||
178 | * ports and paths will be modified to select available ports on the local | ||
179 | * system. The default configuration will be available in PATHS section under | ||
180 | * the option DEFAULTCONFIG after the call. SERVICE_HOME is also set in PATHS | ||
181 | * section to the temporary directory specific to this configuration. If we run | ||
182 | * out of "*port" numbers, return SYSERR. | ||
183 | * | ||
184 | * This is primarily a helper function used internally | ||
185 | * by 'GNUNET_TESTING_peer_configure'. | ||
186 | * | ||
187 | * @param system system to use to coordinate resource usage | ||
188 | * @param cfg template configuration to update | ||
189 | * @return GNUNET_OK on success, GNUNET_SYSERR on error - the configuration will | ||
190 | * be incomplete and should not be used there upon | ||
191 | */ | ||
192 | int | ||
193 | GNUNET_TESTING_configuration_create (struct GNUNET_TESTING_System *system, | ||
194 | struct GNUNET_CONFIGURATION_Handle *cfg); | ||
195 | // FIXME: add dual to 'release' ports again... | ||
196 | |||
197 | |||
198 | /** | ||
199 | * Configure a GNUnet peer. GNUnet must be installed on the local | ||
200 | * system and available in the PATH. | ||
201 | * | ||
202 | * @param system system to use to coordinate resource usage | ||
203 | * @param cfg configuration to use; will be UPDATED (to reflect needed | ||
204 | * changes in port numbers and paths) | ||
205 | * @param key_number number of the hostkey to use for the peer | ||
206 | * @param id identifier for the daemon, will be set, can be NULL | ||
207 | * @param emsg set to freshly allocated error message (set to NULL on success), | ||
208 | * can be NULL | ||
209 | * @return handle to the peer, NULL on error | ||
210 | */ | ||
211 | struct GNUNET_TESTING_Peer * | ||
212 | GNUNET_TESTING_peer_configure (struct GNUNET_TESTING_System *system, | ||
213 | struct GNUNET_CONFIGURATION_Handle *cfg, | ||
214 | uint32_t key_number, | ||
215 | struct GNUNET_PeerIdentity *id, | ||
216 | char **emsg); | ||
217 | |||
218 | |||
219 | /** | ||
220 | * Obtain the peer identity from a peer handle. | ||
221 | * | ||
222 | * @param peer peer handle for which we want the peer's identity | ||
223 | * @param id identifier for the daemon, will be set | ||
224 | */ | ||
225 | void | ||
226 | GNUNET_TESTING_peer_get_identity (const struct GNUNET_TESTING_Peer *peer, | ||
227 | struct GNUNET_PeerIdentity *id); | ||
228 | |||
229 | |||
230 | /** | ||
231 | * Start the peer. | ||
232 | * | ||
233 | * @param peer peer to start | ||
234 | * @return GNUNET_OK on success, GNUNET_SYSERR on error (i.e. peer already running) | ||
235 | */ | ||
236 | int | ||
237 | GNUNET_TESTING_peer_start (struct GNUNET_TESTING_Peer *peer); | ||
238 | |||
239 | |||
240 | /** | ||
241 | * Stop the peer. | ||
242 | * | ||
243 | * @param peer peer to stop | ||
244 | * @return GNUNET_OK on success, GNUNET_SYSERR on error (i.e. peer not running) | ||
245 | */ | ||
246 | int | ||
247 | GNUNET_TESTING_peer_stop (struct GNUNET_TESTING_Peer *peer); | ||
248 | |||
249 | |||
250 | /** | ||
251 | * Destroy the peer. Releases resources locked during peer configuration. | ||
252 | * If the peer is still running, it will be stopped AND a warning will be | ||
253 | * printed (users of the API should stop the peer explicitly first). | ||
254 | * | ||
255 | * @param peer peer to destroy | ||
256 | */ | ||
257 | void | ||
258 | GNUNET_TESTING_peer_destroy (struct GNUNET_TESTING_Peer *peer); | ||
259 | |||
260 | |||
261 | /** | ||
262 | * Sends SIGTERM to the peer's main process | ||
263 | * | ||
264 | * @param peer the handle to the peer | ||
265 | * @return GNUNET_OK if successful; GNUNET_SYSERR if the main process is NULL | ||
266 | * or upon any error while sending SIGTERM | ||
267 | */ | ||
268 | int | ||
269 | GNUNET_TESTING_peer_kill (struct GNUNET_TESTING_Peer *peer); | ||
270 | |||
271 | |||
272 | /** | ||
273 | * Waits for a peer to terminate. The peer's main process will also be destroyed. | ||
274 | * | ||
275 | * @param peer the handle to the peer | ||
276 | * @return GNUNET_OK if successful; GNUNET_SYSERR if the main process is NULL | ||
277 | * or upon any error while waiting | ||
278 | */ | ||
279 | int | ||
280 | GNUNET_TESTING_peer_wait (struct GNUNET_TESTING_Peer *peer); | ||
281 | |||
282 | |||
283 | /** | ||
284 | * Signature of the 'main' function for a (single-peer) testcase that | ||
285 | * is run using 'GNUNET_TESTING_peer_run'. | ||
286 | * | ||
287 | * @param cls closure | ||
288 | * @param cfg configuration of the peer that was started | ||
289 | * @param peer identity of the peer that was created | ||
290 | */ | ||
291 | typedef void (*GNUNET_TESTING_TestMain)(void *cls, | ||
292 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
293 | struct GNUNET_TESTING_Peer *peer); | ||
294 | |||
295 | |||
296 | /** | ||
297 | * Start a single peer and run a test using the testing library. | ||
298 | * Starts a peer using the given configuration and then invokes the | ||
299 | * given callback. This function ALSO initializes the scheduler loop | ||
300 | * and should thus be called directly from "main". The testcase | ||
301 | * should self-terminate by invoking 'GNUNET_SCHEDULER_shutdown'. | ||
302 | * | ||
303 | * @param testdir only the directory name without any path. This is used for | ||
304 | * all service homes; the directory will be created in a temporary | ||
305 | * location depending on the underlying OS | ||
306 | * @param cfgfilename name of the configuration file to use; | ||
307 | * use NULL to only run with defaults | ||
308 | * @param tm main function of the testcase | ||
309 | * @param tm_cls closure for 'tm' | ||
310 | * @return 0 on success, 1 on error | ||
311 | */ | ||
312 | int | ||
313 | GNUNET_TESTING_peer_run (const char *testdir, | ||
314 | const char *cfgfilename, | ||
315 | GNUNET_TESTING_TestMain tm, | ||
316 | void *tm_cls); | ||
317 | |||
318 | |||
319 | /** | ||
320 | * Start a single service (no ARM, except of course if the given | ||
321 | * service name is 'arm') and run a test using the testing library. | ||
322 | * Starts a service using the given configuration and then invokes the | ||
323 | * given callback. This function ALSO initializes the scheduler loop | ||
324 | * and should thus be called directly from "main". The testcase | ||
325 | * should self-terminate by invoking 'GNUNET_SCHEDULER_shutdown'. | ||
326 | * | ||
327 | * This function is useful if the testcase is for a single service | ||
328 | * and if that service doesn't itself depend on other services. | ||
329 | * | ||
330 | * @param testdir only the directory name without any path. This is used for | ||
331 | * all service homes; the directory will be created in a temporary | ||
332 | * location depending on the underlying OS | ||
333 | * @param service_name name of the service to run | ||
334 | * @param cfgfilename name of the configuration file to use; | ||
335 | * use NULL to only run with defaults | ||
336 | * @param tm main function of the testcase | ||
337 | * @param tm_cls closure for 'tm' | ||
338 | * @return 0 on success, 1 on error | ||
339 | */ | ||
340 | int | ||
341 | GNUNET_TESTING_service_run (const char *testdir, | ||
342 | const char *service_name, | ||
343 | const char *cfgfilename, | ||
344 | GNUNET_TESTING_TestMain tm, | ||
345 | void *tm_cls); | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Sometimes we use the binary name to determine which specific | ||
350 | * test to run. In those cases, the string after the last "_" | ||
351 | * in 'argv[0]' specifies a string that determines the configuration | ||
352 | * file or plugin to use. | ||
353 | * | ||
354 | * This function returns the respective substring, taking care | ||
355 | * of issues such as binaries ending in '.exe' on W32. | ||
356 | * | ||
357 | * @param argv0 the name of the binary | ||
358 | * @return string between the last '_' and the '.exe' (or the end of the string), | ||
359 | * NULL if argv0 has no '_' | ||
360 | */ | ||
361 | char * | ||
362 | GNUNET_TESTING_get_testname_from_underscore (const char *argv0); | ||
363 | |||
364 | |||
365 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
366 | { | ||
367 | #endif | ||
368 | #ifdef __cplusplus | ||
369 | } | ||
370 | #endif | ||
371 | |||
372 | #endif | ||