Windows UI オートメーション (pywinauto)

pywinauto を使用して任意の Windows デスクトップアプリケーションを操作します：ウィンドウの発見、コントロールの検査、ボタンのクリック、テキストの入力、コンテンツの読み取りが可能です。 2つのバックエンドをサポートしています：Win32 API（従来型アプリケーション）と MS UI Automation（モダンアプリケーション）。

ユースケース

• ユーザーが「XX アプリのそのボタンをクリックして」「このフォームを自動入力して」と依頼
• API のないデスクトップアプリケーション（ERP システム、社内管理システムなど）を操作する必要がある
• GUI アプリケーションをバッチ操作する（データの自動入力など）
• 他のアプリケーションのインターフェース上のテキストコンテンツを読み取る必要がある

バックエンドの選択

バックエンド	パラメータ	対応アプリケーション
Win32 API	backend="win32"	MFC、VB6、VCL、シンプルな WinForms
MS UI Automation	backend="uia"	WinForms、WPF、UWP Store アプリケーション、Qt5、ブラウザ

どちらを使うか不確定な場合は、まず uia を試してください。コントロールが見つからない場合は win32 に切り替えてください。

コマンドリファレンス

既存のアプリケーションに接続

from pywinauto import Application

# 方法 1：ウィンドウタイトルで接続
app = Application(backend="uia").connect(title="記事本", timeout=10)

# 方法 2：プロセス名で接続
app = Application(backend="uia").connect(path="notepad.exe")

# 方法 3：プロセス ID で接続
app = Application(backend="uia").connect(process=12345)

新しいアプリケーションを起動

from pywinauto import Application

app = Application(backend="uia").start("notepad.exe")
# ウィンドウが表示されるまで待機
app.window(title_re=".*記事本.*").wait("ready", timeout=10)

ウィンドウとコントロールの発見

# すべてのトップレベルウィンドウをリストアップ
from pywinauto import Desktop
windows = Desktop(backend="uia").windows()
for w in windows:
    print(f"{w.window_text()} — {w.class_name()}")

# ウィンドウコントロールツリーを出力（デバッグ用）
dlg = app.window(title_re=".*記事本.*")
dlg.print_control_identifiers()

ボタンとメニューのクリック

dlg = app.window(title="記事本")

# メニューをクリック
dlg.menu_select("ファイル->開く")

# ボタンをクリック（テキストマッチングによる）
dlg.child_window(title="OK", control_type="Button").click()

# ボタンをクリック（auto_id による）
dlg.child_window(auto_id="btnSubmit").click()

テキストの入力

dlg = app.window(title="記事本")

# 編集ボックスに入力
edit = dlg.child_window(control_type="Edit")
edit.set_text("入力するコンテンツ")

# キーボード入力をシミュレート（特殊キーをサポート）
edit.type_keys("Hello{ENTER}World", with_spaces=True)

# 特殊キー：{ENTER} {TAB} {ESC} {DELETE} {BACKSPACE}
# 修飾キー：^ = Ctrl、% = Alt、+ = Shift
# 例：Ctrl+A = ^a、Ctrl+Shift+S = ^+s

インターフェースコンテンツの読み取り

dlg = app.window(title="記事本")

# テキストボックスの内容を読み取る
content = dlg.child_window(control_type="Edit").window_text()

# リストアイテムを読み取る
listbox = dlg.child_window(control_type="List")
items = [item.window_text() for item in listbox.children()]

# テーブルを読み取る
table = dlg.child_window(control_type="Table")
for row in table.children():
    cells = [c.window_text() for c in row.children()]
    print(" | ".join(cells))

待機と同期

# ウィンドウが表示されるまで待機
dlg = app.window(title="保存").wait("visible", timeout=10)

# ウィンドウが非表示になるまで待機
app.window(title="読み込み中...").wait_not("visible", timeout=30)

# コントロールが有効になるまで待機
dlg.child_window(title="送信").wait("enabled", timeout=5)

ウィンドウ管理

dlg = app.window(title="記事本")

# 最大化 / 最小化 / 復元
dlg.maximize()
dlg.minimize()
dlg.restore()

# 移動とサイズ変更
dlg.move_window(x=100, y=100, width=800, height=600)

# 前面に設定
dlg.set_focus()

# 閉じる
dlg.close()

スクロール

from pywinauto import mouse

# 指定座標で 3 行下にスクロール
mouse.scroll(coords=(500, 400), wheel_dist=-3)

# 5 行上にスクロール
mouse.scroll(coords=(500, 400), wheel_dist=5)

# コントロール内でスクロール（先にコントロール位置を取得）
rect = dlg.child_window(control_type="List").rectangle()
mouse.scroll(coords=(rect.mid_point()), wheel_dist=-3)

マウス座標操作

from pywinauto import mouse

# マウスを座標に移動
mouse.move(coords=(500, 300))

# 指定座標で左クリック
mouse.click(coords=(500, 300))

# 右クリック
mouse.right_click(coords=(500, 300))

# ダブルクリック
mouse.double_click(coords=(500, 300))

ドラッグ

from pywinauto import mouse

# ドラッグ：(100,200) から (300,400) へ
mouse.press(coords=(100, 200))
mouse.move(coords=(300, 400))
mouse.release(coords=(300, 400))

典型的なワークフロー

1. Desktop().windows() でオープンしているウィンドウをリストアップ
2. app.connect() でターゲットアプリケーションに接続
3. dlg.print_control_identifiers() でコントロールツリーを確認
4. コントロールタイプと属性に基づいてターゲット要素を特定
5. 操作を実行（click / set_text / type_keys / scroll）
6. 結果を読み取るか、操作完了を待機

セーフティルール

• 操作前に必ず HITL 確認：どのアプリケーションのどのコントロールを操作するかをユーザーに通知
• ユーザー文書を自動的に閉じない：保存されていない文書の close() を呼び出さない
• 管理者ウィンドウを操作しない：UAC ポップアップとシステム設定をスキップ
• 操作失敗時にスクリーンショットをフィードバック：ユーザーに現在のインターフェース状態を見せる
• 各操作ステップ間に 0.5 秒の間隔を設ける：UI が応答しないほど操作が速くなるのを回避