aboutsummaryrefslogtreecommitdiff
path: root/src/include/taler_merchant_testing_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/taler_merchant_testing_lib.h')
-rw-r--r--src/include/taler_merchant_testing_lib.h338
1 files changed, 250 insertions, 88 deletions
diff --git a/src/include/taler_merchant_testing_lib.h b/src/include/taler_merchant_testing_lib.h
index 57457399..30116786 100644
--- a/src/include/taler_merchant_testing_lib.h
+++ b/src/include/taler_merchant_testing_lib.h
@@ -35,9 +35,6 @@
#define MERCHANT_FAIL() \
do {GNUNET_break (0); return NULL; } while (0)
-#define CMD_NOT_FOUND "Command not found"
-#define TRAIT_NOT_FOUND "Trait not found"
-
/**
* Prepare the merchant execution. Create tables and check if
* the port is available.
@@ -66,19 +63,18 @@ struct GNUNET_OS_Process *
TALER_TESTING_run_merchant (const char *config_filename,
const char *merchant_url);
-/* ******************* Generic interpreter logic ************ */
-
/* ************** Specific interpreter commands ************ */
/**
- * Make a /proposal interpreter command.
+ * Make the "proposal" command.
*
* @param label command label
- * @param merchant_url merchant base url.
- * @param ctx context
- * @param http_status expected HTTP status code.
- * @param order the order
- * @param instance the merchant instance
+ * @param merchant_url base URL of the merchant serving
+ * the proposal request.
+ * @param ctx CURL context.
+ * @param http_status expected HTTP status.
+ * @param order the order to PUT to the merchant.
+ * @param instance merchant instance performing the operation.
*
* @return the command
*/
@@ -89,22 +85,18 @@ TALER_TESTING_cmd_proposal (const char *label,
unsigned int http_status,
const char *order,
const char *instance);
-
/**
- * Make a "proposal lookup" interpreter command.
+ * Make a "proposal lookup" command.
*
- * @param label command label
- * @param ctx
- * @param merchant_url merchant base URL where to address
- * the request
- * @param http_status expected HTTP response code
- * @param proposal_reference reference to a proposal command.
- * This reference will provide a order it to make the
- * request about
- * @param order_id order id to make the request about; takes
- * precedence over @a proposal_reference.
+ * @param label command label.
+ * @param ctx CURL context.
+ * @param merchant_url base URL of the merchant backend
+ * serving the proposal lookup request.
+ * @param http_status expected HTTP response code.
+ * @param proposal_reference reference to a "proposal" CMD.
+ * @param order_id order id to lookup, can be NULL.
*
- * @return the command
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_proposal_lookup
@@ -116,11 +108,11 @@ TALER_TESTING_cmd_proposal_lookup
const char *order_id);
/**
- * Make a "check payment" interpreter command.
+ * Make a "check payment" test command.
*
* @param label command label.
- * @param merchant_url merchant base url to address the request to
- * @param ctx context.
+ * @param merchant_url merchant base url
+ * @param ctx CURL context.
* @param http_status expected HTTP response code.
* @param proposal_reference the proposal whose payment status
* is going to be checked.
@@ -136,7 +128,6 @@ TALER_TESTING_cmd_check_payment (const char *label,
unsigned int http_status,
const char *proposal_reference,
unsigned int expect_paid);
-
/**
* Make a "pay" test command.
*
@@ -165,9 +156,11 @@ TALER_TESTING_cmd_pay (const char *label,
const char *amount_with_fee,
const char *amount_without_fee,
const char *refund_fee);
-
/**
- * Make a "pay again" test command.
+ * Make a "pay again" test command. Its purpose is to
+ * take all the data from a aborted "pay" CMD, and use
+ * good coins - found in @a coin_reference - to correctly
+ * pay for it.
*
* @param label command label
* @param merchant_url merchant base URL
@@ -205,7 +198,19 @@ TALER_TESTING_cmd_pay_abort (const char *label,
unsigned int http_status);
/**
- * FIXME.
+ * Make a "pay abort refund" CMD. This command uses the
+ * refund permission from a "pay abort" CMD, and redeems it
+ * at the exchange.
+ *
+ * @param label command label.
+ * @param exchange connection label to the exchange.
+ * @param abort_reference reference to the "pay abort" CMD that
+ * will offer the refund permission.
+ * @param num_coins how many coins are expected to be refunded.
+ * @param refund_amount the amount we are going to redeem as
+ * refund.
+ * @param refund_fee the refund fee (FIXME: who pay it?)
+ * @param http_status expected HTTP response code.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_pay_abort_refund
@@ -218,7 +223,22 @@ TALER_TESTING_cmd_pay_abort_refund
unsigned int http_status);
/**
- * FIXME
+ * Define a "refund lookup" CMD.
+ *
+ * @param label command label.
+ * @param merchant_url base URL of the merchant serving the
+ * "refund lookup" request.
+ * @param ctx CURL context.
+ * @param increase_reference reference to a "refund increase" CMD
+ * that will offer the amount to check the looked up refund
+ * against. Must NOT be NULL.
+ * @param pay_reference reference to the "pay" CMD whose coins got
+ * refunded. It is used to double-check if the refunded
+ * coins were actually spent in the first place.
+ * @param order_id order id whose refund status is to be looked up.
+ * @param http_code expected HTTP response code.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_refund_lookup
@@ -230,6 +250,28 @@ TALER_TESTING_cmd_refund_lookup
const char *order_id,
unsigned int http_code);
+/**
+ * Define a "refund lookup" CMD, equipped with a expected refund
+ * amount.
+ *
+ * @param label command label.
+ * @param merchant_url base URL of the merchant serving the
+ * "refund lookup" request.
+ * @param ctx CURL context.
+ * @param increase_reference reference to a "refund increase" CMD
+ * that will offer the amount to check the looked up refund
+ * against. Can be NULL, takes precedence over @a
+ * refund_amount.
+ * @param pay_reference reference to the "pay" CMD whose coins got
+ * refunded. It is used to double-check if the refunded
+ * coins were actually spent in the first place.
+ * @param order_id order id whose refund status is to be looked up.
+ * @param http_code expected HTTP response code.
+ * @param refund_amount expected refund amount. Must be defined
+ * if @a increase_reference is NULL.
+ *
+ * @return the command.
+ */
struct TALER_TESTING_Command
TALER_TESTING_cmd_refund_lookup_with_amount
(const char *label,
@@ -243,7 +285,19 @@ TALER_TESTING_cmd_refund_lookup_with_amount
/**
- * FIXME
+ * Define a "refund increase" CMD.
+ *
+ * @param label command label.
+ * @param merchant_url base URL of the backend serving the
+ * "refund increase" request.
+ * @param ctx CURL context.
+ * @param reason refund justification, human-readable.
+ * @param order_id order id of the contract to refund.
+ * @param refund_amount amount to be refund-increased.
+ * @param refund_fee refund fee.
+ * @param http_code expected HTTP response code.
+ *
+ * @return the command.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_refund_increase
@@ -256,17 +310,18 @@ TALER_TESTING_cmd_refund_increase
const char *refund_fee,
unsigned int http_code);
-
/**
* Make a "history" command.
*
- * @param label command label
- * @param merchant_url merchant base URL
- * @param ctx main CURL context
+ * @param label command label.
+ * @param merchant_url base URL of the merchant serving the
+ * request.
+ * @param ctx CURL context.
* @param http_status expected HTTP response code
- * @param time FIXME
+ * @param time limit towards the past for the history
+ * records we want returned.
* @param nresult how many results are expected
- * @param start FIXME.
+ * @param start first row id we want in the result.
* @param nrows how many row we want to receive, at most.
*/
struct TALER_TESTING_Command
@@ -280,7 +335,16 @@ TALER_TESTING_cmd_history (const char *label,
unsigned int nrows);
/**
- * FIXME
+ * Define a "track transaction" CMD.
+ *
+ * @param label command label.
+ * @param merchant_url base URL of the merchant serving the
+ * /track/transaction request.
+ * @param ctx CURL context.
+ * @param http_status expected HTTP response code.
+ * @param transfer_reference FIXME not used.
+ * @param pay_reference used to retrieve the order id to track.
+ * @param wire_fee FIXME not used.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_merchant_track_transaction
@@ -293,7 +357,17 @@ TALER_TESTING_cmd_merchant_track_transaction
const char *wire_fee);
/**
- * FIXME
+ * Define a "track transfer" CMD.
+ *
+ * @param label command label.
+ * @param merchant_url base URL of the merchant serving the
+ * /track/transfer request.
+ * @param ctx CURL context.
+ * @param http_status expected HTTP response code.
+ * @param check_bank_reference reference to a "check bank" CMD
+ * that will provide the WTID and exchange URL to issue
+ * the track against.
+ * @param pay_reference FIXME not used.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_merchant_track_transfer
@@ -312,6 +386,7 @@ TALER_TESTING_cmd_merchant_track_transfer
* @param index which signature to offer if there are multiple
* on offer
* @param merchant_sig set to the offered signature.
+ *
* @return the trait
*/
struct TALER_TESTING_Trait
@@ -326,6 +401,7 @@ TALER_TESTING_make_trait_merchant_sig
* @param index which signature to pick if @a cmd has multiple
* on offer
* @param merchant_sig[out] set to the wanted signature.
+ *
* @return #GNUNET_OK on success
*/
int
@@ -334,7 +410,6 @@ TALER_TESTING_get_trait_merchant_sig
unsigned int index,
struct TALER_MerchantSignatureP **merchant_sig);
-
/**
* Obtain a reference to a proposal command. Any command that
* works with proposals, might need to offer their reference to
@@ -343,10 +418,11 @@ TALER_TESTING_get_trait_merchant_sig
* the same data needed by the former in order to use the "pay
* abort" API.
*
- * @param cmd command to extract trait from
+ * @param cmd command to extract the trait from.
* @param index which reference to pick if @a cmd has multiple
- * on offer
+ * on offer.
* @param proposal_reference[out] set to the wanted reference.
+ *
* @return #GNUNET_OK on success
*/
int
@@ -359,8 +435,9 @@ TALER_TESTING_get_trait_proposal_reference
* Offer a proposal reference.
*
* @param index which reference to offer if there are
- * multiple on offer
- * @param proposal_reference set to the offered reference.
+ * multiple on offer.
+ * @param proposal_reference pointer to the reference to offer.
+ *
* @return the trait
*/
struct TALER_TESTING_Trait
@@ -372,8 +449,9 @@ TALER_TESTING_make_trait_proposal_reference
* Offer a coin reference.
*
* @param index which reference to offer if there are
- * multiple on offer
+ * multiple on offer.
* @param coin_reference set to the offered reference.
+ *
* @return the trait
*/
struct TALER_TESTING_Trait
@@ -388,12 +466,14 @@ TALER_TESTING_make_trait_coin_reference
* @param cmd command to extract trait from
* @param index which reference to pick if @a cmd has multiple
* on offer
- * @param coin_reference[out] set to the wanted reference. NOTE:
- * a _single_ reference can contain _multiple_ token,
- * using semi-colon as separator. For example, a _single_
- * reference can be this: "coin-ref-1", or even this:
- * "coin-ref-1;coin-ref-2". The "pay" command contains
- * functions that can parse such format.
+ * @param coin_reference[out] set to the wanted reference.
+ * NOTE: a _single_ reference can contain
+ * _multiple_ instances, using semi-colon as separator.
+ * For example, a _single_ reference can be this:
+ * "coin-ref-1", or even this: "coin-ref-1;coin-ref-2".
+ * The "pay" command contains functions that can parse
+ * such format.
+ *
* @return #GNUNET_OK on success
*/
int
@@ -406,10 +486,10 @@ TALER_TESTING_get_trait_coin_reference
/**
* Obtain planchet secrets from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param index which signature to pick if @a cmd has multiple
- * on offer
+ * @param cmd command to extract trait from.
+ * @param index index of the trait.
* @param planchet_secrets[out] set to the wanted secrets.
+ *
* @return #GNUNET_OK on success
*/
int
@@ -418,13 +498,12 @@ TALER_TESTING_get_trait_planchet_secrets
unsigned int index,
struct TALER_PlanchetSecretsP **planchet_secrets);
-
/**
* Offer planchet secrets.
*
- * @param index which secrets to offer if there are multiple
- * on offer
+ * @param index of the trait.
* @param planchet_secrets set to the offered secrets.
+ *
* @return the trait
*/
struct TALER_TESTING_Trait
@@ -436,8 +515,8 @@ TALER_TESTING_make_trait_planchet_secrets
* Offer tip id.
*
* @param index which tip id to offer if there are
- * multiple on offer
- * @param planchet_secrets set to the offered secrets.
+ * multiple on offer.
+ * @param tip_id set to the offered tip id.
* @return the trait
*/
struct TALER_TESTING_Trait
@@ -445,14 +524,14 @@ TALER_TESTING_make_trait_tip_id
(unsigned int index,
const struct GNUNET_HashCode *tip_id);
-
/**
* Obtain tip id from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param index which signature to pick if @a cmd has multiple
- * on offer
+ * @param cmd command to extract the trait from.
+ * @param index which tip id to pick if @a
+ * cmd has multiple on offer
* @param tip_id[out] set to the wanted data.
+ *
* @return #GNUNET_OK on success
*/
int
@@ -464,9 +543,11 @@ TALER_TESTING_get_trait_tip_id
/**
* Offer contract terms hash code.
*
- * @param index which hash code to offer if there are
- * multiple on offer
- * @param h_contract_terms set to the offered hash code.
+ * @param index which hashed contract terms to
+ * offer if there are multiple on offer
+ * @param h_contract_terms set to the offered hashed
+ * contract terms.
+ *
* @return the trait
*/
struct TALER_TESTING_Trait
@@ -477,10 +558,10 @@ TALER_TESTING_make_trait_h_contract_terms
/**
* Obtain contract terms hash from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param index which hash code to pick if @a cmd has multiple
- * on offer
+ * @param cmd command to extract the trait from.
+ * @param index index number of the trait to fetch.
* @param h_contract_terms[out] set to the wanted data.
+ *
* @return #GNUNET_OK on success
*/
int
@@ -489,13 +570,12 @@ TALER_TESTING_get_trait_h_contract_terms
unsigned int index,
const struct GNUNET_HashCode **h_contract_terms);
-
/**
* Offer refund entry.
*
- * @param index which tip id to offer if there are
- * multiple on offer
+ * @param index index number of the trait to offer.
* @param refund_entry set to the offered refund entry.
+ *
* @return the trait
*/
struct TALER_TESTING_Trait
@@ -507,10 +587,10 @@ TALER_TESTING_make_trait_refund_entry
/**
* Obtain refund entry from a @a cmd.
*
- * @param cmd command to extract trait from
- * @param index which signature to pick if @a cmd has multiple
- * on offer
+ * @param cmd command to extract the trait from.
+ * @param index the trait index.
* @param refund_entry[out] set to the wanted data.
+ *
* @return #GNUNET_OK on success
*/
int
@@ -519,9 +599,23 @@ TALER_TESTING_get_trait_refund_entry
unsigned int index,
const struct TALER_MERCHANT_RefundEntry **refund_entry);
-
/**
- * FIXME
+ * Create a /tip-authorize CMD, specifying the Taler error code
+ * that is expected to be returned by the backend.
+ *
+ * @param label this command label
+ * @param merchant_url the base URL of the merchant that will
+ * serve the /tip-authorize request.
+ * @param exchange_url the base URL of the exchange that owns
+ * the reserve from which the tip is going to be gotten.
+ * @param ctx the CURL context to carry on the HTTP work.
+ * @param http_status the HTTP response code which is expected
+ * for this operation.
+ * @param instance which merchant instance is running this CMD.
+ * @param justification human-readable justification for this
+ * tip authorization.
+ * @param amount the amount to authorize for tipping.
+ * @param ec expected Taler-defined error code.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_tip_authorize_with_ec
@@ -535,12 +629,36 @@ TALER_TESTING_cmd_tip_authorize_with_ec
const char *amount,
enum TALER_ErrorCode ec);
+
+/**
+ * This commands does not query the backend at all,
+ * but just makes up a fake authorization id that will
+ * be subsequently used by the "pick up" CMD in order
+ * to test against such a case.
+ *
+ * @param label command label.
+ *
+ * @return the command.
+ */
struct TALER_TESTING_Command
TALER_TESTING_cmd_tip_authorize_fake
(const char *label);
/**
- * FIXME
+ * Create a /tip-authorize CMD.
+ *
+ * @param label this command label
+ * @param merchant_url the base URL of the merchant that will
+ * serve the /tip-authorize request.
+ * @param exchange_url the base URL of the exchange that owns
+ * the reserve from which the tip is going to be gotten.
+ * @param ctx the CURL context to carry on the HTTP work.
+ * @param http_status the HTTP response code which is expected
+ * for this operation.
+ * @param instance which merchant instance is running this CMD.
+ * @param justification human-readable justification for this
+ * tip authorization.
+ * @param amount the amount to authorize for tipping.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_tip_authorize (const char *label,
@@ -553,7 +671,15 @@ TALER_TESTING_cmd_tip_authorize (const char *label,
const char *amount);
/**
- * FIXME
+ * Define a /tip-query CMD.
+ *
+ * @param label the command label
+ * @param merchant_url base URL of the merchant which will
+ * server the /tip-query request.
+ * @param ctx CURL context to carry on the HTTP work.
+ * @param http_status expected HTTP response code for the
+ * /tip-query request.
+ * @param instance the merchant instance running this CMD.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_tip_query (const char *label,
@@ -561,9 +687,21 @@ TALER_TESTING_cmd_tip_query (const char *label,
struct GNUNET_CURL_Context *ctx,
unsigned int http_status,
const char *instance);
-
/**
- * FIXME
+ * Define a /tip-query CMD equipped with a expected amount.
+ *
+ * @param label the command label
+ * @param merchant_url base URL of the merchant which will
+ * server the /tip-query request.
+ * @param ctx CURL context to carry on the HTTP work.
+ * @param http_status expected HTTP response code for the
+ * /tip-query request.
+ * @param instance the merchant instance running this CMD.
+ * @param expected_amount_picked_up expected amount already
+ * picked up.
+ * @param expected_amount_authorized expected amount that was
+ * authorized in the first place.
+ * @param expected_amount_available FIXME what is this?
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_tip_query_with_amounts
@@ -576,9 +714,22 @@ TALER_TESTING_cmd_tip_query_with_amounts
const char *expected_amount_authorized,
const char *expected_amount_available);
-
/**
- * FIXME
+ * Define a /tip-pickup CMD, equipped with the expected error
+ * code.
+ *
+ * @param label the command label
+ * @param merchant_url base URL of the backend which will serve
+ * the /tip-pickup request.
+ * @param ctx CURL context to carry on HTTP work.
+ * @param http_status expected HTTP response code.
+ * @param authorize_reference reference to a /tip-autorize CMD
+ * that offers a tip id to pick up.
+ * @param amounts array of string-defined amounts that specifies
+ * which denominations will be accepted for tipping.
+ * @param exchange connection handle to the exchange that will
+ * eventually serve the withdraw operation.
+ * @param ec expected Taler error code.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_tip_pickup_with_ec
@@ -591,9 +742,20 @@ TALER_TESTING_cmd_tip_pickup_with_ec
struct TALER_EXCHANGE_Handle *exchange,
enum TALER_ErrorCode ec);
-
/**
- * FIXME
+ * Define a /tip-pickup CMD.
+ *
+ * @param label the command label
+ * @param merchant_url base URL of the backend which will serve
+ * the /tip-pickup request.
+ * @param ctx CURL context to carry on HTTP work.
+ * @param http_status expected HTTP response code.
+ * @param authorize_reference reference to a /tip-autorize CMD
+ * that offers a tip id to pick up.
+ * @param amounts array of string-defined amounts that specifies
+ * which denominations will be accepted for tipping.
+ * @param exchange connection handle to the exchange that will
+ * eventually serve the withdraw operation.
*/
struct TALER_TESTING_Command
TALER_TESTING_cmd_tip_pickup
@@ -612,7 +774,7 @@ TALER_TESTING_cmd_tip_pickup
* @param label command label
* @param new_ip new instruction pointer's value. Note that,
* when the next instruction will be called, the interpreter
- * will increment the ip under the hood so this value must be
+ * will increment the ip _anyway_ so this value must be
* set to the index of the instruction we want to execute next
* MINUS one.
* @param counter counts how many times the rewinding has