Felhasználói felület automatizálása

Vizsgálja meg és használja a parancssorból futó Windows alkalmazásokat. Az AI-ügynökök és fejlesztők használják a felhasználói felület teszteléséhez, hibakereséséhez és automatizálásához.

Áttekintés

winapp ui parancsokat biztosít Windows alkalmazás felhasználói felületeinek vizsgálatához és azokkal való interakcióhoz. Windows UI-automatizálás (UIA) használata. Bármilyen Windows alkalmazással használható – WPF, WinForms, Win32, Electron és WinUI 3. A legtöbb parancs UIA-mintákon keresztül vezeti az alkalmazást (nincs bemeneti injektálás). A kivételek valós bemenetet injektálnak: ui click/ui hover/ui dragegérszimuláció használata,ui touch/ui pen érintés- és toll-/tollbemenet szintetizálása, valamint ui send-keys billentyűzetbemenet szintetizálása – olyan vezérlők és forgatókönyvek esetén, amelyeket az UIA-minták nem tudnak vezetni.

Important

Interaktív asztali követelmény (beviteli-injektálási igék).click, hover, drag, touch, pen, , , scroll --wheelés send-keys --via send-input szintetizálja az operációsrendszer-szintű bemenetet, ezért egy nyitott, interaktív asztalra van szükségük, amely az előtérben található célablakot tartalmazza. Zárolt munkaállomáson vagy biztonságos asztalon (LogonUI/UAC) nem tudnak gyorsan injektálni és sikertelenül no_interactive_desktop működni (a szintemeléstől/foreground_not_target esetektől eltérően). touch / pen továbbá elutasíthatja, ha egyetlen ablak sem oldódik fel (no_target); a célablakon kívüli koordináták nem végzetes figyelmeztetések ( warnings[] szöveges módban egy bejegyzés --jsonvagy figyelmeztető sor), és az injektálás továbbra is folytatódik – az egéres igékkel összhangban. Minden más – inspect, , search, get-property, get-valuewait-for, set-value, invoke, scroll --direction/--toscreenshot – UIA-mintákon keresztül vezérli az alkalmazást, és fej nélküli/zárolt munkamenet-barát. Előnyben részesíti az UIA-minta igéket a CI-ben; az injektálási igéket olyan forgatókönyvek esetében foglalja le, amelyekhez valóban valós bemenetre van szükség. Az injektálás előtt a kézmozdulati igék újra feloldják a célelemet , és elutasítják target_moved , ha még mindig animálják/áthelyezik, ahelyett, hogy üres helyre adnák a bemenetet.

gyorskonfigurálás

# Connect to any app and see its UI tree
winapp ui inspect -a notepad

# Find specific elements
winapp ui search Button -a notepad

# Activate an element
winapp ui invoke Close -a notepad

# Take a screenshot
winapp ui screenshot -a notepad

Alkalmazások célzása

Folyamatnév alapján

winapp ui inspect -a notepad
winapp ui inspect -a slack            # auto-picks visible window for multi-process apps
winapp ui inspect -a imageresizer     # partial match: finds PowerToys.ImageResizer

Ablak címe szerint

winapp ui inspect -a "LICENSE - Notepad"
winapp ui inspect -a "Fix WinApp"     # partial title match

Készítette: PID

winapp ui inspect -a 12345

HWND szerint (stabil – túléli a lap/cím változásait)

# Discover HWNDs
winapp ui list-windows -a Terminal
  → HWND 985238: "🤖 Testing" (WindowsTerminal, PID 21228)
  → HWND 131906: "Fix WinApp" (WindowsTerminal, PID 21228)

# Target specific window
winapp ui inspect -w 131906
winapp ui screenshot -w 131906

Felderítéshez, -a-w stabil célzáshoz használható. Ha -a több ablaknak felel meg, a parancs felsorolja őket a kiválasztandó HWND-kkel.

Szelektorok

Célelemek az ellenőrzés/keresés kimenetében [brackets] látható választóval. A választóknak három típusa van:

Selector Értelmezés Example
MinimizeButton AutomationId (egyedi – stabil, előnyben részesített) winapp ui invoke MinimizeButton -a myapp
btn-close-d1a0 Szemantikai csiga (akkor jelenik meg, ha nincs egyedi AutomationId) winapp ui invoke btn-close-d1a0 -a myapp
Submit Egyszerű szöveges keresés név/AutomationId (kis- és nagybetűk megkülönböztetése) alapján winapp ui invoke Submit -a myapp

Az AutomationId-választók fejlesztői azonosítók (AutomationProperties.AutomationId XAML-ben). Ha egy AutomationId egyedi a teljes felhasználói felületi fán, inspect és search közvetlenül választóként jeleníti meg – ezek túlélik az elrendezés változásait, a honosítást és a fa szerkezetátalakítását.

A slug selectorok (például) akkor jönnek létre, btn-close-d1a0ha nincs egyedi AutomationId. Formátum: prefix-name-hash. A kivonat ellenőrzi az elemidentitást, de a felhasználói felület módosítása után elavult lehet.

Kimeneti formátum vizsgálata

A inspect parancs színes kimenettel jeleníti meg az elemfát (kijelölő ciánban, név zöldben, metaadatok szürkében):

TabView Tab (0,-1 1200x48)
  TabListView List (4,-1 1100x48)
    tab-newtab-5f5b TabItem "New Tab" (14,-1 200x48)
  NewTabButton SplitButton "New Tab" [collapsed] (1104,5 96x36)
Found 10 elements (--depth 3). Use the first token as selector, e.g.: winapp ui invoke TabView -a terminal

Minden sorban az első szó a választó – használja más ui parancsokkal. Ha egy elem egyedi AutomationId azonosítóval rendelkezik, az közvetlenül (például TabView, ). NewTabButton Ha nem létezik egyedi AutomationId, a rendszer létrehoz egy létrehozott csigákat (pl. tab-newtab-5f5b).

Szemantikus csigák

A csigák a következő formátumot használják: prefix-normalizedname-hash

  • előtag – 3 betűs rövidítés (btn, txt, chk, cmb, itm, tab, img, lbl, pn, win, grp, lnk, mnu stb.)
  • normalizedname – kisbetűs alfanumerikus az AutomationId (előnyben részesített) vagy a Name (legfeljebb 15 karakter) karakterből
  • kivonat – Az elem futtatókörnyezetazonosítójának 4 karakteres hexa kivonata (ellenőrzi az elemidentitást)

A csigák héjbiztosak (nincsenek speciális karakterek), egyediek, és közvetlenül argumentumként használhatók. A kivonat elavultsági észlelést biztosít – ha az elemet lecserélték, a következőt kapja: "Előfordulhat, hogy az elem módosult. Újrafuttathatja az ellenőrzést."

A névvel vagy AutomationId azonosítóval nem rendelkező elemek csak az előtagot és a kivonatot jelenítik meg (pl. pn-c8a3).

Több találat egyértelműsítője

A kimenetből származó inspect/search csigák egyediek, de az elrendezés változásai között változhatnak – egyszerű típusneveken vagy szövegen keresztül használhatják őket, ha több egyezés is van. Ha egy választó nem egyértelmű, a parancssori felület az összes egyezést kinyomtatja a csigákkal, így kiválaszthatja a megfelelőt, és újra futtathatja az adott golyót.

winapp ui search Button -a myapp            # shows: btn-ok-a1b2 "OK", btn-cancel-c3d4 "Cancel"
winapp ui invoke btn-ok-a1b2 -a myapp       # invoke using slug (preferred)
winapp ui invoke btn-cancel-c3d4 -a myapp   # invoke the other Button by its slug

Egyszerű szöveges keresés

Egyszerű szöveg használata elemek kereséséhez – nincs szükség speciális szintaxisra:

winapp ui search Minimize -a notepad        # finds elements with "Minimize" in Name or AutomationId
winapp ui search Close -a notepad           # case-insensitive substring match
winapp ui invoke Minimize -a notepad        # search + invoke in one step (disambiguates if needed)
winapp ui search "Save" -a notepad          # find elements containing "Save"
winapp ui search "error" -a myapp           # case-insensitive match

Ha egy szöveges keresés több elemnek felel meg (például a SettingsExpander, ahol a Csoport, a Gomb és a Szöveg azonos néven szerepel), a parancssori felület automatikusan kiválasztja az egyetlen kimondható elemet. Ha több is invokable, akkor felsorolja az összes egyezést a csigákkal.

A nem invokálható keresési eredmények (például egy Gombon belüli TextBlock) esetén a keresés automatikusan megjeleníti a legközelebbi invokálható elődöt – a szülőelemet, amellyel invokehasználhatja. Ez az összes keresőválasztó esetében működik:

  lbl-savechanges-a1b2 "Save changes" (120,40 80x20)
        ^ invoke via: btn-save-c3d4 "Save"

A felületi választó közvetlenül használható:

winapp ui invoke btn-save-c3d4 -a myapp    # invoke the parent Button

Parancsok

állapot

Csatlakozzon egy alkalmazáshoz, és jelenítse meg a kapcsolat adatait.

winapp ui status -a notepad
winapp ui status -a notepad --json

Ellenőrizni

Tekintse meg a felhasználói felület elemfáját. A kimenet szemantikai csigákat jelenít meg, 2 szóköz behúzással a hierarchia számára:

winapp ui inspect -a notepad                    # full window tree, depth 3
winapp ui inspect -a notepad --depth 5          # deeper tree
winapp ui inspect txt-searchbox-e5f6 -a notepad # subtree rooted at element
winapp ui inspect --ancestors btn-close-d1a2 -a notepad  # walk up from element to root
winapp ui inspect -a myapp --interactive        # invokable elements only, auto-depth 8
winapp ui inspect -a myapp --hide-disabled      # hide disabled elements
winapp ui inspect -a myapp --hide-offscreen     # hide offscreen elements

Példakimenet (alapértelmezett):

win-aidevgalleryp-f1a3 "AI Dev Gallery Preview" (94,206 1280x1023)
  pn-c8a3 (102,207 1264x1014)
    btn-minimize-d1a0 "Minimize" (1222,206 48x48)
    btn-maximize-e2b1 "Maximize" (1270,206 48x48)
    itm-samples-3f2c "Samples" (102,330 72x62)

Példakimenet (--interactive — csak invokable elements, flat list):

btn-minimize-d1a0 "Minimize" (1222,206 48x48)
btn-maximize-e2b1 "Maximize" (1270,206 48x48)
btn-close-d1a2 "Close" (1318,206 48x48)
itm-home-7b3e "Home" (102,268 72x62)
itm-samples-3f2c "Samples" (102,330 72x62)
itm-models-9a4f "Models" (102,392 72x62)

Az elemek a következő állapotjelölőket jeleníthetik meg:

  • [on] / [off] / [indeterminate] — kapcsoló/jelölőnégyzet állapota
  • [collapsed] / [expanded] — fák, kombinált listák, menüelemek kibontása/összecsukása
  • [scroll:v] / [scroll:h] / [scroll:vh] — görgethető tároló (függőleges, vízszintes vagy mindkettő)
  • [offscreen] — az elem nem látható a képernyőn
  • [disabled] — az elem nincs engedélyezve
  • value="..." — a szerkeszthető elemek aktuális szöveges tartalma (ha eltér a névtől)

A választónak megfelelő elemek keresése. A kimenet szemantikai csigákat jelenít meg:

winapp ui search Button -a notepad              # all buttons
winapp ui search Close -a notepad               # finds elements with "Close" in name
winapp ui search SearchBox -a notepad           # finds elements with "SearchBox" in name or AutomationId
winapp ui search Button --max 10 -a notepad     # limit results

A kimenet példája:

  btn-minimize-d1a0 "Minimize" (1222,206 48x48)
  btn-maximize-e2b1 "Maximize" (1270,206 48x48)
  btn-close-d1a2 "Close" (1318,206 48x48)

A kimenetben látható csigák (pl. btn-minimize-d1a0) közvetlenül használhatók más parancsokkal:

winapp ui invoke btn-minimize-d1a0 -a notepad

get-property

Tulajdonságértékek olvasása elemből. Mintaspecifikus állapotot tartalmaz (ToggleState, Value, IsSelected stb.).

winapp ui get-property btn-submit-7a90 -a myapp              # all properties
winapp ui get-property chk-checkbox-b2c3 -p ToggleState -a myapp   # checkbox state
winapp ui get-property txt-textbox-a4b1 -p Value -a myapp          # current text value
winapp ui get-property cmb-combobox-d5e6 -p ExpandCollapseState -a myapp  # expanded or collapsed

képernyőkép

Ablak vagy elem rögzítése PNG-ként. Ha több ablak is létezik (például alkalmazás + megnyitott párbeszédpanel), a rendszer egyetlen PNG-be alakítja őket, amelyben minden ablak össze van fűzve.

winapp ui screenshot -a notepad                     # saves screenshot.png in cwd
winapp ui screenshot -a notepad --output my.png     # custom filename
winapp ui screenshot -a notepad --json              # returns file path as JSON
winapp ui screenshot -w 131906                      # target specific HWND (+ its dialogs)
winapp ui screenshot txt-searchbox-e5f6 -a myapp          # crop to element bounds
winapp ui screenshot -a myapp --capture-screen      # capture from screen (includes popups/overlays; foregrounds window)
winapp ui screenshot -a myapp --focus               # bring window to foreground first, then capture (default WGC path)

Amikor a párbeszédpanelek vagy előugró ablakok meg vannak nyitva, a rendszer az összes ablakot egyetlen PNG-re alakítja, így egyetlen képen láthatja a teljes felhasználói felületi állapotot.

Az alapértelmezett rögzítési útvonal Windows használ. Graphics.Capture (WGC), a tényleges DWM-összetett felület olvasása – a lekerekített sarkok, az átlátszóság és a munka még akkor is, ha az ablakot elzárja más windows. Ha a WGC nem érhető el (régebbi Windows buildek), a parancssori felület visszaesik a PrintWindow-ba.

Akkor használható --capture-screen , ha olyan előugró menüket, legördülő listákat, szórólapokat vagy elemleírás-átfedéseket kell rögzítenie, amelyek nem a célablak tulajdonában lévők. --capture-screen felolvassa a képernyő DC-jét, és először az előtérbe viszi az ablakot. Ha --focus csak a rögzítési módok váltása nélkül szeretné előtérbe helyezni az ablakot (például annak biztosítására, hogy a képernyőkép megegyezik azzal, amit a felhasználó éppen néz).

rekord

Ablak- vagy elemrégió rögzítése H.264 MP4-es verzióra. Alapértelmezés szerint a felvétel a Ctrl+C billentyűkombinációig vagy az átirányított stdin esetén egy új vonalig vagy EOF-ig folytatódik.

# Record for 10 seconds
winapp ui record -a myapp --duration-sec 10 --fps 15 --output demo.mp4

# Add agent-readable frames
winapp ui record -a myapp --frames --duration-sec 10 --fps 10 --output demo.mp4 --json

# Stop an unbounded recording through stdin
"" | winapp ui record -a myapp --json --output capture.mp4

# Include screen overlays and popups
winapp ui record -a myapp --capture-screen --duration-sec 5 --output with-popups.mp4

Lehetőségek:

  • --duration-sec N — Rekord N másodpercig. Alapértelmezett 0 rekord, amíg le nem áll.
  • --fps N — Célkeretek másodpercenként (alapértelmezett 15).
  • --max-edge N — Leskálázás, hogy a leghosszabb él legfeljebb N képpont legyen (0 = nincs leskálázás).
  • --capture-screen — Rögzítés a képernyő tartományvezérlőjén (beleértve az átfedéseket/előugró ablakokat; az ablak előterét).
  • --output <path> — Kimeneti MP4 elérési út. Alapértelmezett érték: recording-<timestamp>-<guid>.mp4.
  • --frames — Időbélyegzős JPEG-bizonyíték írása a fájlba <output-name>.frames. Támogatja az 1-30 fps és --max-edge a 64-4096 (alapértelmezett 1280). A keretadatok megfeleltetése 1 GiB; az MP4 folytatódik, ha eléri a korlátot.

Ügynök által olvasható keretösszetevők:

demo.mp4
demo.frames/
  manifest.json
  frames.ndjson
  frames/
    frame-000000-t000000000012.jpg

frames.ndjsonmintánként sampleIndexegy vonallal rendelkezik, monotonelapsedMs, MP4-relatívmediaTimeMs, fileimageIndexés changed. Az egymást követő képpont-azonos minták újra felhasználják az előző minőségi-85 JPEG-et.

manifest.jsonrögzíti a kérést, az időzítést, az MP4-állapotot, a képméreteket és az állapotot (completevagy partialtruncated). A csonkolt időzítés a megtartott előtagot fedi le, miközben video a teljes MP4-et ismerteti.

A --framesmeglévő MP4 és keret elérési útjai nem lesznek lecserélve. Ha az MP4 véglegesítése sikertelen, a rendszer a megőrzött kereteket a következő alatt <output-name>.frames.partial-*teszi közzé: . A keretösszetevők titkosítatlan képernyőtartalmakat tartalmaznak; kezelheti őket, például képernyőképeket vagy videót.

Rögzítési módok (a JSON mode mezőben jelentve):

  • wgc— Windows Grafikus rögzítés (alapértelmezett; az ablak elzárt állapotában működik).
  • printwindow — GDI PrintWindow (tartalék, ha a WGC nem érhető el ezen a rendszeren/munkamenetben; futtassa újra a --capture-screen képernyő tartományvezérlőjét).
  • screen — Képernyő dc keresztül --capture-screen (beleértve az átfedések / előugró ablakok; hozza az ablakot az előtérben).

JSON-kimenet (--json):

  • stdout: A végső rögzítés eredménye, beleértve a ütemet, a leállítás okát, az opcionálist frameArtifactsés a figyelmeztetéseket.
  • stderr: Soronként egy JSON-objektum: az recording-started első keret utáni esemény, amelyet hiba követ, ha a rögzítés később sikertelen lesz. A keret elérési útjai csak akkor jelennek meg, ha a keretkimenet aktív.

Hibakódok:

  • element_not_found — A választó nem egyezett.
  • ambiguous_selector – A választó több elemet is megfeleltet; használjon egy javasolt golyót.
  • invalid_arguments – A beállítás értéke érvénytelen.
  • output_exists — Ezzel --framesaz MP4 vagy keretkönyvtár már létezik.
  • frame_output_failed – A keretkimenet meghiúsulása után egyik összetevő sem őrizhető meg.
  • partial_output — Csak egy összetevő fejeződött be; vizsgálja meg partialOutput és recoveryHint.

Ismert korlátozás: Ha egy elemet egy ablakos előugró ablakban rögzít, az rögzítheti az alapul szolgáló ablakot. Jegyezze fel a teljes ablakot, vagy használja a következőt ui screenshot --capture-screen: Lásd : #646.

Programozott módon aktiválhat egy elemet (kattintson a gombra, jelölje be a jelölőnégyzetet, bontsa ki a kombinált listát).

winapp ui invoke btn-submit-7a90 -a myapp             # by slug from inspect
winapp ui invoke btn-submit-a1b2 -a myapp  # by slug from inspect/search
winapp ui invoke cmb-sizecombobox-b4c5 -a myapp # expand combo box

Minták sorrendbe rendezése: InvokePattern → TogglePattern → SelectionItemPattern → ExpandCollapsePattern.

click

Kattintson a képernyő koordinátáinak egyik elemére egérszimulációval. Használja ezt a nem támogatott InvokePattern vezérlőkhöz (például oszlopfejlécekhez, listaelemekhez).

winapp ui click btn-column1-a3f2 -a myapp              # single click by slug
winapp ui click "Column1" -a myapp                      # single click by text search
winapp ui click btn-column1-a3f2 -a myapp --double      # double-click
winapp ui click btn-column1-a3f2 -a myapp --right       # right-click

A többi bemeneti injektálási igéhez hasonlóan a cél az előtérbe kerül, click és gyorsan meghiúsul (no_interactive_desktop zárolt/biztonságos asztalon, ha a fókusz nem helyezhető át) ahelyett, foreground_not_target hogy rossz ablakra kattintanál. Az elemet a gomb lenyomása előtt is újra feloldja: a kurzor elhelyezése után egy utolsó pozícióellenőrzést végez, így a folyamatosan mozgó/animáló cél sikertelen lesz target_moved ahelyett, hogy a kattintás üres helyre került volna – a jelentett sikeresség azt jelenti, hogy a cél továbbra is a helyén volt, amikor a gomb lement.

húz

Nyomja le az egérgombot az egyik ponton, lépjen a másikra, majd engedje fel a következővel drag <from> <to>: ahol minden végpont elemválasztó (az elem közepéről vagy közepére húz), vagy a képernyő koordinátái x,y pontosan az általuk winapp ui inspectjelentett módon vannak bejelentve. Keverje össze és egyezzen szabadon (választó→választó, választó→koordok, koordok→koordok).

Köztes áthelyezéssel használja SendInput , hogy az alkalmazás reális üzenetfolyamot WM_MOUSEMOVE láthassa. A fogópontok, csúszkák, vászonrajzok és húzások átrendezéséhez/átméretezéséhez használható.

winapp ui drag itm-card-9f8e itm-slot-2c1a -a myapp           # reorder: card center → slot center
winapp ui drag itm-card-9f8e 300,400 -a myapp                 # element center → screen coords (from inspect)
winapp ui drag 120,200 480,200 -a myapp                       # raw screen coords → screen coords
winapp ui drag itm-card-9f8e itm-trash-0001 -a myapp --right  # right-button drag

# Press-and-hold / long-press and drop-target dwell
winapp ui drag tile-photo-7b3c tile-photo-7b3c -a myapp --hold-ms 600   # long-press: from == to, hold 600ms, no move
winapp ui drag itm-card-9f8e pane-left-2c1a -a myapp --dwell-ms 350      # settle on the drop target before releasing

Lehetőségek:

  • --right — Húzza a jobb egérgombbal a bal gomb helyett.
  • --hold-ms <ms> — Az áthelyezés előtt tartsa lenyomva a gombot az elején (alapértelmezett: 0). A <from> == <to> (mozgás nélkül) ez egy lenyomásos/ hosszúnyomású kézmozdulatot hajt végre.
  • --dwell-ms <ms> — Költözés után a célhelyen tartózkodik, a kiadás előtt (alapértelmezett: 0). Lehetővé teszi a célokat / egyesítés átfedéseket , hogy a kar egy tartós rámutatás (ahelyett, hogy a pillanat, amikor a kurzor érkezik) retesz előtt a gomb-up.

x,y A csupasz képernyőkoordináták ugyanabban a térjelentésbenwinapp ui inspect/search, a választó pedig az elem középpontjába kerül – először vizsgálja meg a pontokat.

Például send-keys --via send-inputa drag cél előtérbe hozása után az operációs rendszer széles képernyő-koordinátáit injektálja. Ha a fókusz nem helyezhető el a célhoz (például a fókuszlopás megakadályozása háttérfolyamatból), a parancs nem a megfelelő ablakra húzással () meghiúsul ,foreground_not_target hanem az ablakra összpontosít, vagy először az ablakra kattint. Zárolt/biztonságos asztalon a hiba a no_interactive_desktop. Az egyes elemvégpontok közvetlenül az húzás előtt újra feloldódnak; ha még mindig mozog/átméretez (animálási cél), a parancs ahelyett target_moved , hogy egy elavult pontra húzza. (A csupasz x,y végpontok nem ellenőrizhetők újra, ezért as-ishasználják őket.)

Érint

Szintetikus érintéses kézmozdulatok injektálása a Windows mutatóinjektálási API használatával. A kapcsolattartó horgony vagy elemválasztó (az elem középpontját használja), vagy explicit képernyőkoordináta x,y (ugyanazon térjelentéseken --at keresztül winapp ui inspect ). Olyan interakciókhoz és több érintéses kézmozdulatokhoz használható, amelyeket az egérszimuláció nem tud kifejezni.

winapp ui touch btn-ok-1a2b -a myapp                                   # tap at the element center
winapp ui touch -a myapp --at 320,240                                  # tap at explicit screen coords
winapp ui touch tile-photo-7b3c -a myapp --gesture long-press --hold-ms 600
winapp ui touch -a myapp --at 100,300 --gesture swipe --to-point 400,300
winapp ui touch img-map-9f8e -a myapp --gesture pinch --distance 200    # pinch-to-zoom out (2 fingers)
winapp ui touch img-map-9f8e -a myapp --gesture stretch --distance 200  # stretch-to-zoom in (2 fingers)

Lehetőségek:

  • --gesture <g>— tap (alapértelmezett), double-tap, long-press, swipe, pinch. stretch
  • --at <x,y> — Explicit kezdőpont (képernyőkoordináták). A választó elemközpontjának alapértelmezett értéke.
  • --to-point <x,y> — Végpont egy swipe. Elsőbbséget élvez a --direction.
  • --direction <right|left|up|down> — Pöccintsen irányban (alapértelmezett: right). Kombinálva --distance a végpont kiszámításához, ha --to-point nincs megadva.
  • --distance <px> — Ujjpárok képpontban pinch/stretch, vagy pöccintsen képpontban.
  • --hold-ms <ms> — Az emelés előtt tartsa lenyomva a névjegyeket (a hosszú lenyomás időtartama, alapértelmezés szerint 500 ms, long-press ha nincs beállítva).
  • --duration-ms <ms> — A kézmozdulatok mozgatási ideje (pöccintés/csippentés/nyúlás; alapértelmezett 300).
  • --fingers <n> — Partnerek száma (1–10; alapértelmezett 1). pinch / stretch mindig 2-t használjon.

Injektálás biztonsága. touch Nem hajlandó injektálni, hacsak egy nem nulla célablak-kezelő nem oldja fel a problémát, és az ablak az előtérben van – akkor meghiúsul no_target , ha nem oldható fel ablak, foreground_not_target ha a fókusz nem helyezhető át, vagy no_interactive_desktop zárolt/biztonságos asztalon. Minden koordináta (elemközpont, explicit --at/--to-pointés generált útpontok) a célablak téglalapján van bejelölve; az ablakon kívüli pont nem végzetes figyelmeztetésként jelenik meg (warnings[]bevitel --jsonvagy figyelmeztető vonal szöveges módban), és az injektálás továbbra is folytatódik – megfeleltetve az egér igéinek (click/drag/hover/scroll), amelyek szintén az ablakon kívüli koordinátákra injektálnak. --fingers 10 felett a rendszer elöl elutasítja.

Hardveres megjegyzés. Az Touch a modern szintetikus mutatóeszközt (CreateSyntheticPointerDevice(PT_TOUCH)) részesíti előnyben, és visszaesik az örökölt InitializeTouchInjection/InjectTouchInput API-ra. Ha az injektálás nem támogatott az aktuális eszközön/munkamenetben, a parancs a hamis sikeresség jelentése helyett a tényleges Win32 hibakódot (például "nem támogatott") jeleníti meg – a nem nulla kimenetet "érintés nem kézbesítve" értékként kezeli.

Távoli asztal/virtuálisgép-munkamenetek. Egy Távoli asztal (RDP) vagy néhány virtuálisgép-munkamenetben az operációs rendszer elfogadhatja a szintetikus érintést (0. kilépés) anélkül, hogy ténylegesen elérnék a célalkalmazást. Ha távoli munkamenetet észlel, touch hozzáfűz egy kézbesítéssel kapcsolatos bizonytalansági figyelmeztetést – bejegyzést warnings[]--jsonvagy szöveges módban egy figyelmeztető sort. A ✅/exit 0 azt jelenti, hogy az injektálási hívás sikeres volt, nem azt, hogy az alkalmazás megkapta a bemenetet; erősítse meg a hatást ui screenshot/ui inspect , amikor számít.

toll

Szintetikus toll-/tollbemenet – koppintások és tollvonások – injektálása a Windows szintetikus mutató API használatával (CreateSyntheticPointerDevice(PT_PEN); Windows 10 1809+). Elem középre, explicit --at pontra vagy teljes --path tollvonásra célozhat.

winapp ui pen canvas-1a2b -a myapp                                     # pen tap at the element center
winapp ui pen -a myapp --at 320,240 --pressure 0.8                     # firm pen tap at explicit coords
winapp ui pen -a myapp --path "100,100 150,120 210,140 260,120"        # draw an ink stroke
winapp ui pen -a myapp --path "100,100 260,100" --eraser               # erase along a stroke
winapp ui pen -a myapp --at 200,200 --tilt-x 30 --tilt-y -15           # tilted pen contact

Lehetőségek:

  • --at <x,y> — Toll kapcsolattartási pontja (képernyőkoordináta). A választó elemközpontjának alapértelmezett értéke. A megadott állapot figyelmen --path kívül hagyva.
  • --path "<x,y x,y …>" — Szabadkézi körvonal elérési útja szóközzel elválasztott x,y párként (az egypontos elérési út egy koppintás).
  • --pressure <0.0–1.0> — Tollnyomás (alapértelmezett 0,5).
  • --tilt-x <deg> / --tilt-y <deg> — Toll dőlési szöge, −90–90 (alapértelmezett 0).
  • --eraser — A toll radírvégét használja a tipp helyett.
  • --duration-ms <ms> — A teljes stroke utazási idő ezredmásodpercben, interpolált UPDATE-keretként elosztva az útvonalon (alapértelmezett: ~10 ms útpontonként). Ezzel szabályozhatja, hogy a toll milyen gyorsan mozog az elejétől a végéig.

Injektálás biztonsága. Mint, touchpen megtagadja az injektálást nem nulla, előtérben lévő célablak (no_target / foreground_not_target / no_interactive_desktop) nélkül, és minden szabadkézi pontot a célablak téglalapjára ellenőriz, és nem végzetes figyelmeztetésként (warnings[]--jsonszöveges módban vagy figyelmeztető vonalként) észleli az ablakon kívüli koordinátákat, miközben továbbra is injektál – az egér igéivel összhangban. Az érvénytelen --pressure (0,0–1,0-s) vagy dőlés (±90°-on kívül) a rendszer elöl elutasítja.

Távoli asztal/virtuálisgép-munkamenetek. A tollak útválasztása különösen megbízhatatlan a Távoli asztal: az injektálási hívás sikerességet jelezhet (0-ás kilépés), miközben a toll bemenete nem éri el az alkalmazást. Ha távoli munkamenetet észlel, pen hozzáfűz egy kézbesítéssel kapcsolatos bizonytalansági figyelmeztetést (warnings[]--jsonszöveges módban, vagy egy figyelmeztető sort), így ✅ a rendszer nem téveszti össze a megerősítést. Tollfüggő folyamatok ellenőrzése helyi, interaktív asztalon.

Hover

Vigye az egeret egy elem közepére a rámutatási effektusok (elemleírások, úszó panelek, vizualizációs állapotok) aktiválásához. A valósághű egérmozgatáshoz használ SendInput egy kis váltógombbal, majd vár egy konfigurálható tartózkodási időre.

winapp ui hover btn-info-a1b2 -a myapp                          # hover with default 800ms dwell
winapp ui hover btn-info-a1b2 -a myapp --dwell-time 1200        # longer dwell for slow tooltips
winapp ui hover btn-info-a1b2 -a myapp; winapp ui screenshot -a myapp --capture-screen  # hover then capture tooltip

Lehetőségek:

  • --dwell-time <ms> — Ezredmásodpercben meg kell várni az effektusok megjelenését (alapértelmezett: 800, tartomány: 0–10000)

küldési kulcsok

Szintetikus billentyűzetbemenet küldése – a billentyűzet megfelelője.click Az UIA nem rendelkezik billentyűzetinjektálási mintával, ezért ez a Win32 rétegre csökken. Használhatja billentyűzetes navigációhoz (nyilak, Tab, Enter, Esc), billentyűparancsokhoz (ctrl+c, ), és olyan vezérlőkbe való beíráshoz, alt+f4amelyeknél az atomi írás helyett set-valuebillentyűleütéses eseményekre van szükség.

winapp ui send-keys "down down enter" -a myapp                 # arrow navigation then commit
winapp ui send-keys "ctrl+a delete" -a myapp                   # select all, then delete
winapp ui send-keys "Hello world" --target txt-name-a1b2 -a myapp  # focus a field, then type text
winapp ui send-keys "text=down text=down text=enter" -a myapp  # type the words, don't press the keys
winapp ui send-keys "down down enter" -a myapp --verbatim      # same, but type the whole argument literally
winapp ui send-keys "alt+f4" -a myapp                          # close window via accelerator
winapp ui send-keys "vk=0x5D" -a myapp                         # a key with no friendly name (Apps/Menu key)
winapp ui send-keys "ctrl+shift+t" -a myapp --via send-input   # use OS-wide injection instead of PostMessage
winapp ui send-keys "win+shift+v" -a myapp --via send-input --allow-system-keys  # opt in to drive a global hotkey

Kulcshelyesség (térelválasztó jogkivonatok, idézőjeles több-token sztringek):

  • Elnevezett kulcsok – enter/return, tab,esc/escape , spacebackspace,delete/del , insert, homeendpageup/pguppagedown/pgdn, . up/down/left/rightf1f16appsprintscreencapslock
  • Sorozatok – a rendszer több tokent nyom a következő sorrendben: down down enter.
  • Módosító kombinációk – ctrl, shift, alt, win összekapcsolva a következővel +: ctrl+shift+t, alt+f4.
  • Literális szöveg – minden olyan jogkivonat, amely nem ismert kulcs, karakter szerint van begépelve: hello. A szomszédos literális szavak megtartják közöttük a szóközt, így egy idézett kifejezés, például "Hello world" szó szerint van begépelve (a szóköz megmarad); egy olyan literál, amely csak szöveget tartalmaz +C++ , vagy a+b szövegként van begépelve, nem pedig kombináltként értelmezve.
  • Explicit literális feloldás – a jogkivonat előtagja, amellyel text= szó szerint beírhatja, még akkor is, ha egy kulccsal vagy módosítóval ütközik: text=enter az Enter billentyű lenyomása helyett írja be az "enter" szót, és text=ctrl+a írja be a literális sztringet. Tükrözi a vk= menekülést; a szökött érték továbbra is összeolvad a szomszédos literális szavakkal (text=down low → "lefelé alacsony"). Mivel a jogkivonatok térelválasztók (és a szomszédos konstansok egyetlen szóközzel újracsatlakoznak), a fordított perjeles feloldásokat egy text= olyan értékbe írja be, amely egyébként nem élné túl: \s → szóköz, \t → lap, \n → új vonal, \r → új vonal, \\ → literális fordított perjel. \n, \rés \r\n mindegyik beszúr egy-egy sortörést (egy Enter/ VK_RETURN), így text=line1\nline2text=line1\r\nline2 mindkettő egy új sort ír be. Ezért text=a\s\sb az "a b" (dupla szóköz) típust írja be, és text=\shi megtartja a vezető helyet. A nem felismert menekülés (pl. \x) szó szerint balra van hagyva.
  • Egész argumentum literál (--verbatim) – ha a teljes hasznos adat literális szöveg, akkor ahelyett, hogy --verbatim minden tokent text=megkerülne. A teljes kulcs argumentumot pontosan a megadott módon típusok – névvel ellátott kulcs/kombinált/vk=/text=értelmezés nélkül –, és a normál elérési úttól eltérően a pontos belső térközt (összecsukás nélkül) megőrzi anélkül, hogy szükség lenne rá.\s Így send-keys "down down enter" --verbatim típusok a szavakat, és send-keys "a b" --verbatim megtartja a dupla helyet. A fordított perjelek feloldása nem módban van dekódolva --verbatim (egy \s fordított perjelként és "s"-ként van begépelve); akkor használjon jogkivonatot text= , ha menekülő vezérlőkarakerre van szüksége.
  • Nyers virtuális kulcsok – vk=0xNN (hexa) vagy vk=NN (decimális) felhasználóbarát név nélküli kulcsokhoz.

Lehetőségek:

  • --target <selector> — A kulcsok elküldése előtt összpontosítsa ezt az elemet (UIA-n keresztül). Nélküle a kulcsok az alkalmazás aktuálisan szűrt eleméhez kerülnek.
  • --verbatim — Írja be a teljes kulcs argumentumot literális szövegként (nincs kulcs/kombinált/vk=/text= elemzés), és megőrzi a pontos szóközt. A jogkivonatonkénti text= feloldás egész argumentuma.
  • --via <transport>— post-message (alapértelmezett) bejegyzések WM_KEYDOWN/WM_KEYUP/WM_CHAR a célablak üzenetsorában. HWND-célzott, és megkerüli az UIPI-t (integritási szinteken működik). send-input az operációs rendszer szélesére SendInput injektál, és az előtérablakba kerül.

Szállítási / ismert korlátok kiválasztása:

  • post-message ez az alapértelmezett, mert áthalad a UIPI-n, és nem függ az előtérben lévő ablaktól. Korlátok: nem tudja aktiválni az alacsony szintű kampókon keresztül WH_KEYBOARD_LL regisztrált globális gyorsbillentyűket (ezek bármelyik ablaksor felső rétegében koppintanak a bemenetre), és a nyerskulcs-állapotot GetAsyncKeyState olvasó alkalmazások nem figyelhetik meg a tárolt módosítókat. Az előtérkezelés után automatikusan feloldja és közzéteszi a célszál szűrt gyermekablakát (via GetGUIThreadInfo) úgy, hogy a klasszikus Win32/WinForms-alkalmazások, amelyek vezérlői külön gyermekablakok, kulcsokat kapnak anélkül, hogy manuálisan céloznák meg a vezérlőt. WinUI 3 / UWP alkalmazások ablak nélküli XAML vezérlők nélkül gyermek HWND, így a közzétett WM_CHAR/WM_KEYDOWN nincs semmi landol, és elvetik - post-message nem tudja vezetni őket (a parancs figyelmezteti és kilép 0); használja.--via send-input (WPF ablakok egy HWND rendszerűek, és a kulcsokat a belsőleg szűrt elemhez irányítják, így az üzenet utáni funkció ott is működik.)
  • send-inputteljesen valós bemenetet hoz létre (a modifiers láthatóGetAsyncKeyState, alacsony szintű horgokat aktivál), de bármilyen előtérablakba kerül, és a UIPI blokkolja, amikor emelt szintű folyamatból injektál egy alacsonyabb integritású célhelyre (AppContainer/AppX). Ha send-input hibajelentést tesz, a cél valószínűleg emelt szintű vagy AppX-alkalmazás – használja post-messagevagy futtassa a parancssori felületet egyező integritási szinten. Biztonsági őrként ellenőrzi, hogy a célablak valóban az előtérben van-e közvetlenül az injekció beadása előtt, és foreground_not_target hogy rossz ablakba gépelne, ha a fókuszt nem lehetett volna hozzá juttatni – összpontosítson vagy kattintson először az ablakra. Egy zárolt vagy biztonságos asztalon ehelyett meghiúsul no_interactive_desktop (nincs előtérablak az injektáláshoz) – oldja fel a munkamenetet, vagy használjon UIA-mintás igét (set-value, invoke).
  • A rendszer által fenntartott kombinált listák (win+l, , win+r, ctrl+shift+escctrl+alt+del, , alt+tabalt+f4, ctrl+esc, magányos win/printscreen, ...) az operációs rendszeren/rendszerhéjon működnek ahelyett, hogy csak a célként szolgálnak, amikor az operációs rendszer egészét elküldik. send-input alapértelmezés szerint elutasítja őket (hibák és invalid_arguments nem küld semmit), mert az operációs rendszer szintjén történő injektálásnak jóval a célablakon túl is vannak hatásai (például win+l zárolná a munkamenetet). Pass --allow-system-keys to opt in – ez lehetővé teszi, hogy vezessen egy globális gyorsbillentyű, mint a PowerToys" win+shift+v , vagy win+r (a globális alacsony szintű horog figyeli az operációsrendszer-szintű bemeneti stream, így az injektált kombinált tűz azt). A kivételek, amelyek még a következőkkel --allow-system-keysis blokkolva maradnak:win+l zárolja a munkaállomástLockWorkStation(), amely nem távolítható el az automatizálásból (megszakítja a CI-t és a távoli asztali munkameneteket), és ctrl+alt+del egy biztonságos figyelem-sorozat (SAS), amely a jelzőtől függetlenül Windows csökken az injektált bemenetből – soha nem lép érvénybe, ezért a félrevezető sikerek jelentése helyett hibát jelez (invalid_arguments1. kilépés). Más kombinációk (alt+f4, , ctrl+shift+esc, win+r...) engedélyezettek lesznek a jelölővel – a hívó vigyázz. Másik lehetőségként, ha egy rendszer-kombinált listát egy adott ablakhoz szeretne --via post-messagetovábbítani, amely ablak hatókörű és nem érintett (a közzétett win+l érték ártalmatlan, bár a közzétett alt+f4 még mindig bezárja a célablakot).

Billentyűleütésenkénti események (KeyDown/ TextChanged):

  • Az elnevezett kulcsok és módosító kombinációk (down, enter, , ctrl+shift+t) vk=0xNNvalódi KeyDown (és KeyUp) elemet aktiválnak mindkét átvitelen – különállóként (vagy WM_KEYDOWN virtuáliskulcs-eseményként /WM_KEYUPSendInput ) kézbesítve.
  • A literálisan beírt szöveg (hello) átvitelenként különbözik:
    • --via send-inputaz egyes karaktereket az aktív billentyűzetkiosztás virtuális kulcsára (plusz Shift) képezi le, így a cél egy valódi, a megfelelő virtuális kulccsal rendelkező,KeyDown majd az operációs rendszer által összeállított WM_CHAR (emelőTextChanged) karaktert lát– azaz karakterenként egy teljes billentyűleütést. Az aktuális elrendezésben nem elérhető karakterek (vagy a Ctrl/AltGr billentyűkombinációt igénylő) Unicode-csomagra esnek vissza, így a pontos karakter továbbra is megjelenik. Akkor használjasend-input, ha kulcsonkénti KeyDown hűségre van szüksége (például winUI 3/WPFTextBox, amelynek kezelőkulcsa ki van kapcsolva KeyDown). Egy normál (nem emelt szintű) WinUI 3 teszt gazdagép esetében először hozza az ablakát az előtérbe (winapp ui focus / kattintson rá), mivel send-input az előtérben lévő ablakot célozza meg.
    • --via post-message karakterenként egyetlen WM_CHAR bejegyzést tesz közzé (a beírt szöveghez nem tesz közzé WM_KEYDOWN/WM_KEYUP bejegyzést – ezek nevesített kulcsokhoz/kombinált listákhoz vannak fenntartva), ami nem emel karakterenként KeyDown. Automatikusan újraküldi az ablak szűrt gyermekvezérlőjét, így a klasszikus Win32/WinForms-alapú szerkesztési vezérlők a szöveget (emeléstWM_CHAR) helyezik TextChangedel. Kikötés: A WinUI 3/UWP/XAML-alkalmazások (a winapp elsődleges célja) ablak nélküli vezérlőkkel rendelkeznek, amelyek figyelmen kívül hagyják a WM_CHAR/WM_KEYDOWN közzétett elemet – így sem a literális szöveg, sem az elnevezett kulcsok (Enter, digits, ...) nem érik el őket, annak ellenére, hogy a parancs sikeresnek bélyegzi őket. Figyelmeztetést ad ki, ha a cél XAML-nek tűnik, és továbbra is kilép a 0-ból (PostMessage a tűz és a felejtés, és nem tudja megerősíteni a kézbesítést). WinUI 3/UWP/WPF-alkalmazások vezetésére használható--via send-input; a klasszikus Win32-vezérlőkre való foglaláshozpost-message, vagy ha csak az integritási szintek közötti hatókörre van szüksége.

JSON-kimenet (--json): az eredmény hwnd az a tényleges ablak, ahová a kulcsokat kézbesítették – ez --via post-message a feloldott, szűrt gyermekvezérlő, amikor a parancs újratározza azt (nem feltétlenül a legfelső szintű -w/-a/-e ablakot), így az automatizálás pontosan meg tudja erősíteni, hogy a bemenet hol landolt. Ha ez a tényleges cél ablak nélküli XAML-gazdagépnek tűnik, a fenti kézbesítési kikötés is bejegyzésként warnings[] jelenik meg (ugyanez a konzolon látható tanácsadás), így ✅ a 0-s kilépés nem téveszthető össze a megerősített kézbesítéssel.

set-value

Állítson be egy értéket programozott módon egy szerkeszthető elemen (nincs billentyűleütés, nincs alkalmazás előtér). Tartalék láncot használ:

  1. ValuePattern – TextBox, ComboBox, PasswordBox és a legtöbb szerkeszthető vezérlő.
  2. RangeValuePattern – numerikus vezérlők (Csúszka, ProgressBar), ha az érték számként van elemezve.
  3. LegacyIAccessible (IAccessible::put_accValue) – a Csak TextPattern szerkesztési vezérlők tartaléka, amelyek nem fednek fel ValuePattern-t (pl. rich-edit/ Document compose box). Ezzel bezárja az olvasási/írási rést, ahol get-value beolvasható egy ilyen vezérlő, de set-value nem.
winapp ui set-value txt-textbox-a4b1 "Hello world" -a notepad
winapp ui set-value sld-volume-b2c3 75 -a myapp
winapp ui set-value doc-compose-9f3a "hello" -a myapp        # RichEdit/compose box via LegacyIAccessible

Ha a három minta közül egyik sem tudja beállítani az értéket, set-value akkor egy egyértelmű hiba jelenik meg, amely végső megoldásként jelenik send-keys meg.

Nem minden gazdag szerkesztő támogatja a programozott készletet. A LegacyIAccessible tartalék csak olyan vezérlőkön IAccessible::put_accValue működik, amelyek akadálymentessége implementálható – a natív Win32 rich-edit vezérlők és a Chromium/Electron/WebView2 komponálási felületek általában igen. A WinUI 3 RichEditBox és a WPF RichTextBox nem támogatják a programozott értékbeállítást – a kialakításuk alapján a tartalmakat írásvédettként UI-automatizálás elérhetővé teszik (szöveges minta, nem állítható értékminta), ezért set-value nem tudnak írni nekik. Használja send-keys (amelyhez egy nyitott, előtérben lévő asztalra van szükség) ezekhez.

get-value

Olvassa el az aktuális értéket egy elemből. Intelligens tartalékláncot használ: TextPattern (RichEditBox, Document) → ValuePattern (TextBox, Slider) → SelectionPattern (ComboBox, RadioButton, TabView) → név (címkék).

winapp ui get-value doc-texteditor-53ad -a notepad          # read full document text
winapp ui get-value SearchBox -a myapp                      # read TextBox content
winapp ui get-value CmbTheme -a myapp                       # read ComboBox selected item
winapp ui get-value sld-volume-b2c3 -a myapp                # read Slider value
winapp ui get-value lbl-title-a1b2 -a myapp --json          # JSON: { "elementId": "...", "text": "..." }

fókusz

A billentyűzetfókusz áthelyezése egy elemre.

winapp ui focus txt-textbox-a4b1 -a notepad

görgetés nézetbe

Görgessen egy elemet a látható területre.

winapp ui scroll-into-view itm-targetitem-c3d4 -a myapp

várakozási idő

Várjon, amíg egy elem megjelenik, eltűnik, vagy egy érték eléri a célt.

winapp ui wait-for Button -a myapp --timeout 5000                       # wait for any button
winapp ui wait-for btn-submit-7a90 -a myapp --timeout 5000             # wait for specific element
winapp ui wait-for CounterDisplay -a myapp --value "5" --timeout 5000  # wait for element value (smart fallback)
winapp ui wait-for lbl-status -a myapp --property Name --value "Done" --timeout 5000  # wait for specific property
winapp ui wait-for btn-submit-a1b2 --gone -a myapp --timeout 2000      # wait for element to disappear
winapp ui wait-for lbl-status -a myapp --value "Done" --contains       # substring match instead of exact equality

Lapozzunk

Tárolóelem görgetése. Keresse meg a search scroll görgethető tárolókat a ( [scroll:v] függőleges) vagy [scroll:h] a (vízszintes) jelölőkkel.

# Find which elements are scrollable and in which direction
winapp ui search scroll -a myapp
#   pn-scrollview-bfef Pane "scrollView" [scroll:v] (main content, vertical)
#   pn-scrollviewer-bfb1 Pane "scrollViewer" [scroll:h] (horizontal list)

# Scroll the main content down
winapp ui scroll pn-scrollview-bfef --direction down -a myapp

# Jump to top/bottom
winapp ui scroll pn-scrollview-bfef --to bottom -a myapp

# If you target an element that's not scrollable, scroll walks up to find the nearest scrollable parent
winapp ui scroll itm-someitem-a1b2 --direction down -a myapp

# Synthesize real mouse-wheel input over the element (1 = one notch up, -1 = one notch down).
# Use this to test handlers that respond to the wheel directly (zoom, custom scroll) rather than ScrollPattern.
winapp ui scroll img-map-a1b2 --wheel -1 -a myapp

Lehetőségek:

  • --direction <up|down|left|right> — Görgetés növekményesen keresztül ScrollPattern.
  • --to <top|bottom> — Ugrás a start/end ScrollPatterngombra.
  • --wheel <notches> — Az egérkerék bemenetének szintetizálása az elem középpontján keresztül SendInput, a tárcsacsúcsokban (detentekben): 1 = egy felfelé/hátra, -1 = egy bevágás lefelé/felé, 3 = három felfelé. (Mindegyik jelölő a felhasznált 120 egység WHEEL_DELTA WindowsSendInput; a CLI 120-tal skálázza a jelöléseket.) Megkerülő .ScrollPattern

--direction, --toés --wheel kölcsönösen kizárják egymást – pontosan egyet adnak át. Mivel --wheel az operációsrendszer-szintű bemenetet a képernyő koordinátáira injektálja, a cél először az előtérbe kerül, és meghiúsul (foreground_not_target), ha a fókusz nem helyezhető át ahelyett, hogy nem a megfelelő ablakot görgeti.

összpontosítás

Az aktuális billentyűzetfókuszú elem megjelenítése.

winapp ui get-focused -a myapp

list-windows

Az alkalmazás összes látható ablakának listázása, beleértve az előugró ablakokat és a párbeszédpaneleket. Alapértelmezés szerint a névtelen, nulla méretű ablakok (láthatatlan rendszerablakok) ki vannak zárva.

winapp ui list-windows -a imageresizer
winapp ui list-windows -a Terminal
winapp ui list-windows                                      # all windows (no filter)
winapp ui list-windows --show-hidden                        # include invisible zero-size windows

Keretrendszer támogatása

Keretrendszer Ellenőrizni keres hív set-value képernyőkép
WPF ✅ Teljes fa ✅ Minden tulajdonság ✅ Minden minta ✅ ¹ ✅
WinForms ✅ ✅ ✅ ✅ ✅
Win32 ✅ ✅ ✅ ✅ ✅
WinUI 3 ✅ ✅ ✅ ✅ ¹ ✅
Elektron ⚠️ Krómfa ⚠️ Korlátozott ⚠️ Változó ⚠️ Változó ✅
Flutter ⚠️ Alapszintű ⚠️ Alapszintű ❌ Minimális ❌ ✅

¹ set-value működik minden olyan vezérlőn, amely kiteszi a ValuePattern/RangeValuePatternt, valamint a Csak TextPattern szerkesztési vezérlőket, amelyek akadálymentességi implementálva IAccessible::put_accValue vannak (LegacyIAccessible tartalék). A WinUI 3 RichEditBox és a WPF RichTextBox kivételek – csak az írásvédett szövegmintát teszik elérhetővé (nincs beállítható értékminta), így nem állíthatók be programozott módon, a beírásukhoz használja send-keys (interaktív asztal szükséges).

Hibaelhárítás

Error A probléma oka Solution
"Nem található futó alkalmazás" Az alkalmazás nem fut, vagy a néveltérés nem egyezik Folyamat nevének ellenőrzése vagy a PID használata
"Több ablak egyezés" Nem egyértelmű -a érték Használat -w <HWND> a felsorolt lehetőségek közül
"több ablaka van" A folyamat több ablakból áll Adott cél célként való használata -w <HWND>
"Választó egyező N elemekkel" Nem egyértelmű örökölt választó A kimenetből származó inspect vagy hozzáfűző [0][1] csigák használata régi választókhoz
"Előfordulhat, hogy az elem megváltozott" A lassú kivonat nem felel meg az aktuális elemnek Újrafuttatás inspect vagy search friss csigák lekérése
"nem támogatja a meghívási mintát" Az elem nem hívható meg Az elem használata inspect invokálható gyermek megkereséséhez
"Nincs UIA-ablak" Az UIA nem látja a folyamatot A list-windows HWND megkereséséhez használja, majd -w
"Az ablak mérete nulla" Az ablak kis méretű Az alkalmazás automatikusan vissza lesz állítva
Előugró/legördülő lista nem a képernyőképen Az alapértelmezett rögzítés ablakonként történik, és nem tartalmaz nem szabályozott átfedéseket Jelölő használata --capture-screen
element_not_found rekord alatt Választó megadott, de nem egyező elem Újrafuttatás inspect vagy search új választó lekérése
A WGC nem érhető el a rekord alatt A WGC-rögzítési init nem sikerült; nincs csendes tartalék GPU/illesztőprogram ellenőrzése; hozzájárulás --capture-screen a képernyő-DC rögzítéshez

Gyakori minták

winapp ui invoke btn-settings-a1b2 -a myapp          # click a button
winapp ui wait-for pn-settingspage-c3d4 -a myapp    # wait for page to load
winapp ui screenshot -a myapp --output settings.png  # verify visually

Szöveg keresése és a szülő meghívása

# Search shows invokable ancestor; invoke auto-walks to it
winapp ui invoke 'Save changes' -a myapp

# Or search first to see what matches, then invoke
winapp ui search "Save changes" -a myapp; winapp ui invoke btn-save-c3d4 -a myapp

Ismétlődő elemek egyértelműsítése

winapp ui search '#Image' -a myapp; winapp ui invoke itm-image-a2b3 -a myapp

Képernyőkép előugró átfedésekkel

winapp ui set-value txt-searchbox-e5f6 "query" -a myapp; winapp ui screenshot -a myapp --capture-screen

winapp ui invoke btn-settings-a1b2 -a myapp; winapp ui wait-for pn-settingspage-c3d4 -a myapp --timeout 3000; winapp ui screenshot -a myapp -o settings.png

Felfedezés, kattintás és ellenőrzés

winapp ui inspect -a myapp --interactive; winapp ui invoke btn-submit-7a90 -a myapp; winapp ui screenshot -a myapp

Fájl párbeszédpanel-interakció

A fájlmegnyitási/mentési párbeszédpanelek szabványos Windows párbeszédpanelek az UIA támogatásával:

# Trigger the dialog, find it, type the path, confirm
winapp ui invoke btn-openfilebtn-a2b3 -a myapp
winapp ui list-windows -a myapp                                      # find dialog HWND
winapp ui set-value txt-1148-c4d5 "C:\path\to\file.png" -w <dialog-hwnd>
winapp ui invoke btn-open-e6f7 -w <dialog-hwnd>

Egy inspect -w <dialog-hwnd> --interactive adott párbeszédpanel tényleges meztelencsomóit derítheti fel.

Miért ; a láncolás (nem &&)

A PowerShell operátora && lefagyhat, ha egy natív parancssori felület ír a stderrbe, vagy ANSI-feloldási sorozatokat használ. Használja ; inkább – feltétel nélkül futtatja az egyes parancsokat, és elkerüli ezt a holtpontot. Ez az ügynök-munkafolyamatok esetében is jobb: általában azt szeretné, hogy a képernyőkép akkor is fusson, ha a meghívás nem nulla kimenetű volt.

CI-tesztelési minták

A ci-folyamatokban (GitHub Actions, Azure DevOps) winapp ui parancsok használata füsttesztekhez és felhasználói felületi ellenőrzéshez. wait-for --property és --value helyességként működik – az 1. kilépési kódot adja vissza időtúllépéskor, és automatikusan meghiúsul a CI-lépés.

Indítás és tesztelés a GitHub Actions

steps:
  - name: Build
    run: dotnet build MyApp.csproj -c Debug -p:Platform=x64

  - name: Launch and test
    run: |
      $result = winapp run .\bin\x64\Debug\net8.0-windows10.0.26100.0\win-x64 --detach --json | ConvertFrom-Json
      $appPid = $result.ProcessId

      # Wait for window to initialize
      winapp ui wait-for "Main Window" -a $appPid --timeout 30000

      # Run tests — each wait-for exits non-zero on failure
      winapp ui invoke "Login" -a $appPid
      winapp ui wait-for "Dashboard" -a $appPid --timeout 10000
      winapp ui screenshot -a $appPid -o dashboard.png

Elemállapot érvényesítése a wait-for

wait-for --value lekérdezi, amíg egy elem értéke meg nem egyezik a várt sztringgel, és ugyanazt az intelligens tartalékot használja, mint get-value (TextPattern → ValuePattern → SelectionPattern → Name). A 0-s kilépési kódot adja vissza egyezéskor, az 1-es kilépési kódot időtúllépéskor – így CI-barát állítás. Ehelyett egy adott UIA-tulajdonság ellenőrzésére használható --property .

# Assert: button click updated the counter (smart value fallback — works for TextBlock, TextBox, etc.)
winapp ui invoke "Counter Button" -a $pid
winapp ui wait-for "Counter Display" -a $pid --value "Count: 1" -t 5000

# Assert: text input was accepted
winapp ui set-value "Search Box" "hello world" -a $pid
winapp ui wait-for "Search Box" -a $pid --value "hello world" -t 3000

# Assert: checkbox was toggled (use --property for specific UIA properties)
winapp ui invoke "Dark Mode" -a $pid
winapp ui wait-for "Dark Mode" -a $pid --property ToggleState --value "On" -t 3000

# Assert: navigation happened (new page appeared)
winapp ui invoke "Settings" -a $pid
winapp ui wait-for "Settings Page" -a $pid -t 10000

# Assert: dialog was dismissed (element disappeared)
winapp ui invoke "Close" -a $pid
winapp ui wait-for "Dialog Title" -a $pid --gone -t 5000

Igény érvényesítése JSON-kimenettel

Összetettebb állítások esetén használja --json a PowerShellt vagy a jq-t:

Kilépési kód szerződése search és wait-for--json módban: ha egyetlen elem sem egyezik (search) vagy a várakozási idő (wait-for), a parancs egy teljesen elemezhető eredményborítékot ír a stdout ({ "matchCount": 0, ... } vagy { "found": false, "timedOut": true, ... }) értékre, és visszaadja az 1. kilépési kódot. A Stderr üres --json módban van (a naplózó kimenete le van tiltva). Elágaztatás a borítékmezőkön vagy attól $LASTEXITCODEfüggően, hogy melyik ergonomikusabb.

# Assert: search found exactly one match
$result = winapp ui search "Submit" -a $pid --json | ConvertFrom-Json
if ($result.matchCount -ne 1) { throw "Expected 1 Submit button, found $($result.matchCount)" }

# Assert: element has expected properties
# inspect --json returns { windows: [{ hwnd, title, elements: [...] }] };
# each window's elements[] is the nested tree (children rendered via .children).
$tree = winapp ui inspect "Counter Display" -a $pid --json | ConvertFrom-Json
$counter = $tree.windows[0].elements[0]
if ($counter.name -ne "Count: 3") { throw "Counter value wrong: $($counter.name)" }

Példa a teljes füsttesztre

# Launch
$app = winapp run .\build-output --detach --json | ConvertFrom-Json

# Verify app loaded
winapp ui wait-for "Main Page" -a $app.ProcessId -t 30000

# Interact and assert
winapp ui invoke "Add Item" -a $app.ProcessId
winapp ui set-value "Item Name" "Test Item" -a $app.ProcessId
winapp ui invoke "Save" -a $app.ProcessId
winapp ui wait-for "Test Item" -a $app.ProcessId -t 5000              # assert item appeared in list
winapp ui wait-for "Save" -a $app.ProcessId --gone -t 3000            # assert save dialog closed

# Visual verification
winapp ui screenshot -a $app.ProcessId -o smoke-test.png
  • Last updated on