README: document tunnel-identifier routing; wait for assets before embedding failure screenshots

Author: jochen-testingbot

README.md

@@ -101,7 +101,19 @@ The plugin then finds the sessions through the TestingBot builds API. Without pe
 
 The TestingBot tunnel is a Java application: the agent needs **Java 11+** (17 LTS recommended) on its `PATH`. The tunnel jar is downloaded once and cached in `~/.cache/testingbot-tunnel`. Set `tunnel: false` if you don't need one.
 
-**Important:** for your tests' traffic to go through the tunnel, point them at the tunnel's local relay — `http://localhost:4445/wd/hub` — instead of `https://hub.testingbot.com/wd/hub`. Sessions created against the public hub do not use the tunnel. If another tunnel may already be running on the agent, move the relay to a different port with `tunnel-args: ["--se-port", "8446"]`.
+**Routing your tests through the tunnel** — two options:
+
+1. Point your tests at the tunnel's local relay, `http://localhost:4445/wd/hub`, instead of `https://hub.testingbot.com/wd/hub`. If another tunnel may already be running on the agent, move the relay to a different port with `tunnel-args: ["--se-port", "8446"]`.
+2. Keep using `https://hub.testingbot.com/wd/hub` and set a `tunnel-identifier` on the plugin; your tests then pass the same value (exported as `$TESTINGBOT_TUNNEL_IDENTIFIER`) as the `tunnel-identifier` capability in `tb:options`:
+
+```js
+capabilities: {
+  'tb:options': {
+    build: process.env.TESTINGBOT_BUILD,
+    'tunnel-identifier': process.env.TESTINGBOT_TUNNEL_IDENTIFIER,
+  }
+}
+```
 
 When a tunnel identifier is configured, it is exported as `$TESTINGBOT_TUNNEL_IDENTIFIER` so your tests can set the matching `tunnelIdentifier` capability.
 

hooks/post-command

@@ -118,8 +118,19 @@ if [[ "${annotate_enabled}" == "true" ]]; then
     details="${STATE_DIR}/tests.jsonl"
     : >"${details}"
     while read -r sid _; do
-      if tb_get_test "${sid}" >>"${details}"; then
-        echo >>"${details}"
+      if resp="$(tb_get_test "${sid}")"; then
+        # screenshots/video are processed shortly after a session ends; wait
+        # briefly on failed tests so the annotation can embed a screenshot
+        if plugin_read_bool THUMBNAILS "true"; then
+          attempts=0
+          while [[ "$(echo "${resp}" | jq -r '(.success == true or .success == 1) or (.assets_available == true)')" != "true" ]] \
+            && [[ "${attempts}" -lt 6 ]]; do
+            sleep "${TESTINGBOT_PLUGIN_POLL_INTERVAL:-5}"
+            attempts=$((attempts + 1))
+            resp="$(tb_get_test "${sid}")" || break
+          done
+        fi
+        printf '%s\n' "${resp}" >>"${details}"
       else
         soft_fail "Failed to fetch details of TestingBot test ${sid}"
       fi