diff --git a/itest/README.md b/itest/README.md new file mode 100644 index 000000000..6413a4e1f --- /dev/null +++ b/itest/README.md @@ -0,0 +1,106 @@ +# Integration Test + +`itest` is a package that houses the integration tests made for `lnd`. This +package builds test cases using the test framework `lntest`. + +## Add New Tests + +To add a new test case, create a `TestFunc` and add it in `list_on_test.go`. +Ideally, the `Name` should just be the snake case of the name used in +`TestFunc` without the leading `test` and underscores. For instance, to test +`lnd`'s exporting channel backup, we have, + +```go +{ + Name: "export channel backup", + TestFunc: testExportChannelBackup, +} +``` + +The place to put the code of the `TestFunc` is case-specific. `itest` package +has loosely defined a list of files to test different functionalities of `lnd`. +The new test needs to be put into one of these files, otherwise, a new file +needs to be created. + +## Run Tests + +#### Run a single test case + +To run a single test case, use `make itest icase=$case`, where `case` is the +name defined in `list_on_test.go`, with spaces replaced with underscores(`_`). + +```shell +# Run `testListChannels`. +make itest icase=list_channels +``` + +#### Run multiple test cases + +There are two ways to run multiple test cases. One way is to use `make itest +icase=$cases`, where `cases` has the format `cases='(case|case|...)'`. The +`case` is the name defined in `list_on_test.go`, with spaces replaced with +underscores(`_`). + +```shell +# Run `testListChannels` and `testListAddresses` together. +make itest icase='(list_channels|list_addresses)' +``` + +Another way to run multiple cases is similar to how Go runs its tests - by +simple regex matching. For instance, the following command will run three cases +since they all start with the word `list`, + +```shell +# Run `testListChannels`, `testListAddresses`, and `testListPayments` together. +make itest icase=list +``` + +#### Run all tests + +To run all tests, use `make itest` without `icase` flag. + +```shell +# Run all test cases. +make itest +``` + +#### Run tests in parallel + +To run tests in parallel, use `make itest-parallel`. This command takes two +special arguments, +- `tranches`, specifies the number of parts the test cases will be split into. +- `parallel`, specifies the number of threads to run in parallel. This value + must be smaller than or equal to `tranches`. + +```shell +# Split the tests into 4 parts, and run them using 2 threads. +make itest-parallel tranches=4 parallel=2 +``` + +By default, `itest-parallel` splits the tests into 4 parts and uses 4 threads +to run each of them. + +#### Additional arguments + +For both `make itest` and `make itest-parallel`, the following arguments are +allowed, +- `timeout`, specifies the timeout value used in testing. +- `dbbackend`, specifies the database backend. Must be `bbolt`, `etcd`, or + `postgres`, default to `bbolt`. +- `backend`, specifies the chain backend to be used. Must be one of, + - `btcd`, the default value. + - `neutrino` + - `bitcoind` + - `bitcoind notxindex` + - `bitcoind rpcpolling` + +```shell +# Run a single test case using bitcoind as the chain backend and etcd as the +# database backend, with a timeout of 5 minutes. +make itest icase=list_channels backend=bitcoind dbbackend=etcd timeout=5m + +# Run all test cases in parallel, using bitcoind notxindex as the chain backend +# and etcd as the database backend, with a timeout of 60 minutes for each +# parallel. +make itest-parallel backend="bitcoind notxindex" dbbackend=etcd timeout=60m +```