itest: add readme

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
+```