454 lines
15 KiB
Bash
Executable File
454 lines
15 KiB
Bash
Executable File
#!/bin/bash
|
||
# ╔═══════════════════════════════════════════════════════════════════╗
|
||
# ║ test-helpers.sh — Core Test Framework for QA Automation ║
|
||
# ╠═══════════════════════════════════════════════════════════════════╣
|
||
# ║ Source this file at the top of every test flow script: ║
|
||
# ║ source "$(dirname "$0")/../../lib/test-helpers.sh" ║
|
||
# ║ ║
|
||
# ║ Provides: ║
|
||
# ║ • Test lifecycle (setup_test, teardown_test, step) ║
|
||
# ║ • Logging (log_pass, log_fail, log_info, log_warn) ║
|
||
# ║ • agent-device wrappers (tap, swipe, scroll, screenshot) ║
|
||
# ║ • Assertion functions (assert_app_foreground, etc.) ║
|
||
# ║ • Navigation helpers (tap_tab, launch_app, close_app) ║
|
||
# ╚═══════════════════════════════════════════════════════════════════╝
|
||
|
||
set -euo pipefail
|
||
|
||
# ── Source configuration ─────────────────────────────────────────────
|
||
HELPERS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||
QA_ROOT="$(cd "$HELPERS_DIR/../.." && pwd)"
|
||
source "$QA_ROOT/qa.config.sh"
|
||
|
||
# ── Auto-detect simulator UDID if set to "auto" ─────────────────────
|
||
if [ "$SIMULATOR_UDID" = "auto" ]; then
|
||
_detected_udid=$(qa_detect_simulator_udid 2>/dev/null || echo "")
|
||
if [ -n "$_detected_udid" ]; then
|
||
SIMULATOR_UDID="$_detected_udid"
|
||
fi
|
||
fi
|
||
|
||
# ── Test State ───────────────────────────────────────────────────────
|
||
TEST_NAME=""
|
||
STEP_COUNT=0
|
||
PASS_COUNT=0
|
||
FAIL_COUNT=0
|
||
TEST_START_TIME=""
|
||
|
||
# ── Initialization ───────────────────────────────────────────────────
|
||
|
||
init_test_env() {
|
||
mkdir -p "$TEST_OUTPUT_DIR"
|
||
mkdir -p "$SCREENSHOT_DIR"
|
||
if [ ! -f "$RESULTS_FILE" ]; then
|
||
echo "Test Run: $(date '+%Y-%m-%d %H:%M:%S')" > "$RESULTS_FILE"
|
||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" >> "$RESULTS_FILE"
|
||
fi
|
||
}
|
||
|
||
init_test_env
|
||
|
||
# ── Test Lifecycle ───────────────────────────────────────────────────
|
||
|
||
setup_test() {
|
||
local name="$1"
|
||
TEST_NAME="$name"
|
||
TEST_START_TIME=$(date +%s)
|
||
STEP_COUNT=0
|
||
PASS_COUNT=0
|
||
FAIL_COUNT=0
|
||
mkdir -p "$SCREENSHOT_DIR/$TEST_NAME"
|
||
echo ""
|
||
echo "═══════════════════════════════════════════"
|
||
echo "🧪 TEST: $TEST_NAME"
|
||
echo "═══════════════════════════════════════════"
|
||
echo "Started: $(date '+%Y-%m-%d %H:%M:%S')"
|
||
echo ""
|
||
}
|
||
|
||
teardown_test() {
|
||
local name="${1:-$TEST_NAME}"
|
||
local end_time=$(date +%s)
|
||
local duration=$((end_time - TEST_START_TIME))
|
||
echo ""
|
||
echo "───────────────────────────────────────────"
|
||
echo "📊 RESULTS: $name"
|
||
echo " Steps: $STEP_COUNT | Passed: $PASS_COUNT | Failed: $FAIL_COUNT"
|
||
echo " Duration: ${duration}s"
|
||
if [ $FAIL_COUNT -eq 0 ]; then
|
||
echo " Status: ✅ ALL PASSED"
|
||
else
|
||
echo " Status: ❌ $FAIL_COUNT FAILURES"
|
||
fi
|
||
echo "───────────────────────────────────────────"
|
||
echo ""
|
||
echo "$(date '+%Y-%m-%d %H:%M:%S') | $name | Steps:$STEP_COUNT Pass:$PASS_COUNT Fail:$FAIL_COUNT | ${duration}s" >> "$RESULTS_FILE"
|
||
}
|
||
|
||
# ── Logging ──────────────────────────────────────────────────────────
|
||
|
||
step() {
|
||
STEP_COUNT=$((STEP_COUNT + 1))
|
||
echo " [$STEP_COUNT] $1"
|
||
}
|
||
|
||
log_pass() {
|
||
PASS_COUNT=$((PASS_COUNT + 1))
|
||
echo " ✅ $1"
|
||
}
|
||
|
||
log_fail() {
|
||
FAIL_COUNT=$((FAIL_COUNT + 1))
|
||
echo " ❌ $1"
|
||
}
|
||
|
||
log_info() {
|
||
echo " ℹ️ $1"
|
||
}
|
||
|
||
log_warn() {
|
||
echo " ⚠️ $1"
|
||
}
|
||
|
||
# ── agent-device Wrappers ────────────────────────────────────────────
|
||
|
||
# Take a screenshot using xcrun simctl (avoids agent-device focus issues)
|
||
# Falls back to agent-device if xcrun isn't available.
|
||
# Usage: take_screenshot "step_name" [session]
|
||
take_screenshot() {
|
||
local name="$1"
|
||
local session="${2:-$ACTIVE_SESSION}"
|
||
local path="$SCREENSHOT_DIR/$TEST_NAME/${name}.png"
|
||
mkdir -p "$(dirname "$path")"
|
||
|
||
# Prefer xcrun simctl for iOS (doesn't steal focus)
|
||
if [ "$SIMULATOR_UDID" != "auto" ] && command -v xcrun >/dev/null 2>&1; then
|
||
xcrun simctl io "$SIMULATOR_UDID" screenshot "$path" 2>/dev/null || {
|
||
# Fallback to agent-device
|
||
agent-device screenshot "$path" --session "$session" 2>/dev/null || {
|
||
log_warn "Screenshot failed for: $name"
|
||
return 1
|
||
}
|
||
}
|
||
else
|
||
agent-device screenshot "$path" --session "$session" 2>/dev/null || {
|
||
log_warn "Screenshot failed for: $name"
|
||
return 1
|
||
}
|
||
fi
|
||
echo "$path"
|
||
}
|
||
|
||
# Tap at coordinates with timeout handling
|
||
# Usage: tap x y [session]
|
||
tap() {
|
||
local x="$1"
|
||
local y="$2"
|
||
local session="${3:-$ACTIVE_SESSION}"
|
||
|
||
agent-device click "$x" "$y" --session "$session" 2>/dev/null &
|
||
local pid=$!
|
||
|
||
sleep 0.5
|
||
if ps -p $pid > /dev/null 2>&1; then
|
||
kill $pid 2>/dev/null || true
|
||
wait $pid 2>/dev/null || true
|
||
fi
|
||
|
||
sleep 1
|
||
}
|
||
|
||
# Swipe gesture
|
||
# Usage: swipe x1 y1 x2 y2 [session]
|
||
swipe() {
|
||
local x1="$1"
|
||
local y1="$2"
|
||
local x2="$3"
|
||
local y2="$4"
|
||
local session="${5:-$ACTIVE_SESSION}"
|
||
|
||
agent-device swipe "$x1" "$y1" "$x2" "$y2" --session "$session" 2>/dev/null &
|
||
local pid=$!
|
||
|
||
sleep 0.5
|
||
if ps -p $pid > /dev/null 2>&1; then
|
||
kill $pid 2>/dev/null || true
|
||
wait $pid 2>/dev/null || true
|
||
fi
|
||
|
||
sleep 1
|
||
}
|
||
|
||
# Scroll in a direction
|
||
# Usage: scroll_dir direction [session]
|
||
scroll_dir() {
|
||
local direction="$1"
|
||
local session="${2:-$ACTIVE_SESSION}"
|
||
|
||
agent-device scroll "$direction" --session "$session" 2>/dev/null &
|
||
local pid=$!
|
||
|
||
sleep 0.5
|
||
if ps -p $pid > /dev/null 2>&1; then
|
||
kill $pid 2>/dev/null || true
|
||
wait $pid 2>/dev/null || true
|
||
fi
|
||
|
||
sleep 1
|
||
}
|
||
|
||
# Type text into focused field
|
||
# Usage: type_text ref_or_coords text [session]
|
||
type_text() {
|
||
local ref="$1"
|
||
local text="$2"
|
||
local session="${3:-$ACTIVE_SESSION}"
|
||
|
||
agent-device fill "$ref" "$text" --session "$session" 2>/dev/null &
|
||
local pid=$!
|
||
|
||
sleep 0.5
|
||
if ps -p $pid > /dev/null 2>&1; then
|
||
kill $pid 2>/dev/null || true
|
||
wait $pid 2>/dev/null || true
|
||
fi
|
||
|
||
sleep 1
|
||
}
|
||
|
||
# Press home button
|
||
go_home() {
|
||
local session="${1:-$ACTIVE_SESSION}"
|
||
agent-device home --session "$session" 2>/dev/null &
|
||
local pid=$!
|
||
sleep 1
|
||
if ps -p $pid > /dev/null 2>&1; then
|
||
kill $pid 2>/dev/null || true
|
||
wait $pid 2>/dev/null || true
|
||
fi
|
||
sleep 2
|
||
}
|
||
|
||
# Go back
|
||
go_back() {
|
||
local session="${1:-$ACTIVE_SESSION}"
|
||
agent-device back --session "$session" 2>/dev/null &
|
||
local pid=$!
|
||
sleep 1
|
||
if ps -p $pid > /dev/null 2>&1; then
|
||
kill $pid 2>/dev/null || true
|
||
wait $pid 2>/dev/null || true
|
||
fi
|
||
sleep 2
|
||
}
|
||
|
||
# Check if the app process is running on the simulator
|
||
check_appstate() {
|
||
local session="${1:-$ACTIVE_SESSION}"
|
||
if [ "$SIMULATOR_UDID" != "auto" ] && command -v xcrun >/dev/null 2>&1; then
|
||
xcrun simctl spawn "$SIMULATOR_UDID" launchctl list 2>/dev/null | grep "UIKitApplication:${APP_BUNDLE_ID}" || echo ""
|
||
else
|
||
agent-device appstate --session "$session" 2>/dev/null || echo ""
|
||
fi
|
||
}
|
||
|
||
# Get accessibility snapshot
|
||
get_snapshot() {
|
||
local session="${1:-$ACTIVE_SESSION}"
|
||
local depth="${2:-5}"
|
||
timeout 10 agent-device snapshot -i --depth "$depth" --session "$session" 2>/dev/null || echo "(snapshot timeout)"
|
||
}
|
||
|
||
# ── Assertion Functions ──────────────────────────────────────────────
|
||
|
||
# Assert app is in foreground
|
||
assert_app_foreground() {
|
||
local session="${1:-$ACTIVE_SESSION}"
|
||
local state=$(check_appstate "$session" 2>/dev/null | grep -o "$APP_BUNDLE_ID" || true)
|
||
|
||
if [ -n "$state" ]; then
|
||
log_pass "App is in foreground ($APP_BUNDLE_ID)"
|
||
return 0
|
||
else
|
||
log_fail "App is NOT in foreground"
|
||
return 1
|
||
fi
|
||
}
|
||
|
||
# Assert screenshot was captured
|
||
assert_screenshot() {
|
||
local name="$1"
|
||
local path="$SCREENSHOT_DIR/$TEST_NAME/${name}.png"
|
||
|
||
if [ -f "$path" ] && [ -s "$path" ]; then
|
||
log_pass "Screenshot captured: $name"
|
||
return 0
|
||
else
|
||
log_fail "Screenshot missing or empty: $name"
|
||
return 1
|
||
fi
|
||
}
|
||
|
||
# Assert text is visible in accessibility tree
|
||
assert_text_visible() {
|
||
local text="$1"
|
||
local session="${2:-$ACTIVE_SESSION}"
|
||
local snapshot=$(get_snapshot "$session")
|
||
|
||
if echo "$snapshot" | grep -qi "$text"; then
|
||
log_pass "Text visible: '$text'"
|
||
return 0
|
||
else
|
||
log_warn "Text not found in accessibility tree: '$text'"
|
||
return 1
|
||
fi
|
||
}
|
||
|
||
# Assert element exists in accessibility tree
|
||
assert_element_exists() {
|
||
local label="$1"
|
||
local session="${2:-$ACTIVE_SESSION}"
|
||
local snapshot=$(get_snapshot "$session")
|
||
|
||
if echo "$snapshot" | grep -qi "label.*$label\|name.*$label"; then
|
||
log_pass "Element found: '$label'"
|
||
return 0
|
||
else
|
||
log_fail "Element not found: '$label'"
|
||
return 1
|
||
fi
|
||
}
|
||
|
||
# ── Navigation Helpers ───────────────────────────────────────────────
|
||
|
||
# Tap a tab by position (1-5)
|
||
# Usage: tap_tab 1 (first tab)
|
||
tap_tab_by_index() {
|
||
local index="$1"
|
||
local x_var="TAB_${index}_X"
|
||
local x="${!x_var:-}"
|
||
|
||
if [ -z "$x" ]; then
|
||
log_fail "No coordinate defined for tab index $index (set TAB_${index}_X)"
|
||
return 1
|
||
fi
|
||
|
||
tap "$x" "$TAB_BAR_Y"
|
||
sleep 2
|
||
}
|
||
|
||
# Tap a tab by name (reads screen names from config and maps to tab index)
|
||
# Usage: tap_tab "explore"
|
||
tap_tab() {
|
||
local tab_name="$1"
|
||
local tab_name_upper=$(echo "$tab_name" | tr '[:lower:]' '[:upper:]')
|
||
|
||
# Map common names to tab indices — customize in qa.config.sh
|
||
case "$tab_name_upper" in
|
||
EXPLORE|HOME|TAB1|1) tap_tab_by_index 1 ;;
|
||
SEARCH|TAB2|2) tap_tab_by_index 2 ;;
|
||
CREATE|TAB3|3) tap_tab_by_index 3 ;;
|
||
WALLET|TAB4|4) tap_tab_by_index 4 ;;
|
||
PROFILE|TAB5|5) tap_tab_by_index 5 ;;
|
||
*)
|
||
log_fail "Unknown tab: $tab_name"
|
||
return 1
|
||
;;
|
||
esac
|
||
}
|
||
|
||
# Launch the app fresh
|
||
launch_app() {
|
||
local session="${1:-$ACTIVE_SESSION}"
|
||
step "Launching app ($APP_BUNDLE_ID)"
|
||
|
||
if [ "$SIMULATOR_UDID" != "auto" ] && command -v xcrun >/dev/null 2>&1; then
|
||
xcrun simctl terminate "$SIMULATOR_UDID" "$APP_BUNDLE_ID" 2>/dev/null || true
|
||
sleep 1
|
||
xcrun simctl launch "$SIMULATOR_UDID" "$APP_BUNDLE_ID" 2>/dev/null || {
|
||
log_fail "Failed to launch app via xcrun"
|
||
return 1
|
||
}
|
||
else
|
||
agent-device open "$APP_BUNDLE_ID" --session "$session" --relaunch 2>/dev/null || {
|
||
log_fail "Failed to launch app"
|
||
return 1
|
||
}
|
||
fi
|
||
|
||
sleep "$APP_SETTLE_TIME"
|
||
log_pass "App launched"
|
||
}
|
||
|
||
# Close the app
|
||
close_app() {
|
||
local session="${1:-$ACTIVE_SESSION}"
|
||
if [ "$SIMULATOR_UDID" != "auto" ] && command -v xcrun >/dev/null 2>&1; then
|
||
xcrun simctl terminate "$SIMULATOR_UDID" "$APP_BUNDLE_ID" 2>/dev/null || {
|
||
log_warn "Could not terminate app via xcrun"
|
||
return 1
|
||
}
|
||
else
|
||
agent-device close --session "$session" 2>/dev/null || {
|
||
log_warn "Could not close app"
|
||
return 1
|
||
}
|
||
fi
|
||
sleep 2
|
||
}
|
||
|
||
# Wait for app to settle
|
||
wait_settle() {
|
||
local seconds="${1:-3}"
|
||
sleep "$seconds"
|
||
}
|
||
|
||
# ── Utility Functions ────────────────────────────────────────────────
|
||
|
||
# Print test summary
|
||
print_test_summary() {
|
||
echo ""
|
||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||
echo "📋 TEST EXECUTION SUMMARY"
|
||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||
tail -20 "$RESULTS_FILE"
|
||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||
}
|
||
|
||
log_debug() {
|
||
local msg="$1"
|
||
echo "[DEBUG] $(date '+%H:%M:%S') $msg" >> "$RESULTS_FILE"
|
||
}
|
||
|
||
save_snapshot() {
|
||
local desc="$1"
|
||
local session="${2:-$ACTIVE_SESSION}"
|
||
local filename="$(echo "$desc" | tr ' ' '_' | tr -cd '[:alnum:]._-')"
|
||
local snap=$(get_snapshot "$session")
|
||
echo "$snap" > "$SCREENSHOT_DIR/$TEST_NAME/${filename}_snapshot.txt"
|
||
log_info "Saved snapshot: $filename"
|
||
}
|
||
|
||
# ── Error Handling ───────────────────────────────────────────────────
|
||
|
||
trap 'teardown_test 2>/dev/null || true' EXIT
|
||
|
||
on_error() {
|
||
local line=$1
|
||
log_fail "Error on line $line"
|
||
log_debug "Exit code: $?"
|
||
}
|
||
|
||
trap 'on_error ${LINENO}' ERR
|
||
|
||
# ── Export Functions ─────────────────────────────────────────────────
|
||
|
||
export -f setup_test teardown_test step log_pass log_fail log_info log_warn 2>/dev/null || true
|
||
export -f take_screenshot tap swipe scroll_dir type_text 2>/dev/null || true
|
||
export -f go_home go_back check_appstate get_snapshot 2>/dev/null || true
|
||
export -f assert_app_foreground assert_screenshot assert_text_visible assert_element_exists 2>/dev/null || true
|
||
export -f tap_tab tap_tab_by_index launch_app close_app wait_settle 2>/dev/null || true
|
||
export -f print_test_summary log_debug save_snapshot 2>/dev/null || true
|
||
|
||
echo "Test helpers loaded. Session: $ACTIVE_SESSION | App: $APP_BUNDLE_ID"
|