Metadata-Version: 2.4
Name: winlenium
Version: 0.2.0
Summary: Winlenium is a CLI tool for automated testing of Windows programs via the MS UI Automation framework.
Author: Andrey Meshkov
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Dist: uiautomation
Requires-Dist: click
Requires-Dist: pillow
Requires-Dist: pyperclip
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/ameshkov/winlenium
Project-URL: Repository, https://github.com/ameshkov/winlenium
Project-URL: Issues, https://github.com/ameshkov/winlenium/issues
Description-Content-Type: text/markdown

# 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

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

```bash
pip install .
```

After installation the `winlenium` command is available in your shell.

## Quick Start

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

```bash
# 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:

```bash
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:

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

## Usage Examples

### Discover running applications

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

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

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

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

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

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

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

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

### Wait for elements

```bash
# 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`:

```bash
# 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](DEVELOPMENT.md) — setup, testing, and contribution
  workflow
- [Changelog](CHANGELOG.md)
- [LLM agent rules](AGENTS.md)
