Package: lnpbp-testkit
LNP/BP TestkitA framework for writing automated tests of applications built on top of LNP/BPAboutThis framework allows you to easily test flow in your application involving LNP/BP payments.
The usual flow is:Create a payment request (BIP21 or BOLT11) in the applicationPay the requestCheck if the application received the paymentThis looks simple, but the step #2 is far from trivial.
It involves setting up regtest bitcoind, two LN nodes, opening a sufficiently big channel between the nodes, using the appropriate RPC API...
The aim of this project is to make step #2 two lines of Python:fromlnpbp_testkit.cadrimportnetworknetwork().auto_pay(request)As you can see fromcadr, this integrates withCryptoanarchy Debian Repositorywhich is recommended but not mandatory.
Read below for instructions on standalone use.Supported and wanted featuresPay any BIP21 request (withbitcoin:scheme)Pay any BOLT11 invoice (with or withoutlightning:scheme)Pay custom amount to chain addressPay using LNURL-payPay using LNURL-withdrawPay using LN keysendPay using PayJoinWithdraw using BIP21 requestWithdraw using chain addressWithdraw using BOLT11Withdraw using LNURL-withdrawWithdraw using LNURL-payWithdraw using LN keysendWithdraw using PayJoinSupport more complicated situations involving multiple LN nodesSupport non-LND LN implementationsFeel free to submit PRs for wanted features!
(If you're confused about LNURL: withdraw using pay and pay using withdraw are useful if you're testing wallets, not services.)UsageWith Cryptoanarchy Debian Repository (recommended)The Testkit is in the repository, justapt install python3-lnpbp-testkit.Important: do NOT install it outside of apt! Versions different than what's in the repository may not work.If you don't have passwordlesssudoyou must set the permissions usingsudo usermod -a -G bitcoin-regtest,lnd-system-regtest $USER.
The Testkit assumes your application is integrated with the repository too,
specifically withbitcoin-regtest/lnd-system-regtest.Once you have created and obtained the payment request (e.g. using Selenium) you can just calllnpbp_testkit.cadr.network().auto_pay(request)to pay it.Yes, it's that simple. :)Without Cryptoanarchy Debian RepositoryMake sure you havesystemdinstalled and active (warning: this is not the default in most Docker images!)Installlndinto your$PATHSetup regtestbitcoindSetup regtestlndconnected tobitcoindCopylnd-testkit-regtest@.servicefile from this repository into/etc/systemd/user/InstantiateNetworkby supplying the required parameters:network_config={"bitcoind_url":"USERNAME:PASSWORD@HOST:PORT","bitcoind_public_port":BITCOIN_RPC_PROXY_PORT,# optional, the port from bitcoind_url will be used if not present"zmq_tx_port":ZMQPUBRAWTX_PORT,"zmq_block_port":ZMQPUBRAWBLOCK_PORT,"lnd_host":"REST_HOST:REST_PORT","lnd_macaroon":"HEX_ENCODED_MACAROON","lnd_tls_cert_file":"PATH_TO_LND_TLS_CERTIFICATE",}network=lnpbp_testkit.Network(network_config)You can now pay the request usingnetwork.auto_pay()FAQHow do I pay an arbitrary amount to a chain address?Useauto_pay_legacy(address, decimal_amount)instead ofauto_payDo I need to generate coins before I can pay the BIP21 request?No, it's automatic, ad-hoc.How do I setup the channels between the nodes?Don't, it's automatic, ad-hoc based on the amount in the invoice.Do I need to create a Debian package for my application in order to test the integration with Cryptoanarchy Debian Repository?No, just configure it with the appropriate settings and launch it before running the test.
That being said, it'd be nice if you avoid hard-coding the parameters of your app into the test - it will make writing tests for packaged application easier.
I plan to support this use case more explicitly in the future.
It will be useful in CI to save time by skipping build of the Debian package.Why doesauto_pay()take so long to execute?One of the key features ofauto_pay()is that it generates coins/sets up channels on-demand.
It also spawns secondary LN node when needed.
This obviously takes some time and LND isn't particularly fast when it comes to initialization.
If you want to improve it, consider writing a PR against LND to speed it up, or complaining at their repository.
As another optimization, you can call thewarm_up()method at the beginning of the test.
This will start LND asynchronously, so that you can perform other operations (such as setting up a web service using Selenium) in parallel to LND initializing.Does this project use semantic versioning?Yes. 0.2.0 will mean breaking change.