feat(linux): add --remote-debug flag to run-tests.sh script

This allows to run the tests in a VM and debug them remotely. Also
document debugging the integration tests, and improve the output if
dependencies are missing.

docs/settings/linux/launch.json

@@ -40,7 +40,7 @@
       "valuesFormatting": "parseText"
     },
     {
-      // start: gdbserver 10.3.0.58:2345 /media/sf_Develop/keyman/keyman/linux/build/x86_64/debug/tests/ibus-keyman-tests
+      // start: linux/ibus-keyman/tests/scripts/run-tests.sh --remote-debug --no-surrounding-text --no-wayland -- k_001___basic_input_unicodei
       // then attach debugger in vscode
       "type": "gdb",
       "request": "attach",

linux/ibus-keyman/src/test/run-tests.sh

@@ -15,6 +15,7 @@ fi
 
 if ! which Xvfb > /dev/null || ! which Xephyr > /dev/null || ! which metacity > /dev/null; then
   echo "# Please install Xvfb, Xephyr and metacity before running these tests!"
+  echo "# sudo apt install xvfb xserver-xephyr metacity"
   exit 1
 fi
 

linux/ibus-keyman/tests/README.md

@@ -24,3 +24,26 @@ To run a single test you pass the testname (as found in
 ```bash
 scripts/run-tests.sh -- k_000___null_keyboard k_005___nul_with_initial_context
 ```
+
+## Debugging tests
+
+This is easiest done by running the tests in a VM and then remote debugging
+into the VM. The VM should be the same Linux version as the host, and the
+Keyman repo should be shared with the VM through a shared folder.
+
+Then you can start the `run-tests.sh` script on the VM with the
+`--remote-debug` option. This will start the background services and then
+start a GDB session waiting for the debugger to connect.
+
+For example:
+
+```bash
+linux/ibus-keyman/tests/scripts/run-tests.sh --remote-debug \
+  --no-surrounding-text --no-wayland -- k_001___basic_input_unicodei
+```
+
+On the host, you can then attach to the VM. See the
+`Attach to gdbserver (ibus-keyman integration tests)` configuration
+in `docs/settings/linux/launch.json` for a sample configuration in
+vscode. You'll have to adjust the IP address to match the VM which the
+`run-tests.sh` script will output.

linux/ibus-keyman/tests/scripts/run-single-test.sh

@@ -16,6 +16,7 @@ fi
 
 if ! which Xvfb > /dev/null || ! which Xephyr > /dev/null || ! which metacity > /dev/null || ! which mutter > /dev/null; then
   echo "Please install Xvfb, Xephyr, metacity and mutter before running these tests!"
+  echo "sudo apt install xvfb xserver-xephyr metacity mutter"
   exit 1
 fi
 

linux/ibus-keyman/tests/scripts/run-tests.sh

@@ -25,6 +25,7 @@ fi
 
 if ! which Xvfb > /dev/null || ! which Xephyr > /dev/null || ! which metacity > /dev/null || ! which mutter > /dev/null; then
   echo "Please install Xvfb, Xephyr, metacity and mutter before running these tests!"
+  echo "sudo apt install xvfb xserver-xephyr metacity mutter"
   exit 1
 fi
 
@@ -36,6 +37,7 @@ function help() {
   echo "  --help, -h, -?          Display this help"
   echo "  --verbose, -v           Run tests verbosely"
   echo "  --debug                 debug test logging output"
+  echo "  --remote-debug          start gdbserver after setup but prior to running the tests"
   echo "  -k                      passed to GLib testing framework"
   echo "  --tap                   output in TAP format. Passed to GLib testing framework"
   echo "  --surrounding-text      run tests with surrounding texts enabled"
@@ -86,10 +88,14 @@ function run_tests() {
   source "$ENV_FILE"
   echo "DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS"
 
+  if [[ -n ${REMOTE_DEBUG:-} ]]; then
+    echo "===> Now attach debugger to ${REMOTE_HOST}"
+  fi
+
   # Note: -k and --tap are consumed by the GLib testing framework
   #shellcheck disable=SC2068 # we want to split array elements!
   #shellcheck disable=SC2086
-  "${G_TEST_BUILDDIR:-../../build/$(arch)/${CONFIG}/tests}/ibus-keyman-tests" ${ARG_K-} ${ARG_TAP-} \
+  ${REMOTE_DEBUG:-} "${G_TEST_BUILDDIR:-../../build/$(arch)/${CONFIG}/tests}/ibus-keyman-tests" ${ARG_K-} ${ARG_TAP-} \
     ${ARG_VERBOSE-} ${ARG_DEBUG-} ${ARG_SURROUNDING_TEXT-} ${ARG_NO_SURROUNDING_TEXT-} \
     --directory "$TESTDIR" "${DISPLAY_SERVER}" ${TESTFILES[@]}
   echo "# Finished tests."
@@ -111,6 +117,7 @@ while (( $# )); do
     --no-x11) USE_X11=0;;
     --verbose|-v) ARG_VERBOSE=--verbose;;
     --debug) ARG_DEBUG=--debug-log;;
+    --remote-debug) REMOTE_HOST="$(ip route get 8.8.8.8 | sed -E 's/.*src (\S+) .*/\1/;t;d'):2345" && REMOTE_DEBUG="gdbserver ${REMOTE_HOST}";;
     --) shift && break ;;
     *) echo "Error: Unexpected argument \"$1\". Exiting." ; exit 4 ;;
   esac

linux/ibus-keyman/tests/scripts/test-helper.inc.sh

@@ -256,7 +256,7 @@ function _setup_ibus() {
     echo "if kill -9 ${PID}; then ibus restart || ibus start; fi # ibus-daemon" >> "${CLEANUP_FILE}"
   else
     # test run as part of the build
-    echo "kill -9 ${PID} || true" >> "${CLEANUP_FILE}"
+    echo "kill -9 ${PID} || true # ibus-daemon" >> "${CLEANUP_FILE}"
   fi
   echo "${PID} ibus-daemon" >> "${PID_FILE}"
   sleep 1s