Elementleri güvenilir şekilde bulma

Sayfalar ve pencereler değişir; dün çalışan bir seçici bugün elementini bulamayabilir. Botream, yedek seçiciler, çapalar ve self-healing (kendi kendini onarma) ile görevlerin çalışmaya devam etmesini sağlar; seçici sağlığı da hangi yakalamaları bozulmadan önce yenilemeniz gerektiğini size bildirir.

#Bir element nasıl bulunur

capture ve desktop element eylemlerinde ajan şu sırayla dener:

1. Komutun kendi seçicisi: web için --dompath, masaüstü için --by/--target.

2. Yedek seçiciler: önce --fallback ile verdikleriniz, ardından nesne özellikleri tablosundan oluşturulan alternatifler.

3. Self-healing: komutla birlikte yakalanan nesne özelliklerine göre karşılaştırılan en benzer element.

4. veya 3. adımda element bulunduğunda çalıştırma, günlüğe bir uyarı yazılarak devam eder. Hiçbir şey bulunamazsa adım başarısız olur ve en yakın catch hatayı işler.

#Yedek seçiciler

--fallback, || ile ayrılmış ve ilk seçici hiçbir şey bulamadığında sırayla denenen başka seçicileri listeler:

capture --browser:$shop$ --action:click --dompath:"#save-btn" --fallback:"//button[normalize-space(.)='Save'] || [data-testid=save]"
desktop --action:click --window:$erp$ --by:automationid --target:"btnSave" --fallback:"name=Save || classname=SaveButton"

• Web: herhangi bir XPath veya CSS seçicisi.
• Masaüstü: name=…, automationid=…, classname=… veya bir XPath.

#Otomatik yedek seçiciler

Yakalanan elementler için yedek seçici yazmanız gerekmez. Bir çalıştırma başladığında Botream, listeyi Object properties tablosunun tamamından tamamlar:

• Önce, index ve DOM XPath olmadan işaretli özellikler; çünkü konumun değişmesi en yaygın bozulma nedenidir. DOM XPath işaretliyse, yakalanan elementin bu özelliklerin eşleşmeleri arasındaki sırası (işaretsiz index) onlardan önce denenir.
• Ardından element türü ile birer tanımlayıcı özellik: web için test id, id, name, aria-label, placeholder, title, for, bağlantı, kaynak, alt metin, metin veya değer; masaüstü için AutomationId, Name, yardım metni veya sınıf adı.

Otomatik üretilmiş gibi görünen değerler (onaltılık dizeler, GUID'ler, çatı sayaçları, uzun rakam dizileri) atlanır. Kayıtlı göreviniz değiştirilmez.

#Bir yedek seçici kullanıldığında ne olur

Eylem ilk seçiciyle çalışır. Ajan, yalnızca bu başarısız olduğunda ve element gerçekten orada olmadığında elementi bulan ilk yedek seçiciyi kullanır, bir uyarı ("Not found: … Using the fallback … re-capture the element") kaydeder ve devam eder. Herhangi bir seçici eşleştiğinde exists true olur; wait --type:element ve wait --type:desktopelement da beliren bir yedek seçiciyi kabul eder.

İpucu: Yedek seçici uyarısı, sayfanın değiştiği anlamına gelir. Yedek seçiciler de tükenmeden önce elementi yeniden yakalayın.

#Çapalar

Bazı elementlerin hiçbir benzersiz yanı yoktur: eski bir formdaki beş aynı metin kutusu, bir tablodaki fiyat hücresi gibi. Çapa, bir etiket veya başlık gibi yakındaki değişmeyen bir elementtir. Seçici birden çok elementle eşleştiğinde çapaya en yakın olan kullanılır.

capture --browser:$shop$ --action:settext --dompath:"input.f" --anchor:"//label[.='Amount']" --anchorposition:right --value:$amount$
desktop --action:settext --window:$erp$ --by:classname --target:"Edit" --anchor:"name=Amount" --anchorposition:right --value:$amount$

• Web: --anchor bir seçicidir.
• Masaüstü: --anchor; name=Amount, automationid=lblTotal, classname=Static veya bir XPath'tir. Çapalar --by:index ile çalışmaz.
• Yakalama: Anchor yanındaki Capture düğmesine tıklayın ve etikete veya başlığa tıklayın. Yalnızca seçicisi saklanır: çapa bir referans noktasıdır, komutun üzerinde işlem yaptığı element değildir.

Id'si olmayan eski uygulamaları bu şekilde otomatikleştirirsiniz: "Amount etiketinin sağındaki metin kutusu".

#Self-healing

Ne seçici ne de herhangi bir yedek seçici elementi bulamadığında self-healing, yakaladığınız elemente en çok benzeyen elementi arar ve yeterince benzerse onu kullanır.

capture ve desktop element eylemlerinde (exists ve beklemeler hariç) ve yalnızca yakalanmış nesne özelliklerine sahip komutlarda çalışır. Elle yazılan komutların nesne özellikleri yoktur ve onarılmazlar.

#Benzerlik nasıl hesaplanır

• Adaylar, sayfadaki veya çerçevedeki aynı HTML etiketine sahip görünür elementler ya da penceredeki aynı denetim türüne sahip elementlerdir. Bir düğmenin yerini yalnızca bir düğme alabilir.
• Her özellik yakalanan değerle karşılaştırılır: tam veya joker karakterli bir eşleşme tam puan alır; etiketler ve metinler paylaştıkları kelime ve karakter sayısına göre, sınıflar ise paylaştıkları sınıf adlarına göre puanlanır.
• Tanımlayıcı özellikler en ağır basar: id, name ve test id'leri (web), AutomationId ve Name (masaüstü). Ardından metin, aria-label ve placeholder; title, bağlantı, tür, rol ve sınıf için daha az; değer için en az.
• Konum yok sayılır: DOM XPath ve index hesaba katılmaz; çünkü onarmanın bulması gereken şey tam da yeri değişmiş bir elementtir.
• Sonuç %0 ile %100 arasında bir puandır.

En iyi aday, puanı Minimum similarity eşiğine (varsayılan %90) ulaştığında ve başka hiçbir aday neredeyse aynı derecede benzer olmadığında kullanılır: iki aday arasındaki fark 2 puan içindeyse hiçbiri tahmin edilmez.

#Çalıştırmada ne görürsünüz

• Healed (onarıldı): günlükte "Self-healed: used … (93 % similar)" gibi bir uyarı görünür ve çalıştırma devam eder.
• Not healed (onarılmadı): adım, özgün hataya ek olarak "Self-healing: the most similar element, button "Save", is 72 % similar; 90 % is needed" gibi bir satırla başarısız olur.

#Ayarlar

Yöneticiler varsayılanları Self-healing ayarları altında belirler:

#Görev politikası

Her görev bu ayarı geçersiz kılabilir. Görev listesinde Edit details seçeneğini seçin; Task details içinde, Self-healing altında When an element is not found değerini ayarlayın:

Only suggest it, tıklamalarının asla yanlış bir elemente ulaşmaması gereken görevler için uygundur. runtask aracılığıyla çağrılan görevler kendi politikalarını izler.

#Geri alınamayan tıklamalar

Only suggest for clicks that cannot be undone açıkken, yakalanan veya bulunan element Delete, Remove, Send, Submit, Approve, Confirm, Pay, Transfer, Purchase, Buy, Sign veya Publish (ayrıca Sil, Kaldır, Gönder, Onayla, Öde, Satın al, İmzala, Yayınla) olarak etiketlenmişse bir tıklama, çift tıklama veya gönderim asla onarılmaz. Metin, aria-label, değer, title ve name denetlenir. En benzer element yalnızca önerilir ve adım başarısız olur.

#Düzenleyicide bir öneriyi uygulama

Onarma içeren bir çalıştırmadan sonra ilgili komutlar düzenleyicide bir Healed rozeti gösterir. Öneriyi özellikler panelinde görmek için bloğu seçin:

• N çalıştırmada Self-healed: element bulunamadı, bu nedenle benzer bir element kullanıldı.
• N çalıştırmada Not found: self-healing benzer bir element buldu ancak kullanmadı (görev yalnızca öneride bulunuyor veya tıklama geri alınamaz), bu nedenle adım başarısız oldu.

Kart, kullanılan elementi adlandırır ve iki düğme sunar:

• Apply, o elementin özelliklerini Object properties tablosuna yerleştirir (sahip olduğu yerlerde aynı işaretlerle, index işaretsiz) ve seçiciyi yeniden oluşturur; böylece görev elementi doğrudan bulur. Değişikliği korumak için görevi kaydedin.
• Dismiss, öneriyi unutur.

Uygulama ve yok sayma işlemleri denetim kaydına yazılır.

#Seçici sağlığı

Seçici sağlığı, yakalanan her elementi ek çalıştırma gerektirmeden normal çalıştırmalarda ölçer: her capture veya desktop element eyleminden hemen önce element okunur ve yakalamayla karşılaştırılır. Karşılaştırma self-healing ile aynı puanı kullanır, ancak web metnini ve değerini dışarıda bırakır; çünkü bunlar sayfanın değiştiğinin bir işareti değil, görevin okuduğu verilerdir.

#Durumlar

Bir seçicinin durumu en son çalıştırmasından gelir:

#Selector health sayfası

Ana menüdeki Selector health (Edit tasks yetkisi), ölçülen her seçiciyi en kötüden başlayarak son 24 hours, 7 days veya 30 days için listeler:

• Status, Task, Line ve Command.
• En son çalıştırmadaki ve dönemin en düşük Similarity değeri.
• Runs ve Last run (o çalıştırmaya bir bağlantı).

Duruma göre filtreleyin ve komutu bloğu seçili olarak düzenleyicide açmak için bir satıra tıklayın. Yalnızca yakalanmış nesne özelliklerine sahip komutlar ölçülür: elementleri Capture düğmesiyle veya kaydediciyle yakalayın.

#Pano kartı

Panodaki Selector health kartı şunları gösterir:

View report, Selector health sayfasını açar.

#Günlük e-posta

Bildirim ayarları altında Daily selector health report, bozuk, onarılmış, bir yedek seçiciyle bulunmuş veya kayan seçicileri listeleyen günlük bir e-posta alacak adresleri alır. Send the selector health report at saati belirler (sunucu saati, varsayılan 6). E-posta son 24 saati kapsar ve yalnızca sağlıklı olmayan bir şey olduğunda gönderilir. Posta (SMTP) ayarlarını gerektirir.

#Kararlı seçiciler için en iyi uygulamalar

• Yazmayın, yakalayın. Yakalanan komutlar nesne özelliklerini taşır; bu da size otomatik yedek seçiciler, self-healing ve seçici sağlığı sağlar. Elle yazılan seçiciler bunların hiçbirinden yararlanamaz.
• Elementin yalnızca nerede olduğunu değil, ne olduğunu da işaretleyin. Test id'lerini, id'leri, adları, etiketleri ve AutomationId'leri tercih edin. Web yakalaması DOM XPath'i bunlarla birlikte işaretler: çalışma tam olarak yakalanan elementi bulur, sayfa düzeni değiştiğinde ise yedekler (yol olmadan aynı özellikler) onu yeniden bulur. Başka bir özellik elementi benzersiz kılıyorsa Index işaretini kaldırılmış bırakın. Masaüstü yakalaması neyin işaretleneceğini seçerken üretilmiş görünen ya da saat içeren değerleri atlar.
• Değişen kısımlar için joker karakter kullanın. Invoice 2026-10-06 yerine Invoice*, tam bir cümle yerine *total*.
• Veriye bağlı elementler için değişken kullanın. $customerName$ şeklinde bir inner text, geçerli müşterinin satırını bulur.
• Adsız alanları bir index ile saymak yerine etiketlerine çapalayın.
• Uyarıları takip edin. Günlükteki bir yedek seçici veya onarma uyarısı, bir Healed rozeti ya da bir Drifting durumu, uygulamanın değiştiği anlamına gelir. Görev hâlâ çalışırken yeniden yakalayın veya öneriyi uygulayın.
• Riskli tıklamaları korumada tutun. Only suggest for clicks that cannot be undone seçeneğini açık bırakın ve para aktaran veya ileti gönderen görevler için Only suggest it kullanın.
• Saati değil, sayfayı bekleyin. Yavaş sayfaların bozuk seçiciler gibi görünmemesi için sabit gecikmeler yerine wait --type:element veya bir --timeout kullanın.