---
id: "navegador-automacao-interacao"
titulo: "Automação: interação com a página"
resumo: "Comandos que clicam, preenchem, digitam, arrastam e leem estado de elementos por referência de snapshot."
idioma: "pt-br"
tipo: "referencia"
categoria: "telas"
aplicavelDesde: "0.0.16"
capabilities: ["browser.element.interact", "browser.element.inspect", "browser.mouse.control", "browser.form.fill"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/pt-br/ferramentas/navegador/automacao-referencia-interacao/"
fonte: "pt-br/ferramentas/navegador/automacao-referencia-interacao.md"
caminhoPublico: "docs/publica/pt-br/ferramentas/navegador/automacao-referencia-interacao.md"
hashFonte: "sha256:3d101604495fd2ad64acfa3e19faeb79df51c9b0cc0ae215d69e1e735d0f5ddb"
hashDestaPagina: "sha256:3d101604495fd2ad64acfa3e19faeb79df51c9b0cc0ae215d69e1e735d0f5ddb"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
Comandos, flags e valores são **literais** — não são traduzidos. Todos aceitam as flags de alvo `--page`/`--node`/`--workspace` descritas em [Automação: navegação](/docs/pt-br/ferramentas/navegador/automacao-referencia-navegacao/), e sem alvo agem na aba ativa do workspace atual.

## A referência vem do snapshot

Os comandos por elemento usam **`--element <ref>`**, e esses `ref` vêm de `elyra snapshot`.

- Tire o snapshot, use os `ref` na mesma página.
- **Depois de navegar ou de mudar a página, os `ref` antigos não valem mais** — tire um snapshot novo.
- A CLI recomenda, depois de cada ação, tirar um snapshot novo para conferir o que realmente assentou.

## Ações por referência

| Comando | Uso |
|---|---|
| `elyra click --element <ref>` | Clique |
| `elyra dblclick --element <ref>` | Clique duplo |
| `elyra hover --element <ref>` | Passar o mouse |
| `elyra focus --element <ref>` | Dar foco |
| `elyra fill --element <ref> --value <texto>` | Limpar e preencher |
| `elyra type --input <texto>` | Digitar no foco atual |
| `elyra select --element <ref> --value <valor>` | Escolher opção de lista |
| `elyra check --element <ref>` / `elyra uncheck --element <ref>` | Marcar / desmarcar caixa ou rádio |
| `elyra clear --element <ref>` | Limpar o conteúdo do campo |
| `elyra select-all --element <ref>` | Selecionar todo o texto do campo |
| `elyra keypress --key <nome>` | Pressionar tecla (`Enter`, `Tab`, `Escape`, `ArrowDown`…) |
| `elyra drag --from <ref> --to <ref>` | Arrastar de um elemento para outro |
| `elyra upload --element <ref> --files <caminho,...>` | Enviar arquivos locais para um campo de arquivo |

Obrigatoriedades: `fill` e `select` exigem `--value`; `drag` exige `--from` e `--to`; `upload` exige `--files`; `keypress` exige `--key`. `check` e `uncheck` são o mesmo handler parametrizado.

> **`clear` apaga sem desfazer.** **`upload` envia arquivos do seu disco para a página** — confira o que está indo e para onde.

## Preencher vários campos de uma vez

```
elyra fill-form (--fields '<json>' | --fields-file <caminho>) [--page <id>] [--workspace <seletor>] [--json]
```

- `--fields` é um vetor JSON no formato `[{"element":"<ref>","value":"<texto>"}]`, com `ref` vindos de `snapshot`.
- `--fields` e `--fields-file` são **mutuamente exclusivos**; informar os dois é erro.
- **Cada campo é reportado**: o resultado diz o que entrou e o que falhou. Use `elyra snapshot --json` para conferir.
- Um arquivo inválido ou vazio falha.

## Ler estado e propriedade

| Comando | O que devolve |
|---|---|
| `elyra get --what text\|html\|value\|url\|title\|count\|box [--element <ref>]` | Propriedade do elemento — ou da página, quando a propriedade é da página |
| `elyra is --what visible\|enabled\|checked --element <ref>` | Estado do elemento |
| `elyra find --locator <tipo> --value <texto> --action <ação>` | Localiza por locator semântico e executa a ação |
| `elyra highlight --selector <ref>` | Destaca o elemento |
| `elyra scrollintoview --element <ref>` | Rola até o elemento |
| `elyra inserttext --text <texto>` | Insere texto **sem eventos de tecla** |

> **`inserttext` não dispara `keydown` nem `keyup`.** Páginas que reagem a eventos de tecla não se comportam como se você tivesse digitado — para esses casos, use digitação real.

## Mouse de baixo nível

```
elyra mouse move --x <n> --y <n> [--page <id>] [--workspace <seletor>] [--json]
elyra mouse down [--button <left|right|middle>] [--page <id>] [--workspace <seletor>] [--json]
elyra mouse up [--button <left|right|middle>] [--page <id>] [--workspace <seletor>] [--json]
elyra mouse wheel --dy <n> [--dx <n>] [--page <id>] [--workspace <seletor>] [--json]
```

- `mouse move` exige `--x` e `--y`; `mouse wheel` exige `--dy`, com `--dx` opcional.
- As coordenadas são **absolutas na página** e dependem do viewport atual. Sem um snapshot recente, o alvo pode errar — em páginas com rolagem, o alvo muda sem aviso.