gnunet_testing_lib.h

Go to the documentation of this file.

/*
      This file is part of GNUnet
      Copyright (C) 2021, 2023, 2024 GNUnet e.V.
 
      GNUnet is free software: you can redistribute it and/or modify it
      under the terms of the GNU Affero General Public License as published
      by the Free Software Foundation, either version 3 of the License,
      or (at your option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      Affero General Public License for more details.
 
      You should have received a copy of the GNU Affero General Public License
      along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
     SPDX-License-Identifier: AGPL3.0-or-later
 */
 
#ifndef GNUNET_TESTING_LIB_H
#define GNUNET_TESTING_LIB_H
 
#include "gnunet_util_lib.h"
 
#define GNUNET_TESTING_CMD_MAX_LABEL_LENGTH 127
 
/* ********************* Helper functions ********************* */
 
#define GNUNET_TESTING_FAIL(is)                 \
        do {                                    \
          GNUNET_break (0);                     \
          GNUNET_TESTING_interpreter_fail (is); \
          return;                               \
        } while (0)
 
 
#define GNUNET_TESTING_command_incomplete(is,label)                       \
        do {                                                              \
          GNUNET_log (GNUNET_ERROR_TYPE_ERROR,                            \
                      "Command %s (%s:%u) did not complete (at %s)\n",    \
                      label,                                              \
                      __FILE__,                                           \
                      __LINE__,                                           \
                      GNUNET_TESTING_interpreter_current_cmd_get_label (is)); \
        } while (0)
 
 
/* ******************* Generic interpreter logic ************ */
 
struct GNUNET_TESTING_Interpreter;
 
struct GNUNET_TESTING_AsyncContext
{
 
  struct GNUNET_TESTING_Interpreter *is;
 
  GNUNET_SCHEDULER_TaskCallback notify_finished;
 
  void *notify_finished_cls;
 
  enum GNUNET_GenericReturnValue finished;
 
  bool next_called;
};
 
 
void
GNUNET_TESTING_async_fail (
  struct GNUNET_TESTING_AsyncContext *ac);
 
 
void
GNUNET_TESTING_async_finish (
  struct GNUNET_TESTING_AsyncContext *ac);
 
 
typedef void
(*GNUNET_TESTING_CommandRunRoutine)(
  void *cls,
  struct GNUNET_TESTING_Interpreter *is);
 
 
typedef void
(*GNUNET_TESTING_CommandCleanupRoutine)(void *cls);
 
 
typedef enum GNUNET_GenericReturnValue
(*GNUNET_TESTING_CommandGetTraits) (void *cls,
                                    const void **ret,
                                    const char *trait,
                                    unsigned int index);
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_command_new_ac (
  void *cls,
  const char *label,
  GNUNET_TESTING_CommandRunRoutine run,
  GNUNET_TESTING_CommandCleanupRoutine cleanup,
  GNUNET_TESTING_CommandGetTraits traits,
  struct GNUNET_TESTING_AsyncContext *ac);
 
 
#define GNUNET_TESTING_command_new(cls,label,run,cleanup,traits) \
        GNUNET_TESTING_command_new_ac (cls,label,run,cleanup,traits,NULL)
 
 
struct GNUNET_TESTING_CommandLabel
{
  char value[GNUNET_TESTING_CMD_MAX_LABEL_LENGTH + 1];
};
 
 
void
GNUNET_TESTING_set_label (
  struct GNUNET_TESTING_CommandLabel *label,
  const char *value);
 
 
struct GNUNET_TESTING_Command
{
 
  struct GNUNET_TESTING_CommandLabel label;
 
  void *cls;
 
  const char *name;
 
  GNUNET_TESTING_CommandRunRoutine run;
 
  struct GNUNET_TESTING_AsyncContext *ac;
 
  GNUNET_TESTING_CommandCleanupRoutine cleanup;
 
  GNUNET_TESTING_CommandGetTraits traits;
 
  struct GNUNET_TIME_Absolute start_time;
 
  struct GNUNET_TIME_Absolute finish_time;
 
  struct GNUNET_TIME_Absolute last_req_time;
 
  unsigned int num_tries;
 
  bool asynchronous_finish;
 
};
 
 
const struct GNUNET_TESTING_Command *
GNUNET_TESTING_interpreter_lookup_command (
  struct GNUNET_TESTING_Interpreter *is,
  const char *label);
 
 
const struct GNUNET_TESTING_Command *
GNUNET_TESTING_interpreter_get_command (
  struct GNUNET_TESTING_Interpreter *is,
  const char *name);
 
 
void
GNUNET_TESTING_interpreter_current_cmd_touch (
  struct GNUNET_TESTING_Interpreter *is);
 
 
void
GNUNET_TESTING_interpreter_current_cmd_inc_tries (
  struct GNUNET_TESTING_Interpreter *is);
 
 
const char *
GNUNET_TESTING_interpreter_current_cmd_get_label (
  struct GNUNET_TESTING_Interpreter *is);
 
 
void
GNUNET_TESTING_interpreter_fail (
  struct GNUNET_TESTING_Interpreter *is);
 
 
void
GNUNET_TESTING_interpreter_skip (
  struct GNUNET_TESTING_Interpreter *is);
 
 
typedef void
(*GNUNET_TESTING_CommandIterator)(
  void *cls,
  const struct GNUNET_TESTING_Command *cmd);
 
 
void
GNUNET_TESTING_interpreter_commands_iterate (
  struct GNUNET_TESTING_Interpreter *is,
  bool asc,
  GNUNET_TESTING_CommandIterator cb,
  void *cb_cls);
 
 
/* ************** Fundamental interpreter commands ************ */
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_end (void);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_batch (
  const char *label,
  struct GNUNET_TESTING_Command *batch);
 
 
struct GNUNET_TESTING_Timer
{
  const char *prefix;
 
  struct GNUNET_TIME_Relative total_duration;
 
  struct GNUNET_TIME_Relative success_latency;
 
  unsigned int num_commands;
 
  unsigned int num_retries;
};
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_stat (
  const char *label,
  struct GNUNET_TESTING_Timer *timers);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_set_var (
  const char *name,
  struct GNUNET_TESTING_Command cmd);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_barrier_create (
  const char *label,
  unsigned int number_to_be_reached);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_barrier_reached (
  const char *label,
  const char *barrier_label);
 
 
#define GNUNET_TESTING_NETJAIL_START_SCRIPT "netjail_start_new.sh"
 
#define GNUNET_TESTING_NETJAIL_STOP_SCRIPT "netjail_stop.sh"
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_netjail_start_helpers (
  const char *label,
  const char *topology_cmd_label,
  struct GNUNET_TIME_Relative timeout);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_netjail_setup (
  const char *label,
  const char *script,
  const char *topology_cmd_label);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_load_topology_from_file (
  const char *label,
  const char *filename);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_load_topology_from_string (
  const char *label,
  const char *topology_data);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_make_unblocking (
  struct GNUNET_TESTING_Command cmd);
 
 
const struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_finish (
  const char *finish_label,
  const char *cmd_ref,
  struct GNUNET_TIME_Relative timeout);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_signal (
  const char *label,
  const char *process_label,
  int signal);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_sleep (
  const char *label,
  struct GNUNET_TIME_Relative duration);
 
 
const struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_exec (
  const char *label,
  enum GNUNET_OS_ProcessStatusType expected_type,
  unsigned long int expected_exit_code,
  char *const script_argv[]);
 
 
const struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_exec_va (
  const char *label,
  enum GNUNET_OS_ProcessStatusType expected_type,
  unsigned long int expected_exit_code,
  ...);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_rewind_ip (
  const char *label,
  const char *target_label,
  unsigned int counter);
 
 
/* ***************** main loop logic ************* */
 
typedef void
(*GNUNET_TESTING_ResultCallback)(
  void *cls,
  enum GNUNET_GenericReturnValue rv);
 
 
struct GNUNET_TESTING_Interpreter *
GNUNET_TESTING_run (
  const struct GNUNET_TESTING_Command *commands,
  struct GNUNET_TIME_Relative timeout,
  GNUNET_TESTING_ResultCallback rc,
  void *rc_cls);
 
 
int
GNUNET_TESTING_main (
  const struct GNUNET_TESTING_Command *commands,
  struct GNUNET_TIME_Relative timeout);
 
 
/* ***************** plugin logic ************* */
 
 
struct GNUNET_TESTING_PluginFunctions;
 
 
struct GNUNET_TESTING_PluginFunctions *
GNUNET_TESTING_make_plugin (
  const struct GNUNET_TESTING_Command *commands);
 
#define GNUNET_TESTING_MAKE_PLUGIN(prefix,name,...)            \
        void *                                                 \
        prefix ## _plugin_ ## name ## _init (void *cls) { \
          const char *my_node_id = cls; (void) my_node_id;     \
          struct GNUNET_TESTING_Command commands[] = {         \
            __VA_ARGS__,                                       \
            GNUNET_TESTING_cmd_end ()                          \
          };                                                   \
          return GNUNET_TESTING_make_plugin (commands);        \
        }                                                      \
        void *                                                 \
        prefix ## _plugin_ ## name ## _done (void *cls) {      \
          struct GNUNET_TESTING_PluginFunctions *api = cls;    \
          GNUNET_free (api);                                   \
          return NULL;                                         \
        }
 
 
/* *** Generic trait logic for implementing traits ********* */
 
struct GNUNET_TESTING_Trait
{
  unsigned int index;
 
  const char *trait_name;
 
  const void *ptr;
};
 
 
struct GNUNET_TESTING_Trait
GNUNET_TESTING_trait_end (void);
 
 
enum GNUNET_GenericReturnValue
GNUNET_TESTING_get_trait (
  const struct GNUNET_TESTING_Trait *traits,
  const void **ret,
  const char *trait,
  unsigned int index);
 
 
#define GNUNET_TESTING_MAKE_DECL_SIMPLE_TRAIT(prefix,name,type)  \
        enum GNUNET_GenericReturnValue                           \
        prefix ## _get_trait_ ## name (                          \
          const struct GNUNET_TESTING_Command *cmd,              \
          type * *ret);                                          \
        struct GNUNET_TESTING_Trait                              \
        prefix ## _make_trait_ ## name (                         \
          type * value);
 
 
#define GNUNET_TESTING_MAKE_IMPL_SIMPLE_TRAIT(prefix,name,type) \
        enum GNUNET_GenericReturnValue                          \
        prefix ## _get_trait_ ## name (                         \
          const struct GNUNET_TESTING_Command *cmd,             \
          type * *ret)                                          \
        {                                                       \
          if (NULL == cmd->traits) return GNUNET_SYSERR;        \
          return cmd->traits (cmd->cls,                         \
                              (const void **) ret,              \
                              GNUNET_S (name),                  \
                              0);                               \
        }                                                       \
        struct GNUNET_TESTING_Trait                             \
        prefix ## _make_trait_ ## name (                        \
          type * value)                                         \
        {                                                       \
          struct GNUNET_TESTING_Trait ret = {                   \
            .trait_name = GNUNET_S (name),                      \
            .ptr = (const void *) value                         \
          };                                                    \
          return ret;                                           \
        }
 
 
#define GNUNET_TESTING_MAKE_DECL_INDEXED_TRAIT(prefix,name,type) \
        enum GNUNET_GenericReturnValue                           \
        prefix ## _get_trait_ ## name (                          \
          const struct GNUNET_TESTING_Command *cmd,              \
          unsigned int index,                                    \
          type * *ret);                                          \
        struct GNUNET_TESTING_Trait                              \
        prefix ## _make_trait_ ## name (                         \
          unsigned int index,                                    \
          type * value);
 
 
#define GNUNET_TESTING_MAKE_IMPL_INDEXED_TRAIT(prefix,name,type)    \
        enum GNUNET_GenericReturnValue                          \
        prefix ## _get_trait_ ## name (                         \
          const struct GNUNET_TESTING_Command *cmd,             \
          unsigned int index,                                   \
          type * *ret)                                          \
        {                                                       \
          if (NULL == cmd->traits) return GNUNET_SYSERR;        \
          return cmd->traits (cmd->cls,                         \
                              (const void **) ret,              \
                              GNUNET_S (name),                  \
                              index);                           \
        }                                                       \
        struct GNUNET_TESTING_Trait                             \
        prefix ## _make_trait_ ## name (                        \
          unsigned int index,                                   \
          type * value)                                         \
        {                                                       \
          struct GNUNET_TESTING_Trait ret = {                   \
            .index = index,                                     \
            .trait_name = GNUNET_S (name),                      \
            .ptr = (const void *) value                         \
          };                                                    \
          return ret;                                           \
        }
 
 
#define GNUNET_TESTING_SIMPLE_TRAITS(op,prefix)                  \
        op (prefix, process, struct GNUNET_OS_Process *)         \
        op (prefix, cmd, const struct GNUNET_TESTING_Command)    \
        op (prefix, batch_cmds, struct GNUNET_TESTING_Command *)
 
 
GNUNET_TESTING_SIMPLE_TRAITS (GNUNET_TESTING_MAKE_DECL_SIMPLE_TRAIT,
                              GNUNET_TESTING)
 
 
#endif