Capturas de tela que se atualizam automaticamente

 (interblah.net)
11 pontos por GN⁺ 2 일 전 | 1 comentários | Compartilhar no WhatsApp
  • Um fluxo que captura capturas de tela automaticamente de uma aplicação web em execução e as atualiza junto com o build da documentação de ajuda, facilitando manter as imagens da documentação sempre atualizadas mesmo após mudanças na UI
  • Comentários SCREENSHOT no Markdown contêm instruções como caminho de destino, modo de captura e seletor CSS, e durante o processo de build դրանք são lidos e preenchidos com imagens reais
  • Uma Rake task executa o Chrome headless por meio de Capybara e Cuprite, agrupa o trabalho por equipe e, após fazer login uma única vez, percorre várias URLs para capturar as imagens
  • A captura oferece suporte a três modos: element, full_page e viewport, e também controla UI aberta ou elementos desnecessários com opções como click, wait, crop, torn e hide
  • Com um único rails manual:build, a geração das capturas e o build das páginas de ajuda rodam juntos, facilitando alinhar código e documentação no mesmo PR ou commit e reduzindo bastante o atrito de capturas e recortes manuais

Método de capturas de tela que se atualizam automaticamente

  • O centro de ajuda do Jelly é configurado para capturar capturas de tela automaticamente de uma aplicação web em execução e atualizá-las junto com cada novo build
  • A documentação é escrita em Markdown e, com base no artigo Self-updating screenshots, é processada em HTML com Redcarpet e então renderizada como views ERB em um app Rails
  • Dentro do Markdown há comentários SCREENSHOT, que incluem instruções como caminho de destino, modo de captura e seletor CSS
    • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
    • A tag de imagem logo abaixo é usada como a posição onde o resultado será inserido
  • Quando a cor da UI, a posição de botões ou os textos mudam mesmo que pouco, as capturas de tela da documentação existente ficam desatualizadas com facilidade; esse fluxo reduz essa carga de atualização manual

Pipeline de captura e efeito na manutenção

  • Internamente, uma Rake task executa o Chrome headless por meio de Capybara e Cuprite para varrer os comentários SCREENSHOT de todos os arquivos Markdown
  • As tarefas de captura são agrupadas por equipe e, dentro da mesma equipe, são configuradas para fazer login apenas uma vez antes de percorrer várias URLs
  • Há suporte a três modos de captura
    • element: captura um elemento DOM específico por seletor CSS
    • full_page: captura a página inteira e, se necessário, pode recortar com base na altura
    • viewport: captura apenas a área atualmente visível na janela do navegador
  • Com opções detalhadas como click, wait e crop, também é possível capturar automaticamente estados exibidos após clicar em um botão ou telas depois de animações
    • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
    • Funciona clicando no botão para abrir o formulário, aguardando 200 ms e então capturando uma área específica recortada
  • Há ainda opções adicionais como torn e hide
    • torn aplica um efeito de borda de papel rasgado usando CSS clip-path
    • hide oculta temporariamente elementos que não devem aparecer na tela, como dev toolbar ou cookie banner
  • Todo o pipeline é executado com um único comando, rails manual:build, que processa todas as capturas de tela e o build das páginas de ajuda em conjunto
  • As fontes da documentação ficam organizadas em public/manual/, em seções como basics, setup e advanced
  • Na etapa de build, esses arquivos Markdown são convertidos em views ERB dentro de app/views/help/, com breadcrumb e navegação de seção gerados junto
  • Como o desenvolvimento de funcionalidades e a atualização da ajuda podem ser tratados juntos no mesmo codebase, fica mais fácil manter a sincronia entre código e documentação no mesmo PR ou no mesmo commit
  • Casos especiais como elementos que exigem rolagem, popovers que só abrem com clique e recortes para evitar partes desnecessárias exigiram mais tempo de implementação, mas depois de pronto isso levou a atualizações muito mais frequentes no centro de ajuda
  • Basta mudar a UI, executar o build novamente e fazer commit do resultado para manter as capturas sempre atualizadas, praticamente eliminando o atrito de capturas e recortes manuais

Leituras relacionadas

1 comentários

 
GN⁺ 2 일 전
Comentários do Hacker News
  • Eu também adicionei algo parecido com uma derivação .#screenshots; o custo de configuração inicial é alto, mas depois quase não exige manutenção
    Já que o programa gera as capturas de tela, dá para criar junto as duas versões do app com tema claro/escuro e alternar entre elas de acordo com prefers-color-scheme: dark
    Esse tipo de coisa também funciona bem em READMEs do GitHub: https://github.com/CyberShadow/CyDo#readme
    • Concordo fortemente com essa abordagem
      Em app mobile, fiz o Nix subir um emulador Android descartável para gerar capturas atualizadas, sem precisar de configuração prévia e sem deixar dados depois da execução
      No meu caso, a configuração em si nem foi tão difícil; o mais complicado foi ter a ideia, e o código Nix eu gerei de primeira com meu LLM favorito
      Atualizar capturas manualmente não é a tarefa mais sofrida do mundo, mas o fluxo upload-apk + take-screenshot + transfer-back-to-PC + edit é sempre incômodo o bastante para eu acabar quase nunca fazendo isso
  • No mobile, rolagem horizontal em exemplos de código é indispensável
    Deu para deduzir mais ou menos pelo contexto, mas ainda assim foi incômodo
  • Isso é muito útil em projetos mobile
    Em lojas de aplicativos, capturas de tela são obrigatórias, e você precisa gerar imagens para cada tamanho de tela e para cada localização, então isso fica trabalhoso muito rápido
    Antigamente eu escrevia scripts para isso; hoje ferramentas como Fastlane, tipo https://fastlane.tools/, ajudam bastante
    Uso Fastlane também no meu jogo de lógica Nonoverse, e dá para ver capturas de exemplo na página do app: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
    Também automatizei a gravação de vídeos de App Preview, incluindo várias cenas, e acho que isso renderia um bom post separado para quem tiver curiosidade
    • Isso me interessou bastante, mas não ficou claro para mim se é um serviço pago ou um app de sistema operacional que roda localmente
  • Muito legal
    Os joguinhos casuais pequenos que faço com vibe coding sempre começam com o app podendo rodar em modo headless por CLI, com renderização em textura offscreen, comando de captura de tela e até medição de desempenho
    Isso quase não leva tempo para incluir e ainda cria um caminho para agentes automatizarem a UI e inspecionarem pontos importantes
    Por isso, fazer o agente atualizar as capturas também fica bem fácil
    Não é tão elegante quanto algo totalmente integrado ao processo de build, mas agora estou pensando em adicionar essa parte também
    • Eu faço exatamente a mesma coisa
      Também tenho argumentos de CLI para offscreen screenshot path e world pos/camera view vector, e rodo benchmarks com um formato de entrada baseado em texto
      Esse formato é composto por várias linhas de segmentos nomeados, a duração de n ticks de jogo por segmento e as entradas de controle de cada segmento
      Uso muito isso para testes A/B de visual e desempenho enquanto trabalho no código do jogo
    • Fiquei curioso se você poderia compartilhar alguns links desses jogos casuais
      Também tenho muito interesse em como vibe coding está facilitando o desenvolvimento de jogos
      Na época do Adobe Flash, o ecossistema de jogos indie era realmente vibrante, e desde então quase nada chegou perto daquele nível de facilidade de desenvolvimento
      Vibe coding parece ser a primeira ferramenta a superar aquilo
    • A frase Isso quase não leva tempo para incluir depende do caso
      Fiquei curioso sobre qual engine você usa
  • Muito bacana
    Gostei especialmente do fato de poder colocar uma declaração de screenshot inline dentro de um documento Markdown
    No meu app desktop, criei uma solução que gera capturas em vários idiomas e modos claro/escuro, remove ruído e até aplica molduras de janela do Windows/macOS
    Está documentado aqui: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
    Hoje isso está em um script separado, então a manutenção é bem chata; vou dar uma olhada em como incorporar isso como parte do markdown/mdx
    Foi uma ótima inspiração
  • Eu precisava muito de algo assim
    Dá até para usar como meme do tipo o melhor trabalho em X que ninguém percebe
  • Isso é bom
    Também há algo parecido no https://github.com/zombocom/rundoc que eu fiz
    Como o objetivo principal é gerar tutoriais, ele também reinsere no documento a saída dos comandos executados
  • Acho que uma abordagem de renderização em tempo real também poderia funcionar aqui
    Seria algo como colocar a prévia ao vivo da ferramenta dentro de um retângulo
    Se a ferramenta for leve, isso pode até ser visualmente ideal, e ainda refletiria as configurações de renderização do navegador, como ajustes de acessibilidade ou addons do usuário
  • Já pensei em aproveitar a execução de testes e2e para também gerar capturas de tela
    Se o docs/ ficar no mesmo repositório e você adicionar um novo teste quando precisar de uma nova captura ao atualizar a documentação, parece combinar bem
  • Bom
    Alguns anos atrás eu comecei a construir exatamente isso, mas acabei abstraindo para algo mais genérico, como https://picshift.io/
    Mesmo assim, continuo gostando muito do caso de uso de screenshots, e o nome original desse projeto era ScreenSync
    • Legal, ficou bem feito, e é bom ver que essas abordagens variadas coexistem