@diegosouzacdv/jev-browser-mcp 0.4.2 → 0.5.0

package/README.md

@@ -17,7 +17,7 @@ versão em produção, use o número explícito no argumento do pacote:
   "mcpServers": {
     "jev-browser": {
       "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.4.0"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.5.0"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
         "JEV_BROWSER_MODE": "computer"
@@ -35,6 +35,18 @@ de configuração. Para instalar no projeto Node do próprio harness:
 npm install @diegosouzacdv/jev-browser-mcp
 ```
 
+Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
+fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cada
+inicialização:
+
+```sh
+npm install --global @diegosouzacdv/jev-browser-mcp@0.5.0
+```
+
+Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
+Para atualizar, rode `npm install --global
+@diegosouzacdv/jev-browser-mcp@<versão>` e reinicie o processo do harness.
+
 O padrão `computer` exige Chrome ou Edge instalado. Se optar por `harness`,
 configure `JEV_BROWSER_MODE=harness` antes de instalar o navegador gerenciado
 pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp --install-browser`.
@@ -95,15 +107,18 @@ Cada plano pode usar:
   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: {"row_containing":"..."}` para limitar por trecho e
+  `within: {"row_containing_exact":"..."}` para exigir um elemento com o
+  texto exato na linha, sem casar com `15287210` ao procurar `1528721`;
 - `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. O índice é
-  zero-based para o mesmo papel e segue o localizador Playwright
-  `{role, name: ""}`; controles desabilitados não aparecem no diagnóstico, mas
-  continuam contando para que o índice aponte ao controle correto;
+  zero-based para o mesmo papel e inclui nomes vazios ou compostos só por
+  espaços/glyphs de uso privado, como ícones Font Awesome; controles
+  desabilitados não aparecem no diagnóstico, mas continuam contando para que o
+  índice aponte ao controle correto;
 - `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;
@@ -113,8 +128,9 @@ Cada plano pode usar:
 - `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
   `text_hidden`). `wait_for_text` aceita `fail_on: {"role":"alert"}` para
   interromper a espera assim que um alerta visível aparecer e incluir seu texto
-  no erro. `network_idle` aceita `url_contains` para aguardar só as requisições
-  correspondentes;
+  no erro. Se o alerta contiver o texto esperado, a etapa passa; caso contrário,
+  o alerta interrompe a espera. `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;
@@ -127,6 +143,58 @@ Cada plano pode usar:
   não repetem uma reação já no estado pedido e distinguem `Curtir` de
   `Descurtir`.
 
+As proteções e evidências por etapa usam estes campos:
+
+- `confirm_dialog` recebe `expected_text` e `button`. O MCP exige um diálogo
+  visível único e confere se ele contém o texto esperado antes de clicar; se o
+  alerta mudou, a etapa falha sem clicar no botão. Reserve `click` comum para
+  ações que não dependem do conteúdo de uma confirmação;
+- `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
+  Com `options.dry_run: true`, o fluxo para imediatamente antes da primeira
+  etapa marcada e retorna `dry_run_stopped_before_step` e `mutating_steps`.
+  Marque toda ação que grava ou envia algo, mesmo quando não for um botão
+  chamado Salvar;
+- `duration_ms` aparece em cada etapa concluída ou falha. `mutating_steps`
+  lista as etapas marcadas e informa quais foram executadas;
+- `screenshot: true` salva uma captura depois da etapa e inclui seu caminho na
+  evidência da etapa;
+- `options.report_path` grava um resumo `.md` ou JUnit `.xml`. O caminho deve
+  ser absoluto e estar dentro de `JEV_BROWSER_ARTIFACT_DIR` (ou do diretório de
+  artefatos configurado). O relatório resume versão/status, duração, alvo e
+  `resolved_target`, asserções de rede, falhas de rede e caminhos das capturas.
+
+`run_browser_flow` também aceita `params` como mapa de texto, números e
+booleanos. Use `{pedido}` em `flow`, `expected_outcome` e nos campos textuais do
+plano para reutilizar um valor sem editar o roteiro em vários lugares. A ação
+`extract` lê `text` (padrão), `value` ou `attribute` de um elemento e salva o
+resultado na variável indicada por `as`; etapas seguintes podem usar
+`{documento}`. O valor extraído é tratado como sensível e fica oculto no
+resultado por padrão; use `sensitive: false` só quando for apropriado exibi-lo.
+`resolved_target.match_strategy` informa quando um rótulo foi
+associado por proximidade (`label-proximity`) em vez de um `label[for]` direto.
+
+A ação `assert_network` verifica respostas observadas depois da etapa anterior,
+incluindo respostas 2xx ou erros esperados como 404. Exemplo:
+
+```json
+{
+  "action": "assert_network",
+  "url_contains": "/documentoFinanceiro/atualizar",
+  "method": "PUT",
+  "status": 404,
+  "message_contains": "Boleto não encontrado"
+}
+```
+
+Essa asserção aparece na evidência como `response_status`, separado do campo
+`status` da etapa (`passed` ou `failed`). `message_contains` lê somente resposta
+da mesma origem e respeita o limite configurado para captura de corpos.
+
+Exemplo de parâmetro e extração: passe `params: {"pedido":"1528721"}`, filtre
+com `within: {"row_containing_exact":"{pedido}"}`, e use uma etapa
+`{"action":"extract","role":"cell","name":"{pedido}","within":{"row_containing_exact":"{pedido}"},"as":"documento"}`.
+A etapa seguinte pode localizar o mesmo documento com `name: "{documento}"`.
+
 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
@@ -166,9 +234,11 @@ Exemplos para controles legados sem nome acessível:
 O reconhecimento retorna `unnamed_controls_initial` e
 `unnamed_controls_final`, cada um com papel, índice Playwright por papel, rótulo
 mais próximo e um trecho HTML sanitizado dos controles visíveis e habilitados
-sem nome. `unnamed_controls` continua disponível como alias da lista final. O
-placeholder conta como nome acessível. O snapshot também resume campos de
-formulário com `id`, `name`, valor, estado
+sem nome. Nomes vazios ou compostos apenas por espaços e glyphs da área Unicode
+de uso privado (como ícones Font Awesome) entram nessa lista e podem ser
+selecionados com `name: ""` e o mesmo índice. `unnamed_controls` continua
+disponível como alias da lista final. O placeholder conta como nome acessível.
+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
@@ -331,9 +401,9 @@ confiança do Jev não substitui essa verificação. `timings_ms.ready_ms` mede
 espera da SPA; `warnings` registra capturas vazias durante transições; e
 `failed_step` identifica índice, ação, localizador, timeout e erro resumido
 quando uma etapa falha. Cada etapa executada também registra a composição do
-localizador usado e, quando disponível, `resolved_target` com tag, `id`, papel
-e nome acessível do elemento resolvido. Etapas `type` só incluem o valor final
-do campo quando `sensitive: false`.
+localizador usado e, quando disponível, `resolved_target` com tag, `id`, papel,
+nome acessível, `title` casado e `href` sanitizado do elemento resolvido.
+Etapas `type` só incluem o valor final do campo quando `sensitive: false`.
 
 Com `capture_network_error_bodies: true`, respostas JSON de erro da mesma
 origem são capturadas mesmo quando usam transferência chunked e não enviam
@@ -358,7 +428,8 @@ 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`,
-`trace_on_failure`, `snapshot_include_hidden` e `stop_on_expected`. Sem override,
+`trace_on_failure`, `snapshot_include_hidden`, `stop_on_expected`, `dry_run` e
+`report_path`. 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
@@ -386,7 +457,21 @@ com o Trace Viewer do Playwright e retorna `trace_path`. O diretório padrão é
 `~/.cache/orquestrador/jev-browser-artifacts`; `JEV_BROWSER_ARTIFACT_DIR` pode
 substituí-lo por uma pasta absoluta fora do pacote. Screenshots e traces podem
 conter dados visíveis da aplicação: mantenha o diretório local protegido e
-compartilhe os arquivos somente se o teste permitir.
+compartilhe os arquivos somente se o teste permitir.
+
+Screenshots por etapa usam `screenshot: true` no próprio passo; o MCP os grava
+depois que a ação termina. `options.report_path` pode apontar para `.md` ou
+JUnit `.xml` dentro da raiz de artefatos. O relatório inclui a versão, tempos,
+localizadores resolvidos, respostas verificadas por `assert_network`, falhas de
+rede e caminhos dos screenshots, para anexar a um PR ou card.
+
+Se o Chrome/Edge não iniciar porque o perfil persistente já está aberto, o erro
+identifica o PID que o mantém ocupado quando o sistema consegue associar o
+perfil ao processo. Em Windows, o MCP consulta a linha de comando dos processos
+Chrome/Edge; em outros sistemas, usa o `SingletonLock` do Chromium. Configure
+`JEV_BROWSER_PROFILE` com outro diretório absoluto para usar uma sessão isolada.
+Resultados MCP incluem `server_version`; erros também começam com a versão do
+servidor para facilitar a comparação entre instalações.
 
 `harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
 `computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;

package/docs/jev-browser-mcp.md

@@ -17,7 +17,7 @@ versão em produção, use o número explícito no argumento do pacote:
   "mcpServers": {
     "jev-browser": {
       "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.4.0"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.5.0"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
         "JEV_BROWSER_MODE": "computer"
@@ -35,6 +35,18 @@ de configuração. Para instalar no projeto Node do próprio harness:
 npm install @diegosouzacdv/jev-browser-mcp
 ```
 
+Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
+fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cada
+inicialização:
+
+```sh
+npm install --global @diegosouzacdv/jev-browser-mcp@0.5.0
+```
+
+Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
+Para atualizar, rode `npm install --global
+@diegosouzacdv/jev-browser-mcp@<versão>` e reinicie o processo do harness.
+
 O padrão `computer` exige Chrome ou Edge instalado. Se optar por `harness`,
 configure `JEV_BROWSER_MODE=harness` antes de instalar o navegador gerenciado
 pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp --install-browser`.
@@ -95,15 +107,18 @@ Cada plano pode usar:
   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: {"row_containing":"..."}` para limitar por trecho e
+  `within: {"row_containing_exact":"..."}` para exigir um elemento com o
+  texto exato na linha, sem casar com `15287210` ao procurar `1528721`;
 - `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. O índice é
-  zero-based para o mesmo papel e segue o localizador Playwright
-  `{role, name: ""}`; controles desabilitados não aparecem no diagnóstico, mas
-  continuam contando para que o índice aponte ao controle correto;
+  zero-based para o mesmo papel e inclui nomes vazios ou compostos só por
+  espaços/glyphs de uso privado, como ícones Font Awesome; controles
+  desabilitados não aparecem no diagnóstico, mas continuam contando para que o
+  índice aponte ao controle correto;
 - `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;
@@ -113,8 +128,9 @@ Cada plano pode usar:
 - `wait_for_text` e `wait_for_condition` (`network_idle`, `hidden` ou
   `text_hidden`). `wait_for_text` aceita `fail_on: {"role":"alert"}` para
   interromper a espera assim que um alerta visível aparecer e incluir seu texto
-  no erro. `network_idle` aceita `url_contains` para aguardar só as requisições
-  correspondentes;
+  no erro. Se o alerta contiver o texto esperado, a etapa passa; caso contrário,
+  o alerta interrompe a espera. `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;
@@ -127,6 +143,58 @@ Cada plano pode usar:
   não repetem uma reação já no estado pedido e distinguem `Curtir` de
   `Descurtir`.
 
+As proteções e evidências por etapa usam estes campos:
+
+- `confirm_dialog` recebe `expected_text` e `button`. O MCP exige um diálogo
+  visível único e confere se ele contém o texto esperado antes de clicar; se o
+  alerta mudou, a etapa falha sem clicar no botão. Reserve `click` comum para
+  ações que não dependem do conteúdo de uma confirmação;
+- `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
+  Com `options.dry_run: true`, o fluxo para imediatamente antes da primeira
+  etapa marcada e retorna `dry_run_stopped_before_step` e `mutating_steps`.
+  Marque toda ação que grava ou envia algo, mesmo quando não for um botão
+  chamado Salvar;
+- `duration_ms` aparece em cada etapa concluída ou falha. `mutating_steps`
+  lista as etapas marcadas e informa quais foram executadas;
+- `screenshot: true` salva uma captura depois da etapa e inclui seu caminho na
+  evidência da etapa;
+- `options.report_path` grava um resumo `.md` ou JUnit `.xml`. O caminho deve
+  ser absoluto e estar dentro de `JEV_BROWSER_ARTIFACT_DIR` (ou do diretório de
+  artefatos configurado). O relatório resume versão/status, duração, alvo e
+  `resolved_target`, asserções de rede, falhas de rede e caminhos das capturas.
+
+`run_browser_flow` também aceita `params` como mapa de texto, números e
+booleanos. Use `{pedido}` em `flow`, `expected_outcome` e nos campos textuais do
+plano para reutilizar um valor sem editar o roteiro em vários lugares. A ação
+`extract` lê `text` (padrão), `value` ou `attribute` de um elemento e salva o
+resultado na variável indicada por `as`; etapas seguintes podem usar
+`{documento}`. O valor extraído é tratado como sensível e fica oculto no
+resultado por padrão; use `sensitive: false` só quando for apropriado exibi-lo.
+`resolved_target.match_strategy` informa quando um rótulo foi
+associado por proximidade (`label-proximity`) em vez de um `label[for]` direto.
+
+A ação `assert_network` verifica respostas observadas depois da etapa anterior,
+incluindo respostas 2xx ou erros esperados como 404. Exemplo:
+
+```json
+{
+  "action": "assert_network",
+  "url_contains": "/documentoFinanceiro/atualizar",
+  "method": "PUT",
+  "status": 404,
+  "message_contains": "Boleto não encontrado"
+}
+```
+
+Essa asserção aparece na evidência como `response_status`, separado do campo
+`status` da etapa (`passed` ou `failed`). `message_contains` lê somente resposta
+da mesma origem e respeita o limite configurado para captura de corpos.
+
+Exemplo de parâmetro e extração: passe `params: {"pedido":"1528721"}`, filtre
+com `within: {"row_containing_exact":"{pedido}"}`, e use uma etapa
+`{"action":"extract","role":"cell","name":"{pedido}","within":{"row_containing_exact":"{pedido}"},"as":"documento"}`.
+A etapa seguinte pode localizar o mesmo documento com `name: "{documento}"`.
+
 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
@@ -166,9 +234,11 @@ Exemplos para controles legados sem nome acessível:
 O reconhecimento retorna `unnamed_controls_initial` e
 `unnamed_controls_final`, cada um com papel, índice Playwright por papel, rótulo
 mais próximo e um trecho HTML sanitizado dos controles visíveis e habilitados
-sem nome. `unnamed_controls` continua disponível como alias da lista final. O
-placeholder conta como nome acessível. O snapshot também resume campos de
-formulário com `id`, `name`, valor, estado
+sem nome. Nomes vazios ou compostos apenas por espaços e glyphs da área Unicode
+de uso privado (como ícones Font Awesome) entram nessa lista e podem ser
+selecionados com `name: ""` e o mesmo índice. `unnamed_controls` continua
+disponível como alias da lista final. O placeholder conta como nome acessível.
+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
@@ -331,9 +401,9 @@ confiança do Jev não substitui essa verificação. `timings_ms.ready_ms` mede
 espera da SPA; `warnings` registra capturas vazias durante transições; e
 `failed_step` identifica índice, ação, localizador, timeout e erro resumido
 quando uma etapa falha. Cada etapa executada também registra a composição do
-localizador usado e, quando disponível, `resolved_target` com tag, `id`, papel
-e nome acessível do elemento resolvido. Etapas `type` só incluem o valor final
-do campo quando `sensitive: false`.
+localizador usado e, quando disponível, `resolved_target` com tag, `id`, papel,
+nome acessível, `title` casado e `href` sanitizado do elemento resolvido.
+Etapas `type` só incluem o valor final do campo quando `sensitive: false`.
 
 Com `capture_network_error_bodies: true`, respostas JSON de erro da mesma
 origem são capturadas mesmo quando usam transferência chunked e não enviam
@@ -358,7 +428,8 @@ 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`,
-`trace_on_failure`, `snapshot_include_hidden` e `stop_on_expected`. Sem override,
+`trace_on_failure`, `snapshot_include_hidden`, `stop_on_expected`, `dry_run` e
+`report_path`. 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
@@ -386,7 +457,21 @@ com o Trace Viewer do Playwright e retorna `trace_path`. O diretório padrão é
 `~/.cache/orquestrador/jev-browser-artifacts`; `JEV_BROWSER_ARTIFACT_DIR` pode
 substituí-lo por uma pasta absoluta fora do pacote. Screenshots e traces podem
 conter dados visíveis da aplicação: mantenha o diretório local protegido e
-compartilhe os arquivos somente se o teste permitir.
+compartilhe os arquivos somente se o teste permitir.
+
+Screenshots por etapa usam `screenshot: true` no próprio passo; o MCP os grava
+depois que a ação termina. `options.report_path` pode apontar para `.md` ou
+JUnit `.xml` dentro da raiz de artefatos. O relatório inclui a versão, tempos,
+localizadores resolvidos, respostas verificadas por `assert_network`, falhas de
+rede e caminhos dos screenshots, para anexar a um PR ou card.
+
+Se o Chrome/Edge não iniciar porque o perfil persistente já está aberto, o erro
+identifica o PID que o mantém ocupado quando o sistema consegue associar o
+perfil ao processo. Em Windows, o MCP consulta a linha de comando dos processos
+Chrome/Edge; em outros sistemas, usa o `SingletonLock` do Chromium. Configure
+`JEV_BROWSER_PROFILE` com outro diretório absoluto para usar uma sessão isolada.
+Resultados MCP incluem `server_version`; erros também começam com a versão do
+servidor para facilitar a comparação entre instalações.
 
 `harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
 `computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;