آموزش تست موبایل با TestComplete — سناریوی واقعی اپلیکیشن Android و iOS

adb devices
# خروجی باید چیزی شبیه این باشد:
# List of devices attached
# R58M3xxxxx    device

def Test_SearchAndAddToCart():
    """
    سناریو: جستجوی محصول و افزودن به سبد خرید
    دستگاه: Android
    """
    # دریافت رابط دستگاه متصل
    device = Mobile.Device("ArinShop_TestDevice")
    device.Activate()
    
    # اطمینان از اینکه اپلیکیشن در صفحه اصلی است
    app = device.Application("com.arinshop.android")
    app.Launch()
    aqUtils.Delay(2000)  # صبر برای لود شدن اپلیکیشن
    
    # ---- مرحله ۱: جستجوی محصول ----
    searchBar = app.FindElement("HomePage.SearchBar")
    searchBar.Touch()
    searchBar.SetText("کفش ورزشی")
    
    # بستن کیبورد و ارسال جستجو
    device.Keys("[Enter]")
    aqUtils.Delay(1500)
    
    # Checkpoint: نتایج جستجو باید نمایش داده شود
    productList = app.FindElement("HomePage.ProductList")
    aqVerification.IsTrue(
        productList.IsVisible(),
        "لیست نتایج جستجو باید نمایش داده شود"
    )
    
    itemCount = productList.ChildCount
    aqVerification.IsTrue(
        itemCount > 0,
        "نتایج جستجو نباید خالی باشد — " + str(itemCount) + " آیتم"
    )
    Log.Message("✓ " + str(itemCount) + " نتیجه برای 'کفش ورزشی' یافت شد")
    
    # ---- مرحله ۲: باز کردن محصول اول ----
    firstProduct = productList.Child(0)
    firstProductName = firstProduct.FindChild("product_name_text").Text
    firstProduct.Touch()
    aqUtils.Delay(1000)
    
    # Checkpoint: صفحه محصول باز شده
    addToCartBtn = app.FindElement("ProductPage.AddToCart")
    aqVerification.IsTrue(
        addToCartBtn.IsVisible(),
        "دکمه 'افزودن به سبد' باید روی صفحه محصول نمایش داشته باشد"
    )
    Log.Message("✓ صفحه محصول باز شد: " + firstProductName)
    
    # ---- مرحله ۳: افزودن به سبد ----
    addToCartBtn.Touch()
    aqUtils.Delay(800)
    
    # Checkpoint: snackbar یا toast تأیید نمایش داده شود
    confirmToast = app.FindElement("*", "text", "به سبد اضافه شد", 2000)
    if confirmToast:
        Log.Message("✓ پیام تأیید افزودن به سبد نمایش داده شد")
    else:
        Log.Warning("پیام تأیید یافت نشد — ممکن است سریع محو شده باشد")
    
    # بررسی badge سبد خرید
    cartIcon = app.FindElement("HomePage.CartIcon")
    cartBadge = cartIcon.FindChild("cart_badge_text")
    aqVerification.IsTrue(
        int(cartBadge.Text) >= 1,
        "badge سبد خرید باید حداقل ۱ نشان دهد"
    )
    Log.Message("✓ badge سبد خرید: " + cartBadge.Text)

def Test_ProductGallerySwipe():
    """
    تست swipe روی گالری تصاویر محصول
    """
    device = Mobile.Device("ArinShop_TestDevice")
    app = device.Application("com.arinshop.android")
    
    # رفتن به صفحه یک محصول خاص
    NavigateToProduct(app, product_id=101)
    aqUtils.Delay(1000)
    
    gallery = app.FindElement("ProductPage.ImageGallery")
    
    # ثبت ایندکس تصویر فعلی قبل از swipe
    initialIndex = gallery.FindChild("image_indicator").Text  # مثلاً "1/5"
    
    # Swipe به چپ برای رفتن به تصویر بعدی
    gallery.Swipe(
        startX=0.8,   # ۸۰٪ از عرض از چپ
        startY=0.5,   # وسط ارتفاع
        endX=0.2,     # ۲۰٪ از عرض از چپ
        endY=0.5,
        duration=300  # میلی‌ثانیه
    )
    aqUtils.Delay(500)
    
    afterSwipeIndex = gallery.FindChild("image_indicator").Text  # باید "2/5" شود
    
    aqVerification.CheckNotEqual(
        initialIndex,
        afterSwipeIndex,
        "بعد از swipe، indicator گالری باید تغییر کند"
    )
    Log.Message("✓ Swipe موفق: از " + initialIndex + " به " + afterSwipeIndex)


def Test_ProductListScroll():
    """
    تست scroll در لیست محصولات و بارگذاری lazy load
    """
    device = Mobile.Device("ArinShop_TestDevice")
    app = device.Application("com.arinshop.android")
    
    productList = app.FindElement("HomePage.ProductList")
    
    # شمارش آیتم‌های قبل از scroll
    countBefore = productList.ChildCount
    Log.Message("آیتم قبل از scroll: " + str(countBefore))
    
    # Scroll به پایین لیست
    productList.ScrollDown(speed=500, distance=3000)
    aqUtils.Delay(1500)  # صبر برای lazy load
    
    countAfter = productList.ChildCount
    Log.Message("آیتم بعد از scroll: " + str(countAfter))
    
    aqVerification.IsTrue(
        countAfter >= countBefore,
        "بعد از scroll به پایین، تعداد آیتم‌ها نباید کاهش یابد"
    )


def Test_LongPressForWishlist():
    """
    تست Long Press برای اضافه کردن به علاقه‌مندی‌ها
    """
    device = Mobile.Device("ArinShop_TestDevice")
    app = device.Application("com.arinshop.android")
    
    productList = app.FindElement("HomePage.ProductList")
    firstItem = productList.Child(0)
    
    # Long Press (نگه داشتن ۸۰۰ میلی‌ثانیه)
    firstItem.TouchAndHold(duration=800)
    aqUtils.Delay(500)
    
    # منوی context باید ظاهر شود
    contextMenu = app.FindElement("*", "resource-id",
                                  "com.arinshop.android:id/context_menu", 1500)
    
    aqVerification.IsTrue(
        contextMenu is not None and contextMenu.IsVisible(),
        "Long Press باید context menu را نمایش دهد"
    )
    
    # انتخاب گزینه «افزودن به علاقه‌مندی»
    wishlistOption = contextMenu.FindChild("menu_add_wishlist")
    wishlistOption.Touch()
    Log.Message("✓ Long Press و افزودن به علاقه‌مندی موفق بود")

def Test_OrientationChange():
    """
    تست اینکه layout اپلیکیشن بعد از چرخش صفحه صحیح است
    """
    device = Mobile.Device("ArinShop_TestDevice")
    app = device.Application("com.arinshop.android")
    
    # ---- حالت Portrait (پیش‌فرض) ----
    device.Orientation = "Portrait"
    aqUtils.Delay(800)
    
    # بررسی نمایش صفحه اصلی در Portrait
    searchBar = app.FindElement("HomePage.SearchBar")
    aqVerification.IsTrue(
        searchBar.IsVisible(),
        "نوار جستجو در حالت Portrait باید نمایش داشته باشد"
    )
    
    # Region Checkpoint از صفحه در Portrait
    Regions.Check("HomePage_Portrait", device.ScreenCapture())
    
    # ---- تغییر به Landscape ----
    device.Orientation = "Landscape"
    aqUtils.Delay(1000)  # صبر برای انیمیشن چرخش
    
    # اپلیکیشن نباید crash کند
    aqVerification.IsTrue(
        app.IsRunning(),
        "اپلیکیشن نباید بعد از چرخش صفحه crash کند"
    )
    
    # عناصر اصلی همچنان باید نمایش داشته باشند
    aqVerification.IsTrue(
        searchBar.IsVisible(),
        "نوار جستجو در حالت Landscape باید نمایش داشته باشد"
    )
    
    # Region Checkpoint از صفحه در Landscape
    Regions.Check("HomePage_Landscape", device.ScreenCapture())
    
    Log.Message("✓ چرخش صفحه بدون مشکل انجام شد")
    
    # برگشت به Portrait
    device.Orientation = "Portrait"
    aqUtils.Delay(500)

def HandleSystemPermissions(app):
    """
    تابع کمکی برای مدیریت dialog های دسترسی
    باید قبل از هر تست فراخوانی شود
    """
    # لیست متن‌هایی که در دکمه Allow/تأیید ممکن است باشد
    allow_texts = ["Allow", "اجازه دادن", "OK", "تأیید", "While using the app"]
    
    # حداکثر ۵ بار تلاش کن
    for attempt in range(5):
        dialog_found = False
        
        for allow_text in allow_texts:
            allow_btn = app.FindElement(
                "*", "text", allow_text, timeout=1000
            )
            if allow_btn and allow_btn.IsVisible():
                allow_btn.Touch()
                aqUtils.Delay(500)
                dialog_found = True
                Log.Message("✓ دسترسی تأیید شد: " + allow_text)
                break
        
        if not dialog_found:
            break  # دیگر dialog ای نیست


def Test_FirstLaunchFlow():
    """
    تست اولین اجرای اپلیکیشن — با مدیریت همه dialog های دسترسی
    """
    device = Mobile.Device("ArinShop_TestDevice")
    
    # پاک کردن داده اپلیکیشن برای شبیه‌سازی نصب تازه
    device.ClearApplicationData("com.arinshop.android")
    
    app = device.Application("com.arinshop.android")
    app.Launch()
    aqUtils.Delay(2000)
    
    # مدیریت dialog های دسترسی
    HandleSystemPermissions(app)
    
    # صفحه onboarding باید نمایش داشته باشد
    onboardingScreen = app.FindElement(
        "*", "resource-id",
        "com.arinshop.android:id/onboarding_container", 3000
    )
    
    aqVerification.IsTrue(
        onboardingScreen is not None,
        "صفحه onboarding برای کاربر جدید باید نمایش داده شود"
    )
    Log.Message("✓ جریان اولین اجرا صحیح است")

def Test_iOS_AddToCart():
    """
    همان تست افزودن به سبد — اما روی iOS Simulator
    """
    # تنها تفاوت: نوع دستگاه
    device = Mobile.Device("iPhone_15_Simulator")
    device.Activate()
    
    app = device.Application("com.arinshop.ios")
    app.Launch()
    aqUtils.Delay(2500)  # iOS معمولاً کمی دیرتر load می‌کند
    
    # در iOS از Accessibility Identifier به جای resource-id استفاده می‌شود
    searchBar = app.FindElement(
        "*", "accessibilityIdentifier", "SearchBarInput"
    )
    searchBar.Touch()
    searchBar.SetText("کفش ورزشی")
    
    # در iOS برای ارسال جستجو باید روی کلید Search در کیبورد بزنیم
    app.FindElement("*", "text", "Search").Touch()
    aqUtils.Delay(1500)
    
    productList = app.FindElement(
        "*", "accessibilityIdentifier", "ProductCollectionView"
    )
    
    aqVerification.IsTrue(
        productList.IsVisible(),
        "لیست محصولات در iOS باید نمایش داشته باشد"
    )
    
    # ادامه تست مشابه Android است...
    Log.Message("✓ تست iOS موفق بود")

# ---- تعریف locator های هر پلتفرم ----
LOCATORS = {
    "android": {
        "search_bar":    ("resource-id", "com.arinshop.android:id/search_input"),
        "product_list":  ("resource-id", "com.arinshop.android:id/product_recycler"),
        "add_to_cart":   ("resource-id", "com.arinshop.android:id/btn_add_to_cart"),
        "cart_badge":    ("resource-id", "com.arinshop.android:id/cart_badge_text"),
        "checkout_btn":  ("resource-id", "com.arinshop.android:id/btn_checkout"),
    },
    "ios": {
        "search_bar":    ("accessibilityIdentifier", "SearchBarInput"),
        "product_list":  ("accessibilityIdentifier", "ProductCollectionView"),
        "add_to_cart":   ("accessibilityIdentifier", "AddToCartButton"),
        "cart_badge":    ("accessibilityIdentifier", "CartBadgeLabel"),
        "checkout_btn":  ("accessibilityIdentifier", "CheckoutButton"),
    }
}

DEVICES = {
    "android": {"name": "ArinShop_Android",  "app_id": "com.arinshop.android"},
    "ios":     {"name": "iPhone_15_Simulator","app_id": "com.arinshop.ios"},
}


def RunPurchaseFlow(platform):
    """
    اجرای کامل فرآیند خرید روی هر دو پلتفرم
    """
    cfg = DEVICES[platform]
    loc = LOCATORS[platform]
    
    device = Mobile.Device(cfg["name"])
    device.Activate()
    app = device.Application(cfg["app_id"])
    app.Launch()
    aqUtils.Delay(2000)
    
    Log.AppendFolder("خرید روی " + platform.upper())
    
    # جستجو
    searchBar = app.FindElement(*loc["search_bar"])
    searchBar.Touch()
    searchBar.SetText("کیف چرم")
    device.Keys("[Enter]")
    aqUtils.Delay(1500)
    
    # انتخاب اولین محصول
    productList = app.FindElement(*loc["product_list"])
    productList.Child(0).Touch()
    aqUtils.Delay(1000)
    
    # افزودن به سبد
    addBtn = app.FindElement(*loc["add_to_cart"])
    addBtn.Touch()
    aqUtils.Delay(800)
    
    # بررسی badge
    badge = app.FindElement(*loc["cart_badge"])
    aqVerification.CheckEqual(
        badge.Text, "1",
        platform + ": badge سبد خرید باید ۱ باشد"
    )
    
    Log.Message("✓ " + platform.upper() + ": فرآیند خرید موفق")
    Log.PopLogFolder()


def Test_CrossPlatform_PurchaseFlow():
    """
    اجرای تست خرید روی Android و iOS به ترتیب
    """
    RunPurchaseFlow("android")
    RunPurchaseFlow("ios")
    
    Log.Message("✓ تست cross-platform با موفقیت انجام شد")

def Test_DataDriven_Search():
    """
    تست جستجو با کلمات مختلف از فایل Excel
    """
    device = Mobile.Device("ArinShop_TestDevice")
    app = device.Application("com.arinshop.android")
    
    DDT.ExcelDriver(
        "C:\\TestData\\mobile_search_terms.xlsx",
        "Sheet1",
        True
    )
    
    while not DDT.CurrentDriver.EOF():
        search_term      = DDT.CurrentDriver.Value("search_term")
        min_results      = int(DDT.CurrentDriver.Value("min_expected_results"))
        should_find      = DDT.CurrentDriver.Value("should_find") == "TRUE"
        
        Log.AppendFolder("جستجو: " + search_term)
        
        # برگشتن به صفحه اصلی قبل از هر جستجو
        app.PressKey("Back")
        app.Launch()
        aqUtils.Delay(1000)
        
        # انجام جستجو
        searchBar = app.FindElement(
            "resource-id", "com.arinshop.android:id/search_input"
        )
        searchBar.Touch()
        searchBar.SetText(search_term)
        device.Keys("[Enter]")
        aqUtils.Delay(1500)
        
        productList = app.FindElement(
            "resource-id", "com.arinshop.android:id/product_recycler"
        )
        
        if should_find:
            aqVerification.IsTrue(
                productList.ChildCount >= min_results,
                "جستجوی '" + search_term + "' باید حداقل " +
                str(min_results) + " نتیجه داشته باشد"
            )
        else:
            emptyState = app.FindElement(
                "resource-id",
                "com.arinshop.android:id/empty_search_state",
                2000
            )
            aqVerification.IsTrue(
                emptyState is not None,
                "جستجوی '" + search_term + "' باید نمایش 'نتیجه‌ای یافت نشد' داشته باشد"
            )
        
        Log.PopLogFolder()
        DDT.CurrentDriver.Next()
    
    DDT.CurrentDriver.Close()

# .gitlab-ci.yml
stages:
  - mobile-test

android-regression:
  stage: mobile-test
  tags:
    - windows-mobile-runner   # Runner مخصوص که به دستگاه Android دسترسی دارد
  script:
    - |
      # راه‌اندازی emulator قبل از تست (اگر دستگاه واقعی نیست)
      & "C:\Android\emulator\emulator.exe" -avd Pixel_6_API_33 -no-window &
      Start-Sleep -Seconds 30
      
      # اجرای تست‌های TestComplete
      & "C:\Program Files\SmartBear\TestComplete 15\Bin\TestComplete.exe" `
        "ArinShopMobileTests\ArinShopMobileTests.pjs" `
        /run /TestItem:"AndroidTests" `
        /exit /SilentMode `
        /ExportLog:"TestResults\android-results.xml"
  artifacts:
    reports:
      junit: TestResults/android-results.xml
    paths:
      - TestResults/
  only:
    - main
    - release/*

def WaitForElement(app, locator_type, locator_value, timeout_ms=5000):
    """
    منتظر می‌ماند تا عنصر نمایش داده شود
    به جای delay ثابت
    """
    start = aqUtils.GetTickCount()
    while aqUtils.GetTickCount() - start < timeout_ms:
        el = app.FindElement("*", locator_type, locator_value, 500)
        if el and el.IsVisible():
            return el
        aqUtils.Delay(200)
    
    Log.Warning("عنصر در " + str(timeout_ms) + "ms یافت نشد: " + locator_value)
    return None

def SetupMobileTest(device_name, app_id):
    """
    آماده‌سازی استاندارد قبل از هر تست موبایل
    """
    device = Mobile.Device(device_name)
    device.Activate()
    device.Orientation = "Portrait"   # همیشه از Portrait شروع کن
    
    app = device.Application(app_id)
    app.Terminate()          # بستن اجرای قبلی
    aqUtils.Delay(500)
    app.Launch()
    aqUtils.Delay(2000)
    
    return device, app