Pausar o código com pontos de interrupção

Kayce Basques

Sofia Emelianova

Usar pontos de interrupção para pausar o código JavaScript. Este guia explica cada tipo de ponto de interrupção disponível no DevTools, quando usar e como definir cada tipo. Para conferir um tutorial interativo do processo de depuração, consulte Introdução à depuração do JavaScript no Chrome DevTools.

Visão geral de quando usar cada tipo de ponto de interrupção

O tipo mais conhecido de ponto de interrupção é a linha de código. No entanto, os pontos de interrupção de linha de código podem ser ineficientes, especialmente se você não souber exatamente onde procurar ou se estiver trabalhando com uma grande base de código. É possível economizar tempo durante a depuração sabendo como e quando usar os outros tipos de pontos de interrupção.

Tipo de ponto de interrupção	Use quando quiser ...
Linha de código	Pause em uma região exata do código.
Linha de código condicional	Pausa em uma região exata do código, mas somente quando alguma outra condição é verdadeira.
Logpoint	Registre uma mensagem no Console sem pausar a execução.
DOM	Pausa no código que altera ou remove um nó DOM específico ou seus filhos.
XHR (link em inglês)	Pausa quando um URL XHR contém um padrão de string.
Listener de eventos	Pause no código executado depois que um evento, como click, é disparado.
Exceção	Pause na linha de código que está gerando uma exceção capturada ou não capturada.
Function	Pausar sempre que uma função específica for chamada.
Tipo confiável	Faça uma pausa em violações do Tipo confiável.

Pontos de interrupção de linha de código

Use um ponto de interrupção de linha de código quando souber a região exata do código que você precisa investigar. O DevTools sempre pausa antes dessa linha de código ser executada.

Para definir um ponto de interrupção da linha de código no DevTools:

1. Clique na guia Origens.
2. Abra o arquivo que contém a linha de código que você quer interromper.
3. Acesse a linha de código.
4. À esquerda da linha de código está a coluna do número da linha. Clique nele. Um ícone azul aparece no topo da coluna do número da linha.

Este exemplo mostra um ponto de interrupção da linha de código definido na linha 29.

Pontos de interrupção de linha de código no código

Chame debugger pelo seu código para pausar nessa linha. Isso é equivalente a um ponto de interrupção de linha de código, exceto que o ponto de interrupção é definido no seu código, não na interface do DevTools.

console.log('a');
console.log('b');
debugger;
console.log('c');

Pontos de interrupção de linha de código condicional

Use um ponto de interrupção de linha de código condicional quando quiser interromper a execução, mas somente quando alguma condição for verdadeira.

Esses pontos de interrupção são úteis quando você quer pular intervalos que são irrelevantes para o seu caso, especialmente em loop.

Para definir um ponto de interrupção de linha de código condicional:

1. Abra a guia Fontes.
2. Abra o arquivo que contém a linha de código que você quer interromper.
3. Acesse a linha de código.
4. À esquerda da linha de código está a coluna do número da linha. Clique nele com o botão direito do mouse.
5. Selecione Adicionar ponto de interrupção condicional. Uma caixa de diálogo vai aparecer abaixo da linha de código.
6. Insira a condição na caixa de diálogo.
7. Pressione Enter para ativar o ponto de interrupção. Um ícone laranja com um ponto de interrogação aparece na parte superior da coluna do número da linha.

Este exemplo mostra um ponto de interrupção de linha de código condicional acionado somente quando o x excedeu 10 em uma repetição na iteração i=6.

Registrar pontos de interrupção da linha de código

Use pontos de interrupção da linha de código (logpoints) para registrar mensagens no Console sem pausar a execução e sobrecarregar seu código com chamadas console.log().

Para definir um logpoint:

1. Abra a guia Fontes.
2. Abra o arquivo que contém a linha de código que você quer interromper.
3. Acesse a linha de código.
4. À esquerda da linha de código está a coluna do número da linha. Clique nele com o botão direito do mouse.
5. Selecione Adicionar logpoint. Uma caixa de diálogo vai aparecer abaixo da linha de código.

6. Digite a mensagem de registro na caixa de diálogo. Use a mesma sintaxe que você usaria com uma chamada console.log(message).

   Por exemplo, você pode registrar:

   "A string " + num, str.length > 1, str.toUpperCase(), obj
   

   Neste caso, a mensagem registrada é:

   // str = "test"
   // num = 3
   // obj = {attr: "x"}
   A string 42 true TEST {attr: 'x'}
   

7. Pressione Enter para ativar o ponto de interrupção. Um ícone rosa com dois pontos aparece na parte superior da coluna do número da linha.

Este exemplo mostra um logpoint na linha 30 que registra uma string e um valor de variável no Console.

Editar pontos de interrupção da linha de código

Use o painel Breakpoints para desativar, editar ou remover pontos de interrupção de linha de código.

Editar grupos de pontos de interrupção

O painel Breakpoints agrupa os pontos de interrupção por arquivo e os ordena por números de linha e coluna. Você pode fazer o seguinte com os grupos:

• Para fechar ou expandir um grupo, clique no nome dele.
• Para ativar ou desativar um grupo ou um ponto de interrupção individualmente, clique no ao lado do grupo ou do ponto de interrupção.
• Para remover um grupo, passe o cursor sobre ele e clique em .

Esse vídeo mostra como recolher grupos e desativar ou ativar pontos de interrupção individualmente ou por grupo. Quando você desativa um ponto de interrupção, o painel Sources torna o marcador ao lado do número da linha transparente.

Os grupos têm menus de contexto. No painel Breakpoints, clique com o botão direito do mouse em um grupo e escolha:

• Remova todos os pontos de interrupção no arquivo (grupo).
• Desative todos os pontos de interrupção no arquivo.
• Ative todos os pontos de interrupção no arquivo.
• Remova todos os pontos de interrupção (em todos os arquivos).
• Remova outros pontos de interrupção (em outros grupos).

Editar pontos de interrupção

Para editar um ponto de interrupção:

• Clique no ao lado de um ponto de interrupção para ativá-lo ou desativá-lo. Quando você desativa um ponto de interrupção, o painel Sources torna o marcador ao lado do número da linha transparente.
• Passe o cursor sobre um ponto de interrupção e clique em para editar e em para removê-lo.

• Ao editar um ponto de interrupção, altere o tipo dele na lista suspensa do editor in-line.

  

• Clique com o botão direito do mouse em um ponto de interrupção para ver o menu de contexto e escolha uma destas opções:

  

  • Revelar o local.
  • Edite a condição ou o logpoint.
  • Ative todos os pontos de interrupção.
  • Desative todos os pontos de interrupção.
  • Remover o ponto de interrupção.
  • Remova outros pontos de interrupção (em todos os arquivos).
  • Remova todos os pontos de interrupção (em todos os arquivos).

Assista ao vídeo para ver várias edições de ponto de interrupção em ação: desativar, remover, editar condição, revelar o local no menu e alterar o tipo.

Pontos de interrupção de mudança DOM

Use um ponto de interrupção de mudança DOM quando quiser pausar o código que altera um nó DOM ou os filhos dele.

Para definir um ponto de interrupção de mudança DOM:

1. Clique na guia Elementos.
2. Acesse o elemento em que você quer definir o ponto de interrupção.
3. Clique com o botão direito do mouse no elemento.
4. Passe o cursor sobre Break on e selecione Subtree arquiteturas, Attribute edits ou Remoção de nó.

Este exemplo mostra o menu de contexto para criar um ponto de interrupção de mudança DOM.

Você pode encontrar uma lista de pontos de interrupção de mudança DOM em:

• Elementos > Painel de pontos de interrupção do DOM.
• Sources > Painel lateral DOM Breakpoints.

Nela, você pode:

• Ative ou desative com .
• Clique com o botão direito do mouse > Remove ou Reveal (Revelar) no DOM.

Tipos de pontos de interrupção de mudança DOM

• Modificações de subárvore. Acionado quando um filho do nó selecionado é removido ou adicionado, ou quando o conteúdo de um filho é alterado. Não é acionada em mudanças de atributo do nó filho ou em qualquer mudança no nó selecionado no momento.
• Modificações de atributos: acionadas quando um atributo é adicionado ou removido no nó selecionado ou quando o valor de um atributo muda.
• Remoção de nó: acionado quando o nó selecionado é removido.

Pontos de interrupção XHR/busca

Use um ponto de interrupção XHR/busca quando quiser interromper quando o URL de solicitação de um XHR contiver uma string especificada. O DevTools faz uma pausa na linha de código em que o XHR chama send().

Isso pode ser útil, por exemplo, quando você perceber que sua página está solicitando um URL incorreto e quiser encontrar rapidamente o código-fonte AJAX ou Fetch que está causando a solicitação incorreta.

Para definir um ponto de interrupção XHR/busca:

1. Clique na guia Origens.
2. Expanda o painel XHR Breakpoints.
3. Clique em Adicionar ponto de interrupção.
4. Insira a string que você quer interromper. O DevTools pausa quando essa string está presente em qualquer lugar no URL de solicitação XHR.
5. Pressione Enter para confirmar.

Este exemplo mostra como criar um ponto de interrupção XHR/busca nos pontos de interrupção XHR/fetch para qualquer solicitação que contenha org no URL.

Pontos de interrupção do listener de eventos

Use pontos de interrupção de listener de eventos quando quiser pausar o código do listener de eventos executado depois que um evento é disparado. Você pode selecionar eventos específicos, como click, ou categorias de eventos, como todos os eventos de mouse.

1. Clique na guia Origens.
2. Expanda o painel Pontos de interrupção do listener de eventos. O DevTools mostra uma lista de categorias de eventos, como Animation.
3. Marque uma dessas categorias para pausar sempre que um evento dela for disparado ou expanda a categoria e verifique um evento específico.

O exemplo a seguir mostra como criar um ponto de interrupção de listener de eventos para deviceorientation.

Além disso, o Debugger faz uma pausa em eventos que acontecem em Web workers ou worklets de qualquer tipo, incluindo os Worklets de armazenamento compartilhado.

Este exemplo mostra o Debugger pausado em um evento setTimer que aconteceu em um service worker.

Você também encontra uma lista de listeners de eventos no painel Elementos > Listeners de eventos.

Pontos de interrupção de exceção

Use pontos de interrupção de exceção quando quiser pausar na linha de código que está gerando uma exceção capturada ou não capturada. É possível pausar em ambas as exceções de maneira independente em qualquer sessão de depuração diferente do Node.js.

Importante: atualmente, em uma sessão de depuração do Node.js, só é possível pausar nas exceções capturadas se você também pausar nas não capturadas. Consulte o bug no 1382762 do Chromium para saber mais.

No painel Breakpoints da guia Sources, ative uma das opções a seguir ou ambas e execute o código:

• Marque a opção Pausar em exceções não capturadas.

  

  Neste exemplo, a execução é pausada em uma exceção não capturada.

• Marque a opção Pausar em exceções capturadas.

  

  Neste exemplo, a execução é pausada em uma exceção capturada.

Exceções em chamadas assíncronas

Com uma ou as caixas de seleção "capturadas" e "não capturadas" ativadas, o Debugger tenta pausar nas exceções correspondentes em chamadas síncronas e assíncronas. No caso assíncrono, o Debugger procura gerenciadores de rejeição nas promessas para determinar quando parar.

Exceções capturadas e código ignorado

Quando a Lista de ignorados está ativada, o Debugger faz uma pausa nas exceções capturadas em frames não ignorados ou ao passar por esse frame na pilha de chamadas.

O próximo exemplo mostra o Debugger pausado em uma exceção capturada gerada pelo library.js ignorado que passa pelo mycode.js não ignorado.

Para saber mais sobre o comportamento do Debugger em casos extremos, teste uma série de cenários nesta página de demonstração.

Pontos de interrupção de função

Chame debug(functionName), em que functionName é a função que você quer depurar, quando quiser pausar sempre que uma função específica for chamada. Você pode inserir debug() no código (como uma instrução console.log()) ou chamá-lo pelo Console do DevTools. debug() é equivalente a definir um ponto de interrupção de linha de código na primeira linha da função.

function sum(a, b) {
  let result = a + b; // DevTools pauses on this line.
  return result;
}
debug(sum); // Pass the function object, not a string.
sum();

Verifique se a função de destino está no escopo

O DevTools gera uma ReferenceError se a função que você quer depurar não está no escopo.

(function () {
  function hey() {
    console.log('hey');
  }
  function yo() {
    console.log('yo');
  }
  debug(yo); // This works.
  yo();
})();
debug(hey); // This doesn't work. hey() is out of scope.

Garantir que a função de destino esteja no escopo pode ser complicado se você estiver chamando debug() no Console do DevTools. Aqui está uma estratégia:

1. Defina um ponto de interrupção de linha de código em algum lugar em que a função esteja no escopo.
2. Acione o ponto de interrupção.
3. Chame debug() no Console do DevTools enquanto o código ainda estiver pausado no ponto de interrupção da linha de código.

Pontos de interrupção do Tipo confiável

A API Trusted Type fornece proteção contra explorações de segurança conhecidas como ataques de scripting em vários locais (XSS).

Termo-chave:o scripting em vários sites baseado em DOM acontece quando os dados de uma fonte controlada pelo usuário (como nome de usuário ou URL de redirecionamento retirado do fragmento de URL) chegam a um coletor, que é uma função como eval(), ou um setter de propriedade, como .innerHTML, que pode executar um código JavaScript arbitrário.

No painel Breakpoints da guia Sources, acesse a seção CSP violation Breakpoints, ative uma das opções a seguir ou ambas e execute o código:

• Marque Violações do coletor.

  

  Neste exemplo, a execução é pausada em uma violação de coletor.

• Marque Violações da política.

  

  Neste exemplo, a execução é pausada devido a uma violação da política. As políticas de Tipo confiável são configuradas usando trustedTypes.createPolicy.

Encontre mais informações sobre como usar a API:

• Para alcançar seus objetivos de segurança, acesse Evitar vulnerabilidades de scripting em vários sites baseado em DOM com Tipos confiáveis.
• Para depurar, acesse Como implementar a CSP e depurar os Tipos confiáveis no Chrome DevTools (em inglês).