Desktop — Windows UI Automation

Automação de aplicativos Windows via UI Automation

Iniciar Aplicação

desktop.launch_app

Inicia um programa (.exe)

Como usar

Abre um programa (.exe) e espera a janela dele aparecer, guardando-a na variável usada pelos demais comandos Desktop. Informe o título da janela para o robô saber qual esperar. Tecnologia: "uia" serve para a maioria dos programas modernos; "win32" é mais rápida em programas antigos (Delphi, VB6, MFC).

Exemplo: Inicie C:\Program Files\ERP\erp.exe esperando a janela com título contendo "ERP - Login" em {window}.

Campos

Campo	Tipo	Padrão	Detalhes
Programa *	Arquivo
Argumentos	Texto
Título da janela (recomendado)	Texto		Necessário para programas que abrem por outro processo (Bloco de Notas do Windows 11, apps da loja)
Salvar a janela na variável *	Variável de saída	`window`

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Pasta de trabalho	Pasta
Comparar título	Opção	`Contém`	Opções: Contém, Exato, Expressão regular
Tempo limite (0 = sem limite)	Número	`30 s`
Tecnologia	Opção	`UI Automation (apps modernos)`	Opções: UI Automation (apps modernos), Win32 (apps antigos, VB6/Delphi)

Resultado: guardado na variável window (Objeto).

Conectar à Aplicação

desktop.connect_app

Conecta a uma aplicação já aberta (por título ou processo)

Como usar

Liga o robô a um programa que já está aberto, pelo título da janela, pelo nome do processo (ex.: erp.exe) ou pelo PID, e guarda a janela na variável.

Exemplo: Conecte ao processo excel.exe já aberto pelo usuário, guardando em {window}.

Campos

Campo	Tipo	Padrão	Detalhes
Conectar por	Opção	`Título da janela`	Opções: Título da janela, Nome do processo (excel.exe), PID
Título, processo ou PID *	Texto
Salvar a janela na variável *	Variável de saída	`window`

+ Avançado (3)

Campo	Tipo	Padrão	Detalhes
Comparar título	Opção	`Contém`	Opções: Contém, Exato, Expressão regular
Tempo limite (0 = sem limite)	Número	`30 s`
Tecnologia	Opção	`UI Automation (apps modernos)`	Opções: UI Automation (apps modernos), Win32 (apps antigos, VB6/Delphi)

Resultado: guardado na variável window (Objeto).

Buscar Janela

desktop.find_window

Localiza janela por título, classe ou auto_id

Como usar

Localiza uma janela aberta pelo título (contém, exato ou expressão regular), opcionalmente pela classe, e guarda na variável. Para diálogos (Salvar como, mensagens), informe a janela principal em "Dentro da janela".

Exemplo: Busque a janela "Salvar como" dentro de {window} e guarde em {dialogo}.

Campos

Campo	Tipo	Padrão	Detalhes
Título da janela *	Texto
Salvar a janela na variável *	Variável de saída	`window`

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Comparar título	Opção	`Contém`	Opções: Contém, Exato, Expressão regular
Dentro da janela (para diálogos)	Variável
Classe da janela	Texto
Tempo limite (0 = sem limite)	Número	`10 s`

Resultado: guardado na variável window (Objeto).

Clicar Controle

desktop.click_control

Clica em um controle da janela (botão, link, etc.)

Como usar

Clica num controle da janela (botão, link, item, aba) localizado pelo AutomationId, pelo nome ou pela classe, sem mover o mouse. Use "Inspecionar" (passar o mouse + Ctrl) para capturar o controle: o Studio preenche o seletor e grava o caminho como plano B. Marque "Usar o mouse de verdade" em programas que só reagem ao clique físico.

Exemplo: Clique no botão de nome "Confirmar" da janela {window}.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle *	Seletor		Ex.: `btnSalvar ou Salvar`
Duplo clique	Sim/Não	`Não`

+ Avançado (5)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Usar o mouse de verdade	Sim/Não	`Não`	Por padrão o botão é acionado sem mover o mouse
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Digitar Texto

desktop.type_text

Digita texto em um campo

Como usar

Preenche um campo com o texto, substituindo o conteúdo (ou acrescentando, se desmarcado), e pode pressionar Enter no fim. Por padrão o valor é colocado direto no campo, sem teclado; marque "Digitar pelo teclado de verdade" em campos que validam a digitação tecla a tecla.

Exemplo: Digite {codigo_cliente} no campo de AutomationId "txtCliente" e pressione Enter.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle *	Seletor		Ex.: `btnSalvar ou Salvar`
Texto *	Texto
Substituir o conteúdo atual	Sim/Não	`Sim`
Pressionar Enter no fim	Sim/Não	`Não`

+ Avançado (5)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Digitar pelo teclado de verdade	Sim/Não	`Não`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Obter Texto do Controle

desktop.get_control_text

Lê texto de um controle

Como usar

Lê o texto de um controle (campo, rótulo, barra de status) e guarda numa variável.

Exemplo: Leia o texto do rótulo "lblSaldo" em {saldo}.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle *	Seletor		Ex.: `btnSalvar ou Salvar`
Salvar resultado na variável *	Variável de saída	`control_text`

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Resultado: guardado na variável control_text (Texto).

Selecionar Item

desktop.select_item

Seleciona item em ComboBox, ListBox ou TreeView

Como usar

Escolhe um item numa caixa de combinação, lista ou árvore, pelo texto ou pela posição. Em árvores, use o caminho separado por barra, como Clientes/Ativos.

Exemplo: Selecione "São Paulo" na combo de AutomationId "cmbEstado".

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle *	Seletor		Ex.: `btnSalvar ou Salvar`
Item (texto, posição ou Pasta/Subpasta em árvores) *	Texto

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Marcar/Desmarcar

desktop.check_control

Marca/desmarca CheckBox ou RadioButton

Como usar

Marca, desmarca ou inverte uma caixa de seleção ou opção, e pode guardar o estado final.

Exemplo: Marque a caixa "Enviar por e-mail" antes de clicar em "Gerar".

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle *	Seletor		Ex.: `btnSalvar ou Salvar`
Ação	Opção	`Marcar`	Opções: Marcar, Desmarcar, Inverter
Salvar o estado final na variável	Variável de saída

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Resultado: guardado na variável escolhida (Booleano).

Aguardar Janela

desktop.wait_window

Espera uma janela aparecer

Como usar

Espera uma janela aparecer ou sumir, como uma tela de carregamento ou um diálogo de confirmação. Com "Falhar o robô" desmarcado, segue mesmo se o tempo acabar; guarde a janela para usá-la em seguida.

Exemplo: Aguarde até 60 s a janela "Processando..." sumir antes de ler o resultado.

Campos

Campo	Tipo	Padrão	Detalhes
Título da janela *	Texto
Esperar a janela	Opção	`Aparecer`	Opções: Aparecer, Fechar
Tempo limite (0 = sem limite)	Número	`30 s`
Salvar a janela na variável	Variável de saída

+ Avançado (3)

Campo	Tipo	Padrão	Detalhes
Comparar título	Opção	`Contém`	Opções: Contém, Exato, Expressão regular
Falhar o robô se o tempo esgotar	Sim/Não	`Sim`
Tecnologia	Opção	`UI Automation (apps modernos)`	Opções: UI Automation (apps modernos), Win32 (apps antigos, VB6/Delphi)

Resultado: guardado na variável escolhida (Objeto).

Fechar Janela

desktop.close_window

Fecha uma janela

Como usar

Fecha a janela (como clicar no X). Se o programa perguntar algo ao fechar, trate o diálogo com Buscar Janela e Clicar Controle.

Exemplo: Feche {window} ao terminar o lançamento das notas.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`

Maximizar/Minimizar

desktop.window_state

Altera estado da janela

Como usar

Maximiza, minimiza ou restaura a janela. Maximizar ajuda quando controles só aparecem com a janela grande.

Exemplo: Maximize {window} logo depois de abrir o sistema.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Estado	Opção	`Maximizar`	Opções: Maximizar, Minimizar, Restaurar

Obter Propriedade

desktop.get_control_property

Lê propriedade de um controle (enabled, visible, etc.)

Como usar

Lê uma propriedade de um controle: texto, se existe, se está habilitado ou visível, se está marcado, posição e outras. Ótimo para decidir com um Se, como esperar um botão habilitar.

Exemplo: Leia a propriedade enabled do botão "Salvar" em {pode_salvar}.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle *	Seletor		Ex.: `btnSalvar ou Salvar`
Propriedade	Opção	`Texto / valor`	Opções: Texto / valor, Existe (verdadeiro/falso), Habilitado, Visível, Marcado / selecionado, Posição e tamanho, Nome, AutomationId, Classe, Tipo do controle
Salvar resultado na variável *	Variável de saída	`property_value`

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Resultado: guardado na variável property_value (Qualquer).

Enviar Teclas

desktop.send_keys

Envia combinação de teclas (ex: Ctrl+S)

Como usar

Envia teclas ou atalhos para a janela (ou para um controle, que recebe o foco antes): Ctrl+S, Alt+F4, Enter, F5 ou o formato do pywinauto (^s, %{F4}).

Exemplo: Envie Ctrl+S para {window} para salvar o documento.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Teclas *	Texto		Ctrl+S, Alt+F4, Enter, F5, Ctrl+Shift+Esc ou o formato do pywinauto (^s, %{F4})Ex.: `Ctrl+S`

+ Avançado (6)

Campo	Tipo	Padrão	Detalhes
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle	Seletor		Ex.: `btnSalvar ou Salvar`
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Selecionar Menu

desktop.menu_select

Navega e clica em item de menu

Como usar

Abre um item do menu da janela pelo caminho, separado por ">". Em menus clássicos do Windows o item é acionado direto, sem abrir o menu.

Exemplo: Selecione Arquivo > Exportar > PDF em {window}.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Caminho do menu *	Texto		Ex.: `Arquivo > Salvar como`

Clicar com Direito

desktop.right_click

Clique com botão direito do mouse

Como usar

Clica com o botão direito num controle para abrir o menu de contexto; depois clique no item do menu com Clicar Controle.

Exemplo: Clique com o direito na linha do pedido e depois em "Cancelar pedido".

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle *	Seletor		Ex.: `btnSalvar ou Salvar`

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Rolar

desktop.scroll

Rola conteúdo de um controle

Como usar

Rola o conteúdo de um controle (lista, grade, documento) ou da janela, em linhas, para cima, baixo ou lados.

Exemplo: Role a grade de pedidos 10 linhas para baixo para mostrar os próximos registros.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle	Seletor		Ex.: `btnSalvar ou Salvar`
Direção	Opção	`Para baixo`	Opções: Para baixo, Para cima, Para a esquerda, Para a direita
Linhas	Número	`3`

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Definir Foco

desktop.set_focus

Traz a janela para frente e define foco

Como usar

Traz a janela para a frente e põe o foco nela ou num controle. Use antes de comandos de teclado e mouse reais.

Exemplo: Defina o foco no campo "Observações" antes de colar o texto com Ctrl+V.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Encontrar controle por	Opção	`Automático (AutomationId ou nome)`	Use Listar Controles para ver os nomes e AutomationIds de uma janelaOpções: Automático (AutomationId ou nome), AutomationId, Nome (exato), Nome contém, Classe
Controle	Seletor		Ex.: `btnSalvar ou Salvar`

+ Avançado (4)

Campo	Tipo	Padrão	Detalhes
Tipo do controle	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Posição entre os iguais (0 = o primeiro)	Número	`0`
Esperar o controle até	Número	`10 s`
Alvo capturado (plano B)	Alvo capturado pelo Inspetor		Caminho na janela e rótulo vizinho capturados pelo Inspetor de Elementos. Usados quando o controle não é achado pelo seletor acima.

Listar Controles

desktop.list_controls

Lista todos os controles de uma janela (para debug)

Como usar

Lista os controles da janela (tipo, nome, AutomationId, classe) no log e numa variável. Ajuda a montar seletores quando o Inspetor não alcança um controle.

Exemplo: Liste os controles do tipo Button de {window} para descobrir o AutomationId do botão de exportar.

Campos

Campo	Tipo	Padrão	Detalhes
Janela *	Variável	`window`
Salvar resultado na variável *	Variável de saída	`controls`	Também aparece no Console, em árvore

+ Avançado (3)

Campo	Tipo	Padrão	Detalhes
Profundidade máxima	Número	`5`
Só do tipo	Opção	`Qualquer`	Opções: Qualquer, Button, CheckBox, ComboBox, DataGrid, DataItem, Document, Edit, Group, Hyperlink, Image, List, ListItem, Menu, MenuBar, MenuItem, Pane, RadioButton, ScrollBar, Slider, Spinner, Tab, TabItem, Table, Text, ToolBar, Tree, TreeItem, Window
Só controles visíveis	Sim/Não	`Sim`

Resultado: guardado na variável controls (Lista).