🚀 Automation Sandbox Documentation / Dökümantasyon

Welcome to Automation Sandbox! / Automation Sandbox projesine hoş geldiniz!

💡 Select Language / Dil Seçin:

• 🇬🇧 English Documentation
• 🇹🇷 Türkçe Dökümantasyon

🇬🇧 English Overview

💡 What is Automation Sandbox? (Simple Explanation)

Imagine you write an automated test that clicks a button called "Submit". One day, the developers rename that button to "Complete Registration". Standard test tools (like Selenium or Appium) will crash because they can no longer find "Submit".

Automation Sandbox is like a smart GPS for your software tests:

1. It remembers what the button looked like (size, location, parent window, role).
2. When the ID or name breaks, it calculates a similarity score (0% - 100%) across all elements on the screen.
3. If it is confident (>= 50%), it identifies the right element without any AI cost (pure heuristic, sub-50ms for 3,000 controls on developer hardware). By default (HealingMode.Review) the candidate is routed to report telemetry for approval rather than applied automatically; opt into HealingMode.AutoHeal to have it retry the action and persist the healed locator automatically.
4. If it is unsure, it collects independent votes from providers such as Gemini, Claude, OpenAI, or local Ollama; an LLM pick is permitted when at least two votes name the same candidate. This agreement is not a correctness guarantee: all 34 unanimous deleted-element verdicts in the measured runs were false heals.

📚 Documentation Index

🇹🇷 Türkçe Genel Bakış

💡 Automation Sandbox Nedir? (En Basit Anlatım)

Yazılım testinizde "Kaydet" adlı bir butona tıklayan otomatik bir test yazdığınızı hayal edin. Bir gün yazılımcılar bu butonun adını "Değişiklikleri Onayla" olarak değiştirdi. Standart test araçları (Selenium, Appium vb.) eski butonu bulamadığı için test hata verir ve çöker.

Automation Sandbox, testleriniz için akıllı bir navigasyon (GPS) gibidir:

1. Butonun eski halini (boyutunu, ekrandaki yerini, penceresini, türünü) hafızasına kaydeder.
2. Adı veya ID’si değiştiğinde, ekrandaki tüm elemanları inceleyerek bir benzerlik skoru (%0 - %100) hesaplar.
3. Eminse (>= %50), doğru elemanı yapay zeka maliyeti olmadan belirler (saf sezgisel; geliştirici donanımında 3.000 kontrol için 50 milisaniyenin altında). Varsayılan modda (HealingMode.Review) aday, otomatik uygulanmak yerine onay için rapor telemetrisine yönlendirilir; eylemi otomatik yeniden deneyip iyileştirilen locator’ı otomatik kaydetmek için HealingMode.AutoHeal moduna geçebilirsiniz.
4. Kararsız kalırsa Gemini, Claude, OpenAI veya yerel Ollama gibi sağlayıcılardan bağımsız oylar toplar; en az iki oy aynı adayı gösterirse LLM seçimine izin verir. Bu uzlaşma bir doğruluk garantisi değildir: silinmiş eleman ölçümlerindeki 34 oybirliği kararının tamamı yanlış iyileştirmeydi.

📚 Döküman Haritası

🏛️ System Architecture Diagram / Mimari Şema

flowchart TB
    subgraph INPUT ["1. Live Target / Canlı Ekran"]
        A1["Windows App (WinForms / WPF)"]
        A2["Web Page (Playwright DOM)"]
    end

    subgraph ENGINE ["2. Heuristic Engine / Sezgisel Motor (Pure Heuristic)"]
        B1["SimilarityScorer (5 Mathematical Components)"]
        B2{"Score ≥ 50%?"}
        B3["✅ Confident Match (Free / 0 Cost)"]
        B4["⚡ Send Top-20 Candidates to AI"]
    end

    subgraph AI ["3. AI Fallback / Yapay Zeka Desteği"]
        C1["Google Gemini"]
        C2["Anthropic Claude"]
        C3["OpenAI / Grok / Kimi"]
        C4["Local Ollama (100% Free / Offline)"]
        C5["Hallucination Guard (Filter Votes)"]
        C6{"Independent Agreement Quorum (≥ 2 Votes? / ≥ 2 Bağımsız Oy?)"}
    end

    subgraph REPO ["4. Locator Repository / Kalıcı Depo"]
        D1[".locator.json (Thread-Safe Persistence)"]
        D2["Healing History Audit Log"]
    end

    A1 & A2 --> B1
    B1 --> B2
    B2 -- Yes / Evet --> B3
    B2 -- Low Confidence / Kararsız --> B4
    B4 --> C1 & C2 & C3 & C4
    C1 & C2 & C3 & C4 --> C5
    C5 --> C6
    C6 -- Agreed / Uzlaşıldı --> D1 & D2
    C6 -- "Split / Beraberlik (Fallback)" --> B3
    B3 --> D1 & D2

Independent model agreement is not a correctness guarantee / Bağımsız model uzlaşması doğruluk garantisi değildir. EN: This quorum rule blocks a single model from deciding, but multiple models can select the same wrong neighbour. In four live runs, all 34 unanimous deleted-element verdicts were false heals. TR: Bu quorum kuralı tek modelin seçimini engeller, fakat birden fazla model aynı yanlış komşuya oy verebilir. Dört canlı koşuda silinmiş elemanlar için verilen 34 oybirliği kararının tamamı yanlış iyileştirmeydi. Full finding / Resmi bulgu