Add API test harness for Linux & OSX

apitest/dao-setup.gradle

@@ -0,0 +1,83 @@
+// This gradle file contains tasks to install and clean dao-setup files downloaded from
+//          https://github.com/bisq-network/bisq/raw/master/docs/dao-setup.zip
+// These tasks are not run by the default build, but they can can be run during a full
+// or partial builds, or by themselves.
+// To run a full Bisq clean build, test, and install dao-setup files:
+//      ./gradlew clean build :apitest:installDaoSetup
+// To install or re-install dao-setup file only:
+//      ./gradlew :apitest:installDaoSetup -x test
+// To clean installed dao-setup files:
+//      ./gradlew :apitest:cleanDaoSetup -x test
+//
+// The :apitest subproject will not run on Windows, and these tasks have not been
+// tested on Windows.
+def buildResourcesDir = project(":apitest").buildDir.path + '/resources/main'
+
+// This task requires ant in the system $PATH.
+task installDaoSetup(dependsOn: 'cleanDaoSetup') {
+    doLast {
+        println "Installing dao-setup directories in build dir $buildResourcesDir ..."
+        def src = 'https://github.com/bisq-network/bisq/raw/master/docs/dao-setup.zip'
+        def destfile = project.rootDir.path + '/apitest/src/main/resources/dao-setup.zip'
+        def url = new URL(src)
+        def f = new File(destfile)
+        if (f.exists()) {
+            println "File $destfile already exists, skipping download."
+        } else {
+            if (!f.parentFile.exists())
+                mkdir "$buildResourcesDir"
+
+            println "Downloading $url to $buildResourcesDir ..."
+            url.withInputStream { i -> f.withOutputStream { it << i } }
+        }
+
+        // We need an ant task for unzipping the dao-setup.zip file.
+        println "Unzipping $destfile to $buildResourcesDir ..."
+        ant.unzip(src: 'src/main/resources/dao-setup.zip',
+                dest: 'src/main/resources',
+                overwrite: "true") {
+            // Warning: overwrite: "true" does not work if empty dirs exist, so the
+            // cleanDaoSetup task should be run before trying to re-install fresh
+            // dao-setup files.
+            patternset() {
+                include(name: '**')
+                exclude(name: '**/bitcoin.conf') // installed at runtime with correct blocknotify script path
+                exclude(name: '**/blocknotify')  // installed from src/main/resources to allow port configs
+            }
+            mapper(type: "identity")
+        }
+
+        // Copy files from unzip target dir 'dao-setup' to build/resources/main.
+        def daoSetupSrc = project.rootDir.path + '/apitest/src/main/resources/dao-setup'
+        def daoSetupDest = buildResourcesDir + '/dao-setup'
+        println "Copying $daoSetupSrc to $daoSetupDest ..."
+        copy {
+            from daoSetupSrc
+            into daoSetupDest
+        }
+
+        // Move dao-setup files from build/resources/main/dao-setup to build/resources/main
+        file(buildResourcesDir + '/dao-setup/Bitcoin-regtest')
+                .renameTo(file(buildResourcesDir + '/Bitcoin-regtest'))
+        file(buildResourcesDir + '/dao-setup/bisq-BTC_REGTEST_Alice_dao')
+                .renameTo(file(buildResourcesDir + '/bisq-BTC_REGTEST_Alice_dao'))
+        file(buildResourcesDir + '/dao-setup/bisq-BTC_REGTEST_Bob_dao')
+                .renameTo(file(buildResourcesDir + '/bisq-BTC_REGTEST_Bob_dao'))
+        delete file(buildResourcesDir + '/dao-setup')
+    }
+}
+
+task cleanDaoSetup {
+    doLast {
+        // When re-installing dao-setup files before re-running tests, the bitcoin
+        // datadir and dao-setup dirs have to be cleaned first.  This task allows
+        // you to re-install dao-setup files and re-run tests without having to
+        // re-compile any code.
+        println "Deleting dao-setup directories in build dir $buildResourcesDir ..."
+        delete file(buildResourcesDir + '/Bitcoin-regtest')
+        delete file(buildResourcesDir + '/bisq-BTC_REGTEST_Seed_2002')
+        delete file(buildResourcesDir + '/bisq-BTC_REGTEST_Arb_dao')
+        delete file(buildResourcesDir + '/bisq-BTC_REGTEST_Alice_dao')
+        delete file(buildResourcesDir + '/bisq-BTC_REGTEST_Bob_dao')
+    }
+}

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): How to categorize a test case as `method`, `scenario` or `e2e`.
+ - [regtest-port-conflicts.md](regtest-port-conflicts.md): Avoid port conflicts when running multiple bitcoin-core apps in regtest mode.

apitest/docs/build-run.md

@@ -0,0 +1,68 @@
+# 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
+
+To run test cases from Intellij, add two JVM arguments to your JUnit launchers:
+
+    -DrunApiTests=true -Dlogback.configurationFile=apitest/build/resources/main/logback.xml
+
+The `-Dlogback.configurationFile` property will prevent `logback` from printing warnings about multiple `logback.xml`
+files it will find in Bisq jars `cli.jar`, `daemon.jar`, and `seednode.jar`.
+
+## 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/regtest-port-conflicts.md

@@ -0,0 +1,12 @@
+# Avoiding bitcoin-core regtest port conflicts
+
+Some developers may already be running a `bitcoind` or `bitcoin-qt` instance in regtest mode when they try to run API
+test cases.  If a `bitcoin-qt` instance is bound to the default regtest port 18444, `apitest` will not be able to start
+its own bitcoind instances.
+
+Though it would be preferable for `apitest` to change the bind port for Bisq's `bitcoinj` module at runtime, this is
+not currently possible because `bitcoinj` hardcodes the default regtest mode bind port in `RegTestParams`.
+
+To avoid the bind address:port conflict, pass a port option to your bitcoin-core instance:
+
+    bitcoin-qt -regtest -port=20444

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

apitest/scripts/get-bisq-pid.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# Find the pid of the java process by grepping for the mainClassName and appName,
+# then print the 2nd column of the output to stdout.
+#
+# Doing this from Java is problematic, probably due to limitation of the
+# apitest.linux.BashCommand implementation.
+
+
+MAIN_CLASS_NAME=$1
+APP_NAME=$2
+
+# TODO args validation
+
+ps aux | grep java | grep "${MAIN_CLASS_NAME}" | grep "${APP_NAME}" | awk '{print $2}'

apitest/src/main/java/bisq/apitest/ApiTestMain.java

@@ -0,0 +1,80 @@
+/*
+ * This file is part of Bisq.
+ *
+ * Bisq is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at
+ * your option) any later version.
+ *
+ * Bisq is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+ * License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Bisq. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package bisq.apitest;
+
+import lombok.extern.slf4j.Slf4j;
+
+import static bisq.apitest.Scaffold.EXIT_FAILURE;
+import static bisq.apitest.Scaffold.EXIT_SUCCESS;
+import static java.lang.System.err;
+import static java.lang.System.exit;
+
+
+
+import bisq.apitest.config.ApiTestConfig;
+
+/**
+ * ApiTestMain is a placeholder for the gradle build file, which requires a valid
+ * 'mainClassName' property in the :apitest subproject configuration.
+ *
+ * It does has some uses:
+ *
+ * It can be used to print test scaffolding options:  bisq-apitest --help.
+ *
+ * It can be used to smoke test your bitcoind environment:  bisq-apitest.
+ *
+ * It can be used to run the regtest/dao environment for release testing:
+ * bisq-test --shutdownAfterTests=false
+ *
+ * All method, scenario and end to end tests are found in the test sources folder.
+ *
+ * Requires bitcoind v0.19.x
+ */
+@Slf4j
+public class ApiTestMain {
+
+    public static void main(String[] args) {
+        new ApiTestMain().execute(args);
+    }
+
+    public void execute(@SuppressWarnings("unused") String[] args) {
+        try {
+            Scaffold scaffold = new Scaffold(args).setUp();
+            ApiTestConfig config = scaffold.config;
+
+            if (config.skipTests) {
+                log.info("Skipping tests ...");
+            } else {
+                new SmokeTestBitcoind(config).run();
+            }
+
+            if (config.shutdownAfterTests) {
+                scaffold.tearDown();
+                exit(EXIT_SUCCESS);
+            } else {
+                log.info("Not shutting down scaffolding background processes will run until ^C / kill -15 is rcvd ...");
+            }
+
+        } catch (Throwable ex) {
+            err.println("Fault: An unexpected error occurred. " +
+                    "Please file a report at https://bisq.network/issues");
+            ex.printStackTrace(err);
+            exit(EXIT_FAILURE);
+        }
+    }
+}