Referência de recursos

Sofia Emelianova

Jecelyn Yeen

Descubra maneiras de compartilhar fluxos de usuários, editá-los e as etapas correspondentes nesta referência abrangente de recursos do painel Gravador do Chrome DevTools.

Para aprender os conceitos básicos do trabalho com o painel Gravador, consulte Gravar, reproduzir e medir fluxos de usuários.

Aprender e personalizar atalhos

Use atalhos para navegar no Gravador mais rapidamente. Confira uma lista dos atalhos padrão em Atalhos de teclado do painel do Gravador.

Para abrir uma dica que lista todos os atalhos no Gravador, clique em ajuda Mostrar atalhos no canto superior direito.

Para personalizar os atalhos do Gravador:

1. Abra Configurações > Atalhos.
2. Role para baixo até a seção Gravador.
3. Siga as etapas em Personalizar atalhos.

Editar fluxos de usuários

Na parte superior do painel Gravador, há opções para:

1. Adicionar uma nova gravação. Clique no ícone + para adicionar uma nova gravação.
2. Acessar todas as gravações. O menu suspenso mostra a lista de gravações salvas. Selecione a opção [número] gravação(ões) para expandir e gerenciar a lista de gravações salvas.

3. Exportar uma gravação. Para personalizar ainda mais o script ou compartilhá-lo para gerar relatórios de bugs, exporte o fluxo do usuário em um dos seguintes formatos:

   • arquivo JSON.
   • @puppeteer/replay.
   • Puppeteer.
   • Puppeteer (incluindo análise do Lighthouse).

   Para mais informações sobre os formatos, consulte Exportar um fluxo do usuário.

4. Importar uma gravação. Somente no formato JSON.

5. Excluir uma gravação. Exclua a gravação selecionada.

Também é possível editar o nome da gravação clicando no botão de edição ao lado dela.

Compartilhar fluxos de usuários

É possível exportar e importar fluxos de usuários no Gravador. Isso é útil para gerar relatórios de bugs porque você pode compartilhar um registro exato das etapas que reproduzem um bug. Também é possível exportá-lo e reproduzi-lo com bibliotecas externas.

Exportar um fluxo do usuário

Para exportar um fluxo do usuário:

1. Abra o fluxo do usuário que você quer exportar.
2. Clique em Exportar na parte superior do painel Gravador.
3. Selecione um dos seguintes formatos na lista suspensa:
   • arquivo JSON. Faça o download da gravação como um arquivo JSON.
   • @puppeteer/replay. Faça o download da gravação como script de Puppeteer Replay.
   • Puppeteer: Faça o download da gravação como um script do Puppeteer.
   • Puppeteer (incluindo análise do Lighthouse). Faça o download da gravação como script do Puppeteer com uma análise do Lighthouse incorporada.
   • Uma ou mais opções fornecidas pelas extensões de exportação do Gravador.
4. Salve o arquivo.

É possível fazer o seguinte com cada opção de exportação padrão:

• JSON. Edite o objeto JSON legível por humanos e importe o arquivo JSON de volta para o Gravador.
• @puppeteer/replay. Reproduza o script novamente com a biblioteca Puppeteer Replay. Ao exportar como um script @puppeteer/replay, as etapas continuam sendo um objeto JSON. Essa opção é perfeita se você quer fazer a integração com o pipeline de CI/CD, mas ainda tem flexibilidade para editar as etapas como JSON, depois convertê-las e importá-las de volta para o Gravador.
• Script Puppeteer: Reproduza o script novamente com o Puppeteer. Como as etapas são convertidas em JavaScript, é possível ter uma personalização mais refinada, por exemplo, repetindo as etapas. Um aviso: não é possível importar esse script de volta para o Gravador.

• Puppeteer (incluindo análise do Lighthouse). Essa opção de exportação é igual à anterior, mas inclui um código que gera uma análise do Lighthouse.

  Execute o script e confira a saída em um arquivo flow.report.html:

  # npm i puppeteer lighthouse
  node your_export.js
  

  

Exportar em um formato personalizado instalando uma extensão

Consulte Extensões do Gravador.

Importar um fluxo do usuário

Para importar um fluxo do usuário:

1. Clique no botão Importar na parte superior do painel Gravador.
2. Selecione o arquivo JSON com o fluxo do usuário registrado.
3. Clique no botão Repetir para executar o fluxo de usuários importado.

Repetir com bibliotecas externas

O Puppeteer Replay é uma biblioteca de código aberto mantida pela equipe do Chrome DevTools. Ele é baseado no Puppeteer. É uma ferramenta de linha de comando que permite reproduzir arquivos JSON com ela.

Além disso, é possível transformar e reproduzir arquivos JSON com as seguintes bibliotecas de terceiros.

Transforme fluxos de usuários JSON em scripts personalizados:

• Cypress Chrome Recorder (em inglês). Ele pode ser usado para converter arquivos JSON de fluxo de usuário em scripts de teste do Cypress. Assista esta demonstração para saber como isso funciona.
• Gravador do Chrome do Nightwatch. Ele pode ser usado para converter arquivos JSON de fluxo do usuário em scripts de teste do Nightwatch.
• Gravador do Chrome do CodeceptJS. Ele pode ser usado para converter arquivos JSON de fluxo de usuário em scripts de teste do CodeceptJS.

Repetir fluxos de usuários JSON:

• Repetir com o Testcafe. Use o TestCafe para reproduzir os arquivos JSON de fluxo do usuário e gerar relatórios de teste para essas gravações.
• Repetir com a Sauce Labs. Para reproduzir os arquivos JSON no Sauce Labs, use saucectl.

.

Ponto-chave: Caso de uso avançado: fazer a integração com a biblioteca Puppeteer Replay Assim como nas bibliotecas de terceiros acima, também é possível criar sua própria biblioteca com base em Puppeteer Replay. A biblioteca do Puppeteer Replay oferece maneiras de personalizar a forma como uma gravação é executada e "stringificar" os arquivos JSON de fluxo do usuário, ou seja, converta-os em outra coisa.

Depurar fluxos de usuários

Como qualquer código, às vezes você precisa depurar os fluxos de usuários gravados.

Para ajudar na depuração, o painel Gravador permite que você desacelere as repetições, defina pontos de interrupção, percorra a execução e inspecione o código em vários formatos em paralelo com as etapas.

Diminuir a velocidade da repetição

Por padrão, o Gravador reproduz o fluxo do usuário o mais rápido possível. Para entender o que acontece na gravação, você pode diminuir a velocidade de repetição:

1. Abra o menu suspenso Repetir.
2. Escolha uma das opções de velocidade de repetição:
   • Normal (padrão)
   • Lento
   • Muito devagar
   • Extremamente lenta

Importante:só é possível usar essas opções de repetição lenta no Gravador. Para adicionar tempos limite à própria gravação, consulte Ajustar tempos limite para etapas.

Inspecionar código

Para inspecionar o código de um fluxo de usuário em vários formatos:

1. Abra uma gravação no painel Gravador.
2. Clique em Mostrar código no canto superior direito da lista de etapas.
3. O Gravador mostra uma visualização lado a lado das etapas e o código delas.
4. Quando você passa o cursor sobre uma etapa, o Gravador destaca o respectivo código em qualquer formato, incluindo os fornecidos pelas extensões.

5. Expanda a lista suspensa de formatos e selecione um formato para exportar fluxos de usuários.

   

   Pode ser um dos três formatos padrão (JSON, @puppeteer/replay, script Puppeteer ou fornecido por uma extensão).

6. Para depurar a gravação, edite os parâmetros e valores da etapa. A visualização de código não é editável, mas é atualizada conforme você faz as alterações nas etapas à esquerda.

Definir pontos de interrupção e executar etapa a etapa

Para definir um ponto de interrupção e executar etapa por etapa:

1. Passe o cursor sobre o círculo ao lado de qualquer etapa da gravação. O círculo se transforma em um ícone de ponto de interrupção .
2. Clique no ícone do ponto de interrupção e reproduza a gravação novamente. A execução é pausada no ponto de interrupção.
3. Para percorrer a execução, clique no botão Execute uma etapa na barra de ações na parte superior do painel Gravador.
4. Para interromper a repetição, clique em Cancelar repetição.

Editar etapas

Para editar qualquer etapa da gravação, clique no botão ao lado dela durante e depois da gravação.

Também é possível adicionar etapas ausentes e remover aquelas que foram registradas acidentalmente.

Adicionar etapas

Às vezes, pode ser necessário adicionar etapas manualmente. Por exemplo, o Gravador não captura automaticamente eventos hover porque isso polui a gravação e nem todos esses eventos são úteis. No entanto, elementos da interface, como menus suspensos, podem aparecer apenas no hover. É possível adicionar manualmente etapas hover aos fluxos de usuários que dependem desses elementos.

Para adicionar uma etapa manualmente:

1. Abra esta página de demonstração e inicie uma nova gravação.
2. Passe o cursor sobre o elemento na janela de visualização. Um menu de ações será exibido.
3. Escolha uma ação no menu e encerre a gravação. O Gravador captura apenas o evento de clique.
4. Tente reproduzir a gravação clicando em Repetir. A repetição falha após um tempo limite porque o Gravador não pode acessar o elemento no menu.
5. Clique no botão de três pontos ao lado da etapa Clicar e selecione Adicionar etapa antes.
6. Expanda a nova etapa. Por padrão, ele tem o tipo waitForElement. Clique no valor ao lado de type e selecione hover.
7. Em seguida, defina um seletor apropriado para a nova etapa. Clique em Selecionar e em uma área do elemento Hover over me! que esteja fora do menu pop-up. O seletor é definido como #clickable.
8. Tente reproduzir a gravação de novo. Com a etapa de passar o cursor adicionada, o Gravador repete o fluxo.

Adicionar declarações

Durante a gravação, você pode declarar, por exemplo, atributos HTML e propriedades JavaScript. Para adicionar uma declaração:

1. Inicie uma gravação, por exemplo, nesta página de demonstração.

2. Clique em Add assertion.

   

   O Gravador cria uma etapa waitForElement configurável.

3. Especificar seletores para esta etapa.

4. Configure a etapa, mas não altere o tipo waitForElement. Por exemplo, é possível especificar:

   • Atributo HTML. Clique em Adicionar atributos e digite o nome e o valor do atributo que os elementos desta página usam. Por exemplo, data-test: <value>.
   • propriedade JavaScript. Clique em Adicionar propriedades e digite o nome e o valor da propriedade no formato JSON. Por exemplo, {".innerText":"<text>"}.
   • Outras propriedades da etapa. Por exemplo, visible: true.

5. Continue a gravar o restante do fluxo do usuário e, em seguida, pare a gravação.

6. Clique em Repetir. Se uma declaração falhar, o Gravador vai mostrar um erro após um tempo limite.

Assista o vídeo a seguir para ver esse fluxo de trabalho em ação.

Copiar etapas

Em vez de exportar todo o fluxo do usuário, copie uma única etapa para a área de transferência:

1. Clique com o botão direito do mouse na etapa que você quer copiar ou clique no ícone de três pontos ao lado dela.
2. No menu suspenso, selecione uma das opções Copiar como ....

É possível copiar etapas em vários formatos: JSON, Puppeteer, @puppeteer/replay e fornecidas por extensões.

Remover etapas

Para remover uma etapa registrada acidentalmente, clique com o botão direito do mouse na etapa ou clique no ícone de três pontos ao lado dela e selecione Remover etapa.

Além disso, o Gravador adiciona automaticamente duas etapas separadas ao início de cada gravação:

• Definir janela de visualização. Permite controlar as dimensões, o dimensionamento e outras propriedades da janela de visualização.
• Navegar. Define o URL e atualiza a página automaticamente a cada repetição.

Para realizar a automação na página sem atualizar a página, remova a etapa de navegação conforme descrito acima.

Etapas de configuração

Para configurar uma etapa:

1. Especifique o tipo: click, doubleClick, hover, (entrada) change, keyUp, keyDown, scroll, close, navigate (para uma página), waitForElement, waitForExpression ou setViewport.

   Outras propriedades dependem do valor type.

2. Especifique as propriedades obrigatórias abaixo de type.

   

3. Clique nos botões correspondentes para adicionar e especificar propriedades opcionais específicas do tipo.

Para uma lista das propriedades disponíveis, consulte Propriedades da etapa.

Para remover uma propriedade opcional, clique no botão Remover ao lado dela.

Para adicionar ou remover um elemento de ou para uma propriedade de matriz, clique nos botões + ou - ao lado do elemento.

Propriedades da etapa

Cada etapa pode ter as seguintes propriedades opcionais:

• target: um URL para o destino do protocolo Chrome DevTools (CDP). A palavra-chave padrão main se refere à página atual.
• assertedEvents, que no momento só podem ser um único evento de navigation

Outras propriedades comuns disponíveis para a maioria dos tipos de etapa são:

• frame: uma matriz de índices baseados em zero que identificam um iframe que pode ser aninhado. Por exemplo, é possível identificar o primeiro (0) iframe dentro de um segundo (1) iframe do destino principal como [1, 0].
• timeout: um número de milissegundos a aguardar antes de executar uma etapa. Para mais informações, consulte Ajustar os tempos limite das etapas.
• selectors: uma matriz de seletores. Para mais informações, consulte Entender os seletores.

As propriedades específicas do tipo são:

Tipo	Propriedade	Obrigatório	Descrição
click doubleClick	offsetX offsetY		Em relação ao canto superior esquerdo da caixa de conteúdo do elemento, em pixels
click doubleClick	button		Botão ponteiro: principal | auxiliar | segundo | voltar | para a frente
change	value		Valor final
keyDown keyUp	key		Nome da chave
scroll	x y		Posições x e y de rolagem absoluta em pixels, padrão 0
navigate	url		URL de destino
waitForElement	operator		>= | == (padrão) | <=
waitForElement	count		Número de elementos identificados por um seletor
waitForElement	attributes		Atributo HTML e seu valor
waitForElement	properties		Propriedade JavaScript e o valor dela em JSON
waitForElement	visible		Booleano. Verdadeiro se o elemento estiver no DOM e estiver visível (não tiver display: none ou visibility: hidden)
waitForElement waitForExpression	asserted events		No momento, apenas type: navigation, mas é possível especificar o título e o URL
waitForElement waitForExpression	timeout		Tempo máximo de espera em milissegundos
waitForExpression	expression		Expressão JavaScript que se resolve como verdadeiro
setViewport	width height		Largura e altura da janela de visualização em pixels
setViewport	deviceScaleFactor		Semelhante à proporção de pixels do dispositivo (DPR), padrão 1
setViewport	isMobile hasTouch isLandscape		Sinalizações booleanas que especificam se é necessário: Considere a metatag Oferecer suporte a eventos de toque Exibir no modo paisagem

Há duas propriedades que fazem a reprodução pausar:

• A propriedade waitForElement faz a etapa aguardar a presença (ou ausência) de vários elementos identificados por um seletor. Por exemplo, a etapa a seguir espera que menos de três elementos estejam na página correspondente ao seletor .my-class.

    "type": "waitForElement",
    "selectors": [".my-class"],
    "operator": "<=",
    "count": 2,
  

• A propriedade waitForExpression faz a etapa esperar até que uma expressão JavaScript seja resolvida como verdadeira. Por exemplo, a etapa a seguir é pausada por dois segundos e, em seguida, definida como verdadeira, permitindo que a repetição continue.

    "type": "waitForExpression",
    "expression": "new Promise(resolve => setTimeout(() => resolve(true), 2000))",
  

Ajustar tempos limite para passos

Caso sua página tenha solicitações de rede lentas ou animações longas, a reprodução poderá falhar em etapas que excedem o tempo limite padrão de 5000 milissegundos.

Para evitar esse problema, você pode ajustar o tempo limite padrão para cada etapa de uma só vez ou definir tempos limite separados para etapas específicas. Os tempos limite em etapas específicas substituem o padrão.

Para ajustar o tempo limite padrão de cada etapa de uma só vez:

1. Clique em Configurações de repetição para tornar a caixa Tempo limite editável.

   

2. Na caixa Tempo limite, defina o valor em milissegundos.

3. Clique em Repetir para conferir o tempo limite padrão ajustado em ação.

Para substituir o tempo limite padrão em uma etapa específica:

1. Expanda a etapa e clique em Adicionar tempo limite.

   

2. Clique no timeout: <value> e defina o valor em milissegundos.

   

3. Clique em Repetir para conferir a etapa com o tempo limite em ação.

Para remover a substituição de tempo limite em uma etapa, clique no botão Excluir ao lado dela.

Entender os seletores

Ao iniciar uma nova gravação, você pode configurar o seguinte:

• Na caixa de texto Atributo do seletor, insira um atributo de teste personalizado. O Gravador usa esse atributo para detectar seletores em vez de uma lista de atributos de teste comuns.

• No conjunto de caixas de seleção Tipos de seletor para registrar, escolha os tipos que serão detectados automaticamente:

  • CSS. Seletores sintáticos.
  • ARIA: Seletores semânticos.
  • Texto. Seletores com o menor texto exclusivo, se disponível.
  • XPath (link em inglês). Seletores que usam a linguagem de caminho XML
  • Pierce. Seletores semelhantes aos de CSS, mas que podem inserir o shadow DOM.

.

Observação:para mais informações, consulte Seletores sintáticos x semânticos e Prioridade do seletor.

Seletores de teste comuns

Em páginas da Web simples, os atributos id e CSS class são suficientes para que o Gravador detecte os seletores. No entanto, esse nem sempre é o caso porque:

• Suas páginas da Web podem usar turmas ou IDs dinâmicos que mudam.
• Os seletores podem falhar devido a mudanças no código ou no framework.

Por exemplo, os valores CSS class podem ser gerados automaticamente para aplicativos desenvolvidos com frameworks modernos de JavaScript (por exemplo, React, Angular, Vue) e CSS.

Nesses casos, é possível usar atributos data-* para criar testes mais resilientes. Já existem alguns seletores data-* comuns que os desenvolvedores usam para automação. O Gravador também oferece suporte a eles.

Se você tiver os seguintes seletores de teste comuns definidos no seu site, o Gravador vai detectá-los e usá-los automaticamente primeiro:

• data-testid
• data-test
• data-qa
• data-cy
• data-test-id
• data-qa-id
• data-testing

Por exemplo, inspecione o "Cappuccino" nesta página de demonstração e veja os atributos de teste:

Grave um clique em "Cappuccino", expanda a etapa correspondente na gravação e verifique os seletores detectados:

Personalizar o seletor da gravação

É possível personalizar o seletor de uma gravação se os seletores de teste comuns não funcionarem para você.

Por exemplo, esta página de demonstração usa o atributo data-automate como seletor. Inicie uma nova gravação e insira data-automate como o atributo do seletor.

Preencha um endereço de e-mail e observe o valor do seletor ([data-automate=email-address]).

Prioridade do seletor

O Gravador procura seletores na seguinte ordem, dependendo do fato de você ter especificado um atributo de seletor de CSS personalizado:

• Se especificado:
  1. seletor de CSS com seu atributo CSS personalizado.
  2. Seletores XPath.
  3. Seletor ARIA, se encontrado.
  4. Um seletor com o menor texto exclusivo, se encontrado.
• Se não for especificado:
  1. Seletor ARIA, se encontrado.
  2. Seletores de CSS com a seguinte prioridade:
     1. Os atributos mais comuns usados para testes:
        • data-testid
        • data-test
        • data-qa
        • data-cy
        • data-test-id
        • data-qa-id
        • data-testing
     2. Atributos de ID, por exemplo, <div id="some_ID">.
     3. Seletores de CSS comuns.
  3. Seletores XPath.
  4. Perfurar seletores.
  5. Um seletor com o menor texto exclusivo, se encontrado.

Pode haver vários seletores comuns de CSS, XPath e Pierce. O Gravador captura:

• Seletores CSS e XPath regulares em todos os níveis raiz, ou seja, hosts sombra aninhados, se houver.
• Faça a perfuração dos seletores que são únicos entre todos os elementos dentro de todas as raízes paralelas.