@diegosouzacdv/jev-browser-mcp 0.4.0 → 0.4.1

package/README.md

@@ -69,9 +69,11 @@ sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
 passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
 hover, espera, teclas aprovadas, asserções por elemento, upload restrito a uma
 raiz local configurada e reações idempotentes a um comentário único. Também
-aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
-JavaScript enviado pelo harness, seletores livres nem coordenadas. Ele usa a
-biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
+aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
+JavaScript enviado pelo harness nem coordenadas. Além de papel/nome acessível,
+aceita `label`, `placeholder`, `title`, `text`, `test_id` e `selector`; CSS/XPath
+são o último recurso e geram um aviso no resultado. Ele usa a
+biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
 Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
 `stderr` para não misturar com JSON-RPC.
 
@@ -87,29 +89,50 @@ a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
 plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
 resultado esperado na tela.
 
-Cada plano pode usar:
-
-- `click`, `type`, `hover` e `select_option` com papel/nome acessível exatos;
+Cada plano pode usar:
+
+- `click`, `type`, `hover`, `select_option`, `press`, `assert_*` e upload com
+  papel/nome acessível ou um localizador: `label`, `placeholder`, `title`,
+  `text`, `test_id` ou `selector`;
+- `near: {"text":"..."}` para localizar o controle logo depois de um texto,
+  e `within: {"row_containing":"..."}` para limitar a ação à linha certa;
+- `within: {"role":"dialog"}` sem `name` para usar o único diálogo visível;
+  o MCP ignora diálogos visualmente ocultos, inclusive os que ficaram no DOM
+  com `opacity: 0`;
+- `name: ""` com `index` não negativo para controles sem nome. O resultado
+  inclui um aviso porque a posição pode mudar entre execuções;
+- `selector` com CSS ou XPath como último recurso. O MCP identifica essa escolha
+  em `warnings`; não é permitido enviar JavaScript nem coordenadas;
 - `timeout_seconds` opcional em cada etapa, limitado pela configuração central;
 - `type` com `mode: "keys"` para digitar sequencialmente em campos com máscara,
   `blur: true` para desfocar o campo e `sensitive: false` para permitir que o
-  valor apareça nas evidências;
+  valor apareça nas evidências. Nesse modo, `\n` envia Enter e `\t` envia Tab;
 - `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
-  `text_hidden`);
-- `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
-  `Enter`, `Escape` ou `Tab`;
+  `text_hidden`); `network_idle` aceita `url_contains` para aguardar só as
+  requisições correspondentes;
+- `press` (o alias legado `press_key` também é aceito) com `PageDown`, `PageUp`,
+  `Home`, `End`, setas, `Enter`, `Escape`, `Tab` ou `Shift+Tab`. Sem alvo,
+  envia a tecla ao elemento focado; com alvo, usa o localizador informado;
 - `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`; `assert_text`
   pode receber apenas `role` quando a região, como `alert`, não tem nome acessível;
 - `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
   dropzone;
 - `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
-- `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
-  não repetem uma reação já no estado pedido e distinguem `Curtir` de
-  `Descurtir`.
-
-Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
-container acessível único, como uma linha ou card. `index` escolhe uma ocorrência
-zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
+- `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
+  não repetem uma reação já no estado pedido e distinguem `Curtir` de
+  `Descurtir`.
+
+Em `wait_for_condition` com `condition: "hidden"`, use qualquer um desses
+localizadores, `near` ou `within`; `text_hidden` recebe o texto direto. Para
+aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
+`url_contains`; o MCP precisa observar a requisição depois da etapa anterior e
+esperar que ela termine.
+
+Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
+container acessível único, como uma linha, card ou diálogo. `index` escolhe uma
+ocorrência zero-based dentro desse escopo; sem `index`, o MCP exige exatamente
+um alvo. Para uma página com rótulo `for` quebrado, `label` também procura o
+controle próximo ao texto visível do rótulo.
 
 ```json
 {
@@ -121,8 +144,40 @@ zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
 ```
 
 ```json
-{"action":"click","role":"button","name":"Add to cart","index":0}
-```
+{"action":"click","role":"button","name":"Add to cart","index":0}
+```
+
+Exemplos para controles legados sem nome acessível:
+
+```json
+{"action":"type","role":"textbox","label":"Vencimento","text":"05/10/2026"}
+{"action":"type","role":"textbox","target_text":"Vencimento","text":"05/10/2026"}
+{"action":"click","role":"link","title":"Editar documento","within":{"row_containing":"1528721"}}
+{"action":"press","key":"Enter","role":"textbox","placeholder":"Busca rápida"}
+{"action":"click","role":"button","name":"","index":0}
+{"action":"click","selector":"#save-document"}
+```
+
+O reconhecimento retorna `unnamed_controls` com papel, posição, rótulo mais
+próximo e um trecho HTML sanitizado dos controles interativos sem nome. O
+snapshot também resume campos de formulário com `id`, `name`, valor, estado
+desabilitado, rótulo e índice zero-based entre campos de mesmo nome. Valores
+sensíveis, como senha, token e cartão, são ocultados. `snapshot_include_hidden`
+é `false` por padrão; defina `true` somente quando precisar inspecionar campos
+ocultos também.
+
+Em uma etapa `type`, `text` contém o valor a digitar; use `target_text` para
+localizar pelo texto visível próximo ao campo. Esse localizador exige `role`
+`textbox`, `searchbox` ou `combobox`.
+
+Por padrão, o MCP executa todos os passos antes de avaliar `expected_outcome`.
+Valores dentro de campos não contam como resultado visível. `stop_on_expected:
+true` habilita parada antecipada quando o texto esperado aparece fora dos
+campos; mantenha `false` para fluxos com várias etapas.
+
+Os erros de validação apontam o campo inválido e os campos aceitos. Os limites
+de `timeout_seconds` informam o máximo configurado, em vez de exigir tentativa
+e erro.
 
 ### Captura de downloads
 
@@ -159,12 +214,13 @@ trechos da página. Qualquer violação reprova esse fluxo. A auditoria automát
 encontra problemas comuns, mas não comprova conformidade WCAG completa; combine-a
 com revisão manual e testes com usuários assistivos.
 
-Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
-corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
-conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
-configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
-próximos quando o snapshot os encontrar. O plano não aceita JavaScript enviado
-pelo harness, coordenadas ou seletores livres.
+Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
+corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
+conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
+configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
+próximos quando o snapshot os encontrar. CSS/XPath são permitidos somente como
+localizadores explícitos de último recurso e geram aviso. O plano não aceita
+JavaScript enviado pelo harness nem coordenadas.
 
 Os aliases `value` → `text` em `type`/`wait_for_text` e `value` → `expected` em
 asserções são aceitos. `comment` também é aceito em planos e passos, mas é
@@ -285,11 +341,13 @@ continua informada mesmo quando a lista é truncada.
 O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
 `block_trackers`, `capture_console_errors`, `capture_network_errors`,
 `capture_network_error_bodies`, `ready_timeout_seconds`, `ready_network_idle`,
-`ready_stable_ms`, `ready_text`, `reuse_page`, `screenshot_on_failure` e
-`trace_on_failure`. Sem override, os padrões são lidos de `jev_browser_mcp` em
+`ready_stable_ms`, `ready_text`, `reuse_page`, `screenshot_on_failure`,
+`trace_on_failure`, `snapshot_include_hidden` e `stop_on_expected`. Sem override,
+os padrões são lidos de `jev_browser_mcp` em
 `config/ui-testing.json`: um plano candidato pula a chamada Decisions;
 captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
-de recursos ficam desligados. O browser espera a SPA renderizar uma captura
+de recursos ficam desligados; o plano roda até o fim e campos ocultos não são
+acrescentados ao snapshot. O browser espera a SPA renderizar uma captura
 acessível estável. `ready_text` pode identificar o conteúdo que marca a
 prontidão. `reuse_page: true` pula a navegação somente quando a página e
 `initial_url` têm a mesma origem. `snapshot_scope` aceita `body`, `main` ou

package/config/ui-testing.json

@@ -32,6 +32,9 @@
       "max_step_timeout_seconds": 60,
       "key_delay_ms_default": 30,
       "reuse_page_default": false,
+      "stop_on_expected_default": false,
+      "snapshot_include_hidden_default": false,
+      "visibility_poll_interval_ms_default": 50,
       "capture_network_error_bodies_default": false,
       "max_network_error_body_bytes": 65536,
       "max_network_error_message_chars": 300,

package/docs/jev-browser-mcp.md

@@ -69,9 +69,11 @@ sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
 passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
 hover, espera, teclas aprovadas, asserções por elemento, upload restrito a uma
 raiz local configurada e reações idempotentes a um comentário único. Também
-aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
-JavaScript enviado pelo harness, seletores livres nem coordenadas. Ele usa a
-biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
+aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
+JavaScript enviado pelo harness nem coordenadas. Além de papel/nome acessível,
+aceita `label`, `placeholder`, `title`, `text`, `test_id` e `selector`; CSS/XPath
+são o último recurso e geram um aviso no resultado. Ele usa a
+biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
 Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
 `stderr` para não misturar com JSON-RPC.
 
@@ -87,29 +89,50 @@ a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
 plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
 resultado esperado na tela.
 
-Cada plano pode usar:
-
-- `click`, `type`, `hover` e `select_option` com papel/nome acessível exatos;
+Cada plano pode usar:
+
+- `click`, `type`, `hover`, `select_option`, `press`, `assert_*` e upload com
+  papel/nome acessível ou um localizador: `label`, `placeholder`, `title`,
+  `text`, `test_id` ou `selector`;
+- `near: {"text":"..."}` para localizar o controle logo depois de um texto,
+  e `within: {"row_containing":"..."}` para limitar a ação à linha certa;
+- `within: {"role":"dialog"}` sem `name` para usar o único diálogo visível;
+  o MCP ignora diálogos visualmente ocultos, inclusive os que ficaram no DOM
+  com `opacity: 0`;
+- `name: ""` com `index` não negativo para controles sem nome. O resultado
+  inclui um aviso porque a posição pode mudar entre execuções;
+- `selector` com CSS ou XPath como último recurso. O MCP identifica essa escolha
+  em `warnings`; não é permitido enviar JavaScript nem coordenadas;
 - `timeout_seconds` opcional em cada etapa, limitado pela configuração central;
 - `type` com `mode: "keys"` para digitar sequencialmente em campos com máscara,
   `blur: true` para desfocar o campo e `sensitive: false` para permitir que o
-  valor apareça nas evidências;
+  valor apareça nas evidências. Nesse modo, `\n` envia Enter e `\t` envia Tab;
 - `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
-  `text_hidden`);
-- `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
-  `Enter`, `Escape` ou `Tab`;
+  `text_hidden`); `network_idle` aceita `url_contains` para aguardar só as
+  requisições correspondentes;
+- `press` (o alias legado `press_key` também é aceito) com `PageDown`, `PageUp`,
+  `Home`, `End`, setas, `Enter`, `Escape`, `Tab` ou `Shift+Tab`. Sem alvo,
+  envia a tecla ao elemento focado; com alvo, usa o localizador informado;
 - `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`; `assert_text`
   pode receber apenas `role` quando a região, como `alert`, não tem nome acessível;
 - `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
   dropzone;
 - `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
-- `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
-  não repetem uma reação já no estado pedido e distinguem `Curtir` de
-  `Descurtir`.
-
-Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
-container acessível único, como uma linha ou card. `index` escolhe uma ocorrência
-zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
+- `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
+  não repetem uma reação já no estado pedido e distinguem `Curtir` de
+  `Descurtir`.
+
+Em `wait_for_condition` com `condition: "hidden"`, use qualquer um desses
+localizadores, `near` ou `within`; `text_hidden` recebe o texto direto. Para
+aguardar o fim de uma chamada específica, use `condition: "network_idle"` com
+`url_contains`; o MCP precisa observar a requisição depois da etapa anterior e
+esperar que ela termine.
+
+Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
+container acessível único, como uma linha, card ou diálogo. `index` escolhe uma
+ocorrência zero-based dentro desse escopo; sem `index`, o MCP exige exatamente
+um alvo. Para uma página com rótulo `for` quebrado, `label` também procura o
+controle próximo ao texto visível do rótulo.
 
 ```json
 {
@@ -121,8 +144,40 @@ zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
 ```
 
 ```json
-{"action":"click","role":"button","name":"Add to cart","index":0}
-```
+{"action":"click","role":"button","name":"Add to cart","index":0}
+```
+
+Exemplos para controles legados sem nome acessível:
+
+```json
+{"action":"type","role":"textbox","label":"Vencimento","text":"05/10/2026"}
+{"action":"type","role":"textbox","target_text":"Vencimento","text":"05/10/2026"}
+{"action":"click","role":"link","title":"Editar documento","within":{"row_containing":"1528721"}}
+{"action":"press","key":"Enter","role":"textbox","placeholder":"Busca rápida"}
+{"action":"click","role":"button","name":"","index":0}
+{"action":"click","selector":"#save-document"}
+```
+
+O reconhecimento retorna `unnamed_controls` com papel, posição, rótulo mais
+próximo e um trecho HTML sanitizado dos controles interativos sem nome. O
+snapshot também resume campos de formulário com `id`, `name`, valor, estado
+desabilitado, rótulo e índice zero-based entre campos de mesmo nome. Valores
+sensíveis, como senha, token e cartão, são ocultados. `snapshot_include_hidden`
+é `false` por padrão; defina `true` somente quando precisar inspecionar campos
+ocultos também.
+
+Em uma etapa `type`, `text` contém o valor a digitar; use `target_text` para
+localizar pelo texto visível próximo ao campo. Esse localizador exige `role`
+`textbox`, `searchbox` ou `combobox`.
+
+Por padrão, o MCP executa todos os passos antes de avaliar `expected_outcome`.
+Valores dentro de campos não contam como resultado visível. `stop_on_expected:
+true` habilita parada antecipada quando o texto esperado aparece fora dos
+campos; mantenha `false` para fluxos com várias etapas.
+
+Os erros de validação apontam o campo inválido e os campos aceitos. Os limites
+de `timeout_seconds` informam o máximo configurado, em vez de exigir tentativa
+e erro.
 
 ### Captura de downloads
 
@@ -159,12 +214,13 @@ trechos da página. Qualquer violação reprova esse fluxo. A auditoria automát
 encontra problemas comuns, mas não comprova conformidade WCAG completa; combine-a
 com revisão manual e testes com usuários assistivos.
 
-Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
-corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
-conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
-configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
-próximos quando o snapshot os encontrar. O plano não aceita JavaScript enviado
-pelo harness, coordenadas ou seletores livres.
+Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
+corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
+conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
+configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
+próximos quando o snapshot os encontrar. CSS/XPath são permitidos somente como
+localizadores explícitos de último recurso e geram aviso. O plano não aceita
+JavaScript enviado pelo harness nem coordenadas.
 
 Os aliases `value` → `text` em `type`/`wait_for_text` e `value` → `expected` em
 asserções são aceitos. `comment` também é aceito em planos e passos, mas é
@@ -285,11 +341,13 @@ continua informada mesmo quando a lista é truncada.
 O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
 `block_trackers`, `capture_console_errors`, `capture_network_errors`,
 `capture_network_error_bodies`, `ready_timeout_seconds`, `ready_network_idle`,
-`ready_stable_ms`, `ready_text`, `reuse_page`, `screenshot_on_failure` e
-`trace_on_failure`. Sem override, os padrões são lidos de `jev_browser_mcp` em
+`ready_stable_ms`, `ready_text`, `reuse_page`, `screenshot_on_failure`,
+`trace_on_failure`, `snapshot_include_hidden` e `stop_on_expected`. Sem override,
+os padrões são lidos de `jev_browser_mcp` em
 `config/ui-testing.json`: um plano candidato pula a chamada Decisions;
 captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
-de recursos ficam desligados. O browser espera a SPA renderizar uma captura
+de recursos ficam desligados; o plano roda até o fim e campos ocultos não são
+acrescentados ao snapshot. O browser espera a SPA renderizar uma captura
 acessível estável. `ready_text` pode identificar o conteúdo que marca a
 prontidão. `reuse_page: true` pula a navegação somente quando a página e
 `initial_url` têm a mesma origem. `snapshot_scope` aceita `body`, `main` ou

package/mcp_servers/jev-browser-npm/src/config.mjs

@@ -27,6 +27,9 @@ const CONFIG_KEYS = {
     "max_step_timeout_seconds",
     "key_delay_ms_default",
     "reuse_page_default",
+    "stop_on_expected_default",
+    "snapshot_include_hidden_default",
+    "visibility_poll_interval_ms_default",
     "capture_network_error_bodies_default",
     "max_network_error_body_bytes",
     "max_network_error_message_chars",
@@ -264,6 +267,7 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
       postStepReadyTimeoutMs: postStepReadyTimeoutSeconds * 1000,
       maxStepTimeoutSeconds: positiveNumber(browserOptions.max_step_timeout_seconds, "jev_browser_mcp.browser.max_step_timeout_seconds"),
       keyDelayMs: positiveNumber(browserOptions.key_delay_ms_default, "jev_browser_mcp.browser.key_delay_ms_default", true),
+      visibilityPollMs: positiveNumber(browserOptions.visibility_poll_interval_ms_default, "jev_browser_mcp.browser.visibility_poll_interval_ms_default", true),
       maxNetworkErrorBodyBytes: positiveNumber(browserOptions.max_network_error_body_bytes, "jev_browser_mcp.browser.max_network_error_body_bytes", true),
       maxNetworkErrorMessageChars: positiveNumber(browserOptions.max_network_error_message_chars, "jev_browser_mcp.browser.max_network_error_message_chars", true),
       maxUploadFiles: positiveNumber(browserOptions.max_upload_files, "jev_browser_mcp.browser.max_upload_files", true),
@@ -287,6 +291,8 @@ export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {
         blockTrackers: booleanValue(browserOptions.block_trackers_default, "jev_browser_mcp.browser.block_trackers_default"),
         readyNetworkIdle: booleanValue(browserOptions.ready_network_idle_default, "jev_browser_mcp.browser.ready_network_idle_default"),
         reusePage: booleanValue(browserOptions.reuse_page_default, "jev_browser_mcp.browser.reuse_page_default"),
+        stopOnExpected: booleanValue(browserOptions.stop_on_expected_default, "jev_browser_mcp.browser.stop_on_expected_default"),
+        snapshotIncludeHidden: booleanValue(browserOptions.snapshot_include_hidden_default, "jev_browser_mcp.browser.snapshot_include_hidden_default"),
         readyTimeoutSeconds: readyTimeoutSecondsDefault,
         readyStableMs: readyStableMsDefault,
         snapshotScope,