Ui-automatisering

Inspecteer en communiceer met het uitvoeren van Windows toepassingen vanaf de opdrachtregel. Wordt gebruikt door AI-agents en ontwikkelaars voor het testen van gebruikersinterfaces, foutopsporing en automatisering.

Overzicht

winapp ui biedt opdrachten voor het controleren en gebruiken van Windows app-API's. Maakt gebruik van Windows UI Automation (UIA). Werkt met elke Windows-app: WPF, WinForms, Win32, Electron en WinUI 3. De meeste opdrachten sturen de app via UIA-patronen (geen invoerinjectie). De uitzonderingen injecteren echte invoer: ui click/ui hoverui drag/gebruik muissimulatie,/ui touchui pen synthetiseer aanraak- en pen-/stylusinvoer en ui send-keys synthetiseert toetsenbordinvoer voor besturingselementen en scenario's die UIA-patronen niet kunnen besturen.

Snel aan de slag

# 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

Apps instellen

Op procesnaam

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

Op venstertitel

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

Per PID

winapp ui inspect -a 12345

Door HWND (stabiel — overleeft tab-/titelwijzigingen)

# 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

Gebruiken -a voor detectie, -w voor stabiele targeting. Wanneer -a deze overeenkomen met meerdere vensters, worden deze weergegeven met HWND's die u kunt kiezen.

Selectoren

Doelelementen met behulp van de selector die wordt weergegeven in [brackets] inspect/search-uitvoer. Er zijn drie typen selectors:

AutomationId-selectors zijn id's voor ontwikkelaarssets (AutomationProperties.AutomationId in XAML). Wanneer een AutomationId uniek is in de hele UI-structuur inspect en search deze rechtstreeks als de selector weergeeft, blijven de indelingswijzigingen, lokalisatie en structuurherstructurering behouden.

Slugselectors (bijvoorbeeld btn-close-d1a0) worden gegenereerd wanneer er geen unieke AutomationId bestaat. Indeling: prefix-name-hash. De hash valideert de elementidentiteit, maar kan verlopen nadat de gebruikersinterface is gewijzigd.

Uitvoerindeling controleren

De inspect opdracht toont de elementstructuur met gekleurde uitvoer (selector in cyaan, naam in groen, metagegevens in grijs):

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

Het eerste woord op elke regel is de selector. Gebruik het met andere ui opdrachten. Wanneer een element een unieke AutomationId heeft, wordt het rechtstreeks gebruikt (bijvoorbeeld TabView, NewTabButton). Wanneer er geen unieke AutomationId bestaat, wordt er een gegenereerde slug gebruikt (bijvoorbeeld tab-newtab-5f5b).

Semantische slugs

Slugs gebruiken de notatie: prefix-normalizedname-hash waarbij:

• voorvoegsel — afkorting van 3 letters (btn, txt, chk, cmb, itm, tab, img, lbl, pn, win, grp, lnk, mnu, enz.)
• normalizedname : alfanumerieke kleine letters van AutomationId (voorkeur) of Naam, maximaal 15 tekens
• hash : hexhash van 4 tekens van de RuntimeId van het element (valideert elementidentiteit)

Slugs zijn shell-safe (geen speciale tekens), uniek en kunnen rechtstreeks als argumenten worden gebruikt. De hash biedt verouderingsdetectie. Als het element is vervangen, krijgt u het volgende: 'Element is mogelijk gewijzigd. Voer de inspectie opnieuw uit."

Elementen zonder naam of AutomationId geven alleen voorvoegsel en hash weer (bijvoorbeeld pn-c8a3).

Meerdere overeenkomsten ondubbelzinnig maken

Slugs van inspect/search uitvoer zijn uniek, maar kunnen worden gewijzigd in indelingswijzigingen. Gebruik ze boven namen of tekst zonder opmaak wanneer meerdere overeenkomsten overeenkomen. Wanneer een selector dubbelzinnig is, worden alle overeenkomsten met hun slugs afgedrukt, zodat u de juiste kunt kiezen en opnieuw kunt uitvoeren met die slug.

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

Zoeken in tekst zonder opmaak

Gebruik tekst zonder opmaak om te zoeken naar elementen. Er is geen speciale syntaxis nodig:

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

Wanneer een tekstzoekopdracht overeenkomt met meerdere elementen (bijvoorbeeld SettingsExpander waarbij groep, knop en tekst allemaal dezelfde naam delen), kiest de CLI automatisch het enige aanroepbare element. Als er meerdere aanroepbaar zijn, worden alle overeenkomsten met slugs weergegeven.

Voor niet-aanroepbare zoekresultaten (bijvoorbeeld een TextBlock binnen een knop), wordt automatisch de dichtstbijzijnde aanroepbare bovenliggende bovenliggende waarde weergegeven, het bovenliggende element waarmee invokeu kunt gebruiken. Dit werkt voor alle zoekkiezers:

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

De surfaced selector kan rechtstreeks worden gebruikt:

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

Opdrachten

status

Maak verbinding met een app en geef verbindingsgegevens weer.

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

Inspecteren

Bekijk de structuur van het ui-element. De uitvoer toont semantische slugs met twee spaties inspringing voor de hiërarchie:

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

Voorbeelduitvoer (standaard):

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)

Voorbeelduitvoer (--interactive — alleen aanroepbare elementen, platte lijst):

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)

Elementen kunnen deze statusmarkeringen weergeven:

• [on] / [off] / [indeterminate] — status van wisselknop/selectievakje
• [collapsed] / [expanded] — de status voor bomen, keuzelijsten met invoervak, menu-items uitvouwen/samenvouwen
• [scroll:v] / [scroll:h] / [scroll:vh] — schuifbare container (verticaal, horizontaal of beide)
• [offscreen] — element is niet zichtbaar op het scherm
• [disabled] — element is niet ingeschakeld
• value="..." — huidige tekstinhoud voor bewerkbare elementen (indien anders dan Naam)

search

Zoek elementen die overeenkomen met een selector. Uitvoer toont semantische slugs:

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

Voorbeelduitvoer:

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

Slugs die worden weergegeven in de uitvoer (bijvoorbeeld btn-minimize-d1a0) kunnen rechtstreeks worden gebruikt met andere opdrachten:

winapp ui invoke btn-minimize-d1a0 -a notepad

get-property

Eigenschapswaarden van een element lezen. Bevat patroonspecifieke status (ToggleState, Waarde, IsSelected, enzovoort).

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

schermopname

Een venster of element vastleggen als PNG. Wanneer er meerdere vensters bestaan (bijvoorbeeld app en dialoogvenster openen), worden ze samengevoegd in één PNG-bestand met elk venster dat is gestikt.

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)

Wanneer dialoogvensters of pop-ups zijn geopend, worden alle vensters samengevoegd in één PNG,zodat u de volledige UI-status in één afbeelding kunt zien.

Het standaardpad voor vastleggen maakt gebruik van Windows. Graphics.Capture (WGC), het lezen van het werkelijke DWM-samengestelde oppervlak, met behoud van afgeronde hoeken, transparantie en werken zelfs terwijl het venster wordt ondergesloten door andere windows. Als WGC niet beschikbaar is (oudere Windows builds) valt de CLI terug naar PrintWindow.

Gebruik --capture-screen deze optie wanneer u pop-upmenu's, vervolgkeuzelijsten, flyouts of knopinfo-overlays wilt vastleggen die niet eigendom zijn van het doelvenster. --capture-screen leest van het scherm DC en brengt het venster eerst op de voorgrond. Gebruik --focus deze optie als u alleen het venster wilt voorgronden zonder over te schakelen tussen opnamemodi (bijvoorbeeld om ervoor te zorgen dat de schermopname overeenkomt met wat de gebruiker momenteel bekijkt).

verslag / opname

Noteer het doelvenster (of de regio van een element) naar een H.264 MP4-video. Frames worden vastgelegd via Windows Graphics Capture (met PrintWindow/screen-DC fallback) en gecodeerd incrementeel met Media Foundation, zodat opnamen nooit de volledige video in het geheugen bufferen.

Standaardgedrag (--duration-sec 0): records totdat ze zijn gestopt. Gebruik Ctrl+C interactief of (voor programmatische/agentoproepers) schrijf een nieuwe regel naar stdin of sluit stdin om de MP4 correct te stoppen en te voltooien. Een geldige, afspeelbare MP4 wordt altijd voltooid op elke sierlijke stop, geen beschadiging.

# Timed: record for 10 s at 15 fps
winapp ui record -a myapp --duration-sec 10 --fps 15 --output demo.mp4

# Unbounded (default): record until Ctrl+C, downscaled to max 1280px longest edge
winapp ui record -a myapp --max-edge 1280 --output capture.mp4

# Programmatic stop (agent/script): pipe a newline; the recorder stops and writes a valid MP4
"" | winapp ui record -a myapp --json --output capture.mp4

# Record a single element's region (fails with element_not_found if the selector doesn't match)
winapp ui record itm-chart-9f8e -a myapp --output chart.mp4

# Include screen overlays / popups (captures from screen DC; brings window to foreground)
winapp ui record -a myapp --capture-screen --duration-sec 5 --output with-popups.mp4

Opties:

• --duration-sec N — Record voor N seconden. Standaard 0 = record totdat deze is gestopt.
• --fps N — Doelframes per seconde (standaard 15).
• --max-edge N — Omlaag schalen zodat de langste rand maximaal N pixels is (0 = geen downscale).
• --capture-screen — Vastleggen vanaf het scherm DC (inclusief overlays/pop-ups; voorgrond van het venster).
• --output <path> — MP4-uitvoerpad. De standaardinstelling is recording-<timestamp>-<guid>.mp4 in de huidige map.

Stopmechanismen:

• Interactief: Ctrl+C (elk platform).
• Programmatisch/agent: schrijf een nieuwe regel ("") of sluit stdin (EOF). De stop wordt toegepast zodra de encoder gereed is (eerste frame vastgelegd); elk stopsignaal dat aankomt voordat het eerste frame wordt vastgelopen en onmiddellijk wordt toegepast - er is geen respijtvenster en geen wandklokvertraging.

Opnamemodi (gerapporteerd in het JSON-veld mode ):

• wgc— Windows Graphics Capture (standaard; werkt terwijl het venster is afgesloten).
• printwindow — GDI PrintWindow (terugval wanneer WGC niet beschikbaar is op dit systeem/sessie; voer opnieuw uit met --capture-screen schermDOMEINCONTROLLER in plaats daarvan).
• screen — Scherm DC via --capture-screen (inclusief overlays/pop-ups; brengt het venster naar de voorgrond).

JSON-uitvoer (--json):

• stdout (eindresultaat): { "path", "frames", "width", "height", "fileSize", "codec": "h264", "mode", "fps", "durationSec" }
• stderr (livenessgebeurtenis, verzonden wanneer het vastleggen begint): { "event": "recording-started", "path", "fps", "durationSec" }

Met de livenessgebeurtenis op stderr kunnen programmatische bellers weten dat de capture-lus live is zonder te wachten op het uiteindelijke resultaat. Het uiteindelijke resultaat van JSON op stdout is één schoon object.

Foutcodes:

• element_not_found — Selector gegeven, maar geen overeenkomend element gevonden; mislukt onmiddellijk (geen gedeeltelijk bestand geschreven).
• ambiguous_selector — Een selector voor tekst zonder opmaak komt overeen met meerdere elementen; gebruik een slak uit de suggesties die worden weergegeven in de fout (of van inspect uitvoer) om een specifiek element te bereiken.
• invalid_arguments — Ongeldige optiewaarde (bijvoorbeeld --duration-sec -1 of > 86400).

Bekende beperking: pop-ups met vensters: Wanneer u een specifiek element (per selector) opneemt dat zich in een pop-up bevindt die in een eigen venster op het hoogste niveau wordt weergegeven, zoals een WinUI/XAML-flyout, onderwijstip, knopinfo of menu (Xaml_WindowedPopupClass) - kan de recorder het onderliggende hoofdvenster vastleggen in plaats van de pop-up, waardoor lege of verlopen frames worden geproduceerd. Noteer het hele venster (laat de selector weg) of gebruik winapp ui screenshot --capture-screen deze voor pop-up stills. Bijgehouden in #646.

Programmatisch een element activeren (klik op de knop, schakeloptie in, keuzelijst met invoervak uitvouwen).

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

Probeert patronen in volgorde: InvokePattern → TogglePattern → SelectionItemPattern → ExpandCollapsePattern.

click

Klik op een element op de schermcoördinaten met behulp van muissimulatie. Gebruik dit voor besturingselementen die geen ondersteuning bieden InvokePattern (bijvoorbeeld kolomkoppen, lijstitems).

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

Net als de andere invoerinjecterende werkwoorden, click brengt u het doel naar de voorgrond en mislukt u snel (no_interactive_desktop op een vergrendeld/beveiligd bureaublad, foreground_not_target als de focus niet kan worden overgedragen) in plaats van op het verkeerde venster te klikken. Het element wordt ook opnieuw omgezet vlak voor de knop omlaag: na het plaatsen van de cursor wordt er één laatste positiecontrole uitgevoerd, zodat een continu bewegend/animatief doel mislukt met target_moved in plaats van het rapporteren van succes nadat de klik op lege ruimte is terechtgekomen. Een gerapporteerd succes betekent dat het doel nog steeds aanwezig was toen de knop omlaag ging.

Drag

Druk op het ene punt op de muisknop, ga naar het andere en laat vervolgens los met drag <from> <to>, waarbij elk eindpunt een elementselector is (sleept van/naar het midden van het element) of schermcoördinaten x,y precies zoals gerapporteerd door winapp ui inspect. Mix en match vrij (selector→selector, selector→coords, coords→coords).

Wordt SendInput gebruikt met tussenliggende verplaatsingen, zodat de app een realistische stroom berichten WM_MOUSEMOVE ziet. Gebruik deze optie voor het opnieuw ordenen/wijzigen van formaatgrepen, schuifregelaars, tekenpapier en slepen en neerzetten.

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

Opties:

• --right — Sleep met de rechtermuisknop in plaats van de linkerknop.
• --hold-ms <ms> — Houd de knop aan het begin ingedrukt voordat u gaat bewegen (standaard: 0). Met <from> == <to> (geen beweging) voert dit een druk-en-hold / long-press beweging uit.
• --dwell-ms <ms> — Dwell op de bestemming na verplaatsing, voordat deze wordt vrijgegeven (standaard: 0). Hiermee kunt u doelen verwijderen/overlays samenvoegen die arm van een aanhoudende muisaanwijzer (in plaats van het moment waarop de cursor binnenkomt) vergrendelen voordat de knop omhoog gaat.

Bare x,y zijn schermcoördinaten in hetzelfde ruimterapport winapp ui inspect/search en een selector wordt omgezet in het midden van het element. Inspecteer eerst om punten te kiezen.

Net zoals send-keys --via send-input, drag injecteert os-brede op schermcoördinaten na het brengen van het doel op de voorgrond. Als de focus niet naar het doel kan worden gebracht (b.v. focus-steeling preventie van een achtergrondproces), mislukt de opdracht (foreground_not_target) in plaats van te slepen op het verkeerde venster: focus of klik eerst op het venster. Op een vergrendeld/beveiligd bureaublad mislukt het met no_interactive_desktop. Elk elementeindpunt wordt onmiddellijk vóór de sleep opnieuw omgezet; als de opdracht nog steeds wordt verplaatst/verkleind (een animatiedoel), mislukt de opdracht in target_moved plaats van naar een verlopen punt te slepen. (Lege x,y eindpunten kunnen niet opnieuw worden geverifieerd, zodat ze worden gebruikt as-is.)

Aanraken

Injecteer synthetische aanraakbewegingen met behulp van de Windows aanwijzer-injectie-API. Het anker voor contactpersonen is een elementkiezer (gebruikt het midden van het element) of een expliciet schermcoördinaat x,y via --at (dezelfde ruimterapporten winapp ui inspect ). Gebruik deze functie voor tikken/drukken op interacties en bewegingen met meerdere aanraakbewegingen die de muissimulatie niet kan uitdrukken.

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)

Opties:

• --gesture <g>— tap (standaard), double-tap, long-press, swipe, , pinch. stretch
• --at <x,y> — Expliciet beginpunt (schermcoördinaten). De standaardinstelling is het elementcentrum van de selector.
• --to-point <x,y> — Eindpunt voor een swipe. Heeft voorrang op --direction.
• --direction <right|left|up|down> — Veegrichting (standaard: right). Gecombineerd met --distance het berekenen van het eindpunt wanneer --to-point dit niet is opgegeven.
• --distance <px> — Vinger verspreid voor pinch/stretchof veeg afstand in pixels.
• --hold-ms <ms> — Houd contactpersonen ingedrukt voordat u opheft (houd de tijd lang ingedrukt; de standaardwaarde is 500 ms voor long-press wanneer deze niet is ingesteld).
• --duration-ms <ms> — Glide tijd voor bewegende bewegingen (veeg/knijp/stretch; standaard 300).
• --fingers <n> — Aantal contactpersonen (1-10; standaard 1). pinch / stretch gebruik altijd 2.

Injectieveiligheid. touch weigert te injecteren tenzij een niet-nul doelvenstergreep wordt omgezet en dat venster de voorgrond bevat. Het mislukt wanneer no_target er geen venster kan worden omgezet, foreground_not_target als de focus niet kan worden overgedragen of no_interactive_desktop op een vergrendeld/beveiligd bureaublad. Elke coördinaat (elementcentrum, expliciet --at/--to-pointen gegenereerde waypoints) wordt gecontroleerd op de rechthoek van het doelvenster; een punt buiten het venster wordt weergegeven als een niet-fatale waarschuwing (een warnings[] vermelding in --json, of een waarschuwingslijn in de tekstmodus) en de injectie gaat nog steeds verder , die overeenkomt met de muiswoorden (drag/scrollclick/hover/), die ook in out-of-window-coördinaten injecteert. --fingers boven de 10 wordt vooraf geweigerd.

Hardwarenotitie. Touch geeft de voorkeur aan het moderne synthetische aanwijzerapparaat (CreateSyntheticPointerDevice(PT_TOUCH)) en valt terug op de verouderde InitializeTouchInjection/InjectTouchInput API. Als injectie niet wordt ondersteund op het huidige apparaat/de huidige sessie, wordt met de opdracht de daadwerkelijke Win32-foutcode (bijvoorbeeld 'niet-ondersteund') weergegeven in plaats van een foutief succes te melden. Behandel een niet-nul-uitgang als 'touch not delivered'.

Extern bureaublad/VM-sessies. In een Extern bureaublad (RDP) of sommige VM-sessies kan het besturingssysteem synthetische aanraking (exit 0) accepteren zonder dat het daadwerkelijk de doel-app bereikt. Wanneer een externe sessie wordt gedetecteerd, touch voegt u een waarschuwing over leveringsonzekerheid toe, een warnings[] vermelding in --jsonof een waarschuwingsregel in de tekstmodus. Een ✅/exit 0 betekent dan dat de injectie-aanroep is geslaagd, niet dat de app de invoer heeft ontvangen; bevestig het effect met ui screenshot/ui inspect wanneer het belangrijk is.

pen

Injecteer synthetische pen-/stylusinvoer — tikken en pennenstreken — met behulp van de Windows synthetische aanwijzer-API (CreateSyntheticPointerDevice(PT_PEN); Windows 10 1809+). Richt u op een elementcentrum, een expliciet --at punt of een volledige --path pennenstreek.

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

Opties:

• --at <x,y> — Pencontactpunt (schermcoördinaten). De standaardinstelling is het elementcentrum van de selector. Genegeerd wanneer --path wordt gegeven.
• --path "<x,y x,y …>" — Pennenstrekenpad als spaties gescheiden x,y paren (een pad met één punt is een tik).
• --pressure <0.0–1.0> — Pendruk (standaard 0,5).
• --tilt-x <deg> / --tilt-y <deg> — Kantelhoeken van pen, −90 tot 90 (standaard 0).
• --eraser — Gebruik het gumeinde van de pen in plaats van de tip.
• --duration-ms <ms> — Totale reistijd voor pennenstreken in milliseconden verdeeld als geïnterpoleerde UPDATE-frames over het pad (standaard: ~10 ms per waypoint). Gebruik deze optie om te bepalen hoe snel de pen zichtbaar van begin tot eind beweegt.

Injectieveiligheid. Zoalstouch, pen weigert te injecteren zonder een niet-nul, voorgronds doelvenster (no_target / no_interactive_desktopforeground_not_target / ) en controleert elk inktpunt tegen de rechthoek van het doelvenster, waarbij een out-of-window coördinaat wordt weergegeven als een niet-fatale waarschuwing (warnings[]in --json, of een waarschuwingsregel in de tekstmodus) terwijl er nog steeds wordt geïnjecteerd , consistent met de muiswoorden. Ongeldig --pressure (buiten 0,0–1.0) of kantelen (buiten ±90°) worden vooraan geweigerd.

Extern bureaublad/VM-sessies. Penroutering is vooral onbetrouwbaar ten opzichte van Extern bureaublad: de injectieaanroep kan slagen (exit 0) melden terwijl er geen peninvoer de app bereikt. Wanneer een externe sessie wordt gedetecteerd, pen voegt u een waarschuwing over bezorgingsonzekerheid (warnings[] in --jsonof een waarschuwingsregel in de tekstmodus) toe, zodat een ✅ waarschuwing niet wordt verward met bevestigde bezorging. Valideer penafhankelijke stromen op een lokaal, interactief bureaublad.

aanwijzen

Verplaats de muis naar het midden van een element om aanwijseffecten te activeren (knopinfo, flyouts, visuele statussen). Gebruikt SendInput voor realistische muisbewegingen met een kleine pruik en wacht vervolgens op een configureerbare woningtijd.

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

Opties:

• --dwell-time <ms> — Tijd in milliseconden om te wachten na het aanwijzen van effecten (standaard: 800, bereik: 0-10000)

send-keys

Synthetische toetsenbordinvoer verzenden - de tegenhanger van het toetsenbord naar click. UIA heeft geen toetsenbordinjectiepatroon, dus dit zakt naar de Win32-laag. Gebruik dit voor toetsenbordnavigatie (pijlen, Tab, Enter, Esc), sneltoetsen (ctrl+c, alt+f4) en typen in besturingselementen die per toetsaanslagen gebeurtenissen nodig hebben in plaats set-valuevan atomische schrijfbewerkingen.

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

Sleutel grammatica (witruimte-gescheiden tokens, aanhalingstekens met meerdere tokentekenreeksen):

• Benoemde sleutels : , escreturn/spacetab/enterescape, deletedelinsertendbackspace/home, pageup/pgup, uppgdn//down//leftf1rightpagedown, – appsf16, . capslockprintscreen
• Reeksen : meerdere tokens worden op volgorde ingedrukt: down down enter.
• Modifier combos — , ctrl, shift, winaltsamengevoegd met +: ctrl+shift+t, . alt+f4
• Letterlijke tekst : een token dat geen bekende sleutel is, wordt per teken getypt: hello. Aangrenzende letterlijke woorden houden de spatie ertussen, zodat een woordgroep tussen aanhalingstekens zoals "Hello world" woordgroepen wordt getypt (de spatie blijft behouden); een letterlijke waarde die alleen tekst bevat +C++ of a+b als tekst is getypt, niet geparseerd als een combinatie.
• Expliciete letterlijke escape - het voorvoegsel van een token om text= deze letterlijk te typen, zelfs wanneer het conflicteert met een sleutel- of wijzigingsnaam: text=enter typt het woord 'enter' in plaats van op Enter te drukken en text=ctrl+a typt de letterlijke tekenreeks. Hiermee wordt de vk= escape gespiegeld; de escape-waarde wordt nog steeds samengevoegd met aangrenzende letterlijke woorden (text=down low → 'laag omlaag'). Omdat tokens spaties splitsen (en aangrenzende letterlijke waarden opnieuw samenvoegen met één spatie), gebruikt u backslash-escapes in een text= waarde om witruimte te typen die anders niet zou overleven: \s → spatie, \t → tabblad, \n → nieuwe regel, \r → nieuwe regel, \\ → letterlijke backslash. \n, \ren \r\n elke regel een regeleinde (een Enter/ VK_RETURN), dus text=line1\nline2 en text=line1\r\nline2 beide typen één nieuwe regel. Typ text=a\s\sb dus 'a b' (dubbele spatie) en text=\shi houdt een voorloopruimte. Een niet-herkende ontsnapping (bijvoorbeeld \x) is letterlijk.
• Geheel argument letterlijk (--verbatim) - wanneer de hele nettolading letterlijke tekst is, geeft u door --verbatim in plaats van elk token met text=te ontsnappen. Het typt het argument voor de hele sleutels precies zoals opgegeven , geen benoemde sleutel / combinatie /vk=/text= interpretatie - en, in tegenstelling tot het normale pad, behoudt exacte interne witruimte (geen samenvouwen) zonder dat dit nodig is.\s Typ send-keys "down down enter" --verbatim dus de woorden en send-keys "a b" --verbatim houdt de dubbele spatie. Backslash-escapes worden niet gedecodeerd in --verbatim de modus (een \s is getypt als een backslash en een 's'); gebruik een token wanneer u een text= escaped-besturingselementteken nodig hebt.
• Onbewerkte virtuele sleutels ( vk=0xNN hex) of vk=NN (decimaal) voor sleutels zonder een beschrijvende naam.

Opties:

• --target <selector> — Richt dit element (via UIA) voordat u sleutels verzendt. Zonder dit gaat u naar het momenteel gerichte element van de app.
• --verbatim — Typ het hele toetsenargument als letterlijke tekst (geen sleutel/combinatie/vk=/text= parsering) en behoud exacte witruimte. De gehele argumentvorm van de escape per token text= .
• --via <transport>— post-message (standaard) berichten WM_KEYDOWN//WM_KEYUPWM_CHAR in de wachtrij van het doelvenster. Het is gericht op HWND en omzeilt UIPI (werkt tussen integriteitsniveaus). send-input injecteert het besturingssysteem breed via SendInput en gaat naar het voorgrondvenster.

Een transport/ bekende limieten kiezen:

• post-message is de standaardinstelling omdat uiPI wordt omzeild en niet afhankelijk is van het venster op de voorgrond. Limieten: er kunnen geen globale sneltoetsen worden geactiveerd die zijn geregistreerd via WH_KEYBOARD_LL hooks op laag niveau (die tikken op invoer upstream van een vensterwachtrij) en apps die de status van onbewerkte sleutel lezen via GetAsyncKeyState , kunnen mogelijk geen heldsaanpassingen observeren. Het lost automatisch op en plaatst berichten in het gerichte onderliggende venster van de doelthread (via GetGUIThreadInfo) na voorgronding, dus klassieke Win32/WinForms-apps waarvan de besturingselementen afzonderlijke onderliggende vensters zijn, ontvangen sleutels zonder handmatig gericht op het besturingselement. WinUI 3/UWP-apps hebben vensterloze XAML-besturingselementen zonder onderliggende HWND, dus een geplaatste app WM_CHAR/WM_KEYDOWN heeft niets om binnen te komen en wordt verwijderd. Post-message kan ze niet sturen (de opdracht waarschuwt en sluit 0); gebruik .--via send-input (WPF vensters zijn single-HWND en routesleutels naar het intern gerichte element, dus post-message werkt daar.)
• send-input produceert volledig echte invoer (modifiers zichtbaar voor GetAsyncKeyState, brandt haakjes op laag niveau) maar gaat naar het venster dat voorgrond is en wordt geblokkeerd door UIPI bij het injecteren van een verhoogd proces in een AppContainer/AppX-doel. Als send-input er een fout wordt gerapporteerd, is het doel waarschijnlijk verhoogd of een AppX-app. Gebruik post-messageof voer de CLI uit op een overeenkomend integriteitsniveau. Als veiligheidsbeveiliging send-input controleert u of het doelvenster zich direct op de voorgrond bevindt voordat u het injecteert en mislukt (foreground_not_target) in plaats van in het verkeerde venster te typen als de focus niet naar het venster kan worden gebracht : focus of klik eerst op het venster. Op een vergrendeld of beveiligd bureaublad mislukt het in plaats daarvan met no_interactive_desktop (er bestaat geen voorgrondvenster om in te injecteren) - ontgrendel de sessie of gebruik een UIA-patroonwoord (set-value, invoke).
• Systeem gereserveerde combinaties (win+l, win+r, ctrl+shift+esc, ctrl+alt+del, alt+tab, , ctrl+escalt+f4lone win/printscreen, ...) handelen op het besturingssysteem/shell in plaats van alleen het doel wanneer het besturingssysteem breed wordt verzonden. send-input negeert ze standaard (fouten met invalid_arguments en verzendt niets), omdat het injecteren ervan op het niveau van het besturingssysteem veel meer dan het doelvenster heeft (bijvoorbeeld win+l de sessie vergrendelt). Pass --allow-system-keys to opt in — hiermee kunt u een globale sneltoets zoals PowerToys' win+shift+v of win+r (de wereldwijde haak op laag niveau kijkt naar de invoerstroom van het besturingssysteem, zodat de geïnjecteerde combinatie deze brandt). Uitzonderingen die geblokkeerd blijven, zelfs bij--allow-system-keys:win+l vergrendelt het werkstation via LockWorkStation() welke niet kan worden hersteld door automatisering (breekt CI- en extern bureaubladsessies) en ctrl+alt+del is een SAS (Secure Attention Sequence) die Windows daalt van geïnjecteerde invoer, ongeacht de vlag, het kan nooit van kracht worden, zodat het fouten (invalid_argumentssluit 1) in plaats van een misleidend succes te melden. Andere combinaties (alt+f4, ctrl+shift+esc, win+r, ...) worden toegestaan met de vlag - bewareer. Als u een systeemcombinatie wilt leveren aan een specifiek venstergebruik --via post-message, wat vensterbereik heeft en niet wordt beïnvloed (een geplaatste is win+l ongevaarlijk, hoewel een geplaatste het alt+f4 doelvenster nog steeds sluit).

Gebeurtenissen per toetsaanslag (KeyDown/ TextChanged):

• Benoemde sleutels en wijzigingscombinaties (down, enter, ctrl+shift+t, vk=0xNN) activeren een echte KeyDown (en KeyUp) op beide transporten: ze worden geleverd als discrete WM_KEYDOWN/WM_KEYUP (of SendInput virtuele-sleutelgebeurtenissen).
• Letterlijk getypte tekst (hello) verschilt per transport:
  • --via send-input wijst elk teken toe aan de virtuele toets (plus Shift) in de actieve toetsenbordindeling, zodat het doel een echte KeyDown virtuele toets ziet met de juiste virtuele toets , gevolgd door het op het besturingssysteem samengestelde WM_CHAR (verhogende TextChanged) - dat wil bijvoorbeeld één volledige toetsaanslag per teken. Tekens die niet bereikbaar zijn in de huidige indeling (of ctrl/AltGr) moeten terugvallen op een Unicode-pakket, zodat het exacte teken nog steeds terechtkomt. Gebruik send-input deze optie wanneer u per toetsaanslagen KeyDown betrouwbaarheid nodig hebt (bijvoorbeeld het rijden van een WinUI 3 / WPF TextBox waarvan de handlers worden uitgeschakeldKeyDown). Voor een normale (niet-verhoogde) WinUI 3-testhost brengt u het venster eerst naar de voorgrond (winapp ui focus /erop klikken) omdat send-input het gericht is op het voorgrondvenster.
  • --via post-message plaatst één WM_CHAR per teken (deze post nietWM_KEYDOWN/WM_KEYUP voor getypte tekst, die zijn gereserveerd voor benoemde sleutels/combo's), waardoor er geen per teken KeyDownwordt gegenereerd. Het wordt automatisch opnieuw gericht op het onderliggende besturingselement van het venster, dus klassieke Besturingselementen voor Win32/WinForms WM_CHAR-driven edit landt de tekst (verhogen TextChanged). Caveat: WinUI 3 / UWP / XAML-apps (winapp's primaire doel) hebben vensterloze besturingselementen die worden WM_CHAR/WM_KEYDOWN genegeerd, dus geen letterlijke tekst of benoemde sleutels (Enter, cijfers, ...) bereiken ze, ook al rapporteert de opdracht is geslaagd. Er wordt een waarschuwing verzonden wanneer het doel eruitziet als XAML en nog steeds 0 afsluit (PostMessage is fire-and-forget en kan de levering niet bevestigen). Gebruik --via send-input dit om WinUI 3/UWP/WPF-apps aan te sturen; reserveer post-message voor klassieke Win32-besturingselementen of wanneer u deze alleen vensterbereiken nodig hebt voor integriteitsniveaus.

JSON-uitvoer (--json): het resultaat hwnd is het effectieve venster waarin de sleutels zijn geleverd. Voor --via post-message dit is het opgeloste onderliggende besturingselement met prioriteit wanneer de opdracht opnieuw wordt gericht (niet noodzakelijkerwijs het venster op het hoogste niveau-w//-a-e), zodat automatisering precies kan bevestigen waar de invoer terecht isgekomen. Wanneer dit effectieve doel eruitziet als een vensterloze XAML-host, wordt de bovenstaande leveringsfout ook weergegeven als een warnings[] vermelding (hetzelfde advies dat op de console wordt weergegeven), zodat een ✅ uitgang 0 niet wordt verward voor bevestigde levering.

set-value

Stel een waarde in op een bewerkbaar element programmatisch (geen toetsaanslagen, geen app voorgrond). Maakt gebruik van een terugvalketen:

1. ValuePattern : tekstvak, keuzelijst met invoervak, wachtwoordvak en de meeste bewerkbare besturingselementen.
2. RangeValuePattern : numerieke besturingselementen (schuifregelaar, voortgangsbalk) wanneer de waarde als een getal wordt geparseerd.
3. LegacyIAccessible (IAccessible::put_accValue) - de terugval voor besturingselementen voor alleen textPattern-bewerkingen die geen ValuePattern beschikbaar maken (bijvoorbeeld rich-edit/ Document compose boxes). Hierdoor wordt de lees-/schrijfruimte gesloten waar get-value een dergelijk besturingselement kan worden gelezen, maar set-value niet.

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

Als geen van de drie patronen de waarde kan instellen, set-value mislukt het met een duidelijke fout die send-keys wijst als laatste redmiddel.

Niet elke uitgebreide editor ondersteunt programmatische set. De LegacyIAccessible-terugval werkt alleen op besturingselementen waarvan de toegankelijkheid implementeert IAccessible::put_accValue : systeemeigen Besturingselementen voor uitgebreide bewerking en Chromium/Electron/WebView2 opstellen oppervlakken meestal. WinUI 3 RichEditBox en WPF RichTextBox bieden geen ondersteuning voor programmatische waarde-instelling. Ze maken hun inhoud standaard zichtbaar voor UI Automation als alleen-lezen (tekstpatroon, geen settabelwaardepatroon), zodat set-value ze er niet naar kunnen schrijven. Gebruik send-keys (waarvoor een ontgrendeld bureaublad op de voorgrond nodig is) voor deze.

get-value

Lees de huidige waarde van een element. Maakt gebruik van een slimme terugvalketen: TextPattern (RichEditBox, Document) → ValuePattern (TextBox, Slider) → SelectionPattern (ComboBox, RadioButton, TabView) → Naam (labels).

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": "..." }

focus

Verplaats de focus van het toetsenbord naar een element.

winapp ui focus txt-textbox-a4b1 -a notepad

scroll-into-view

Schuif een element naar het zichtbare gebied.

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

wachten op

Wacht tot een element wordt weergegeven, verdwijnt of heeft een waarde een doel bereikt.

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

Schuiven

Schuif door een containerelement. Schuifbare containers zoeken met search scroll : zoek [scroll:v] naar (verticale) of [scroll:h] (horizontale) markeringen.

# 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

Opties:

• --direction <up|down|left|right> — Schuif stapsgewijs via ScrollPattern.
• --to <top|bottom> — Ga naar het begin/einde via ScrollPattern.
• --wheel <notches> — Synthetiseer de invoer van het muiswiel over het midden van het element via SendInput, in wielkepingen (tenten): 1 = één inkeping omhoog/weg, -1 = één inkeping naar beneden/naar, 3 = drie inkepingen omhoog. (Elke notch is de Windows WHEEL_DELTA van 120 eenheden die SendInput verbruiken; de CLI schaalt met 120 voor u.) Omzeilt ScrollPattern.

--direction, --toen --wheel sluiten elkaar wederzijds uit - geef precies één door. Omdat --wheel het besturingssysteembrede invoer op schermcoördinaten injecteert, wordt het doel eerst op de voorgrond geplaatst en mislukt (foreground_not_target) als de focus niet kan worden overgedragen, in plaats van het verkeerde venster te schuiven.

get-focused

Het element weergeven dat momenteel de toetsenbordfocus heeft.

winapp ui get-focused -a myapp

list-windows

Alle zichtbare vensters voor een app weergeven, inclusief pop-ups en dialoogvensters. Standaard worden naamloze vensters met nulgrootte (onzichtbare systeemvensters) uitgesloten.

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

Framework-ondersteuning

¹ set-value werkt op elk besturingselement dat ValuePattern/RangeValuePattern weergeeft, plus besturingselementen voor bewerken met alleen TextPattern waarvan de toegankelijkheid wordt geïmplementeerd IAccessible::put_accValue (LegacyIAccessible fallback). WinUI 3 RichEditBox en WPF RichTextBox zijn uitzonderingen: ze maken alleen het alleen-lezen tekstpatroon (geen instelbaar waardepatroon) beschikbaar, zodat ze niet programmatisch kunnen worden ingesteld op basis van ontwerp; gebruik send-keys (interactief bureaublad vereist) om erin te typen.

Troubleshooting

Algemene patronen

Navigeren en controleren

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

Tekst zoeken en het bovenliggende item aanroepen

# 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

Dubbele elementen ondubbelzinnig maken

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

Schermopname met pop-up-overlays

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

Navigeren, wachten en controleren (enkele keten)

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

Ontdekken, klikken en controleren

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

Interactie in dialoogvenster Bestand

Dialoogvensters voor openen/opslaan van bestanden zijn standaarddialoogvensters Windows met UIA-ondersteuning:

# 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>

Gebruik inspect -w <dialog-hwnd> --interactive deze functie om de werkelijke slugs voor een specifiek dialoogvenster te ontdekken.

Waarom ; ketenen (niet &&)

De operator van && PowerShell kan blokkeren wanneer een systeemeigen CLI schrijft naar stderr of ANSI-escapereeksen gebruikt. In ; plaats daarvan wordt elke opdracht voorwaardelijke uitgevoerd en wordt deze impasse vermeden. Dit is ook beter voor agentwerkstromen: meestal wilt u dat de schermafbeelding wordt uitgevoerd, zelfs als de aanroep een afsluit zonder nul heeft.

CI-testpatronen

Gebruik winapp ui opdrachten in CI-pijplijnen (GitHub Actions, Azure DevOps) voor betrouwbaarheidstests en ui-validatie. wait-for met --property en --value fungeert als een assertie: het retourneert afsluitcode 1 bij time-out, waarbij de CI-stap automatisch mislukt.

Starten en testen in 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

Status van element assertie met wait-for

wait-for --value pollt totdat de waarde van een element overeenkomt met de verwachte tekenreeks, waarbij dezelfde slimme terugval wordt gebruikt als get-value (TextPattern → ValuePattern → SelectionPattern → Name). Retourneert afsluitcode 0 bij overeenkomst, afsluitcode 1 bij time-out, waardoor deze een CI-vriendelijke assertie is. Gebruik --property in plaats daarvan om een specifieke UIA-eigenschap te controleren.

# 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

Assert met JSON-uitvoer

Gebruik --json met PowerShell of jq voor complexere asserties:

Afsluitcodecontract voor search en wait-for in --json de modus: als er geen element overeenkomt (search) of de wachttijd (wait-for), schrijft de opdracht een volledig parseerbare resultaatenvelop naar stdout ({ "matchCount": 0, ... } of { "found": false, "timedOut": true, ... }) en retourneert afsluitcode 1. Stderr is leeg in --json de modus (loggeruitvoer wordt onderdrukt). Vertakking op de envelopvelden, of op $LASTEXITCODE, afhankelijk van welke ergonomischer is.

# 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)" }

Voorbeeld van een volledige betrouwbaarheidstest

# 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