aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_testing_ng_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_testing_ng_lib.h')
-rw-r--r--src/include/gnunet_testing_ng_lib.h663
1 files changed, 37 insertions, 626 deletions
diff --git a/src/include/gnunet_testing_ng_lib.h b/src/include/gnunet_testing_ng_lib.h
index 1bc66e59d..407f50bb7 100644
--- a/src/include/gnunet_testing_ng_lib.h
+++ b/src/include/gnunet_testing_ng_lib.h
@@ -1,6 +1,6 @@
1/* 1/*
2 This file is part of GNUnet 2 This file is part of GNUnet
3 Copyright (C) 2021 GNUnet e.V. 3 Copyright (C) 2021, 2023 GNUnet e.V.
4 4
5 GNUnet is free software: you can redistribute it and/or modify it 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 6 under the terms of the GNU Affero General Public License as published
@@ -19,7 +19,7 @@
19 */ 19 */
20 20
21/** 21/**
22 * @brief API for writing an interpreter to test GNUnet components 22 * @brief Meta-header for next-generation testing logic
23 * @author Christian Grothoff <christian@grothoff.org> 23 * @author Christian Grothoff <christian@grothoff.org>
24 * @author Marcello Stanisci 24 * @author Marcello Stanisci
25 * @author t3sserakt 25 * @author t3sserakt
@@ -27,409 +27,15 @@
27#ifndef GNUNET_TESTING_NG_LIB_H 27#ifndef GNUNET_TESTING_NG_LIB_H
28#define GNUNET_TESTING_NG_LIB_H 28#define GNUNET_TESTING_NG_LIB_H
29 29
30#include "gnunet_util_lib.h"
31#include "gnunet_testing_plugin.h"
32#include "gnunet_testing_lib.h"
33
34/**
35 * Stringify operator.
36 *
37 * @param a some expression to stringify. Must NOT be a macro.
38 * @return same expression as a constant string.
39 */
40#define GNUNET_S(a) #a
41
42
43/* ********************* Helper functions ********************* */
44
45/**
46 * Print failing line number and trigger shutdown. Useful
47 * quite any time after the command "run" method has been called.
48 */
49#define GNUNET_TESTING_FAIL(is) \
50 do \
51 { \
52 GNUNET_break (0); \
53 GNUNET_TESTING_interpreter_fail (is); \
54 return; \
55 } while (0)
56
57
58/* ******************* Generic interpreter logic ************ */
59
60/**
61 * Global state of the interpreter, used by a command
62 * to access information about other commands.
63 */
64struct GNUNET_TESTING_Interpreter;
65
66/**
67 * State each asynchronous command must have in its closure.
68 */
69struct GNUNET_TESTING_AsyncContext
70{
71
72 /**
73 * Interpreter we are part of.
74 */
75 struct GNUNET_TESTING_Interpreter *is;
76
77 /**
78 * Function to call when done.
79 */
80 GNUNET_SCHEDULER_TaskCallback cont;
81
82 /**
83 * Closure for @e cont.
84 */
85 void *cont_cls;
86
87 /**
88 * Indication if the command finished (#GNUNET_OK).
89 * #GNUNET_NO if it did not finish,
90 * #GNUNET_SYSERR if it failed.
91 */
92 enum GNUNET_GenericReturnValue finished;
93};
94
95
96/**
97 * A command to be run by the interpreter.
98 */
99struct GNUNET_TESTING_Command
100{
101
102 /**
103 * Closure for all commands with command-specific context information.
104 */
105 void *cls;
106
107 /**
108 * Label for the command.
109 */
110 const char *label;
111
112 /**
113 * Runs the command. Note that upon return, the interpreter
114 * will not automatically run the next command, as the command
115 * may continue asynchronously in other scheduler tasks. Thus,
116 * the command must ensure to eventually call
117 * #GNUNET_TESTING_interpreter_next() or
118 * #GNUNET_TESTING_interpreter_fail().
119 *
120 * If this function creates some asynchronous activity, it should
121 * initialize @e finish to a function that can be used to wait for
122 * the asynchronous activity to terminate.
123 *
124 * @param cls closure
125 * @param is interpreter state
126 */
127 void
128 (*run)(void *cls,
129 struct GNUNET_TESTING_Interpreter *is);
130
131 /**
132 * Pointer to the asynchronous context in the command's
133 * closure. Used by the
134 * #GNUNET_TESTING_async_finish() and
135 * #GNUNET_TESTING_async_fail() functions.
136 *
137 * Must be NULL if a command is synchronous.
138 */
139 struct GNUNET_TESTING_AsyncContext *ac;
140
141 /**
142 * Clean up after the command. Run during forced termination
143 * (CTRL-C) or test failure or test success.
144 *
145 * @param cls closure
146 */
147 void
148 (*cleanup)(void *cls);
149
150 /**
151 * Extract information from a command that is useful for other
152 * commands. Can be NULL if a command has no traits.
153 *
154 * @param cls closure
155 * @param[out] ret result (could be anything)
156 * @param trait name of the trait
157 * @param index index number of the object to extract.
158 * @return #GNUNET_OK on success,
159 * #GNUNET_NO if no trait was found
160 */
161 enum GNUNET_GenericReturnValue
162 (*traits)(void *cls,
163 const void **ret,
164 const char *trait,
165 unsigned int index);
166
167 /**
168 * When did the execution of this command start?
169 */
170 struct GNUNET_TIME_Absolute start_time;
171
172 /**
173 * When did the execution of this command finish?
174 */
175 struct GNUNET_TIME_Absolute finish_time;
176
177 /**
178 * When did we start the last run of this command? Delta to @e finish_time
179 * gives the latency for the last successful run. Useful in case @e
180 * num_tries was positive and the command was run multiple times. In that
181 * case, the @e start_time gives the time when we first tried to run the
182 * command, so the difference between @e start_time and @e finish_time would
183 * be the time all of the @e num_tries took, while the delta to @e
184 * last_req_time is the time the last (successful) execution took.
185 */
186 struct GNUNET_TIME_Absolute last_req_time;
187
188 /**
189 * In case @e asynchronous_finish is true, how long should we wait for this
190 * command to complete? If @e finish did not complete after this amount of
191 * time, the interpreter will fail. Should be set generously to ensure
192 * tests do not fail on slow systems.
193 */
194 struct GNUNET_TIME_Relative default_timeout;
195
196 /**
197 * How often did we try to execute this command? (In case it is a request
198 * that is repated.) Note that a command must have some built-in retry
199 * mechanism for this value to be useful.
200 */
201 unsigned int num_tries;
202
203 /**
204 * If "true", the interpreter should not immediately call
205 * @e finish, even if @e finish is non-NULL. Otherwise,
206 * #GNUNET_TESTING_cmd_finish() must be used
207 * to ensure that a command actually completed.
208 */
209 bool asynchronous_finish;
210
211};
212
213
214/**
215 * Lookup command by label.
216 * Only future commands are looked up.
217 *
218 * @param is interpreter to lookup command in
219 * @param label label of the command to lookup.
220 * @return the command, if it is found, or NULL.
221 */
222const struct GNUNET_TESTING_Command *
223GNUNET_TESTING_interpreter_lookup_future_command (
224 struct GNUNET_TESTING_Interpreter *is,
225 const char *label);
226
227
228/**
229 * Lookup command by label.
230 *
231 * @param is interpreter to lookup command in
232 * @param label label of the command to lookup.
233 * @return the command, if it is found, or NULL.
234 */
235const struct GNUNET_TESTING_Command *
236GNUNET_TESTING_interpreter_lookup_command (
237 struct GNUNET_TESTING_Interpreter *is,
238 const char *label);
239
240
241/**
242 * Lookup command by label.
243 * All commands, first into the past, then into the future are looked up.
244 *
245 * @param is interpreter to lookup command in
246 * @param label label of the command to lookup.
247 * @return the command, if it is found, or NULL.
248 */
249const struct GNUNET_TESTING_Command *
250GNUNET_TESTING_interpreter_lookup_command_all (
251 struct GNUNET_TESTING_Interpreter *is,
252 const char *label);
253
254
255/**
256 * Obtain label of the command being now run.
257 *
258 * @param is interpreter state.
259 * @return the label.
260 */
261const char *
262GNUNET_TESTING_interpreter_get_current_label (
263 struct GNUNET_TESTING_Interpreter *is);
264
265
266/**
267 * Current command failed, clean up and fail the test case.
268 *
269 * @param is interpreter state.
270 */
271void
272GNUNET_TESTING_interpreter_fail (struct GNUNET_TESTING_Interpreter *is);
273
274
275/**
276 * The asynchronous command of @a ac has failed.
277 *
278 * @param ac command-specific context
279 */
280void
281GNUNET_TESTING_async_fail (struct GNUNET_TESTING_AsyncContext *ac);
282
283
284/**
285 * The asynchronous command of @a ac has finished.
286 *
287 * @param ac command-specific context
288 */
289void
290GNUNET_TESTING_async_finish (struct GNUNET_TESTING_AsyncContext *ac);
291
292
293/**
294 * Create command array terminator.
295 *
296 * @return a end-command.
297 */
298struct GNUNET_TESTING_Command
299GNUNET_TESTING_cmd_end (void);
300
301
302/**
303 * Turn asynchronous command into non blocking command by setting asynchronous_finish to true.
304 *
305 * @param cmd command to make synchronous.
306 * @return a finish-command.
307 */
308struct GNUNET_TESTING_Command
309GNUNET_TESTING_cmd_make_unblocking (struct GNUNET_TESTING_Command cmd);
310
311
312/**
313 * Create (synchronous) command that waits for another command to finish.
314 * If @a cmd_ref did not finish after @a timeout, this command will fail
315 * the test case.
316 *
317 * @param finish_label label for this command
318 * @param cmd_ref reference to a previous command which we should
319 * wait for (call `finish()` on)
320 * @param timeout how long to wait at most for @a cmd_ref to finish
321 * @return a finish-command.
322 */
323const struct GNUNET_TESTING_Command
324GNUNET_TESTING_cmd_finish (const char *finish_label,
325 const char *cmd_ref,
326 struct GNUNET_TIME_Relative timeout);
327
328 30
329/** 31#include "gnunet_util_lib.h"
330 * Make the instruction pointer point to @a target_label
331 * only if @a counter is greater than zero.
332 *
333 * @param label command label
334 * @param target_label label of the new instruction pointer's destination after the jump;
335 * must be before the current instruction
336 * @param counter counts how many times the rewinding is to happen.
337 */
338struct GNUNET_TESTING_Command
339GNUNET_TESTING_cmd_rewind_ip (const char *label,
340 const char *target_label,
341 unsigned int counter);
342
343
344/**
345 * Function called with the final result of the test.
346 *
347 * @param cls closure
348 * @param rv #GNUNET_OK if the test passed
349 */
350typedef void
351(*GNUNET_TESTING_ResultCallback)(void *cls,
352 enum GNUNET_GenericReturnValue rv);
353
354
355/**
356 * Run the testsuite. Note, CMDs are copied into
357 * the interpreter state because they are _usually_
358 * defined into the "run" method that returns after
359 * having scheduled the test interpreter.
360 *
361 * @param commands the list of command to execute
362 * @param timeout how long to wait for each command to execute
363 * @param rc function to call with the final result
364 * @param rc_cls closure for @a rc
365 */
366void
367GNUNET_TESTING_run (struct GNUNET_TESTING_Command *commands,
368 struct GNUNET_TIME_Relative timeout,
369 GNUNET_TESTING_ResultCallback rc,
370 void *rc_cls);
371
372
373/**
374 * Start a GNUnet scheduler event loop and
375 * run the testsuite. Return 0 upon success.
376 * Expected to be called directly from main().
377 *
378 * @param commands the list of command to execute
379 * @param timeout how long to wait for each command to execute
380 * @return EXIT_SUCCESS on success, EXIT_FAILURE on failure
381 */
382int
383GNUNET_TESTING_main (struct GNUNET_TESTING_Command *commands,
384 struct GNUNET_TIME_Relative timeout);
385
386
387/**
388 * Look for substring in a programs' name.
389 *
390 * @param prog program's name to look into
391 * @param marker chunk to find in @a prog
392 * // FIXME: this does not belong here! => libgnunetutil, maybe?
393 * // FIXME: return bool? document return value!
394 */
395int
396GNUNET_TESTING_has_in_name (const char *prog,
397 const char *marker);
398
399
400/* ************** Specific interpreter commands ************ */
401
402
403/**
404 * Returns the actual running command.
405 *
406 * @param is Global state of the interpreter, used by a command
407 * to access information about other commands.
408 * @return The actual running command.
409 */
410struct GNUNET_TESTING_Command *
411GNUNET_TESTING_interpreter_get_current_command (
412 struct GNUNET_TESTING_Interpreter *is);
413
414
415/**
416 * Check if the command is running.
417 *
418 * @param cmd The command to check.
419 * @return GNUNET_NO if the command is not running, GNUNET_YES if it is running.
420 */
421enum GNUNET_GenericReturnValue
422GNUNET_TESTING_running (const struct GNUNET_TESTING_Command *command);
423 32
33/* FIXME: legacy test header, to be removed!! */
34#include "gnunet_testing_lib.h"
424 35
425/** 36#include "gnunet_testing_plugin.h"
426 * Check if a command is finished. 37#include "gnunet_testing_loop_lib.h"
427 * 38#include "gnunet_testing_netjail_lib.h"
428 * @param cmd The command to check.
429 * @return GNUNET_NO if the command is not finished, GNUNET_YES if it is finished.
430 */
431enum GNUNET_GenericReturnValue
432GNUNET_TESTING_finished (struct GNUNET_TESTING_Command *command);
433 39
434 40
435/** 41/**
@@ -437,14 +43,12 @@ GNUNET_TESTING_finished (struct GNUNET_TESTING_Command *command);
437 * 43 *
438 * @param label command label. 44 * @param label command label.
439 * @param process_label label of a command that has a process trait 45 * @param process_label label of a command that has a process trait
440 * @param process_index index of the process trait at @a process_label // FIXME: enum? needed?
441 * @param signal signal to send to @a process. 46 * @param signal signal to send to @a process.
442 * @return the command. 47 * @return the command.
443 */ 48 */
444struct GNUNET_TESTING_Command 49struct GNUNET_TESTING_Command
445GNUNET_TESTING_cmd_signal (const char *label, 50GNUNET_TESTING_cmd_signal (const char *label,
446 const char *process_label, 51 const char *process_label,
447 unsigned int process_index,
448 int signal); 52 int signal);
449 53
450 54
@@ -461,244 +65,51 @@ GNUNET_TESTING_cmd_sleep (const char *label,
461 65
462 66
463/** 67/**
464 * Create a "batch" command. Such command takes a end_CMD-terminated array of 68 * Command to execute a script synchronously.
465 * CMDs and executed them. Once it hits the end CMD, it passes the control to
466 * the next top-level CMD, regardless of it being another batch or ordinary
467 * CMD.
468 *
469 * @param label the command label.
470 * @param batch array of CMDs to execute.
471 * @return the command.
472 */
473struct GNUNET_TESTING_Command
474GNUNET_TESTING_cmd_batch (const char *label,
475 struct GNUNET_TESTING_Command *batch);
476
477
478/**
479 * Performance counter.
480 * // FIXME: this might not belong here!
481 */
482struct GNUNET_TESTING_Timer
483{
484 /**
485 * For which type of commands.
486 */
487 const char *prefix;
488
489 /**
490 * Total time spend in all commands of this type.
491 */
492 struct GNUNET_TIME_Relative total_duration;
493
494 /**
495 * Total time spend waiting for the *successful* exeuction
496 * in all commands of this type.
497 */
498 struct GNUNET_TIME_Relative success_latency;
499
500 /**
501 * Number of commands summed up.
502 */
503 unsigned int num_commands;
504
505 /**
506 * Number of retries summed up.
507 */
508 unsigned int num_retries;
509};
510
511
512/**
513 * Retrieve the public key from the test system with the unique node id.
514 *
515 * @param num The unique node id.
516 * @param tl_system The test system.
517 * @return The peer identity wrapping the public key.
518 */
519struct GNUNET_PeerIdentity *
520GNUNET_TESTING_get_pub_key (unsigned int num,
521 const struct GNUNET_TESTING_System *tl_system);
522
523
524/**
525 * Obtain performance data from the interpreter.
526 * 69 *
527 * @param timers what commands (by label) to obtain runtimes for 70 * FIXME: is this accurate? How is this limited to BASH scripts or even scripts?
528 * @return the command
529 */
530struct GNUNET_TESTING_Command
531GNUNET_TESTING_cmd_stat (struct GNUNET_TESTING_Timer *timers);
532
533
534/* *** Generic trait logic for implementing traits ********* */
535
536/**
537 * A trait.
538 */
539struct GNUNET_TESTING_Trait
540{
541 /**
542 * Index number associated with the trait. This gives the
543 * possibility to have _multiple_ traits on offer under the
544 * same name.
545 */
546 unsigned int index;
547
548 /**
549 * Trait type, for example "reserve-pub" or "coin-priv".
550 */
551 const char *trait_name;
552
553 /**
554 * Pointer to the piece of data to offer.
555 */
556 const void *ptr;
557};
558
559
560/**
561 * "end" trait. Because traits are offered into arrays,
562 * this type of trait is used to mark the end of such arrays;
563 * useful when iterating over those.
564 */
565struct GNUNET_TESTING_Trait
566GNUNET_TESTING_trait_end (void);
567
568
569/**
570 * Extract a trait.
571 * 71 *
572 * @param traits the array of all the traits. 72 * @param label Label of the command.
573 * @param[out] ret where to store the result. 73 * @param script The name of the script.
574 * @param trait type of the trait to extract. 74 * @param script_argv The arguments of the script.
575 * @param index index number of the trait to extract. 75*/
576 * @return #GNUNET_OK when the trait is found. 76const struct GNUNET_TESTING_Command
577 */ 77GNUNET_TESTING_cmd_exec_bash_script (const char *label,
578enum GNUNET_GenericReturnValue 78 const char *script,
579GNUNET_TESTING_get_trait (const struct GNUNET_TESTING_Trait *traits, 79 char *const script_argv[],
580 const void **ret, 80 // FIXME: wtf are these two args here for!?
581 const char *trait, 81 int argc,
582 unsigned int index); 82 GNUNET_ChildCompletedCallback cb);
583
584
585/* ****** Specific traits supported by this component ******* */
586
587
588/**
589 * Create headers for a trait with name @a name for
590 * statically allocated data of type @a type.
591 */
592#define GNUNET_TESTING_MAKE_DECL_SIMPLE_TRAIT(name,type) \
593 enum GNUNET_GenericReturnValue \
594 GNUNET_TESTING_get_trait_ ## name ( \
595 const struct GNUNET_TESTING_Command *cmd, \
596 type **ret); \
597 struct GNUNET_TESTING_Trait \
598 GNUNET_TESTING_make_trait_ ## name ( \
599 type * value);
600
601
602/**
603 * Create C implementation for a trait with name @a name for statically
604 * allocated data of type @a type.
605 */
606#define GNUNET_TESTING_MAKE_IMPL_SIMPLE_TRAIT(name,type) \
607 enum GNUNET_GenericReturnValue \
608 GNUNET_TESTING_get_trait_ ## name ( \
609 const struct GNUNET_TESTING_Command *cmd, \
610 type **ret) \
611 { \
612 if (NULL == cmd->traits) return GNUNET_SYSERR; \
613 return cmd->traits (cmd->cls, \
614 (const void **) ret, \
615 GNUNET_S (name), \
616 0); \
617 } \
618 struct GNUNET_TESTING_Trait \
619 GNUNET_TESTING_make_trait_ ## name ( \
620 type * value) \
621 { \
622 struct GNUNET_TESTING_Trait ret = { \
623 .trait_name = GNUNET_S (name), \
624 .ptr = (const void *) value \
625 }; \
626 return ret; \
627 }
628
629 83
630/**
631 * Create headers for a trait with name @a name for
632 * statically allocated data of type @a type.
633 */
634#define GNUNET_TESTING_MAKE_DECL_INDEXED_TRAIT(name,type) \
635 enum GNUNET_GenericReturnValue \
636 GNUNET_TESTING_get_trait_ ## name ( \
637 const struct GNUNET_TESTING_Command *cmd, \
638 unsigned int index, \
639 type **ret); \
640 struct GNUNET_TESTING_Trait \
641 GNUNET_TESTING_make_trait_ ## name ( \
642 unsigned int index, \
643 type * value);
644 84
645 85
646/** 86/* ****** Specific traits needed by this component ******* */
647 * Create C implementation for a trait with name @a name for statically
648 * allocated data of type @a type.
649 */
650#define GNUNET_TESTING_MAKE_IMPL_INDEXED_TRAIT(name,type) \
651 enum GNUNET_GenericReturnValue \
652 GNUNET_TESTING_get_trait_ ## name ( \
653 const struct GNUNET_TESTING_Command *cmd, \
654 unsigned int index, \
655 type **ret) \
656 { \
657 if (NULL == cmd->traits) return GNUNET_SYSERR; \
658 return cmd->traits (cmd->cls, \
659 (const void **) ret, \
660 GNUNET_S (name), \
661 index); \
662 } \
663 struct GNUNET_TESTING_Trait \
664 GNUNET_TESTING_make_trait_ ## name ( \
665 unsigned int index, \
666 type * value) \
667 { \
668 struct GNUNET_TESTING_Trait ret = { \
669 .index = index, \
670 .trait_name = GNUNET_S (name), \
671 .ptr = (const void *) value \
672 }; \
673 return ret; \
674 }
675 87
676 88
677/** 89/**
678 * Call #op on all simple traits. 90 * Call #op on all simple traits.
679 */ 91 */
680#define GNUNET_TESTING_SIMPLE_TRAITS(op) \ 92#define GNUNET_TESTING_SIMPLE_TRAITS(op, prefix) \
681 op (batch_cmds, struct GNUNET_TESTING_Command *) \ 93 op (prefix, process, struct GNUNET_OS_Process *)
682 op (process, struct GNUNET_OS_Process *) 94
683 95
96GNUNET_TESTING_SIMPLE_TRAITS (GNUNET_TESTING_MAKE_DECL_SIMPLE_TRAIT, GNUNET_TESTING)
684 97
685/** 98/**
686 * Call #op on all indexed traits. 99 * Call #op on all indexed traits.
687 */ 100 */
688#define GNUNET_TESTING_INDEXED_TRAITS(op) \ 101#define GNUNET_TESTING_INDEXED_TRAITS(op, prefix) \
689 op (uint32, const uint32_t) \ 102 op (prefix, uint32, const uint32_t) \
690 op (uint64, const uint64_t) \ 103 op (prefix, uint64, const uint64_t) \
691 op (int64, const int64_t) \ 104 op (prefix, int64, const int64_t) \
692 op (uint, const unsigned int) \ 105 op (prefix, uint, const unsigned int) \
693 op (string, const char) \ 106 op (prefix, string, const char) \
694 op (cmd, const struct GNUNET_TESTING_Command) \ 107 op (prefix, uuid, const struct GNUNET_Uuid) \
695 op (uuid, const struct GNUNET_Uuid) \ 108 op (prefix, time, const struct GNUNET_TIME_Absolute) \
696 op (time, const struct GNUNET_TIME_Absolute) \ 109 op (prefix, absolute_time, const struct GNUNET_TIME_Absolute) \
697 op (absolute_time, const struct GNUNET_TIME_Absolute) \ 110 op (prefix, relative_time, const struct GNUNET_TIME_Relative)
698 op (relative_time, const struct GNUNET_TIME_Relative)
699 111
700GNUNET_TESTING_SIMPLE_TRAITS (GNUNET_TESTING_MAKE_DECL_SIMPLE_TRAIT) 112GNUNET_TESTING_INDEXED_TRAITS (GNUNET_TESTING_MAKE_DECL_INDEXED_TRAIT, GNUNET_TESTING)
701 113
702GNUNET_TESTING_INDEXED_TRAITS (GNUNET_TESTING_MAKE_DECL_INDEXED_TRAIT)
703 114
704#endif 115#endif