chore(test): gate integration tests behind build tag, add emulator runner (#50)

* chore(test): gate integration tests behind build tag, add emulator runner

- Add `//go:build integration` to rename_integration_test.go so it is
  excluded from `go test ./...` and only compiled with `-tags integration`.
  The existing FIRESTORE_EMULATOR_HOST skip guard is retained as a
  friendly fallback.
- Add scripts/run-integration-tests.sh: boots the Firestore emulator in
  its own process group (set -m), waits for "Dev App Server is now
  running", exports FIRESTORE_EMULATOR_HOST, runs the tagged tests, and
  tears the emulator down on exit via an EXIT trap — even on test failure.
- Add Makefile with an `integration-test` target (PORT overridable).
- Add .github/workflows/integration-test.yml to run integration tests in
  CI via Java + gcloud setup.
- Add "Running Integration Tests" section to README.

Verified locally: `go test ./...` stays green (4 integration tests
excluded); `make integration-test` boots the emulator, runs all 4 tests
without skips, and releases port 8765 on exit.

* fix(ci): bump Java to 21 for Firestore emulator requirement

---------

Co-authored-by: Gustavo Hoirisch <355877+gugahoi@users.noreply.github.com>

Author: gugahoi

.github/workflows/integration-test.yml

@@ -0,0 +1,40 @@
+name: Integration Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  integration-test:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v6
+      with:
+        fetch-depth: 0
+
+    - name: Set up Go
+      uses: actions/setup-go@v6
+      with:
+        go-version-file: go.mod
+        cache: true
+
+    - name: Set up Java
+      uses: actions/setup-java@v4
+      with:
+        java-version: '21'
+        distribution: 'temurin'
+
+    - name: Set up gcloud
+      uses: google-github-actions/setup-gcloud@v2
+
+    - name: Install Firestore emulator
+      run: gcloud components install cloud-firestore-emulator --quiet
+
+    - name: Run integration tests
+      run: make integration-test

Makefile

@@ -0,0 +1,5 @@
+PORT ?= 8765
+
+.PHONY: integration-test
+integration-test:
+	PORT=$(PORT) ./scripts/run-integration-tests.sh $(ARGS)

README.md

@@ -137,3 +137,22 @@ firestore --host localhost:9090 document get /my-collection/my-document
 ```
 
 The `--host` flag will override the environment variable if both are set.
+
+## Running Integration Tests
+
+Integration tests live in `pkg/cmd/browse/rename_integration_test.go` and are gated by the `integration` build tag, so they are excluded from the normal `go test ./...` run.
+
+**Prerequisites:** `gcloud` CLI with the `cloud-firestore-emulator` component and Java installed.
+
+```bash
+# Install the emulator component once
+gcloud components install cloud-firestore-emulator
+
+# Run all integration tests (boots the emulator automatically on port 8765)
+make integration-test
+
+# Use a different port
+make integration-test PORT=9000
+```
+
+The `make integration-test` target starts the emulator in the background, exports `FIRESTORE_EMULATOR_HOST`, runs `go test -tags integration -v ./...`, and tears the emulator down on exit — even if the tests fail.

pkg/cmd/browse/rename_integration_test.go

@@ -1,3 +1,5 @@
+//go:build integration
+
 package browse
 
 import (

scripts/run-integration-tests.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Boots the Firestore emulator, runs integration tests, then tears it down.
+set -euo pipefail
+
+PORT="${PORT:-8765}"
+LOG=$(mktemp)
+PGID=""
+
+cleanup() {
+    [[ -n "$PGID" ]] && kill -- "-$PGID" 2>/dev/null || true
+    rm -f "$LOG"
+}
+trap cleanup EXIT
+
+# ── prerequisites ──────────────────────────────────────────────────────────────
+if ! command -v gcloud &>/dev/null; then
+    echo "error: gcloud not found — install the Google Cloud SDK" >&2
+    exit 1
+fi
+if ! gcloud components list --filter="id=cloud-firestore-emulator" \
+        --format="value(state.name)" 2>/dev/null | grep -qi "installed"; then
+    echo "error: cloud-firestore-emulator component not installed" >&2
+    echo "       Run: gcloud components install cloud-firestore-emulator" >&2
+    exit 1
+fi
+
+# ── start emulator ─────────────────────────────────────────────────────────────
+echo "Starting Firestore emulator on localhost:${PORT} ..."
+# set -m assigns each background job its own process group so kill -- -$PGID
+# also terminates the Java subprocess spawned by the gcloud wrapper.
+set -m
+gcloud emulators firestore start --host-port="localhost:${PORT}" 2>"$LOG" &
+EMULATOR_PID=$!
+PGID=$(ps -o pgid= -p "$EMULATOR_PID" 2>/dev/null | tr -d ' ') || PGID=$EMULATOR_PID
+set +m
+
+# ── wait for ready (up to 30 s) ────────────────────────────────────────────────
+for i in $(seq 1 30); do
+    if grep -q "Dev App Server is now running" "$LOG" 2>/dev/null; then
+        echo "Emulator ready."
+        break
+    fi
+    if ! kill -0 "$EMULATOR_PID" 2>/dev/null; then
+        echo "error: emulator exited before becoming ready. Log:" >&2
+        cat "$LOG" >&2
+        exit 1
+    fi
+    if [[ $i -eq 30 ]]; then
+        echo "error: emulator did not become ready within 30 s. Log:" >&2
+        cat "$LOG" >&2
+        exit 1
+    fi
+    sleep 1
+done
+
+# ── run tests ──────────────────────────────────────────────────────────────────
+export FIRESTORE_EMULATOR_HOST="localhost:${PORT}"
+go test -tags integration -v ./... "$@"