diff options
Diffstat (limited to 'src/include/gnunet_testing_ng_lib.h')
-rw-r--r-- | src/include/gnunet_testing_ng_lib.h | 1147 |
1 files changed, 1147 insertions, 0 deletions
diff --git a/src/include/gnunet_testing_ng_lib.h b/src/include/gnunet_testing_ng_lib.h new file mode 100644 index 000000000..aa997a77c --- /dev/null +++ b/src/include/gnunet_testing_ng_lib.h | |||
@@ -0,0 +1,1147 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | Copyright (C) 2008, 2009, 2012 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @brief API for writing an interpreter to test GNUnet components | ||
23 | * @author Christian Grothoff <christian@grothoff.org> | ||
24 | * @author Marcello Stanisci | ||
25 | * @author t3sserakt | ||
26 | */ | ||
27 | #ifndef GNUNET_TESTING_NG_LIB_H | ||
28 | #define GNUNET_TESTING_NG_LIB_H | ||
29 | |||
30 | #include <gnunet/gnunet_json_lib.h> | ||
31 | #include <microhttpd.h> | ||
32 | |||
33 | |||
34 | /* ********************* Helper functions ********************* */ | ||
35 | |||
36 | /** | ||
37 | * Print failing line number and trigger shutdown. Useful | ||
38 | * quite any time after the command "run" method has been called. | ||
39 | */ | ||
40 | #define GNUNET_TESTING_FAIL(is) \ | ||
41 | do \ | ||
42 | { \ | ||
43 | GNUNET_break (0); \ | ||
44 | GNUNET_TESTING_interpreter_fail (is); \ | ||
45 | return; \ | ||
46 | } while (0) | ||
47 | |||
48 | /** | ||
49 | * Remove files from previous runs | ||
50 | * | ||
51 | * @param config_name configuration file to use+ | ||
52 | */ | ||
53 | void | ||
54 | GNUNET_TESTING_cleanup_files (const char *config_name); | ||
55 | |||
56 | |||
57 | /** | ||
58 | * Remove files from previous runs | ||
59 | * | ||
60 | * @param cls NULL | ||
61 | * @param cfg configuration | ||
62 | * @return #GNUNET_OK on success | ||
63 | */ | ||
64 | int | ||
65 | GNUNET_TESTING_cleanup_files_cfg (void *cls, | ||
66 | const struct | ||
67 | GNUNET_CONFIGURATION_Handle *cfg); | ||
68 | |||
69 | |||
70 | /* ******************* Generic interpreter logic ************ */ | ||
71 | |||
72 | /** | ||
73 | * Global state of the interpreter, used by a command | ||
74 | * to access information about other commands. | ||
75 | */ | ||
76 | struct GNUNET_TESTING_Interpreter | ||
77 | { | ||
78 | |||
79 | /** | ||
80 | * Commands the interpreter will run. | ||
81 | */ | ||
82 | struct GNUNET_TESTING_Command *commands; | ||
83 | |||
84 | /** | ||
85 | * Interpreter task (if one is scheduled). | ||
86 | */ | ||
87 | struct GNUNET_SCHEDULER_Task *task; | ||
88 | |||
89 | /** | ||
90 | * ID of task called whenever we get a SIGCHILD. | ||
91 | * Used for #GNUNET_TESTING_wait_for_sigchld(). | ||
92 | */ | ||
93 | struct GNUNET_SCHEDULER_Task *child_death_task; | ||
94 | |||
95 | /** | ||
96 | * Our configuration. | ||
97 | */ | ||
98 | const struct GNUNET_CONFIGURATION_Handle *cfg; | ||
99 | |||
100 | /** | ||
101 | * Task run on timeout. | ||
102 | */ | ||
103 | struct GNUNET_SCHEDULER_Task *timeout_task; | ||
104 | |||
105 | /** | ||
106 | * Function to call for cleanup at the end. Can be NULL. | ||
107 | */ | ||
108 | GNUNET_SCHEDULER_TaskCallback final_cleanup_cb; | ||
109 | |||
110 | /** | ||
111 | * Closure for #final_cleanup_cb(). | ||
112 | */ | ||
113 | void *final_cleanup_cb_cls; | ||
114 | |||
115 | /** | ||
116 | * Instruction pointer. Tells #interpreter_run() which instruction to run | ||
117 | * next. Need (signed) int because it gets -1 when rewinding the | ||
118 | * interpreter to the first CMD. | ||
119 | */ | ||
120 | int ip; | ||
121 | |||
122 | /** | ||
123 | * Result of the testcases, #GNUNET_OK on success | ||
124 | */ | ||
125 | int result; | ||
126 | |||
127 | /** | ||
128 | * Handle to the auditor. NULL unless specifically initialized | ||
129 | * as part of #GNUNET_TESTING_auditor_setup(). | ||
130 | */ | ||
131 | struct AUDITOR_Handle *auditor; | ||
132 | |||
133 | /** | ||
134 | * Handle to exchange process; some commands need it | ||
135 | * to send signals. E.g. to trigger the key state reload. | ||
136 | */ | ||
137 | struct GNUNET_OS_Process *exchanged; | ||
138 | |||
139 | /** | ||
140 | * URL of the auditor (as per configuration). | ||
141 | */ | ||
142 | char *auditor_url; | ||
143 | |||
144 | /** | ||
145 | * URL of the exchange (as per configuration). | ||
146 | */ | ||
147 | char *exchange_url; | ||
148 | |||
149 | /** | ||
150 | * Is the interpreter running (#GNUNET_YES) or waiting | ||
151 | * for /keys (#GNUNET_NO)? | ||
152 | */ | ||
153 | int working; | ||
154 | |||
155 | /** | ||
156 | * Is the auditor running (#GNUNET_YES) or waiting | ||
157 | * for /version (#GNUNET_NO)? | ||
158 | */ | ||
159 | int auditor_working; | ||
160 | |||
161 | /** | ||
162 | * How often have we gotten a /keys response so far? | ||
163 | */ | ||
164 | unsigned int key_generation; | ||
165 | |||
166 | /** | ||
167 | * Exchange keys from last download. | ||
168 | */ | ||
169 | const struct EXCHANGE_Keys *keys; | ||
170 | |||
171 | }; | ||
172 | |||
173 | |||
174 | /** | ||
175 | * A command to be run by the interpreter. | ||
176 | */ | ||
177 | struct GNUNET_TESTING_Command | ||
178 | { | ||
179 | |||
180 | /** | ||
181 | * Closure for all commands with command-specific context | ||
182 | * information. | ||
183 | */ | ||
184 | void *cls; | ||
185 | |||
186 | /** | ||
187 | * Label for the command. | ||
188 | */ | ||
189 | const char *label; | ||
190 | |||
191 | /** | ||
192 | * Runs the command. Note that upon return, the interpreter | ||
193 | * will not automatically run the next command, as the command | ||
194 | * may continue asynchronously in other scheduler tasks. Thus, | ||
195 | * the command must ensure to eventually call | ||
196 | * #GNUNET_TESTING_interpreter_next() or | ||
197 | * #GNUNET_TESTING_interpreter_fail(). | ||
198 | * | ||
199 | * @param cls closure | ||
200 | * @param cmd command being run | ||
201 | * @param i interpreter state | ||
202 | */ | ||
203 | void | ||
204 | (*run)(void *cls, | ||
205 | const struct GNUNET_TESTING_Command *cmd, | ||
206 | struct GNUNET_TESTING_Interpreter *i); | ||
207 | |||
208 | |||
209 | /** | ||
210 | * Clean up after the command. Run during forced termination | ||
211 | * (CTRL-C) or test failure or test success. | ||
212 | * | ||
213 | * @param cls closure | ||
214 | * @param cmd command being cleaned up | ||
215 | */ | ||
216 | void | ||
217 | (*cleanup)(void *cls, | ||
218 | const struct GNUNET_TESTING_Command *cmd); | ||
219 | |||
220 | /** | ||
221 | * Extract information from a command that is useful for other | ||
222 | * commands. | ||
223 | * | ||
224 | * @param cls closure | ||
225 | * @param[out] ret result (could be anything) | ||
226 | * @param trait name of the trait | ||
227 | * @param index index number of the object to extract. | ||
228 | * @return #GNUNET_OK on success | ||
229 | */ | ||
230 | int | ||
231 | (*traits)(void *cls, | ||
232 | const void **ret, | ||
233 | const char *trait, | ||
234 | unsigned int index); | ||
235 | |||
236 | /** | ||
237 | * When did the execution of this command start? | ||
238 | */ | ||
239 | struct GNUNET_TIME_Absolute start_time; | ||
240 | |||
241 | /** | ||
242 | * When did the execution of this command finish? | ||
243 | */ | ||
244 | struct GNUNET_TIME_Absolute finish_time; | ||
245 | |||
246 | /** | ||
247 | * When did we start the last request of this command? | ||
248 | * Delta to @e finish_time gives the latency for the last | ||
249 | * successful request. | ||
250 | */ | ||
251 | struct GNUNET_TIME_Absolute last_req_time; | ||
252 | |||
253 | /** | ||
254 | * How often did we try to execute this command? (In case | ||
255 | * it is a request that is repated.) | ||
256 | */ | ||
257 | unsigned int num_tries; | ||
258 | |||
259 | }; | ||
260 | |||
261 | |||
262 | /** | ||
263 | * Lookup command by label. | ||
264 | * | ||
265 | * @param is interpreter state. | ||
266 | * @param label label of the command to lookup. | ||
267 | * @return the command, if it is found, or NULL. | ||
268 | */ | ||
269 | const struct GNUNET_TESTING_Command * | ||
270 | GNUNET_TESTING_interpreter_lookup_command (struct | ||
271 | GNUNET_TESTING_Interpreter *is, | ||
272 | const char *label); | ||
273 | |||
274 | |||
275 | /** | ||
276 | * Obtain label of the command being now run. | ||
277 | * | ||
278 | * @param is interpreter state. | ||
279 | * @return the label. | ||
280 | */ | ||
281 | const char * | ||
282 | GNUNET_TESTING_interpreter_get_current_label ( | ||
283 | struct GNUNET_TESTING_Interpreter *is); | ||
284 | |||
285 | /** | ||
286 | * Current command is done, run the next one. | ||
287 | * | ||
288 | * @param is interpreter state. | ||
289 | */ | ||
290 | void | ||
291 | GNUNET_TESTING_interpreter_next (struct GNUNET_TESTING_Interpreter *is); | ||
292 | |||
293 | /** | ||
294 | * Current command failed, clean up and fail the test case. | ||
295 | * | ||
296 | * @param is interpreter state. | ||
297 | */ | ||
298 | void | ||
299 | GNUNET_TESTING_interpreter_fail (struct GNUNET_TESTING_Interpreter *is); | ||
300 | |||
301 | /** | ||
302 | * Create command array terminator. | ||
303 | * | ||
304 | * @return a end-command. | ||
305 | */ | ||
306 | struct GNUNET_TESTING_Command | ||
307 | GNUNET_TESTING_cmd_end (void); | ||
308 | |||
309 | |||
310 | /** | ||
311 | * Make the instruction pointer point to @a target_label | ||
312 | * only if @a counter is greater than zero. | ||
313 | * | ||
314 | * @param label command label | ||
315 | * @param target_label label of the new instruction pointer's destination after the jump; | ||
316 | * must be before the current instruction | ||
317 | * @param counter counts how many times the rewinding is to happen. | ||
318 | */ | ||
319 | struct GNUNET_TESTING_Command | ||
320 | GNUNET_TESTING_cmd_rewind_ip (const char *label, | ||
321 | const char *target_label, | ||
322 | unsigned int counter); | ||
323 | |||
324 | |||
325 | /** | ||
326 | * Wait until we receive SIGCHLD signal. | ||
327 | * Then obtain the process trait of the current | ||
328 | * command, wait on the the zombie and continue | ||
329 | * with the next command. | ||
330 | * | ||
331 | * @param is interpreter state. | ||
332 | */ | ||
333 | void | ||
334 | GNUNET_TESTING_wait_for_sigchld (struct GNUNET_TESTING_Interpreter *is); | ||
335 | |||
336 | |||
337 | /** | ||
338 | * Schedule the first CMD in the CMDs array. | ||
339 | * | ||
340 | * @param is interpreter state. | ||
341 | * @param commands array of all the commands to execute. | ||
342 | */ | ||
343 | void | ||
344 | GNUNET_TESTING_run (struct GNUNET_TESTING_Interpreter *is, | ||
345 | struct GNUNET_TESTING_Command *commands); | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Run the testsuite. Note, CMDs are copied into | ||
350 | * the interpreter state because they are _usually_ | ||
351 | * defined into the "run" method that returns after | ||
352 | * having scheduled the test interpreter. | ||
353 | * | ||
354 | * @param is the interpreter state | ||
355 | * @param commands the list of command to execute | ||
356 | * @param timeout how long to wait | ||
357 | */ | ||
358 | void | ||
359 | GNUNET_TESTING_run2 (struct GNUNET_TESTING_Interpreter *is, | ||
360 | struct GNUNET_TESTING_Command *commands, | ||
361 | struct GNUNET_TIME_Relative timeout); | ||
362 | |||
363 | /** | ||
364 | * The function that contains the array of all the CMDs to run, | ||
365 | * which is then on charge to call some fashion of | ||
366 | * GNUNET_TESTING_run*. In all the test cases, this function is | ||
367 | * always the GNUnet-ish "run" method. | ||
368 | * | ||
369 | * @param cls closure. | ||
370 | * @param is interpreter state. | ||
371 | */ | ||
372 | typedef void | ||
373 | (*GNUNET_TESTING_Main)(void *cls, | ||
374 | struct GNUNET_TESTING_Interpreter *is); | ||
375 | |||
376 | |||
377 | /** | ||
378 | * Install signal handlers plus schedules the main wrapper | ||
379 | * around the "run" method. | ||
380 | * | ||
381 | * @param main_cb the "run" method which coontains all the | ||
382 | * commands. | ||
383 | * @param main_cb_cls a closure for "run", typically NULL. | ||
384 | * @param cfg configuration to use | ||
385 | * @param exchanged exchange process handle: will be put in the | ||
386 | * state as some commands - e.g. revoke - need to send | ||
387 | * signal to it, for example to let it know to reload the | ||
388 | * key state.. if NULL, the interpreter will run without | ||
389 | * trying to connect to the exchange first. | ||
390 | * @param exchange_connect GNUNET_YES if the test should connect | ||
391 | * to the exchange, GNUNET_NO otherwise | ||
392 | * @return #GNUNET_OK if all is okay, != #GNUNET_OK otherwise. | ||
393 | * non-GNUNET_OK codes are #GNUNET_SYSERR most of the | ||
394 | * times. | ||
395 | */ | ||
396 | int | ||
397 | GNUNET_TESTING_setup (GNUNET_TESTING_Main main_cb, | ||
398 | void *main_cb_cls, | ||
399 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
400 | struct GNUNET_OS_Process *exchanged, | ||
401 | int exchange_connect); | ||
402 | |||
403 | |||
404 | /** | ||
405 | * Install signal handlers plus schedules the main wrapper | ||
406 | * around the "run" method. | ||
407 | * | ||
408 | * @param main_cb the "run" method which contains all the | ||
409 | * commands. | ||
410 | * @param main_cb_cls a closure for "run", typically NULL. | ||
411 | * @param config_filename configuration filename. | ||
412 | * @return #GNUNET_OK if all is okay, != #GNUNET_OK otherwise. | ||
413 | * non-GNUNET_OK codes are #GNUNET_SYSERR most of the | ||
414 | * times. | ||
415 | */ | ||
416 | int | ||
417 | GNUNET_TESTING_auditor_setup (GNUNET_TESTING_Main main_cb, | ||
418 | void *main_cb_cls, | ||
419 | const char *config_filename); | ||
420 | |||
421 | |||
422 | /** | ||
423 | * Closure for #GNUNET_TESTING_setup_with_exchange_cfg(). | ||
424 | */ | ||
425 | struct GNUNET_TESTING_SetupContext | ||
426 | { | ||
427 | /** | ||
428 | * Main function of the test to run. | ||
429 | */ | ||
430 | GNUNET_TESTING_Main main_cb; | ||
431 | |||
432 | /** | ||
433 | * Closure for @e main_cb. | ||
434 | */ | ||
435 | void *main_cb_cls; | ||
436 | |||
437 | /** | ||
438 | * Name of the configuration file. | ||
439 | */ | ||
440 | const char *config_filename; | ||
441 | }; | ||
442 | |||
443 | |||
444 | /** | ||
445 | * Initialize scheduler loop and curl context for the test case | ||
446 | * including starting and stopping the exchange using the given | ||
447 | * configuration file. | ||
448 | * | ||
449 | * @param cls must be a `struct GNUNET_TESTING_SetupContext *` | ||
450 | * @param cfg configuration to use. | ||
451 | * @return #GNUNET_OK if no errors occurred. | ||
452 | */ | ||
453 | int | ||
454 | GNUNET_TESTING_setup_with_exchange_cfg ( | ||
455 | void *cls, | ||
456 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
457 | |||
458 | |||
459 | /** | ||
460 | * Initialize scheduler loop and curl context for the test case | ||
461 | * including starting and stopping the exchange using the given | ||
462 | * configuration file. | ||
463 | * | ||
464 | * @param main_cb main method. | ||
465 | * @param main_cb_cls main method closure. | ||
466 | * @param config_file configuration file name. Is is used | ||
467 | * by both this function and the exchange itself. In the | ||
468 | * first case it gives out the exchange port number and | ||
469 | * the exchange base URL so as to check whether the port | ||
470 | * is available and the exchange responds when requested | ||
471 | * at its base URL. | ||
472 | * @return #GNUNET_OK if no errors occurred. | ||
473 | */ | ||
474 | int | ||
475 | GNUNET_TESTING_setup_with_exchange (GNUNET_TESTING_Main main_cb, | ||
476 | void *main_cb_cls, | ||
477 | const char *config_file); | ||
478 | |||
479 | |||
480 | /** | ||
481 | * Initialize scheduler loop and curl context for the test case | ||
482 | * including starting and stopping the auditor and exchange using | ||
483 | * the given configuration file. | ||
484 | * | ||
485 | * @param cls must be a `struct GNUNET_TESTING_SetupContext *` | ||
486 | * @param cfg configuration to use. | ||
487 | * @return #GNUNET_OK if no errors occurred. | ||
488 | */ | ||
489 | int | ||
490 | GNUNET_TESTING_setup_with_auditor_and_exchange_cfg ( | ||
491 | void *cls, | ||
492 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
493 | |||
494 | |||
495 | /** | ||
496 | * Initialize scheduler loop and curl context for the test case | ||
497 | * including starting and stopping the auditor and exchange using | ||
498 | * the given configuration file. | ||
499 | * | ||
500 | * @param main_cb main method. | ||
501 | * @param main_cb_cls main method closure. | ||
502 | * @param config_file configuration file name. Is is used | ||
503 | * by both this function and the exchange itself. In the | ||
504 | * first case it gives out the exchange port number and | ||
505 | * the exchange base URL so as to check whether the port | ||
506 | * is available and the exchange responds when requested | ||
507 | * at its base URL. | ||
508 | * @return #GNUNET_OK if no errors occurred. | ||
509 | */ | ||
510 | int | ||
511 | GNUNET_TESTING_setup_with_auditor_and_exchange (GNUNET_TESTING_Main main_cb, | ||
512 | void *main_cb_cls, | ||
513 | const char *config_file); | ||
514 | |||
515 | /** | ||
516 | * Look for substring in a programs' name. | ||
517 | * | ||
518 | * @param prog program's name to look into | ||
519 | * @param marker chunk to find in @a prog | ||
520 | */ | ||
521 | int | ||
522 | GNUNET_TESTING_has_in_name (const char *prog, | ||
523 | const char *marker); | ||
524 | |||
525 | |||
526 | /* ************** Specific interpreter commands ************ */ | ||
527 | |||
528 | /** | ||
529 | * Make the "exec-auditor" CMD. | ||
530 | * | ||
531 | * @param label command label. | ||
532 | * @param config_filename configuration filename. | ||
533 | * @return the command. | ||
534 | */ | ||
535 | struct GNUNET_TESTING_Command | ||
536 | GNUNET_TESTING_cmd_exec_auditor (const char *label, | ||
537 | const char *config_filename); | ||
538 | |||
539 | |||
540 | /** | ||
541 | * Make a "wirewatch" CMD. | ||
542 | * | ||
543 | * @param label command label. | ||
544 | * @param config_filename configuration filename. | ||
545 | * | ||
546 | * @return the command. | ||
547 | */ | ||
548 | struct GNUNET_TESTING_Command | ||
549 | GNUNET_TESTING_cmd_exec_wirewatch (const char *label, | ||
550 | const char *config_filename); | ||
551 | |||
552 | /** | ||
553 | * Make a "aggregator" CMD. | ||
554 | * | ||
555 | * @param label command label. | ||
556 | * @param config_filename configuration file for the | ||
557 | * aggregator to use. | ||
558 | * @return the command. | ||
559 | */ | ||
560 | struct GNUNET_TESTING_Command | ||
561 | GNUNET_TESTING_cmd_exec_aggregator (const char *label, | ||
562 | const char *config_filename); | ||
563 | |||
564 | |||
565 | /** | ||
566 | * Make a "closer" CMD. Note that it is right now not supported to run the | ||
567 | * closer to close multiple reserves in combination with a subsequent reserve | ||
568 | * status call, as we cannot generate the traits necessary for multiple closed | ||
569 | * reserves. You can work around this by using multiple closer commands, one | ||
570 | * per reserve that is being closed. | ||
571 | * | ||
572 | * @param label command label. | ||
573 | * @param config_filename configuration file for the | ||
574 | * closer to use. | ||
575 | * @param expected_amount amount we expect to see wired from a @a expected_reserve_ref | ||
576 | * @param expected_fee closing fee we expect to see | ||
577 | * @param expected_reserve_ref reference to a reserve we expect the closer to drain; | ||
578 | * NULL if we do not expect the closer to do anything | ||
579 | * @return the command. | ||
580 | */ | ||
581 | struct GNUNET_TESTING_Command | ||
582 | GNUNET_TESTING_cmd_exec_closer (const char *label, | ||
583 | const char *config_filename, | ||
584 | const char *expected_amount, | ||
585 | const char *expected_fee, | ||
586 | const char *expected_reserve_ref); | ||
587 | |||
588 | |||
589 | /** | ||
590 | * Make a "transfer" CMD. | ||
591 | * | ||
592 | * @param label command label. | ||
593 | * @param config_filename configuration file for the | ||
594 | * transfer to use. | ||
595 | * @return the command. | ||
596 | */ | ||
597 | struct GNUNET_TESTING_Command | ||
598 | GNUNET_TESTING_cmd_exec_transfer (const char *label, | ||
599 | const char *config_filename); | ||
600 | |||
601 | |||
602 | /** | ||
603 | * Create a withdraw command, letting the caller specify | ||
604 | * the desired amount as string. | ||
605 | * | ||
606 | * @param label command label. | ||
607 | * @param reserve_reference command providing us with a reserve to withdraw from | ||
608 | * @param amount how much we withdraw. | ||
609 | * @param expected_response_code which HTTP response code | ||
610 | * we expect from the exchange. | ||
611 | * @return the withdraw command to be executed by the interpreter. | ||
612 | */ | ||
613 | struct GNUNET_TESTING_Command | ||
614 | GNUNET_TESTING_cmd_withdraw_amount (const char *label, | ||
615 | const char *reserve_reference, | ||
616 | const char *amount, | ||
617 | unsigned int expected_response_code); | ||
618 | |||
619 | /** | ||
620 | * Create a "wire" command. | ||
621 | * | ||
622 | * @param label the command label. | ||
623 | * @param expected_method which wire-transfer method is expected | ||
624 | * to be offered by the exchange. | ||
625 | * @param expected_fee the fee the exchange should charge. | ||
626 | * @param expected_response_code the HTTP response the exchange | ||
627 | * should return. | ||
628 | * @return the command. | ||
629 | */ | ||
630 | struct GNUNET_TESTING_Command | ||
631 | GNUNET_TESTING_cmd_wire (const char *label, | ||
632 | const char *expected_method, | ||
633 | const char *expected_fee, | ||
634 | unsigned int expected_response_code); | ||
635 | |||
636 | |||
637 | /** | ||
638 | * Create a GET "reserves" command. | ||
639 | * | ||
640 | * @param label the command label. | ||
641 | * @param reserve_reference reference to the reserve to check. | ||
642 | * @param expected_balance expected balance for the reserve. | ||
643 | * @param expected_response_code expected HTTP response code. | ||
644 | * @return the command. | ||
645 | */ | ||
646 | struct GNUNET_TESTING_Command | ||
647 | GNUNET_TESTING_cmd_status (const char *label, | ||
648 | const char *reserve_reference, | ||
649 | const char *expected_balance, | ||
650 | unsigned int expected_response_code); | ||
651 | |||
652 | /** | ||
653 | * Index of the deposit value trait of a deposit command. | ||
654 | */ | ||
655 | #define GNUNET_TESTING_CMD_DEPOSIT_TRAIT_IDX_DEPOSIT_VALUE 0 | ||
656 | |||
657 | /** | ||
658 | * Index of the deposit fee trait of a deposit command. | ||
659 | */ | ||
660 | #define GNUNET_TESTING_CMD_DEPOSIT_TRAIT_IDX_DEPOSIT_FEE 1 | ||
661 | |||
662 | /** | ||
663 | * Create a "signal" CMD. | ||
664 | * | ||
665 | * @param label command label. | ||
666 | * @param process handle to the process to signal. | ||
667 | * @param signal signal to send. | ||
668 | * | ||
669 | * @return the command. | ||
670 | */ | ||
671 | struct GNUNET_TESTING_Command | ||
672 | GNUNET_TESTING_cmd_signal (const char *label, | ||
673 | struct GNUNET_OS_Process *process, | ||
674 | int signal); | ||
675 | |||
676 | |||
677 | /** | ||
678 | * Sleep for @a duration_s seconds. | ||
679 | * | ||
680 | * @param label command label. | ||
681 | * @param duration_s number of seconds to sleep | ||
682 | * @return the command. | ||
683 | */ | ||
684 | struct GNUNET_TESTING_Command | ||
685 | GNUNET_TESTING_cmd_sleep (const char *label, | ||
686 | unsigned int duration_s); | ||
687 | |||
688 | /** | ||
689 | * Create a "batch" command. Such command takes a | ||
690 | * end_CMD-terminated array of CMDs and executed them. | ||
691 | * Once it hits the end CMD, it passes the control | ||
692 | * to the next top-level CMD, regardless of it being | ||
693 | * another batch or ordinary CMD. | ||
694 | * | ||
695 | * @param label the command label. | ||
696 | * @param batch array of CMDs to execute. | ||
697 | * | ||
698 | * @return the command. | ||
699 | */ | ||
700 | struct GNUNET_TESTING_Command | ||
701 | GNUNET_TESTING_cmd_batch (const char *label, | ||
702 | struct GNUNET_TESTING_Command *batch); | ||
703 | |||
704 | |||
705 | /** | ||
706 | * Test if this command is a batch command. | ||
707 | * | ||
708 | * @return false if not, true if it is a batch command | ||
709 | */ | ||
710 | int | ||
711 | GNUNET_TESTING_cmd_is_batch (const struct GNUNET_TESTING_Command *cmd); | ||
712 | |||
713 | /** | ||
714 | * Advance internal pointer to next command. | ||
715 | * | ||
716 | * @param is interpreter state. | ||
717 | */ | ||
718 | void | ||
719 | GNUNET_TESTING_cmd_batch_next (struct GNUNET_TESTING_Interpreter *is); | ||
720 | |||
721 | /** | ||
722 | * Obtain what command the batch is at. | ||
723 | * | ||
724 | * @return cmd current batch command | ||
725 | */ | ||
726 | struct GNUNET_TESTING_Command * | ||
727 | GNUNET_TESTING_cmd_batch_get_current (const struct GNUNET_TESTING_Command *cmd); | ||
728 | |||
729 | |||
730 | /** | ||
731 | * Set what command the batch should be at. | ||
732 | * | ||
733 | * @param cmd current batch command | ||
734 | * @param new_ip where to move the IP | ||
735 | */ | ||
736 | void | ||
737 | GNUNET_TESTING_cmd_batch_set_current (const struct GNUNET_TESTING_Command *cmd, | ||
738 | unsigned int new_ip); | ||
739 | |||
740 | |||
741 | /** | ||
742 | * Performance counter. | ||
743 | */ | ||
744 | struct GNUNET_TESTING_Timer | ||
745 | { | ||
746 | /** | ||
747 | * For which type of commands. | ||
748 | */ | ||
749 | const char *prefix; | ||
750 | |||
751 | /** | ||
752 | * Total time spend in all commands of this type. | ||
753 | */ | ||
754 | struct GNUNET_TIME_Relative total_duration; | ||
755 | |||
756 | /** | ||
757 | * Total time spend waiting for the *successful* exeuction | ||
758 | * in all commands of this type. | ||
759 | */ | ||
760 | struct GNUNET_TIME_Relative success_latency; | ||
761 | |||
762 | /** | ||
763 | * Number of commands summed up. | ||
764 | */ | ||
765 | unsigned int num_commands; | ||
766 | |||
767 | /** | ||
768 | * Number of retries summed up. | ||
769 | */ | ||
770 | unsigned int num_retries; | ||
771 | }; | ||
772 | |||
773 | |||
774 | /** | ||
775 | * Obtain performance data from the interpreter. | ||
776 | * | ||
777 | * @param timers what commands (by label) to obtain runtimes for | ||
778 | * @return the command | ||
779 | */ | ||
780 | struct GNUNET_TESTING_Command | ||
781 | GNUNET_TESTING_cmd_stat (struct GNUNET_TESTING_Timer *timers); | ||
782 | |||
783 | |||
784 | /* *** Generic trait logic for implementing traits ********* */ | ||
785 | |||
786 | /** | ||
787 | * A trait. | ||
788 | */ | ||
789 | struct GNUNET_TESTING_Trait | ||
790 | { | ||
791 | /** | ||
792 | * Index number associated with the trait. This gives the | ||
793 | * possibility to have _multiple_ traits on offer under the | ||
794 | * same name. | ||
795 | */ | ||
796 | unsigned int index; | ||
797 | |||
798 | /** | ||
799 | * Trait type, for example "reserve-pub" or "coin-priv". | ||
800 | */ | ||
801 | const char *trait_name; | ||
802 | |||
803 | /** | ||
804 | * Pointer to the piece of data to offer. | ||
805 | */ | ||
806 | const void *ptr; | ||
807 | }; | ||
808 | |||
809 | |||
810 | /** | ||
811 | * "end" trait. Because traits are offered into arrays, | ||
812 | * this type of trait is used to mark the end of such arrays; | ||
813 | * useful when iterating over those. | ||
814 | */ | ||
815 | struct GNUNET_TESTING_Trait | ||
816 | GNUNET_TESTING_trait_end (void); | ||
817 | |||
818 | |||
819 | /** | ||
820 | * Extract a trait. | ||
821 | * | ||
822 | * @param traits the array of all the traits. | ||
823 | * @param[out] ret where to store the result. | ||
824 | * @param trait type of the trait to extract. | ||
825 | * @param index index number of the trait to extract. | ||
826 | * @return #GNUNET_OK when the trait is found. | ||
827 | */ | ||
828 | int | ||
829 | GNUNET_TESTING_get_trait (const struct GNUNET_TESTING_Trait *traits, | ||
830 | const void **ret, | ||
831 | const char *trait, | ||
832 | unsigned int index); | ||
833 | |||
834 | |||
835 | /* ****** Specific traits supported by this component ******* */ | ||
836 | |||
837 | /** | ||
838 | * Obtain location where a command stores a pointer to a process. | ||
839 | * | ||
840 | * @param cmd command to extract trait from. | ||
841 | * @param index which process to pick if @a cmd | ||
842 | * has multiple on offer. | ||
843 | * @param[out] processp set to the address of the pointer to the | ||
844 | * process. | ||
845 | * @return #GNUNET_OK on success. | ||
846 | */ | ||
847 | int | ||
848 | GNUNET_TESTING_get_trait_process (const struct GNUNET_TESTING_Command *cmd, | ||
849 | unsigned int index, | ||
850 | struct GNUNET_OS_Process ***processp); | ||
851 | |||
852 | |||
853 | /** | ||
854 | * Offer location where a command stores a pointer to a process. | ||
855 | * | ||
856 | * @param index offered location index number, in case there are | ||
857 | * multiple on offer. | ||
858 | * @param processp process location to offer. | ||
859 | * @return the trait. | ||
860 | */ | ||
861 | struct GNUNET_TESTING_Trait | ||
862 | GNUNET_TESTING_make_trait_process (unsigned int index, | ||
863 | struct GNUNET_OS_Process **processp); | ||
864 | |||
865 | /** | ||
866 | * Offer number trait, 32-bit version. | ||
867 | * | ||
868 | * @param index the number's index number. | ||
869 | * @param n number to offer. | ||
870 | */ | ||
871 | struct GNUNET_TESTING_Trait | ||
872 | GNUNET_TESTING_make_trait_uint32 (unsigned int index, | ||
873 | const uint32_t *n); | ||
874 | |||
875 | |||
876 | /** | ||
877 | * Obtain a "number" value from @a cmd, 32-bit version. | ||
878 | * | ||
879 | * @param cmd command to extract the number from. | ||
880 | * @param index the number's index number. | ||
881 | * @param[out] n set to the number coming from @a cmd. | ||
882 | * @return #GNUNET_OK on success. | ||
883 | */ | ||
884 | int | ||
885 | GNUNET_TESTING_get_trait_uint32 (const struct GNUNET_TESTING_Command *cmd, | ||
886 | unsigned int index, | ||
887 | const uint32_t **n); | ||
888 | |||
889 | |||
890 | /** | ||
891 | * Offer number trait, 64-bit version. | ||
892 | * | ||
893 | * @param index the number's index number. | ||
894 | * @param n number to offer. | ||
895 | */ | ||
896 | struct GNUNET_TESTING_Trait | ||
897 | GNUNET_TESTING_make_trait_uint64 (unsigned int index, | ||
898 | const uint64_t *n); | ||
899 | |||
900 | |||
901 | /** | ||
902 | * Obtain a "number" value from @a cmd, 64-bit version. | ||
903 | * | ||
904 | * @param cmd command to extract the number from. | ||
905 | * @param index the number's index number. | ||
906 | * @param[out] n set to the number coming from @a cmd. | ||
907 | * @return #GNUNET_OK on success. | ||
908 | */ | ||
909 | int | ||
910 | GNUNET_TESTING_get_trait_uint64 (const struct GNUNET_TESTING_Command *cmd, | ||
911 | unsigned int index, | ||
912 | const uint64_t **n); | ||
913 | |||
914 | |||
915 | /** | ||
916 | * Offer number trait, 64-bit signed version. | ||
917 | * | ||
918 | * @param index the number's index number. | ||
919 | * @param n number to offer. | ||
920 | */ | ||
921 | struct GNUNET_TESTING_Trait | ||
922 | GNUNET_TESTING_make_trait_int64 (unsigned int index, | ||
923 | const int64_t *n); | ||
924 | |||
925 | |||
926 | /** | ||
927 | * Obtain a "number" value from @a cmd, 64-bit signed version. | ||
928 | * | ||
929 | * @param cmd command to extract the number from. | ||
930 | * @param index the number's index number. | ||
931 | * @param[out] n set to the number coming from @a cmd. | ||
932 | * @return #GNUNET_OK on success. | ||
933 | */ | ||
934 | int | ||
935 | GNUNET_TESTING_get_trait_int64 (const struct GNUNET_TESTING_Command *cmd, | ||
936 | unsigned int index, | ||
937 | const int64_t **n); | ||
938 | |||
939 | |||
940 | /** | ||
941 | * Offer a number. | ||
942 | * | ||
943 | * @param index the number's index number. | ||
944 | * @param n the number to offer. | ||
945 | * @return #GNUNET_OK on success. | ||
946 | */ | ||
947 | struct GNUNET_TESTING_Trait | ||
948 | GNUNET_TESTING_make_trait_uint (unsigned int index, | ||
949 | const unsigned int *i); | ||
950 | |||
951 | |||
952 | /** | ||
953 | * Obtain a number from @a cmd. | ||
954 | * | ||
955 | * @param cmd command to extract the number from. | ||
956 | * @param index the number's index number. | ||
957 | * @param[out] n set to the number coming from @a cmd. | ||
958 | * @return #GNUNET_OK on success. | ||
959 | */ | ||
960 | int | ||
961 | GNUNET_TESTING_get_trait_uint (const struct GNUNET_TESTING_Command *cmd, | ||
962 | unsigned int index, | ||
963 | const unsigned int **n); | ||
964 | |||
965 | /** | ||
966 | * Obtain a string from @a cmd. | ||
967 | * | ||
968 | * @param cmd command to extract the subject from. | ||
969 | * @param index index number associated with the transfer | ||
970 | * subject to offer. | ||
971 | * @param[out] s where to write the offered | ||
972 | * string. | ||
973 | * @return #GNUNET_OK on success. | ||
974 | */ | ||
975 | int | ||
976 | GNUNET_TESTING_get_trait_string ( | ||
977 | const struct GNUNET_TESTING_Command *cmd, | ||
978 | unsigned int index, | ||
979 | const char **s); | ||
980 | |||
981 | |||
982 | /** | ||
983 | * Offer string subject. | ||
984 | * | ||
985 | * @param index index number associated with the transfer | ||
986 | * subject being offered. | ||
987 | * @param s string to offer. | ||
988 | * @return the trait. | ||
989 | */ | ||
990 | struct GNUNET_TESTING_Trait | ||
991 | GNUNET_TESTING_make_trait_string (unsigned int index, | ||
992 | const char *s); | ||
993 | |||
994 | /** | ||
995 | * Offer a command in a trait. | ||
996 | * | ||
997 | * @param index always zero. Commands offering this | ||
998 | * kind of traits do not need this index. For | ||
999 | * example, a "meta" CMD returns always the | ||
1000 | * CMD currently being executed. | ||
1001 | * @param cmd wire details to offer. | ||
1002 | * | ||
1003 | * @return the trait. | ||
1004 | */ | ||
1005 | struct GNUNET_TESTING_Trait | ||
1006 | GNUNET_TESTING_make_trait_cmd (unsigned int index, | ||
1007 | const struct GNUNET_TESTING_Command *cmd); | ||
1008 | |||
1009 | |||
1010 | /** | ||
1011 | * Obtain a command from @a cmd. | ||
1012 | * | ||
1013 | * @param cmd command to extract the command from. | ||
1014 | * @param index always zero. Commands offering this | ||
1015 | * kind of traits do not need this index. For | ||
1016 | * example, a "meta" CMD returns always the | ||
1017 | * CMD currently being executed. | ||
1018 | * @param[out] _cmd where to write the wire details. | ||
1019 | * @return #GNUNET_OK on success. | ||
1020 | */ | ||
1021 | int | ||
1022 | GNUNET_TESTING_get_trait_cmd (const struct GNUNET_TESTING_Command *cmd, | ||
1023 | unsigned int index, | ||
1024 | struct GNUNET_TESTING_Command **_cmd); | ||
1025 | |||
1026 | |||
1027 | /** | ||
1028 | * Obtain a uuid from @a cmd. | ||
1029 | * | ||
1030 | * @param cmd command to extract the uuid from. | ||
1031 | * @param index which amount to pick if @a cmd has multiple | ||
1032 | * on offer | ||
1033 | * @param[out] uuid where to write the uuid. | ||
1034 | * @return #GNUNET_OK on success. | ||
1035 | */ | ||
1036 | int | ||
1037 | GNUNET_TESTING_get_trait_uuid (const struct GNUNET_TESTING_Command *cmd, | ||
1038 | unsigned int index, | ||
1039 | struct GNUNET_Uuid **uuid); | ||
1040 | |||
1041 | |||
1042 | /** | ||
1043 | * Offer a uuid in a trait. | ||
1044 | * | ||
1045 | * @param index which uuid to offer, in case there are | ||
1046 | * multiple available. | ||
1047 | * @param uuid the uuid to offer. | ||
1048 | * | ||
1049 | * @return the trait. | ||
1050 | */ | ||
1051 | struct GNUNET_TESTING_Trait | ||
1052 | GNUNET_TESTING_make_trait_uuid (unsigned int index, | ||
1053 | const struct GNUNET_Uuid *uuid); | ||
1054 | |||
1055 | /** | ||
1056 | * Obtain a absolute time from @a cmd. | ||
1057 | * | ||
1058 | * @param cmd command to extract trait from | ||
1059 | * @param index which time stamp to pick if | ||
1060 | * @a cmd has multiple on offer. | ||
1061 | * @param[out] time set to the wanted WTID. | ||
1062 | * @return #GNUNET_OK on success | ||
1063 | */ | ||
1064 | int | ||
1065 | GNUNET_TESTING_get_trait_absolute_time ( | ||
1066 | const struct GNUNET_TESTING_Command *cmd, | ||
1067 | unsigned int index, | ||
1068 | const struct GNUNET_TIME_Absolute **time); | ||
1069 | |||
1070 | |||
1071 | /** | ||
1072 | * Offer a absolute time. | ||
1073 | * | ||
1074 | * @param index associate the object with this index | ||
1075 | * @param time which object should be returned | ||
1076 | * @return the trait. | ||
1077 | */ | ||
1078 | struct GNUNET_TESTING_Trait | ||
1079 | GNUNET_TESTING_make_trait_absolute_time ( | ||
1080 | unsigned int index, | ||
1081 | const struct GNUNET_TIME_Absolute *time); | ||
1082 | |||
1083 | |||
1084 | /** | ||
1085 | * Obtain a relative time from @a cmd. | ||
1086 | * | ||
1087 | * @param cmd command to extract trait from | ||
1088 | * @param index which time to pick if | ||
1089 | * @a cmd has multiple on offer. | ||
1090 | * @param[out] time set to the wanted WTID. | ||
1091 | * @return #GNUNET_OK on success | ||
1092 | */ | ||
1093 | int | ||
1094 | GNUNET_TESTING_get_trait_relative_time ( | ||
1095 | const struct GNUNET_TESTING_Command *cmd, | ||
1096 | unsigned int index, | ||
1097 | const struct GNUNET_TIME_Relative **time); | ||
1098 | |||
1099 | |||
1100 | /** | ||
1101 | * Offer a relative time. | ||
1102 | * | ||
1103 | * @param index associate the object with this index | ||
1104 | * @param time which object should be returned | ||
1105 | * @return the trait. | ||
1106 | */ | ||
1107 | struct GNUNET_TESTING_Trait | ||
1108 | GNUNET_TESTING_make_trait_relative_time ( | ||
1109 | unsigned int index, | ||
1110 | const struct GNUNET_TIME_Relative *time); | ||
1111 | |||
1112 | /** | ||
1113 | * Offer data from trait | ||
1114 | * | ||
1115 | * @param cmd command to extract the url from. | ||
1116 | * @param pt which url is to be picked, in case | ||
1117 | * multiple are offered. | ||
1118 | * @param[out] url where to write the url. | ||
1119 | * @return #GNUNET_OK on success. | ||
1120 | */ | ||
1121 | int | ||
1122 | GNUNET_TESTING_get_trait_what_am_i (const struct | ||
1123 | GNUNET_TESTING_Command *cmd, | ||
1124 | char *what_am_i); | ||
1125 | /** | ||
1126 | * Create command. | ||
1127 | * | ||
1128 | * @param label name for command. | ||
1129 | * @param now when the command was started. | ||
1130 | * @return command. | ||
1131 | */ | ||
1132 | struct GNUNET_TESTING_Command | ||
1133 | GNUNET_TESTING_cmd_hello_world_birth (const char *label, | ||
1134 | struct GNUNET_TIME_Absolute *now); | ||
1135 | |||
1136 | /** | ||
1137 | * Create command. | ||
1138 | * | ||
1139 | * @param label name for command. | ||
1140 | * @param message initial message. | ||
1141 | * @return command. | ||
1142 | */ | ||
1143 | struct GNUNET_TESTING_Command | ||
1144 | GNUNET_TESTING_cmd_hello_world (const char *label, | ||
1145 | char *message); | ||
1146 | |||
1147 | #endif | ||