instructions for integration tests with the wallet

1 files changed, 61 insertions, 0 deletions

diff --git a/taler-wallet.rst b/taler-wallet.rst
index bb9b34e8..995237bd 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -78,3 +78,64 @@ APIs and Data Formats
 =====================
 
 *TBD.*
+
+
+
+Integration Test Example
+========================
+
+Integration tests can be done with the low-level wallet commands.  To select which coins and denominations
+to use, the wallet can dump the coins in an easy-to-process format (`CoinDumpJson <https://git.taler.net/wallet-core.git/tree/src/types/talerTypes.ts#n734>`__).
+
+The following example does a simple withdrawal recoup:
+
+.. code-block:: sh
+
+  # Withdraw digital cash
+  $ taler-wallet-cli --wallet-db=mydb.json testing withdraw \
+      -b https://bank.int.taler.net/ \
+      -e https://exchange.int.taler.net/ \
+      -a INTKUDOS:10
+
+  $ coins=$(taler-wallet-cli --wallet-db=mydb.json advanced dump-coins)
+
+  # Find coin we want to revoke
+  $ rc=$(echo "$coins" | jq -r '[.coins[] | select((.denom_value == "INTKUDOS:5"))][0] | .coin_pub')
+  # Find the denom
+  $ rd=$(echo "$coins" | jq -r '[.coins[] | select((.denom_value == "INTKUDOS:5"))][0] | .denom_pub_hash')
+  # Find all other coins, which will be suspended
+  $ susp=$(echo "$coins" | jq --arg rc "$rc" '[.coins[] | select(.coin_pub != $rc) | .coin_pub]')
+
+  # The exchange revokes the denom
+  $ taler-exchange-keyup -r $rd
+  $ taler-deployment-restart
+
+  # Now we suspend the other coins, so later we will pay with the recouped coin
+  $ taler-wallet-cli --wallet-db=mydb.json advanced suspend-coins "$susp"
+
+  # Update exchange /keys so recoup gets scheduled
+  $ taler-wallet-cli --wallet-db=mydb.json exchanges update -f https://exchange.int.taler.net/
+
+  # Block until scheduled operations are done
+  $ taler-wallet-cli --wallet-db=mydb.json run-until-done
+
+  # Now we buy something, only the coins resulting from recouped will be
+  # used, as other ones are suspended
+  $ taler-wallet-cli --wallet-db=mydb.json testing test-pay -m https://backend.int.taler.net/ -k sandbox -a "INTKUDOS:1" -s "foo"
+  $ taler-wallet-cli --wallet-db=mydb.json run-until-done
+
+
+To test refreshing, force a refresh:
+
+.. code-block:: sh
+
+  $ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub"
+
+
+To test zombie coins, use the timetravel option, it **must** be passed to the top-level command and not the subcommand:
+
+.. code-block:: sh
+
+  # Update exchange /keys with time travel, value in microseconds
+  $ taler-wallet-cli --timetravel=1000000 --wallet-db=mydb.json exchanges update -f https://exchange.int.taler.net/
+