feat(appium): add Unity SDK support

[fadi-george]

Description

Adds Unity SDK support to the Appium test suite alongside a series of fixes and refactors that make the cross-platform test runs more reliable.

Details

Unity support

• Add Unity SDK support to Appium tests with build caching keyed off relevant source paths (now includes *.java)
• Bump Unity to 6000.4.6f1 and deduplicate xcodebuild invocations
• Improve Unity build failure hints
• Improve Unity modal confirmation flow and avoid accidental taps on Unity iOS
• Extract isUnitySDK constant for clarity

Helpers and reliability

• Extract openModal helper; simplify it and drop the Unity-specific retry
• Add waitForDisappear helper (renamed from waitForTestIdNotDisplayed)
• Wait for the scroll view after IAM close
• Extend the IAM retry-tap behavior to native iOS
• Suppress first-attempt log noise
• Remove unused isWebViewVisible import

Dependencies

• Bump deps and pin vite-plus to 0.1.20

Scope

Changes are limited to the appium/ directory: helpers, selectors, specs, the local run script, and dependency manifests. No production SDK code is touched.

Made with Cursor

[fadi-george]

@claude review

[fadi-george]

@claude[agent] review

[fadi-george]

@claude review

[claude]

🔴 Empty SPEC normalization (line 118-125) rewrites the default SPEC="" to tests/specs/*.spec.ts, which then satisfies the if [[ -n "$SPEC" ]] check in run_tests (lines 1591-1593) and gets forwarded to wdio. This silently defeats the grouped-spec optimization the comment at lines 1587-1589 explicitly warns about, costing ~2-6 min of extra iOS session-setup overhead on every no-flag invocation. Gate the case with if [[ -n "$SPEC" ]] or add a "") ;; arm.

Extended reasoning...

What the bug is

SPEC defaults to "" at line 31, and the new --spec normalization at lines 118-125 runs unconditionally on it:

case "$SPEC" in
  */*|*\**|*\?*) ;;
  *)
    base="${SPEC%.spec.ts}"
    base="${base%.ts}"
    SPEC="tests/specs/${base}*.spec.ts"
    ;;
esac

The empty string contains no /, no *, and no ?, so it matches none of the early-exit alternatives and falls into the default arm. Both ${SPEC%.spec.ts} and ${base%.ts} leave base empty, and the final assignment produces SPEC="tests/specs/*.spec.ts".

Why this defeats the explicit optimization

run_tests at lines 1581-1596 reads:

# Only forward --spec when the user explicitly overrode it. Passing --spec
# to wdio re-expands the glob into one runner per file (~10-30s of session
# setup each on iOS) and bypasses the grouped specs in the conf.
local -a wdio_args=("$conf")
if [[ -n "$SPEC" ]]; then
  info "Running tests (conf: $conf, spec: $SPEC)..."
  wdio_args+=(--spec "$SPEC")
else
  info "Running tests (conf: $conf, spec: <conf default>)..."
fi

After the normalization, SPEC is non-empty for every no-flag invocation, so the [[ -n "$SPEC" ]] branch always wins and --spec tests/specs/*.spec.ts is forwarded to wdio. That is the exact scenario the comment was written to prevent. The grouped-spec configuration in wdio.ios.conf.ts / wdio.android.conf.ts becomes unreachable on the default path, and wdio.shared.conf.ts lines 37-38 explicitly pre-expand the glob into a single array element with a matching comment: "Pre-expand the glob so WDIO groups all specs into one runner and reuses a single Appium session (a raw glob or --spec flag spawns one runner per file, costing ~10-30s of iOS session setup each)."

Step-by-step proof

1. User runs ./scripts/run-local.sh --platform=ios --sdk=unity (no --spec flag).
2. Line 31: SPEC="". No CLI override.
3. Lines 118-125: case statement runs. Empty string matches none of */*, *\**, *\?* (each requires the literal char to appear), so falls into default arm.
4. base="${SPEC%.spec.ts}" → base="".
5. base="${base%.ts}" → base="".
6. SPEC="tests/specs/${base}*.spec.ts" → SPEC="tests/specs/*.spec.ts".
7. Later in run_tests: line 1591 [[ -n "$SPEC" ]] → true. wdio_args+=(--spec "tests/specs/*.spec.ts").
8. wdio re-expands the glob and spawns one runner per spec file (~12 specs on iOS × ~10-30s session setup = ~2-6 min wasted per run).

Verified locally: bash -c 'SPEC=""; case "$SPEC" in */*|*\**|*\?*) ;; *) base="${SPEC%.spec.ts}"; base="${base%.ts}"; SPEC="tests/specs/${base}*.spec.ts" ;; esac; echo "$SPEC"' prints tests/specs/*.spec.ts.

Impact

Every no-flag invocation — by far the most common path — now incurs ~2-6 min of extra iOS session-setup overhead and the grouped-spec configuration in the conf files becomes dead code. Functional tests still pass; this is a perf regression, but a measurable one that directly contradicts the explicit intent in the same area of code (the warning comment lives just five lines above the forwarding code).

Fix

Either gate the case on a non-empty SPEC:

if [[ -n "$SPEC" ]]; then
  case "$SPEC" in
    */*|*\**|*\?*) ;;
    *)
      base="${SPEC%.spec.ts}"
      base="${base%.ts}"
      SPEC="tests/specs/${base}*.spec.ts"
      ;;
  esac
fi

Or add an empty-string arm to the case:

case "$SPEC" in
  ""|*/*|*\**|*\?*) ;;
  *)
    base="${SPEC%.spec.ts}"
    base="${base%.ts}"
    SPEC="tests/specs/${base}*.spec.ts"
    ;;
esac

Either way the no-flag path keeps SPEC empty so run_tests falls through to the grouped specs in the conf, restoring the optimization the comment promises.

[claude]

🔴 The 'can pause iam' test calls isWebViewVisible() on lines 41 and 51, but the symbol is no longer in the named imports on line 1 (only checkInAppMessage, checkTooltip, scrollToEl, waitForAppReady are imported). This causes a TypeScript compile error (TS2304) and a runtime ReferenceError, breaking the entire spec. Add isWebViewVisible back to the import list.

Extended reasoning...

What the bug is

appium/tests/specs/03_iam.spec.ts at HEAD has:

import { checkInAppMessage, checkTooltip, scrollToEl, waitForAppReady } from '../helpers/app';

But the body of the 'can pause iam' test uses isWebViewVisible() twice:

• Line 41: await driver.waitUntil(async () => !(await isWebViewVisible()), { ... }) — drains a lingering IAM context before asserting that pause is effective.
• Line 51: expect(await isWebViewVisible()).toBe(false); — the actual pause-effective assertion.

The PR description says 'Remove unused isWebViewVisible import', which was correct at the time the import was removed. A subsequent edit re-introduced the pause-effective assertion (and a drain check) without restoring the import.

Why existing code doesn't prevent it

isWebViewVisible is exported from appium/tests/helpers/app.ts (export async function isWebViewVisible() at app.ts:869), so the symbol exists in the module graph. The spec file just never pulls it in. There is no fallback / global definition: TypeScript will flag this as TS2304 (Cannot find name 'isWebViewVisible') and Node/tsx will throw a ReferenceError at runtime as soon as the test function executes.

Code path that triggers it

1. wdio run wdio.ios.conf.ts loads tests/specs/03_iam.spec.ts via the tsx loader.
2. tsx type-checks the file (or at minimum module-resolves it). TS2304 fires on lines 41 and 51 — the build fails before any test runs.
3. Even if type checking is skipped (transpile-only mode), at runtime the 'can pause iam' test calls isWebViewVisible(), hits a ReferenceError, and Mocha records the test as failed.

Impact

Breaks the entire 03_iam.spec.ts spec on every run for every SDK/platform combination. The PR check that runs this file will fail. Other tests in the same describe block ('should show correct tooltip info', the four IAM-type cases) may still execute, but the 'can pause iam' test will always fail.

Step-by-step proof

Take any SDK/platform pair where this spec runs (e.g. Unity iOS):

1. Test runner starts it('can pause iam', ...) (line 32).
2. Lines 33-38: scroll to and click the pause toggle.
3. Line 41: JavaScript evaluates the arrow function. isWebViewVisible is not in scope (no import, no global, no var/let/const declaration). ReferenceError: isWebViewVisible is not defined is thrown.
4. driver.waitUntil surfaces the rejection. Mocha marks the test failed.
5. Even if line 41 somehow passed, line 51 would throw the same ReferenceError.

Fix

One-line change at line 1:

-import { checkInAppMessage, checkTooltip, scrollToEl, waitForAppReady } from '../helpers/app';
+import {
+  checkInAppMessage,
+  checkTooltip,
+  isWebViewVisible,
+  scrollToEl,
+  waitForAppReady,
+} from '../helpers/app';

No other changes needed — isWebViewVisible is already exported from ../helpers/app.