Add build / run / test categories docs

apitest/docs/README.md

@@ -0,0 +1,5 @@
+# Bisq apitest docs
+
+ - [build-run.md](build-run.md): Build and run API tests at the command line and from Intellij
+ - [test-categories.md](test-categories.md): Learn about the Bisq testing process and how you can contribute.
+ - [regtest-port-conflicts.md](regtest-port-conflicts.md): (deprecated) Set up a complete Bisq DAO development environment

apitest/docs/build-run.md

@@ -0,0 +1,61 @@
+# Build and Run API Test Harness
+
+## Linux & OSX
+
+The API test harness uses the GNU Bourne-Again SHell `bash`, and is not supported on Windows.
+
+## Predefined DAO / Regtest Setup
+
+The API test harness depends on the contents of https://github.com/bisq-network/bisq/raw/master/docs/dao-setup.zip.
+The files contained in dao-setup.zip include a bitcoin-core wallet, a regtest genesis tx and chain of 111 blocks, plus
+data directories for Bob and Alice Bisq instances.  Bob & Alice wallets are pre-configured with 10 BTC each, and the
+equivalent of 2.5 BTC in BSQ distributed among Bob & Alice's BSQ wallets.
+
+See https://github.com/bisq-network/bisq/blob/master/docs/dao-setup.md for details.
+
+## Install DAO / Regtest Setup Files
+
+Bisq's gradle build file defines a task for downloading dao-setup.zip and extracting its contents to the
+`apitest/src/main/resources` folder, and the test harness will install a fresh set of data files to the
+`apitest/build/resources/main` folder during a test case's scaffold setup phase -- normally a static `@BeforeAll` method.
+
+The dao-setup files can be downloaded during a normal build:
+
+    $ ./gradlew clean build :apitest:installDaoSetup
+
+Or by running a single task:
+
+    $ ./gradlew :apitest:installDaoSetup
+
+The `:apitest:installDaoSetup` task does not need to be run again until after the next time you run the gradle `clean` task.
+
+## Run API Tests
+
+The API test harness supports narrow & broad functional and full end to end test cases requiring
+long setup and teardown times -- for example, to start a bitcoind instance, seednode, arbnode, plus Bob & Alice
+Bisq instances, then shut everything down in proper order.  For this reason, API test cases do not run during a normal
+gradle build.
+
+To run API test cases, pass system property`-DrunApiTests=true`.
+
+To run all existing test cases:
+
+    $ ./gradlew  :apitest:test -DrunApiTests=true
+
+To run all test cases in a package:
+
+    $ ./gradlew  :apitest:test --tests "bisq.apitest.method.*" -DrunApiTests=true
+
+To run a single test case:
+
+    $ ./gradlew  :apitest:test --tests "bisq.apitest.method.GetBalanceTest" -DrunApiTests=true
+
+## Gradle Test Reports
+
+To see detailed test results, logs, and full stack traces for test failures, open
+`apitest/build/reports/tests/test/index.html` in a browser.
+
+## See also
+
+ - [test-categories.md](test-categories.md)
+

apitest/docs/test-categories.md

@@ -0,0 +1,35 @@
+# API Test Categories
+
+This guide describes the categorization of tests.
+
+## Method Tests
+
+A `method` test is the `apitest` analog of a unit test.  It tests a single API method such as `getbalance`, but is not
+considered a unit test because the code execution path traverses so many layers:  from `gRPC` client -> `gRPC` server
+side service -> one or more Bisq `core` services, and back to the client.
+
+Method tests have direct access to `gRPC` client stubs, and test asserts are made directly on `gRPC` return values --
+Java Objects.
+
+All `method` tests are part of the `bisq.apitest.method` package.
+
+## Scenario Tests
+
+A `scenario` test is a narrow or broad functional test case covering a simple use case such as funding a wallet to a
+complex series of trades.  Generally, a scenario test case requires multiple `gRPC` method calls.
+
+Scenario tests have direct access to `gRPC` client stubs, and test asserts are made directly on `gRPC` return values --
+Java Objects.
+
+All `scenario` tests are part of the `bisq.apitest.scenario` package.
+
+## End to End Tests
+
+An end to end (`e2e`) test can cover a narrow or broad use case, and all client calls go through the `CLI` shell script
+`bisq-cli`.  End to end tests do not have access to `gRPC` client stubs, and test asserts are made on what the end
+user sees on the console -- what`gRPC CLI` prints to `STDOUT`.
+
+As test coverage grows, stable scenario test cases should be migrated to `e2e` test cases.
+
+All `e2e` tests are part of the `bisq.apitest.e2e` package.
+