agent-browser: como gravar a tela do navegador de 1 a 60 fps

Como escolher o FPS para gravar a tela do navegador

Comece com 30 fps. Esse é o novo padrão porque cliques comuns, estados de hover, rolagens, transições CSS e demonstrações continuam fáceis de acompanhar sem a carga adicional de 60 fps.

O intervalo válido de --fps vai de 1 a 60. Um número maior não produz automaticamente uma evidência melhor. Se a página redesenha a tela com menos frequência do que a taxa solicitada, pedir 60 fps não cria 60 estados de página realmente diferentes.

O que mudou no agent-browser v0.37.0

Agora, o gravador trata o vídeo como um registro temporal da página em uso. record start e record restart capturam a página ativa atual a 30 fps por padrão, aceitam --fps 1-60 e usam o Page.startScreencast do Chrome. É o próprio Chrome que fornece os quadros a cada redesenho da página — como ligar uma câmera diretamente ao pipeline de exibição do navegador, em vez de tirar capturas de tela de tempos em tempos.

O lançamento da v0.37.0 também tornou mais rígido o comportamento em caso de falha. Se o ffmpeg estiver ausente, o caminho de saída não tiver extensão ou uma opção de gravação for inválida, o comando falha antes de alterar o navegador ou o estado da gravação. Se uma gravação substituta não puder ser iniciada, a gravação em andamento é preservada. Navegar durante a gravação agora limpa referências antigas de elementos e o estado dos frames da mesma forma que uma navegação normal.

Isso faz diferença em um ciclo real de QA. Um caminho de vídeo inválido não deve mudar silenciosamente a página em teste, e começar uma segunda gravação não deve destruir a primeira antes de haver certeza de que a substituta funciona.

Fluxo de gravação em cinco etapas

A sequência confiável é verificar, abrir, gravar, validar e parar. O comando final faz parte do contrato da evidência, pois descarrega os dados pendentes e salva o arquivo.

agent-browser doctor
agent-browser open https://app.example.com/login
agent-browser record start ./login-flow.mp4 --fps 30
agent-browser snapshot -i
agent-browser click @e1
agent-browser wait --url "**/dashboard"
agent-browser record stop

1. Verifique primeiro o codificador. agent-browser doctor informa quais codificadores de gravação estão disponíveis no ffmpeg. Para MP4, é preciso ter libx264; para WebM, libvpx. Uma instalação padrão do ffmpeg pelo Homebrew ou no Debian/Ubuntu normalmente inclui ambos.

2. Deixe a página certa na aba ativa. Quando record start é usado sem URL, o gravador se conecta à página ativa exatamente no estado em que ela se encontra. Ele não recarrega a página, não abre outra aba nem cria um contexto limpo do navegador. Isso ajuda quando o bug depende de um aplicativo já hidratado, de uma sessão autenticada ou de um estado interno da página. Se uma URL for informada, a aba ativa navega primeiro e a gravação começa depois que a página carrega.

3. Escolha o contêiner pela extensão. .mp4 seleciona H.264 por meio de libx264; .webm seleciona VP8 por meio de libvpx. Outras extensões são enviadas ao ffmpeg com H.264 e só funcionam se o ffmpeg reconhecer o contêiner. Um nome de arquivo sem extensão é rejeitado.

4. Mantenha a verificação de aprovação ou falha na automação. No exemplo, wait --url confirma se o navegador chegou ao dashboard. O clipe ajuda uma pessoa a entender o que aconteceu, mas não transforma pixels em uma asserção de teste.

5. Pare antes de fechar. record stop salva a gravação e descarrega os dados pendentes. Encerrar a sessão primeiro pode deixar você sem o arquivo que pretendia guardar. Use record restart quando quiser concluir uma gravação e começar imediatamente a próxima na página ativa.

capturedFrames e frames respondem a perguntas diferentes

Leia os dois contadores como matéria-prima e vídeo finalizado. capturedFrames contabiliza os quadros distintos produzidos pela página. frames contabiliza os quadros gravados no arquivo de vídeo. Uma página estática pode gerar pouquíssimas imagens diferentes enquanto o ffmpeg repete quadros no arquivo para manter a reprodução contínua.

Há uma ressalva importante sobre a duração. Quando a página para de mudar, o último quadro fica retido. Um único intervalo estático é mantido por até cinco segundos; o restante desse período sem alterações é omitido. Na prática, o vídeo preserva pausas curtas, mas comprime longos períodos ociosos. Não use o tempo de reprodução como cronômetro de um soak test.

Por isso, uma contagem baixa em capturedFrames não indica automaticamente uma falha de gravação: a página pode simplesmente ter ficado parada. É também por isso que 60 fps deve ficar reservado para movimentos que mereçam inspeção. Segundo o guia de gravação, 60 fps praticamente dobra a taxa de bits de 30 fps, enquanto o total de quadros distintos ainda depende dos redesenhos da página.

O impacto no orçamento

Se a equipe já usa agent-browser, a evidência básica em vídeo não precisa mais começar com a compra de outra licença de gravador. O pacote v0.37.0 declara a licença Apache-2.0, portanto o gravador em si não cobra licença de software por usuário. Os custos incrementais ficam no que a equipe opera: configuração do ffmpeg, tempo de CI, armazenamento dos artefatos e os minutos que alguém dedica à revisão do resultado.

É uma conta bem diferente da compra de uma plataforma completa de feedback ou testes. O Jam Team anuncia $14 por criador ao mês no plano anual. O BugHerd Standard anuncia $50 por mês para cinco integrantes na cobrança mensal e inclui feedback em vídeo. O BrowserStack Automate anuncia uma execução paralela do Chrome Desktop por $59 ao mês, com cobrança anual, e inclui gravações de vídeo entre suas ferramentas de depuração.

Esses produtos oferecem muito mais do que gravação, então concluir que devem ser substituídos seria um erro. O BrowserStack oferece cobertura gerenciada de navegadores. BugHerd e Jam vendem colaboração, captura de problemas e integrações. A decisão de custo útil é mais estreita: não compre uma segunda camada de captura quando o agent-browser já executa o fluxo e o único artefato ausente é um vídeo fácil de analisar.

Sete casos de uso, em ordem de benefício

1. Equipes de produto investigando falhas em fluxos de CI

Uma equipe de produto com um teste instável de login ou checkout pode iniciar uma gravação a 30 fps logo antes do trecho arriscado, manter as asserções de URL ou elemento e guardar o MP4 como artefato de CI quando a execução falhar. O engenheiro passa a enxergar o banner de consentimento, o overlay atrasado, a mudança de foco ou a transição que um log em texto pode não registrar. O resultado é menos tempo de engenharia pago desperdiçado na tentativa de recriar um estado intermitente.

2. Equipes de front-end revisando arrastos, rolagens e animações

Um engenheiro de front-end pode isolar uma interação curta, capturá-la a 60 fps e combinar o clipe com screenshots dos estados inicial e final. O vídeo mostra se o movimento entre os dois estados foi limpo; as screenshots preservam os pixels exatos. Isso vale a pena quando o defeito existe entre duas capturas, como na perda de um quadro ou em um alvo de arrasto atravessado no momento errado.

3. Equipes de produtos de IA auditando agentes de navegador

Uma equipe de produto de IA pode gravar a página autenticada ativa a 30 fps enquanto o agente executa uma tarefa e anexar o vídeo ao lado do histórico de comandos e das asserções. Assim, quem revisa consegue separar um plano ruim de uma página que mudou durante a atuação do agente. Uma execução opaca vira uma evidência que o gerente de produto e o engenheiro podem discutir juntos.

4. Engenheiros de QA reproduzindo bugs que dependem de estado

Um engenheiro de QA pode preparar a sessão até que as condições do bug estejam presentes e só então executar record start sem uma URL. Como a gravação se conecta à página no lugar, ela não é substituída por uma navegação a frio. Isso compensa quando o bug depende do estado acumulado do carrinho, de um modal, de uma rota autenticada ou de outra condição que desaparece ao recarregar.

5. Agências entregando uma versão ao cliente

Uma agência web pode gravar um fluxo de aceite a 30 fps, inserir esperas curtas nos pontos de decisão e entregar ao cliente um clipe no ritmo de uma pessoa, não de um mecanismo de automação. O cliente revisa o caminho exato sem precisar acessar o executor de testes. A agência gasta menos tempo em reuniões narrando um fluxo que o próprio artefato já demonstra.

6. Equipes de confiabilidade preservando linhas do tempo de execuções longas

Um engenheiro de confiabilidade pode gravar um soak test longo a 10 fps quando a sequência importa mais que o movimento. A taxa menor reduz a sobrecarga da gravação e o crescimento do arquivo em comparação com 30 ou 60 fps. A gravação ainda ajuda a localizar o momento visível da falha, mas os intervalos estáticos comprimidos significam que os timestamps devem vir dos logs, não da duração da reprodução.

7. Engenheiros de suporte escalando um problema difícil no navegador

Um engenheiro de suporte pode reproduzir a jornada do cliente em uma conta controlada, gravá-la a 30 fps, encerrar a gravação e anexá-la ao escalonamento. A equipe de desenvolvimento recebe a sequência temporal e os overlays inesperados que costumam desaparecer em um chamado escrito. Isso só vale a pena se o fluxo também impedir que segredos e dados de clientes entrem na gravação.

Três produtos que valem a pena criar

Melhor oportunidade: um pacote de evidências gerado pelo agente

Crie um serviço enxuto que transforme uma execução do agente de navegador em um único pacote de revisão: resultado da asserção, histórico de comandos, screenshot final, MP4, contadores de quadros e um link publicado no Jira ou Linear. Equipes de produto e engenharia pagariam porque a saída se encaixa no fluxo de acompanhamento de problemas que elas já usam.

A demanda é concreta. Dados de palavras-chave dos EUA apontam cerca de 590 buscas mensais por “bug reporting tool”, com CPC de $43.80. Também há gastos visíveis no mercado: o Jam Team custa $14 por criador ao mês na cobrança anual, enquanto o BugHerd Standard custa $50 por mês na cobrança mensal. A menor versão comercializável precisa apenas de um wrapper para agent-browser, armazenamento de artefatos, uma integração com um sistema de acompanhamento de problemas e um checklist para ocultar dados sensíveis.

É a oportunidade mais forte porque vende o handoff, não o codec. O problema é a barreira técnica baixa. Publicar no Jira e armazenar vídeos são recursos fáceis de copiar; por isso, o produto precisa ser excepcional ao reunir contexto confiável e manter dados sensíveis fora dos artefatos.

Um portal de entrega de QA para agências

Crie uma página de revisão voltada ao cliente, na qual a agência escolhe um fluxo, executa-o no ambiente de staging e publica a asserção, as screenshots e o vídeo com ritmo adequado sob um único link de aprovação. Agências e equipes fracionadas de QA são o público comprador, porque a aprovação do cliente é o ponto em que evidências técnicas costumam virar uma reunião.

Dados de palavras-chave dos EUA indicam 110 buscas mensais por “website qa testing”, em alta de 55% em relação ao ano anterior, com CPC de $23.91. Um MVP poderia oferecer alguns fluxos reutilizáveis, captura a 30 fps, comentários e opções de aprovar ou rejeitar. O obstáculo é a profundidade dos concorrentes: o BugHerd já inclui projetos, usuários clientes, screenshots e metadados ilimitados, além de feedback em vídeo no plano Standard. O novo produto precisa vencer pela evidência gerada por agentes, não por oferecer mais um pin de comentário.

Uma camada de presets para testes de movimento

Crie uma ferramenta enxuta de CI que classifique os testes como timeline, default ou motion, associe-os a 10, 30 ou 60 fps e sinalize diferenças inesperadas entre quadros capturados e gravados. Equipes de plataforma front-end pagariam para manter evidências consistentes entre regressões de animação e interação.

Dados de palavras-chave dos EUA mostram 110 buscas mensais por “automated browser testing”, com CPC de $14.96. A expressão comercial mais específica, “automated browser testing tools”, registra apenas 20 buscas mensais, mas tem CPC de $63.21 — sinal de que custa caro alcançar esse pequeno grupo de compradores. O MVP é formado por um manifesto de testes, um wrapper de comandos do agent-browser, clipes retidos apenas nas falhas e um índice compacto de artefatos.

O ponto fraco é a perda de tração: o termo mais amplo caiu 18% em relação ao ano anterior, e 60 fps aumenta a sobrecarga sem deixar de depender da taxa de redesenho da página. A ideia deve começar como um recurso dentro de um produto de evidências, não como uma empresa independente.

O que a gravação não comprova

Vídeo oferece observabilidade; não comprova que o sistema está correto. Ele não informa se a linha certa foi gravada no banco de dados, se a resposta de uma API era válida ou se todos os navegadores e dispositivos se comportam da mesma forma. Mantenha asserções, logs e screenshots junto com a gravação.

A gravação também não elimina o risco do ambiente. O ffmpeg precisa estar no PATH junto com o codificador compatível. Taxas de quadros maiores acrescentam sobrecarga, gravações longas consomem disco e máquinas headless com poucos recursos podem ter limites de codec ou GPU. Uma página que redesenha devagar não consegue fornecer 60 quadros distintos por segundo.

Trate a privacidade como requisito do produto. O gravador captura o viewport ativo e o estado interno da página — justamente o que o torna útil e também o motivo para definir regras de contas de teste, mascaramento de segredos, retenção de artefatos e controle de acesso. Isso exige julgamento operacional; não é uma promessa nativa de mascaramento automático.

Por fim, o agent-browser registra a evidência, mas não a interpreta. Se a intenção for usar um modelo para analisar o vídeo depois da execução, será preciso outro sistema, mais próximo da compreensão agêntica de vídeo. Mantenha essa camada separada da verificação determinística de aprovação ou falha.

O passo para segunda-feira

Na próxima semana, escolha um fluxo instável de login, checkout ou publicação. Execute doctor, grave a página ativa atual a 30 fps, preserve a asserção existente, chame record stop e anexe o MP4 ao resultado do teste. Passe para 60 fps apenas se o revisor não conseguir avaliar um defeito de movimento; reduza para 10 fps quando uma execução longa servir principalmente como sequência. O piloto terá sucesso quando alguém conseguir diagnosticar a falha sem repetir a execução, não quando o vídeo apenas parecer fluido.

Se você quer um agente de navegador que produza evidências prontas para revisão pela sua equipe, posso desenvolvê-lo com base no seu fluxo real de QA.