@diegosouzacdv/jev-browser-mcp 0.1.2 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +95 -81
- package/config/ui-testing.json +37 -0
- package/docs/jev-browser-mcp.md +350 -192
- package/mcp_servers/jev-browser-npm/bin/jev-browser-mcp.cjs +4 -3
- package/mcp_servers/jev-browser-npm/src/accessibility.mjs +38 -0
- package/mcp_servers/jev-browser-npm/src/config.mjs +128 -15
- package/mcp_servers/jev-browser-npm/src/flow.mjs +888 -125
- package/mcp_servers/jev-browser-npm/src/server.mjs +5 -3
- package/package.json +2 -1
package/docs/jev-browser-mcp.md
CHANGED
|
@@ -1,192 +1,350 @@
|
|
|
1
|
-
# Automação de tela com Jev e Playwright
|
|
2
|
-
|
|
3
|
-
## Instalar em outros harnesses com npm/npx
|
|
4
|
-
|
|
5
|
-
O repositório também contém um pacote Node independente do harness. Ele fala
|
|
6
|
-
MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
|
|
7
|
-
qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
|
|
8
|
-
usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
|
|
9
|
-
Python do orquestrador.
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
"
|
|
20
|
-
"
|
|
21
|
-
|
|
22
|
-
"
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
do
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
um
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
O
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
}
|
|
108
|
-
}
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
`browser.
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
`
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
1
|
+
# Automação de tela com Jev e Playwright
|
|
2
|
+
|
|
3
|
+
## Instalar em outros harnesses com npm/npx
|
|
4
|
+
|
|
5
|
+
O repositório também contém um pacote Node independente do harness. Ele fala
|
|
6
|
+
MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
|
|
7
|
+
qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
|
|
8
|
+
usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
|
|
9
|
+
Python do orquestrador. As opções específicas do pacote ficam isoladas no
|
|
10
|
+
bloco `jev_browser_mcp` para preservar o contrato do servidor Python.
|
|
11
|
+
|
|
12
|
+
Instale a versão publicada do npm diretamente no harness. Para fixar uma
|
|
13
|
+
versão em produção, use o número explícito no argumento do pacote:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"mcpServers": {
|
|
18
|
+
"jev-browser": {
|
|
19
|
+
"command": "npx",
|
|
20
|
+
"args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.3.0"],
|
|
21
|
+
"env": {
|
|
22
|
+
"OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
|
|
23
|
+
"JEV_BROWSER_MODE": "harness"
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
O formato de interpolação de variáveis varia por harness. Injete a chave por
|
|
31
|
+
um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
|
|
32
|
+
de configuração. Para instalar no projeto Node do próprio harness:
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
npm install @diegosouzacdv/jev-browser-mcp
|
|
36
|
+
npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
No modo `harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright
|
|
40
|
+
controlará. No modo `computer`, o pacote abre o Chrome/Edge instalado e usa um
|
|
41
|
+
perfil persistente exclusivo em `browser.computer_user_data_dir`; personalize
|
|
42
|
+
as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
|
|
43
|
+
`JEV_BROWSER_PROFILE`. O browser permanece aquecido enquanto o processo MCP
|
|
44
|
+
estiver ativo e fecha quando o harness encerra o processo. `JEV_PROVIDER_URL`
|
|
45
|
+
e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
|
|
46
|
+
nome de variável declarado em `jev.credential_env`.
|
|
47
|
+
|
|
48
|
+
Uma aplicação Node também pode importar `createJevBrowserServer` por
|
|
49
|
+
`@diegosouzacdv/jev-browser-mcp/server` e conectar o servidor ao transporte MCP
|
|
50
|
+
que ela já utiliza.
|
|
51
|
+
|
|
52
|
+
O pacote é montado pela raiz do repositório, mas o campo `files` do `package.json`
|
|
53
|
+
inclui somente o código Node, a configuração compartilhada e esta documentação
|
|
54
|
+
(além do README que o npm inclui automaticamente). Ele não publica o restante
|
|
55
|
+
do orquestrador. A instalação por npm é a recomendada; use a referência GitHub
|
|
56
|
+
somente quando precisar experimentar uma revisão ainda não publicada.
|
|
57
|
+
|
|
58
|
+
### Contrato do pacote
|
|
59
|
+
|
|
60
|
+
O executável oferece `choose_next_action` e `run_browser_flow`, mantém uma
|
|
61
|
+
sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
|
|
62
|
+
passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
|
|
63
|
+
hover, espera, teclas aprovadas, asserções por elemento, upload restrito a uma
|
|
64
|
+
raiz local configurada e reações idempotentes a um comentário único. Também
|
|
65
|
+
aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
|
|
66
|
+
JavaScript enviado pelo harness, seletores livres nem coordenadas. Ele usa a
|
|
67
|
+
biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
|
|
68
|
+
Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
|
|
69
|
+
`stderr` para não misturar com JSON-RPC.
|
|
70
|
+
|
|
71
|
+
O modo `computer` grava cookies no perfil exclusivo configurado, e conteúdo da
|
|
72
|
+
página pode conter instruções maliciosas. O Jev recebe a captura acessível com
|
|
73
|
+
uma instrução para tratar esse conteúdo como dado não confiável; não inclua
|
|
74
|
+
segredos no fluxo, no resultado esperado ou nas descrições dos planos.
|
|
75
|
+
|
|
76
|
+
Para um fluxo conhecido, o LLM do harness procura o cenário e os critérios de
|
|
77
|
+
aceitação no projeto e chama `jev_browser.run_browser_flow` com planos
|
|
78
|
+
candidatos declarativos. O MCP abre uma única sessão do Playwright, navega para
|
|
79
|
+
a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
|
|
80
|
+
plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
|
|
81
|
+
resultado esperado na tela.
|
|
82
|
+
|
|
83
|
+
Cada plano pode usar:
|
|
84
|
+
|
|
85
|
+
- `click`, `type`, `hover` e `select_option` com papel/nome acessível exatos;
|
|
86
|
+
- `wait_for_text` e `wait_for_condition` (`network_idle`, limitado pelo timeout
|
|
87
|
+
de ação configurado);
|
|
88
|
+
- `press_key` com `PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`,
|
|
89
|
+
`Enter`, `Escape` ou `Tab`;
|
|
90
|
+
- `assert_text`, `assert_value`, `assert_visible` e `assert_hidden`;
|
|
91
|
+
- `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
|
|
92
|
+
dropzone;
|
|
93
|
+
- `audit_accessibility` com axe-core para WCAG 2.1 A/AA;
|
|
94
|
+
- `like_comment` e `unlike_comment`, que localizam uma linha pelo autor e texto,
|
|
95
|
+
não repetem uma reação já no estado pedido e distinguem `Curtir` de
|
|
96
|
+
`Descurtir`.
|
|
97
|
+
|
|
98
|
+
Quando vários controles têm o mesmo papel e nome, `within` limita a busca a um
|
|
99
|
+
container acessível único, como uma linha ou card. `index` escolhe uma ocorrência
|
|
100
|
+
zero-based dentro desse escopo; sem `index`, o MCP exige exatamente um alvo.
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"action": "click",
|
|
105
|
+
"role": "button",
|
|
106
|
+
"name": "Add to cart",
|
|
107
|
+
"within": {"role": "group", "name": "Sauce Labs Backpack"}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{"action":"click","role":"button","name":"Add to cart","index":0}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Captura de downloads
|
|
116
|
+
|
|
117
|
+
Marque o clique que deve iniciar um download com `expect_download: true`. O
|
|
118
|
+
Playwright começa a aguardar o evento antes do clique; após a transferência
|
|
119
|
+
terminar, o MCP verifica o tamanho, sanitiza o nome sugerido e copia o arquivo
|
|
120
|
+
para `JEV_BROWSER_ARTIFACT_DIR` (ou para o diretório de artefatos configurado).
|
|
121
|
+
O resultado inclui a lista `downloaded_files`, com nome, caminho local e bytes;
|
|
122
|
+
cada passo também contém o arquivo capturado. Os limites contam arquivos e bytes
|
|
123
|
+
por fluxo. A checagem de tamanho acontece depois da transferência do navegador,
|
|
124
|
+
antes de copiar para a pasta de artefatos.
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{"action":"click","role":"button","name":"Export report","expect_download":true}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`jev_browser_mcp.browser.max_download_files`, `max_download_file_bytes`,
|
|
131
|
+
`max_download_total_bytes` e `max_download_timeout_seconds` definem os limites.
|
|
132
|
+
O diretório de artefatos deve ser local e protegido: arquivos baixados podem
|
|
133
|
+
conter dados da aplicação.
|
|
134
|
+
|
|
135
|
+
### Auditoria automatizada de acessibilidade
|
|
136
|
+
|
|
137
|
+
Use `audit_accessibility` depois de colocar a página no estado que deseja
|
|
138
|
+
verificar:
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{"action":"audit_accessibility","standard":"wcag2aa"}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
O MCP usa `@axe-core/playwright` com as tags WCAG 2.0 e 2.1 A/AA. O retorno
|
|
145
|
+
resume as violações por regra, impacto e quantidade de nós, sem copiar HTML ou
|
|
146
|
+
trechos da página. Qualquer violação reprova esse fluxo. A auditoria automática
|
|
147
|
+
encontra problemas comuns, mas não comprova conformidade WCAG completa; combine-a
|
|
148
|
+
com revisão manual e testes com usuários assistivos.
|
|
149
|
+
|
|
150
|
+
Para ações em iframe, acrescente `"frame": "payment-iframe"`; o valor precisa
|
|
151
|
+
corresponder ao atributo `name` ou `title` do iframe. O snapshot inclui o
|
|
152
|
+
conteúdo acessível dos iframes nomeados dentro do escopo, limitado pela
|
|
153
|
+
configuração. Se um alvo estiver ausente, o erro inclui até três nomes acessíveis
|
|
154
|
+
próximos quando o snapshot os encontrar. O plano não aceita JavaScript enviado
|
|
155
|
+
pelo harness, coordenadas ou seletores livres.
|
|
156
|
+
|
|
157
|
+
Os aliases `value` → `text` em `type`/`wait_for_text` e `value` → `expected` em
|
|
158
|
+
asserções são aceitos. `comment` também é aceito em planos e passos, mas é
|
|
159
|
+
ignorado e não é enviado ao Jev. Campos fora do contrato continuam sendo
|
|
160
|
+
recusados.
|
|
161
|
+
|
|
162
|
+
### Upload de arquivos
|
|
163
|
+
|
|
164
|
+
Defina `JEV_BROWSER_UPLOAD_ROOT` como uma pasta absoluta que contenha os arquivos
|
|
165
|
+
de fixture. Cada caminho passado ao fluxo também precisa ser absoluto; o MCP
|
|
166
|
+
resolve links simbólicos e recusa qualquer arquivo fora dessa raiz. Só aceita
|
|
167
|
+
arquivos regulares, até 5 arquivos por passo, 10 MiB por arquivo e 25 MiB no
|
|
168
|
+
total do passo, conforme `jev_browser_mcp.browser` em `config/ui-testing.json`.
|
|
169
|
+
Os bytes são lidos e validados no processo local antes de serem entregues ao
|
|
170
|
+
Playwright. O MCP não envia esses bytes ao Jev nem os inclui diretamente na
|
|
171
|
+
resposta; texto que o próprio site exibir na interface ainda pode aparecer no
|
|
172
|
+
snapshot devolvido ao harness.
|
|
173
|
+
|
|
174
|
+
```json
|
|
175
|
+
{"action":"upload_file","target":"input","label":"Nota fiscal","file_path":"/fixtures/nota.pdf"}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Para uma área de arrastar, use o papel e o nome acessível da dropzone. Para um
|
|
179
|
+
botão que abre a janela nativa, use `target: "button"`; sem `target`, a presença
|
|
180
|
+
de `label` seleciona o input e `role`/`name` seleciona esse botão.
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{"action":"upload_file","target":"dropzone","role":"region","name":"Anexos","file_paths":["/fixtures/a.pdf","/fixtures/b.png"]}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Se `JEV_BROWSER_UPLOAD_ROOT` não estiver definido, a ação recusa a execução. O
|
|
187
|
+
limite evita que um plano transforme o MCP em leitor arbitrário de arquivos do
|
|
188
|
+
computador.
|
|
189
|
+
|
|
190
|
+
Exemplo de chamada:
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"flow": "Adicionar o produto ao carrinho e confirmar o resumo",
|
|
195
|
+
"initial_url": "http://127.0.0.1:4173/products/coffee",
|
|
196
|
+
"expected_outcome": "Coffee added to cart",
|
|
197
|
+
"options": {
|
|
198
|
+
"fast_path": true,
|
|
199
|
+
"snapshot_scope": "main",
|
|
200
|
+
"capture_network_errors": true,
|
|
201
|
+
"screenshot_on_failure": true
|
|
202
|
+
},
|
|
203
|
+
"candidate_plans": {
|
|
204
|
+
"add_and_confirm": {
|
|
205
|
+
"description": "Adicionar o produto visível ao carrinho e abrir o resumo",
|
|
206
|
+
"steps": [
|
|
207
|
+
{"action": "click", "role": "button", "name": "Add to cart"},
|
|
208
|
+
{"action": "wait_for_text", "text": "Coffee added to cart"},
|
|
209
|
+
{"action": "click", "role": "link", "name": "View cart"},
|
|
210
|
+
{"action": "assert_text", "role": "heading", "name": "Order summary", "expected": "Coffee"}
|
|
211
|
+
]
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
O plano é montado pelo LLM do harness, mas o Jev escolhe qual plano fornecido
|
|
218
|
+
deve executar usando o fluxo e o snapshot inicial. O Jev não cria ações, nomes
|
|
219
|
+
de controles ou valores de formulário. Valores de `type` são usados localmente
|
|
220
|
+
pelo Playwright e são removidos do texto enviado ao provedor e da evidência de
|
|
221
|
+
retorno. Use valores de teste; autenticação deve ficar no perfil de navegador
|
|
222
|
+
configurado.
|
|
223
|
+
|
|
224
|
+
O MCP também mantém `choose_next_action` para fluxos exploratórios em que o
|
|
225
|
+
harness precisa inspecionar e decidir entre ações uma por vez. Esse caminho é
|
|
226
|
+
mais lento porque exige uma nova decisão e uma nova chamada de ferramenta por
|
|
227
|
+
ação; prefira `run_browser_flow` quando os passos esperados puderem ser
|
|
228
|
+
descritos antes da execução.
|
|
229
|
+
|
|
230
|
+
## Configuração
|
|
231
|
+
|
|
232
|
+
Edite `config/ui-testing.json`. URL, modelo do provedor, variável de credencial
|
|
233
|
+
e limites compartilhados ficam nos blocos `browser` e `jev`. As opções próprias
|
|
234
|
+
do pacote Node ficam no bloco opcional `jev_browser_mcp`, que não altera o
|
|
235
|
+
contrato lido pelo servidor Python. Preserve a estrutura completa exigida pelos
|
|
236
|
+
validadores.
|
|
237
|
+
|
|
238
|
+
`browser.mode` aceita `harness` ou `computer`:
|
|
239
|
+
|
|
240
|
+
- `harness` usa Chrome headless e perfil isolado, adequado a execuções do
|
|
241
|
+
harness e CI; o estado de autenticação é descartado ao final da chamada.
|
|
242
|
+
- `computer` abre o Chrome ou Edge instalado em modo visível e usa o diretório
|
|
243
|
+
persistente `browser.computer_user_data_dir`, separado por navegador. Não
|
|
244
|
+
reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
|
|
245
|
+
cookies permanecem nele entre chamadas.
|
|
246
|
+
|
|
247
|
+
`browser.max_flow_steps` limita a soma de passos declarados entre os planos e
|
|
248
|
+
`browser.max_text_entry_chars` limita cada valor digitado. O resultado contém
|
|
249
|
+
`status`, o plano escolhido, as ações executadas, a última captura acessível e
|
|
250
|
+
se o critério esperado apareceu. Quando existem asserções explícitas, `status`
|
|
251
|
+
também pode ser `passed` com todas elas satisfeitas; `assertions_passed` registra
|
|
252
|
+
esse resultado e `expected_outcome_visible` continua descrevendo somente o
|
|
253
|
+
texto global. `incomplete` significa que nenhum critério foi comprovado;
|
|
254
|
+
confiança do Jev não substitui essa verificação.
|
|
255
|
+
|
|
256
|
+
`jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
|
|
257
|
+
seletores e condições. `JEV_BROWSER_UPLOAD_ROOT` libera uploads somente dentro
|
|
258
|
+
de uma pasta absoluta escolhida pelo operador.
|
|
259
|
+
`jev_browser_mcp.browser.max_upload_files`, `max_upload_path_chars`,
|
|
260
|
+
`max_upload_file_bytes` e `max_upload_total_bytes` limitam quantidade e tamanho.
|
|
261
|
+
Não configure a raiz como o disco inteiro ou a pasta home: use uma pasta de
|
|
262
|
+
fixtures dedicada.
|
|
263
|
+
|
|
264
|
+
Os limites de download ficam no mesmo bloco: `max_download_files`,
|
|
265
|
+
`max_download_file_bytes`, `max_download_total_bytes` e
|
|
266
|
+
`max_download_timeout_seconds`. `jev_browser_mcp.jev.max_accessibility_violations`
|
|
267
|
+
limita quantas descrições de violações axe entram no resultado; a contagem total
|
|
268
|
+
continua informada mesmo quando a lista é truncada.
|
|
269
|
+
|
|
270
|
+
O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
|
|
271
|
+
`block_trackers`, `capture_console_errors`, `capture_network_errors`,
|
|
272
|
+
`screenshot_on_failure` e `trace_on_failure`. Sem override, os padrões são lidos
|
|
273
|
+
de `jev_browser_mcp` em `config/ui-testing.json`: um plano candidato pula a chamada Decisions;
|
|
274
|
+
captura de console e screenshot de falha ficam ligadas; trace, rede e bloqueio
|
|
275
|
+
de recursos ficam desligados. `snapshot_scope` aceita `body`, `main` ou `dialog`.
|
|
276
|
+
|
|
277
|
+
`block_trackers: true` bloqueia os domínios e tipos de recurso listados na
|
|
278
|
+
configuração (analytics, Hotjar, fontes externas e mídia). Isso pode alterar o
|
|
279
|
+
layout ou o comportamento do site, então a opção é desligada por padrão.
|
|
280
|
+
|
|
281
|
+
Com `capture_console_errors` e `capture_network_errors`, o retorno traz
|
|
282
|
+
`console_errors` e `network_failures`, limitados em quantidade e tamanho.
|
|
283
|
+
Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
|
|
284
|
+
fragmentos, valores de formulário e nomes de arquivo são removidos ou
|
|
285
|
+
sanitizados. Em falhas, `screenshot_on_failure` salva screenshot local e retorna
|
|
286
|
+
`screenshot_path`. `trace_on_failure: true` também grava um `.zip` compatível
|
|
287
|
+
com o Trace Viewer do Playwright e retorna `trace_path`. O diretório padrão é
|
|
288
|
+
`~/.cache/orquestrador/jev-browser-artifacts`; `JEV_BROWSER_ARTIFACT_DIR` pode
|
|
289
|
+
substituí-lo por uma pasta absoluta fora do pacote. Screenshots e traces podem
|
|
290
|
+
conter dados visíveis da aplicação: mantenha o diretório local protegido e
|
|
291
|
+
compartilhe os arquivos somente se o teste permitir.
|
|
292
|
+
|
|
293
|
+
`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
|
|
294
|
+
`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;
|
|
295
|
+
o diretório persistente armazena dados de login e é resolvido sob a pasta home
|
|
296
|
+
do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
|
|
297
|
+
`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
|
|
298
|
+
|
|
299
|
+
Defina o valor secreto na variável indicada por `jev.credential_env`, usando o
|
|
300
|
+
secret manager ou ambiente do processo que inicia o harness. Não grave a chave
|
|
301
|
+
em `config/ui-testing.json`. `provider_url` é o endpoint HTTPS completo da API
|
|
302
|
+
Decisions. O cliente não
|
|
303
|
+
segue redirects e recusa URL com credencial, query string ou fragmento. O Jev
|
|
304
|
+
fica indisponível quando a política de MCP está em modo offline.
|
|
305
|
+
|
|
306
|
+
Na primeira execução, aqueça uma vez o cache local do pacote declarado em
|
|
307
|
+
`browser.playwright_mcp_package` com `npx --yes <pacote> --help`. O MCP inicia
|
|
308
|
+
depois com `--offline`, evitando uma consulta ao registry npm em cada fluxo.
|
|
309
|
+
Quando a versão configurada mudar, aqueça o novo pacote uma vez.
|
|
310
|
+
|
|
311
|
+
## Desempenho e evidência
|
|
312
|
+
|
|
313
|
+
O pacote Node usa a decisão remota do Jev para escolher entre múltiplos planos.
|
|
314
|
+
Com exatamente um plano e `fast_path` ligado (padrão), executa esse plano sem
|
|
315
|
+
chamar a API Decisions; `jev_decisions` fica em zero. Inclua o fluxo completo em
|
|
316
|
+
um plano candidato para evitar chamadas separadas ao harness; seleção,
|
|
317
|
+
navegação, ações e asserções ficam em uma chamada MCP. O servidor Python
|
|
318
|
+
`mcp_servers/jev_browser_server.py` mantém seu fluxo próprio e usa uma decisão
|
|
319
|
+
remota do Jev por chamada. A sessão Playwright fecha antes de o MCP Python
|
|
320
|
+
retornar. O perfil do modo `computer` preserva o login para chamadas seguintes;
|
|
321
|
+
nesse servidor o processo e a janela não são reutilizados. O pacote Node mantém
|
|
322
|
+
o browser aquecido até o harness encerrar o processo. O snapshot enviado ao Jev
|
|
323
|
+
e devolvido ao harness remove o rodapé e, se ainda exceder o limite, mantém o
|
|
324
|
+
início e o fim da captura com um marcador de truncamento. `snapshot_scope` pode
|
|
325
|
+
limitar a captura a `main` ou `dialog`; iframes nomeados contidos nesse escopo
|
|
326
|
+
também podem ser incluídos.
|
|
327
|
+
|
|
328
|
+
A chamada composta aquecida deve ficar dentro da meta de 20 segundos em páginas
|
|
329
|
+
que respondem normalmente; a inicialização fria, páginas lentas, MFA e conteúdo
|
|
330
|
+
sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
|
|
331
|
+
`navigation_ms`, `initial_snapshot_ms`, `jev_decision_ms` e `browser_plan_ms`
|
|
332
|
+
para localizar o custo. O teto observado em um fluxo sintético local anterior
|
|
333
|
+
foi 6,411 s; isso não mede o Instagram nem garante o mesmo tempo em outros sites.
|
|
334
|
+
|
|
335
|
+
O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
|
|
336
|
+
são enviados ao endpoint Decisions quando há mais de uma opção. Com fast-path,
|
|
337
|
+
um plano não gera chamada remota. Os passos, valores digitados, valores
|
|
338
|
+
esperados pelas asserções, caminhos e conteúdo dos arquivos não são enviados.
|
|
339
|
+
Não inclua segredos em `flow`, `expected_outcome` ou nas descrições. A resposta
|
|
340
|
+
retorna o plano escolhido quando houver decisão, custo/confiança do provedor
|
|
341
|
+
quando disponíveis e o snapshot final sanitizado. O fluxo passa quando o texto
|
|
342
|
+
esperado aparece no snapshot ou quando todas as asserções declaradas passam.
|
|
343
|
+
|
|
344
|
+
`network_idle` é uma espera limitada e opcional; páginas com polling ou conexões
|
|
345
|
+
contínuas podem atingir o timeout. Prefira `wait_for_text` e asserções de
|
|
346
|
+
elemento quando houver um sinal de interface específico.
|
|
347
|
+
|
|
348
|
+
Consulte a [introdução do Jev](https://docs.typesafe.ai/introduction) e o
|
|
349
|
+
[tutorial da API Decisions no OpenRouter](https://openrouter.ai/docs/guides/community/jev-tutorial)
|
|
350
|
+
para os tipos de resposta e autenticação.
|
|
@@ -9,9 +9,10 @@ Usage:
|
|
|
9
9
|
Install the configured browser for harness mode
|
|
10
10
|
jev-browser-mcp --help Show this help
|
|
11
11
|
|
|
12
|
-
Configuration is read from config/ui-testing.json. Set OPENROUTER_API_KEY in
|
|
13
|
-
the environment and use JEV_BROWSER_MODE=harness or computer to choose a browser.
|
|
14
|
-
|
|
12
|
+
Configuration is read from config/ui-testing.json. Set OPENROUTER_API_KEY in
|
|
13
|
+
the environment and use JEV_BROWSER_MODE=harness or computer to choose a browser.
|
|
14
|
+
For upload_file, set JEV_BROWSER_UPLOAD_ROOT to a dedicated fixture directory.
|
|
15
|
+
`;
|
|
15
16
|
|
|
16
17
|
async function main() {
|
|
17
18
|
const args = process.argv.slice(2);
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { JevBrowserError } from "./config.mjs";
|
|
2
|
+
|
|
3
|
+
export const ACCESSIBILITY_STANDARDS = Object.freeze({
|
|
4
|
+
wcag2aa: Object.freeze(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]),
|
|
5
|
+
});
|
|
6
|
+
|
|
7
|
+
export async function runAccessibilityAudit(page, standard, settings) {
|
|
8
|
+
const tags = ACCESSIBILITY_STANDARDS[standard];
|
|
9
|
+
if (!tags) throw new JevBrowserError("audit_accessibility standard must be wcag2aa");
|
|
10
|
+
|
|
11
|
+
let AxeBuilder;
|
|
12
|
+
try {
|
|
13
|
+
({ default: AxeBuilder } = await import("@axe-core/playwright"));
|
|
14
|
+
} catch {
|
|
15
|
+
throw new JevBrowserError("accessibility auditing requires the installed @axe-core/playwright dependency");
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
let results;
|
|
19
|
+
try {
|
|
20
|
+
results = await new AxeBuilder({ page }).withTags([...tags]).analyze();
|
|
21
|
+
} catch {
|
|
22
|
+
throw new JevBrowserError("axe-core could not complete the accessibility audit");
|
|
23
|
+
}
|
|
24
|
+
const violations = Array.isArray(results?.violations) ? results.violations : [];
|
|
25
|
+
const incomplete = Array.isArray(results?.incomplete) ? results.incomplete : [];
|
|
26
|
+
return {
|
|
27
|
+
standard,
|
|
28
|
+
violations_count: violations.length,
|
|
29
|
+
violations_truncated: violations.length > settings.jev.maxAccessibilityViolations,
|
|
30
|
+
violations: violations.slice(0, settings.jev.maxAccessibilityViolations).map((violation) => ({
|
|
31
|
+
id: String(violation.id || "unknown").slice(0, 100),
|
|
32
|
+
impact: ["minor", "moderate", "serious", "critical"].includes(violation.impact) ? violation.impact : null,
|
|
33
|
+
help: String(violation.help || "").slice(0, settings.jev.maxDiagnosticChars),
|
|
34
|
+
nodes_count: Array.isArray(violation.nodes) ? violation.nodes.length : 0,
|
|
35
|
+
})),
|
|
36
|
+
incomplete_count: incomplete.length,
|
|
37
|
+
};
|
|
38
|
+
}
|