feat(tests): integration tests framework

Author: LemonNekoGH

docs/architecture.md

@@ -7,7 +7,7 @@ We are standardizing only the minimum plugin shape needed to support:
 - a Godot-facing Kirie service
 - a scene-friendly KirieView node
 - Android and iOS native WebView implementations
-- an example project used for integration testing
+- a repo-level platform integration test project
 
 Anything beyond that, such as dedicated protocol packages, CLI tooling, or
 adapters, is deferred until the IPC model is proven.

docs/platform-integration-tests.md

@@ -0,0 +1,220 @@
+# Platform Integration Tests
+
+Kirie platform integration tests live in a repo-level Godot project:
+
+```text
+tests/integration/
+```
+
+They are not Android instrumentation tests and are not part of
+`examples/basic-ipc`. Android and iOS should eventually run the same Godot test
+project; the platform only provides the WebView runtime and app launch
+mechanism.
+
+## Goals
+
+These tests cover the platform bridge path:
+
+```text
+Godot -> Kirie platform singleton -> platform WebView -> JavaScript -> Godot
+```
+
+The current focus is:
+
+- WebView lifecycle behavior from Godot
+- raw JavaScript bridge IPC
+- resource loading through `res://`
+- exported app behavior, not editor-only behavior
+
+The tests intentionally do not depend on the browser-facing `@kirie/ipc`
+package. That package is a convenience SDK above the raw bridge contract and
+should be tested separately.
+
+## Project Layout
+
+```text
+tests/integration/
+  project.godot
+  export_presets.cfg
+  main.tscn
+  addons/kirie -> ../../../packages/kirie/addon/addons/kirie
+  scripts/
+    test_runner.gd
+    test_probe.gd
+    test_cases/
+      ipc_round_trip_probe.gd
+      webview_lifecycle_probe.gd
+      res_asset_loading_probe.gd
+  web/
+    probe.html
+```
+
+`web/probe.html` is a minimal fixture, not a web app project. There is no Vite
+project, package.json, TypeScript config, or generated web bundle under
+`tests/integration/web`.
+
+## Runner Contract
+
+The exported app runs one test per app session.
+
+On Android, the runner reads the test name from the launch option:
+
+```text
+kirie_test
+```
+
+The Android plugin exposes this through:
+
+```gdscript
+Kirie.get_launch_option("kirie_test")
+```
+
+The runner also supports `--kirie-test=<name>` from Godot command-line user
+args for local non-Android runs.
+
+`scripts/test_runner.gd` owns only:
+
+- resolving the test name
+- loading `res://scripts/test_cases/<test_name>.gd`
+- calling `run(kirie, tree, test_name)`
+- printing pass/fail markers
+- quitting the app
+
+Test cases return a `String`:
+
+- `""` means pass
+- non-empty string means fail reason
+
+The runner prints exactly one final marker:
+
+```text
+KIRIE_TEST_PASS <test_name>
+KIRIE_TEST_FAIL <test_name> <reason>
+```
+
+## Test Case Contract
+
+Each test case owns its own lifecycle operations. A test should explicitly call
+the Kirie API it wants to exercise:
+
+- `create_webview()`
+- `load_html_string(...)`
+- `load_url(...)`
+- `send_ipc_message(...)`
+- `destroy_webview()`
+
+Shared waiting and probe observation lives in `scripts/test_probe.gd`.
+`KirieIntegrationProbe` may:
+
+- connect to Kirie signals
+- wait for `webview_ready`
+- collect `ipc_message_received`
+- wait for a specific probe message
+- read `web/probe.html`
+
+It should not decide which URL a test loads. Page URLs are test inputs and must
+be provided by the test case itself.
+
+## Web Fixture
+
+`web/probe.html` is a small raw bridge fixture. It uses the platform-level
+contract directly:
+
+- Android JavaScript to Godot:
+  `globalThis.KirieAndroidBridge.postMessage(messageJson)`
+- iOS JavaScript to Godot:
+  `globalThis.webkit.messageHandlers.kirie.postMessage(messageJson)`
+- Godot to JavaScript:
+  `kirie:ipc-message` DOM events
+
+For tests that do not care about asset loading, the GDScript case reads
+`probe.html` and injects it with `load_html_string(...)`. This keeps the test
+case in Godot while preserving HTML/JavaScript syntax highlighting in the
+fixture file.
+
+For tests that do care about exported resources, the case loads
+`res://web/probe.html?...` with `load_url(...)`.
+
+## Test Coverage Shape
+
+Individual test behavior belongs in `scripts/test_cases/*.gd`, not in this
+architecture note.
+
+The suite should stay organized around a small number of platform-facing
+coverage categories:
+
+- IPC round trips through the raw JavaScript bridge
+- WebView lifecycle transitions driven from Godot
+- exported `res://` web resource loading
+
+New tests should add a focused case under `scripts/test_cases/` when they need
+different lifecycle operations, a different loaded URL, or a different platform
+bridge assertion.
+
+## Android Local Flow
+
+Build the test APK:
+
+```bash
+scripts/build_integration_android.sh
+```
+
+Install it once:
+
+```bash
+adb install -r dist/integration/android_debug.apk
+```
+
+Run one test:
+
+```bash
+scripts/run_integration_android_test.sh ipc_round_trip_probe
+```
+
+The run script:
+
+- clears logcat
+- force-stops the package
+- clears app data
+- starts the exported app with `--es kirie_test <test_name>`
+- waits for `KIRIE_TEST_PASS` or `KIRIE_TEST_FAIL`
+
+The Android package defaults to:
+
+```text
+ai.moeru.kirie.integrationtests
+```
+
+The Android launcher component defaults to:
+
+```text
+com.godot.game.GodotAppLauncher
+```
+
+## Isolation Model
+
+Tests are isolated by app session:
+
+- export one test APK
+- install it once
+- run each test in a fresh app start
+- run `pm clear` before each test
+
+This avoids residual WebView, JavaScript, singleton, signal, and cache state
+without exporting a separate APK for every test.
+
+## CI Direction
+
+The intended GitHub Actions shape is:
+
+- set up Node and Java with `jdx/mise-action`
+- set up Godot and export templates with `chickensoft-games/setup-godot`
+- install pnpm dependencies
+- build the Android AAR
+- export `tests/integration` as an Android APK
+- start an emulator with `reactivecircus/android-emulator-runner`
+- install the APK once
+- run each test through `scripts/run_integration_android_test.sh`
+
+CI should reuse the same marker contract and app-session isolation used
+locally.

package.json

@@ -6,12 +6,12 @@
     "build": "pnpm -r run build",
     "format": "pnpm run format:biome && pnpm run format:gdscript && pnpm run format:kotlin && pnpm run format:swift",
     "format:biome": "biome check --write .",
-    "format:gdscript": "gdformat packages/kirie/addon/addons/kirie examples/basic-ipc/scripts",
+    "format:gdscript": "gdformat packages/kirie/addon/addons/kirie examples/basic-ipc/scripts tests/integration/scripts",
     "format:kotlin": "ktlint --format \"packages/kirie/native/android/**/*.kt\" \"packages/kirie/native/android/**/*.kts\"",
     "format:swift": "swiftlint lint --fix --format --no-cache --config .swiftlint.yml",
     "lint": "pnpm run lint:biome && pnpm run lint:gdscript && pnpm run lint:kotlin && pnpm run lint:swift",
     "lint:biome": "biome check .",
-    "lint:gdscript": "gdlint packages/kirie/addon/addons/kirie examples/basic-ipc/scripts",
+    "lint:gdscript": "gdlint packages/kirie/addon/addons/kirie examples/basic-ipc/scripts tests/integration/scripts",
     "lint:kotlin": "ktlint \"packages/kirie/native/android/**/*.kt\" \"packages/kirie/native/android/**/*.kts\"",
     "lint:swift": "swiftlint lint --strict --no-cache --config .swiftlint.yml",
     "typecheck": "pnpm -r run typecheck"

scripts/build_integration_android.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [ ! -f "tests/integration/project.godot" ]; then
+    echo "This script must be run from the repository root." >&2
+    exit 1
+fi
+
+APK_PATH="${APK_PATH:-dist/integration/android_debug.apk}"
+
+mkdir -p "$(dirname "${APK_PATH}")"
+
+mise x -- packages/kirie/native/android/gradlew \
+    --project-dir packages/kirie/native/android \
+    :plugin:assembleDebug
+
+if [ -n "${GODOT_BIN:-}" ]; then
+    godot_command=("${GODOT_BIN}")
+else
+    godot_path="$(mise which godot)"
+    resolved_godot_path="$(readlink "${godot_path}" || true)"
+    if [ -n "${resolved_godot_path}" ] && [ -x "${resolved_godot_path}" ]; then
+        godot_command=(mise x -- "${resolved_godot_path}")
+    else
+        godot_command=(mise x -- "${godot_path}")
+    fi
+fi
+
+"${godot_command[@]}" \
+    --headless \
+    --path tests/integration \
+    --install-android-build-template \
+    --export-debug "Android" \
+    "../../${APK_PATH}"
+
+echo "Exported ${APK_PATH}"

scripts/run_integration_android_test.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [ ! -f "tests/integration/project.godot" ]; then
+    echo "This script must be run from the repository root." >&2
+    exit 1
+fi
+
+if [ "$#" -ne 1 ]; then
+    echo "Usage: scripts/run_integration_android_test.sh <test_name>" >&2
+    exit 1
+fi
+
+TEST_NAME="$1"
+PACKAGE_NAME="${PACKAGE_NAME:-ai.moeru.kirie.integrationtests}"
+ACTIVITY_NAME="${ACTIVITY_NAME:-com.godot.game.GodotAppLauncher}"
+TIMEOUT_SECONDS="${TIMEOUT_SECONDS:-30}"
+LOG_FILE="${LOG_FILE:-${TMPDIR:-/tmp}/kirie-integration-${TEST_NAME}.log}"
+
+cleanup() {
+    if [ -n "${LOGCAT_PID:-}" ]; then
+        kill "${LOGCAT_PID}" >/dev/null 2>&1 || true
+        wait "${LOGCAT_PID}" >/dev/null 2>&1 || true
+    fi
+}
+trap cleanup EXIT
+
+: > "${LOG_FILE}"
+adb logcat -c
+adb shell am force-stop "${PACKAGE_NAME}" >/dev/null 2>&1 || true
+adb shell pm clear "${PACKAGE_NAME}" >/dev/null
+
+adb logcat > "${LOG_FILE}" &
+LOGCAT_PID="$!"
+
+adb shell am start \
+    -n "${PACKAGE_NAME}/${ACTIVITY_NAME}" \
+    --es kirie_test "${TEST_NAME}" \
+    >/dev/null
+
+deadline=$((SECONDS + TIMEOUT_SECONDS))
+while [ "${SECONDS}" -lt "${deadline}" ]; do
+    if fail_line="$(grep -m 1 -E "KIRIE_TEST_FAIL (${TEST_NAME}|unknown)( |$)" "${LOG_FILE}")"; then
+        echo "${fail_line}" >&2
+        exit 1
+    fi
+
+    if pass_line="$(grep -m 1 -E "KIRIE_TEST_PASS ${TEST_NAME}( |$)" "${LOG_FILE}")"; then
+        echo "${pass_line}"
+        exit 0
+    fi
+
+    sleep 0.5
+done
+
+echo "Timed out waiting for KIRIE_TEST_PASS or KIRIE_TEST_FAIL for ${TEST_NAME}" >&2
+tail -n 120 "${LOG_FILE}" >&2
+exit 1

tests/integration/addons/kirie

@@ -0,0 +1 @@
+../../../packages/kirie/addon/addons/kirie

tests/integration/export_presets.cfg

@@ -0,0 +1,33 @@
+[preset.0]
+
+name="Android"
+platform="Android"
+runnable=true
+dedicated_server=false
+custom_features=""
+export_filter="all_resources"
+include_filter="web/probe.html"
+exclude_filter=""
+export_path=""
+encryption_include_filters=""
+encryption_exclude_filters=""
+encrypt_pck=false
+encrypt_directory=false
+script_export_mode=2
+
+[preset.0.options]
+
+gradle_build/use_gradle_build=true
+gradle_build/export_format=0
+architectures/armeabi-v7a=false
+architectures/arm64-v8a=true
+architectures/x86=false
+architectures/x86_64=false
+package/unique_name="ai.moeru.kirie.integrationtests"
+package/signed=true
+package/show_as_launcher_app=false
+screen/immersive_mode=true
+screen/support_small=true
+screen/support_normal=true
+screen/support_large=true
+screen/support_xlarge=true