commit 3f3f5d875ae78698a874540e184a8cf49837ecce
parent 1221d7dc8a607188b95b6146817715cbea212bc7
Author: Marcello Stanisci <stanisci.m@gmail.com>
Date: Tue, 29 May 2018 17:16:36 +0200
Commenting the "testing API"
Diffstat:
1 file changed, 156 insertions(+), 77 deletions(-)
diff --git a/src/twister/testing_api_cmd_exec_client.c b/src/twister/testing_api_cmd_exec_client.c
@@ -29,6 +29,10 @@
#include <taler/taler_testing_lib.h>
#include "taler_twister_testing_lib.h"
+
+/**
+ * State for a "modify object" CMD.
+ */
struct ModifyObjectState
{
/**
@@ -41,16 +45,22 @@ struct ModifyObjectState
*/
const char *path;
+
+ /**
+ * Value to substitute to the original one.
+ */
const char *value;
/**
* Config file name to pass to the CLI client.
*/
const char *config_filename;
-
};
+/**
+ * State for a "flip object" CMD.
+ */
struct FlipObjectState
{
/**
@@ -59,7 +69,7 @@ struct FlipObjectState
struct GNUNET_OS_Process *proc;
/**
- * Object-like notation to the object to delete.
+ * Object-like notation to the string-object to flip.
*/
const char *path;
@@ -69,6 +79,10 @@ struct FlipObjectState
const char *config_filename;
};
+
+/**
+ * State for a "delete object" CMD.
+ */
struct DeleteObjectState
{
/**
@@ -87,6 +101,10 @@ struct DeleteObjectState
const char *config_filename;
};
+
+/**
+ * State for a "malform request" CMD.
+ */
struct MalformRequestState
{
/**
@@ -100,6 +118,10 @@ struct MalformRequestState
const char *config_filename;
};
+
+/**
+ * State for a "malform response" CMD.
+ */
struct MalformResponseState
{
/**
@@ -113,6 +135,10 @@ struct MalformResponseState
const char *config_filename;
};
+
+/**
+ * State for a "hack response code" CMD.
+ */
struct HackResponseCodeState
{
/**
@@ -121,8 +147,7 @@ struct HackResponseCodeState
struct GNUNET_OS_Process *proc;
/**
- * HTTP status code the twister will return upon its next
- * connection.
+ * HTTP status code to substitute to the original one.
*/
unsigned int http_status;
@@ -134,10 +159,11 @@ struct HackResponseCodeState
/**
- * Clean up after the command. Run during forced termination
- * (CTRL-C) or test failure or test success.
+ * Free the state from a "hack response code" CMD, and
+ * possibly kill its process if it did not terminate yet.
*
- * @param cls closure
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
*/
static void
hack_response_code_cleanup
@@ -158,15 +184,13 @@ hack_response_code_cleanup
}
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "hack response code" CMD,
+ * to other commands.
*
* @param cls closure
* @param ret[out] result (could be anything)
* @param trait name of the trait
- * @param selector more detailed information about which object
- * to return in case there were multiple generated
- * by the command
+ * @param index index number of the object to offer.
* @return #GNUNET_OK on success
*/
static int
@@ -188,6 +212,14 @@ hack_response_code_traits (void *cls,
index);
}
+
+/**
+ * Run a "hack response code" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
+ */
static void
hack_response_code_run (void *cls,
const struct TALER_TESTING_Command *cmd,
@@ -220,13 +252,13 @@ hack_response_code_run (void *cls,
/**
- * Command that replaces the HTTP response code for
- * the next connection that will be made to the twister.
+ * Define a "hack response code" CMD. This causes the next
+ * response code (from the service proxied by the twister) to
+ * be substituted with @a http_status.
*
* @param label command label
* @param config_filename configuration filename.
* @param http_status new response code to use
- *
* @return the command
*/
struct TALER_TESTING_Command
@@ -251,10 +283,11 @@ TALER_TESTING_cmd_hack_response_code (const char *label,
}
/**
- * Clean up after the command. Run during forced termination
- * (CTRL-C) or test failure or test success.
+ * Free the state from a "delete object" CMD, and
+ * possibly kill its process if it did not terminate yet.
*
- * @param cls closure
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
*/
static void
delete_object_cleanup
@@ -275,15 +308,13 @@ delete_object_cleanup
}
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "delete object" CMD,
+ * to other commands.
*
* @param cls closure
* @param ret[out] result (could be anything)
* @param trait name of the trait
- * @param selector more detailed information about which object
- * to return in case there were multiple generated
- * by the command
+ * @param index index number of the object to offer.
* @return #GNUNET_OK on success
*/
static int
@@ -306,7 +337,11 @@ delete_object_traits (void *cls,
}
/**
- * FIXME: document.
+ * Run a "delete object" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
*/
static void
delete_object_run (void *cls,
@@ -333,7 +368,11 @@ delete_object_run (void *cls,
}
/**
- * TODO.
+ * Free the state from a "modify object" CMD, and
+ * possibly kill its process if it did not terminate yet.
+ *
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
*/
static void
modify_object_cleanup
@@ -353,17 +392,14 @@ modify_object_cleanup
GNUNET_free (mos);
}
-
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "modify object" CMD,
+ * to other commands.
*
* @param cls closure
* @param ret[out] result (could be anything)
* @param trait name of the trait
- * @param selector more detailed information about which object
- * to return in case there were multiple generated
- * by the command
+ * @param index index number of the object to offer.
* @return #GNUNET_OK on success
*/
static int
@@ -385,9 +421,12 @@ modify_object_traits (void *cls,
index);
}
-
/**
- * FIXME: document.
+ * Run a "modify object" CMD. The "download fashion" of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
*/
static void
modify_object_dl_run (void *cls,
@@ -414,6 +453,14 @@ modify_object_dl_run (void *cls,
TALER_TESTING_wait_for_sigchld (is);
}
+
+/**
+ * Run a "modify object" CMD, the "upload fashion" of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
+ */
static void
modify_object_ul_run (void *cls,
const struct TALER_TESTING_Command *cmd,
@@ -440,13 +487,13 @@ modify_object_ul_run (void *cls,
}
/**
- * This command deletes the JSON object pointed by @a path.
+ * Create a "delete object" CMD. This command deletes
+ * the JSON object pointed by @a path.
*
* @param label command label
* @param config_filename configuration filename.
* @param path object-like path notation to point the object
* to delete.
- *
* @return the command
*/
struct TALER_TESTING_Command
@@ -471,13 +518,12 @@ TALER_TESTING_cmd_delete_object (const char *label,
}
-//////
-
/**
- * Clean up after the command. Run during forced termination
- * (CTRL-C) or test failure or test success.
+ * Free the state from a "flip object" CMD, and
+ * possibly kill its process if it did not terminate yet.
*
- * @param cls closure
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
*/
static void
flip_object_cleanup
@@ -498,15 +544,13 @@ flip_object_cleanup
}
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "flip object" CMD,
+ * to other commands.
*
* @param cls closure
* @param ret[out] result (could be anything)
* @param trait name of the trait
- * @param selector more detailed information about which object
- * to return in case there were multiple generated
- * by the command
+ * @param index index number of the object to offer.
* @return #GNUNET_OK on success
*/
static int
@@ -529,7 +573,11 @@ flip_object_traits (void *cls,
}
/**
- * FIXME: document.
+ * Run a "flip object" CMD, the upload fashion of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
*/
static void
flip_upload_run (void *cls,
@@ -556,9 +604,12 @@ flip_upload_run (void *cls,
}
-
/**
- * FIXME: document.
+ * Run a "flip object" CMD, the download fashion of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
*/
static void
flip_download_run (void *cls,
@@ -584,14 +635,14 @@ flip_download_run (void *cls,
TALER_TESTING_wait_for_sigchld (is);
}
+
/**
- * This command deletes the JSON object pointed by @a path.
+ * Define a "flip object" command, for objects to upload.
*
* @param label command label
* @param config_filename configuration filename.
* @param path object-like path notation to point the object
- * to delete.
- *
+ * to flip.
* @return the command
*/
struct TALER_TESTING_Command
@@ -617,13 +668,12 @@ TALER_TESTING_cmd_flip_upload (const char *label,
/**
- * This command deletes the JSON object pointed by @a path.
+ * Define a "flip object" command, for objects to download.
*
* @param label command label
* @param config_filename configuration filename.
* @param path object-like path notation to point the object
- * to delete.
- *
+ * to flip.
* @return the command
*/
struct TALER_TESTING_Command
@@ -649,8 +699,13 @@ TALER_TESTING_cmd_flip_download (const char *label,
/**
- * TODO.
+ * Free the state from a "malform request" CMD, and
+ * possibly kill its process if it did not terminate yet.
+ *
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
*/
+
static void
malform_request_cleanup
(void *cls,
@@ -671,15 +726,13 @@ malform_request_cleanup
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "malform request" CMD,
+ * to other commands.
*
* @param cls closure
* @param ret[out] result (could be anything)
* @param trait name of the trait
- * @param selector more detailed information about which object
- * to return in case there were multiple generated
- * by the command
+ * @param index index number of the object to offer.
* @return #GNUNET_OK on success
*/
static int
@@ -701,9 +754,12 @@ malform_request_traits (void *cls,
index);
}
-
/**
- * FIXME: document.
+ * Run a "malform request" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
*/
static void
malform_request_run (void *cls,
@@ -729,9 +785,12 @@ malform_request_run (void *cls,
TALER_TESTING_wait_for_sigchld (is);
}
-
/**
- * TODO.
+ * Free the state from a "malform response" CMD, and
+ * possibly kill its process if it did not terminate yet.
+ *
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
*/
static void
malform_response_cleanup
@@ -752,16 +811,15 @@ malform_response_cleanup
}
+
/**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "malform response" CMD,
+ * to other commands.
*
* @param cls closure
* @param ret[out] result (could be anything)
* @param trait name of the trait
- * @param selector more detailed information about which object
- * to return in case there were multiple generated
- * by the command
+ * @param index index number of the object to offer.
* @return #GNUNET_OK on success
*/
static int
@@ -785,7 +843,11 @@ malform_response_traits (void *cls,
/**
- * FIXME: document.
+ * Run a "malform response" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
*/
static void
malform_response_run (void *cls,
@@ -812,12 +874,11 @@ malform_response_run (void *cls,
}
/**
- * This command makes the next request randomly malformed
- * (by truncating it).
+ * Create a "malform request" CMD. This command makes the
+ * next request randomly malformed (by truncating it).
*
* @param label command label
* @param config_filename configuration filename.
- *
* @return the command
*/
struct TALER_TESTING_Command
@@ -840,8 +901,8 @@ TALER_TESTING_cmd_malform_request (const char *label,
}
/**
- * This command makes the next response randomly malformed
- * (by truncating it).
+ * Create a "malform response" CMD. This command makes
+ * the next response randomly malformed (by truncating it).
*
* @param label command label
* @param config_filename configuration filename.
@@ -869,12 +930,15 @@ TALER_TESTING_cmd_malform_response (const char *label,
}
/**
- * This command deletes the JSON object pointed by @a path.
+ * Create a "modify object" CMD. This command instructs
+ * the twister to modify the next object that is downloaded
+ * from the proxied service.
*
* @param label command label
* @param config_filename configuration filename.
* @param path object-like path notation to point the object
- * to delete.
+ * to modify.
+ * @param value value to put as the object's.
*
* @return the command
*/
@@ -901,6 +965,19 @@ TALER_TESTING_cmd_modify_object_dl (const char *label,
return cmd;
}
+
+/**
+ * Create a "modify object" CMD. This command instructs
+ * the twister to modify the next object that will be uploaded
+ * to the proxied service.
+ *
+ * @param label command label
+ * @param config_filename configuration filename.
+ * @param path object-like path notation pointing the object
+ * to modify.
+ * @param value value to put as the object's.
+ * @return the command
+ */
struct TALER_TESTING_Command
TALER_TESTING_cmd_modify_object_ul (const char *label,
const char *config_filename,
@@ -924,3 +1001,5 @@ TALER_TESTING_cmd_modify_object_ul (const char *label,
return cmd;
}
+
+/* end of testing_api_cmd_exec_client.c */
