winlenium 0.2.0

Winlenium is a CLI tool for automated testing of Windows programs via the MS UI Automation framework.

Winlenium

A command-line tool for automated testing of Windows applications using the Microsoft UI Automation framework. Winlenium exposes a set of shell commands (click, type, key, inspect, wait, and others) that locate UI elements by selector and perform actions on them. Designed for CI/CD pipelines, test scripts, and any workflow where you need to drive a Windows GUI without writing UIA code.

Key Concepts

Selectors are the primary way to identify UI elements. Every action command accepts a combination of --name, --automationid, --controltype, --pid, and --index options that narrow the search to a single element in the accessibility tree.

Window selectors scope an action to a specific top-level window. They use the --window-* prefix (--window-name, --window-pid, --window-handle, etc.) and can be combined with element selectors so you can say "click the OK button inside the Save dialog of process 1234."

Output formats — commands that produce output support --format text (human-readable, default) and --format json (machine-readable for scripts).

Installation

Requirements

• Python 3.12+
• Node.js 18+ (for development formatting checks that run markdownlint-cli2)
• Windows 10 or 11 with a desktop session (UI Automation requires an active desktop)

Install from source

# Clone the repository
git clone https://github.com/ameshkov/winlenium.git
cd winlenium

# Install with uv
uv sync

# Verify installation
winlenium --version

Install with pip

pip install .

After installation the winlenium command is available in your shell.

Quick Start

Launch Notepad, type some text, and save the file:

# 1. Start Notepad and wait for its window
winlenium run notepad.exe

# 2. Type text into the editor
winlenium type --text "Hello from Winlenium" --window-name "Untitled - Notepad"

# 3. Save the file with Ctrl+S
winlenium key --keys "Ctrl+S" --window-name "Untitled - Notepad"

# 4. Wait for the Save As dialog
winlenium wait --name "Save As" --timeout 5000

# 5. Type a filename and press Enter
winlenium type --text "demo.txt" --window-name "Save As"
winlenium key --keys "Enter" --window-name "Save As"

Commands

Process and Window Management

Command	Description
run	Launch an executable and wait for its main window
close	Close a window (WindowPattern) or terminate a process
focus	Bring a window to the foreground and set input focus
window	Manage window state (minimize, maximize, restore)
list-windows	List all top-level windows, optionally filtered by PID
list-processes	List running processes that have visible windows

Element Interaction

Command	Description
click	Click a UI element identified by selector
type	Send text input to an element or the focused control
key	Send a key combination (e.g. Ctrl+S, Alt+F4)
move	Mouse move, hover, or drag-and-drop
scroll	Scroll within a scrollable element
toggle	Toggle a checkbox or toggle button
select	Select an item in a list, combo box, or tab control
expand	Expand a tree node, menu, or dropdown
collapse	Collapse a tree node, menu, or dropdown
set-value	Set an element's value via ValuePattern

Inspection and Queries

Command	Description
inspect	Print the accessibility tree of a window or element
get-value	Read an element's value (ValuePattern)
get-property	Read a specific UIA property (e.g. IsEnabled)
wait	Wait for an element to appear or disappear
screenshot	Capture a screenshot of a window or element
clipboard	Get or set clipboard content (get / set)

Run winlenium <command> --help for the full list of options for any command.

Element Selectors

Most commands accept the following options to locate a UI element:

Option	Description
--name	Match element by its Name property
--automationid	Match element by AutomationId
--controltype	Match element by ControlType (e.g. Button, Edit)
--pid	Scope the search to a process ID
--index	Select the Nth match (0-based) when multiple elements match

Selectors can be combined to narrow the search:

winlenium click --name "OK" --controltype Button --window-name "My App"

At least one selector (--name, --automationid, --controltype, or --pid) must be provided.

Window Selectors

Commands that interact with elements inside a window accept window selector options to first locate the correct window:

Option	Description
--window-name	Match window by Name property
--window-automationid	Match window by AutomationId
--window-controltype	Match window by ControlType
--window-pid	Match window by process ID
--window-index	Select the Nth matching window (0-based)
--window-handle	Match window by native handle (hex 0x1A2B or decimal)

Combine window and element selectors for precise targeting:

winlenium click --name "OK" --controltype Button --window-pid 1234 --window-index 0

Usage Examples

Discover running applications

# Find all processes with "notepad" in the name
winlenium list-processes --name notepad --format json

# List all windows belonging to a process
winlenium list-windows --pid 12345

Inspect the accessibility tree

# Show the first two levels of a window's element tree
winlenium inspect --window-name "Untitled - Notepad" --depth 2

# Inspect a specific element
winlenium inspect --name "Text Editor" --window-name "Untitled - Notepad"

Interact with UI controls

# Click a button
winlenium click --name "Submit" --controltype Button --window-name "My App"

# Toggle a checkbox
winlenium toggle --name "Enable feature" --window-name "Settings"

# Select a tab or list item
winlenium select --name "Advanced" --window-name "Settings"

# Expand a tree node
winlenium expand --name "Documents" --window-name "Explorer"

# Set a slider or text field value directly (no keystrokes)
winlenium set-value --name "Volume" --value "75" --window-name "Settings"

Read element state

# Check if a button is enabled
winlenium get-property --name "Submit" --property IsEnabled --window-name "My App"

# Read the current value of a text field
winlenium get-value --name "Username" --window-name "Login"

Mouse actions

# Hover over an element
winlenium move --name "Help" --hover --window-name "My App"

# Drag and drop
winlenium move --name "DragItem" --to-name "DropTarget" --window-name "My App"

# Scroll down three increments
winlenium scroll --name "ItemList" --direction down --amount 3 --window-name "My App"

Screenshots

# Capture a window screenshot to a file
winlenium screenshot --window-name "My App" --output screenshot.png

# Capture a specific element
winlenium screenshot --name "Chart" --window-name "Dashboard" --output chart.png

Window management

# Bring a window to the foreground
winlenium focus --window-name "Notepad"

# Minimize / maximize / restore
winlenium window minimize --window-name "Notepad"
winlenium window maximize --window-pid 12345
winlenium window restore --window-handle 0x1A2B3C

# Close a window gracefully
winlenium close --window-name "Save As"

# Force-terminate a process
winlenium close --pid 12345 --force

Clipboard

winlenium clipboard set --text "Copied text"
winlenium clipboard get

Wait for elements

# Wait for an element to appear (default)
winlenium wait --name "Success" --window-name "My App" --timeout 10000

# Wait for a dialog to disappear
winlenium wait --name "Loading" --until gone --timeout 15000

Output Formats

Commands that produce output accept --format text (default) or --format json:

# Human-readable text output
winlenium inspect --window-name "Notepad"

# Machine-readable JSON for scripting
winlenium inspect --window-name "Notepad" --format json

Exit Codes

Code	Meaning
0	Success
1	Error (element not found, invalid selector, etc.)
2	Timeout (element did not appear within the limit)

Documentation

• Development guide — setup, testing, and contribution workflow
• Changelog
• LLM agent rules