Depurar regras de especulação com o Chrome DevTools

As regras de especulação podem ser usadas para pré-buscar e pré-renderizar as navegações nas próximas páginas, conforme detalhado na postagem anterior. Isso permite um carregamento de página muito mais rápido ou até mesmo instantâneo, melhorando muito as Core Web Vitals para essas outras navegações nas páginas.

A depuração de regras de especulação pode ser complicada. Isso é particularmente verdadeiro para páginas pré-renderizadas, já que elas são renderizadas em um renderizador separado, como uma guia oculta em segundo plano que substitui a guia atual quando ativada. Portanto, as opções comuns do DevTools nem sempre podem ser usadas para depurar problemas.

A equipe do Chrome tem trabalhado muito para aprimorar o suporte do DevTools para a depuração de regras de especulação. Nesta postagem, você verá todas as várias maneiras de usar essas ferramentas para entender as regras de especulação de uma página, por que elas podem não estar funcionando e quando os desenvolvedores podem usar as opções mais conhecidas do DevTools (e quando não).

Explicação de "pré-" termos

Há muito "pré-" confusos, portanto, começaremos com uma explicação sobre isso:

  • Pré-busca: buscar um recurso ou documento com antecedência para melhorar o desempenho futuro. Esta postagem aborda a pré-busca de documentos com a API Speculation Rules, em vez da opção <link rel="prefetch"> semelhante, mas mais antiga, que costuma ser usada para a pré-busca de sub-recursos.
  • Pré-renderização: vai além da pré-busca e renderiza toda a página como se o usuário tivesse navegado até ela, mas a mantém em um processo de renderizador oculto em segundo plano pronto para ser usado caso o usuário realmente navegue até lá. Mais uma vez, este documento está relacionado à versão mais recente da API Speculation Rules, em vez da opção <link rel="prerender"> mais antiga, que não faz mais uma pré-renderização completa.
  • Especulações de navegação: o termo coletivo para as novas opções de pré-busca e pré-renderização acionadas por regras de especulação.
  • Pré-carregamento: um termo sobrecarregado que pode se referir a várias tecnologias e processos, incluindo <link rel="preload">, o verificador de pré-carregamento e pré-carregamentos de navegação do service worker. Esses itens não serão abordados aqui, mas o termo foi incluído para diferenciá-los claramente de "especulações de navegação" termo.
.

Regras de especulação para prefetch

As regras de especulação podem ser usadas para pré-buscar o documento da próxima navegação. Por exemplo, ao inserir o JSON a seguir em uma página, next.html e next2.html serão pré-buscados:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "source": "list",
        "urls": ["next.html", "next2.html"]
      }
    ]
  }
</script>

O uso de regras de especulação para pré-buscas de navegação tem algumas vantagens em relação à sintaxe <link rel="prefetch"> mais antiga, como uma API mais expressiva e os resultados armazenados no cache de memória em vez de no cache de disco HTTP.

Depurar regras de especulação prefetch

As pré-buscas acionadas por regras de especulação podem ser vistas no painel Rede da mesma forma que outras buscas:

Painel Network no Chrome DevTools mostrando documentos pré-buscados
Painel Network no Chrome DevTools mostrando documentos pré-buscados

As duas solicitações destacadas em vermelho são os recursos pré-buscados, como mostrado na coluna Type. Eles são buscados na prioridade Lowest, assim como em navegações futuras, e o Chrome prioriza os recursos da página atual.

Clique em uma das linhas para ver o cabeçalho HTTP Sec-Purpose: prefetch. É assim que essas solicitações podem ser identificadas no lado do servidor:

Cabeçalhos de pré-busca do Chrome DevTools com o Sec-Purpose definido para pré-busca
Cabeçalhos de pré-busca do Chrome DevTools com o Sec-Purpose definido para pré-busca

Depurar o prefetch com as guias de carregamento especulativo

Uma nova seção de carregamentos especulativos foi adicionada ao painel Application do Chrome DevTools, na seção Serviços em segundo plano, para ajudar na depuração das regras de especulação:

Guias de carregamento especulativo do Chrome DevTools mostrando a regra de pré-busca
Guias de carregamento especulativo do Chrome DevTools mostrando a regra de pré-busca

Há três guias disponíveis nessa seção:

  • Carregamentos especulativos, que lista o status pré-renderizado da página atual.
  • Regras, que lista todos os conjuntos de regras encontrados na página atual.
  • Especulações, que lista todos os URLs pré-buscados e pré-renderizados dos conjuntos de regras.
.

A guia Especulações é mostrada na captura de tela anterior. É possível observar que esta página de exemplo tem um único conjunto de regras de especulação para a pré-busca de três páginas. Duas dessas pré-buscas foram concluídas e uma falhou. Clique no ícone ao lado de Conjunto de regras para acessar a origem do conjunto de regras no painel Elementos. Também é possível clicar no link Status para acessar a guia Especulações filtrada pelo conjunto de regras.

A guia Especulações lista todos os URLs de destino, junto com a ação (pré-busca ou pré-renderização), de qual conjunto de regras eles vieram (pode haver várias em uma página) e o status de cada especulação:

Guia &quot;Especulações&quot; do Chrome DevTools mostrando URLs pré-buscados e o status deles
Guia "Especulações" do Chrome DevTools mostrando URLs pré-buscados e o status deles

Acima dos URLs, um menu suspenso pode ser usado para mostrar os URLs de todos os grupos de regras ou apenas os URLs de um determinado grupo de regras. Abaixo dele, todos os URLs estão listados. Clique em um URL para conferir informações mais detalhadas.

Nesta captura de tela, podemos ver o motivo da falha da página next3.html, que não existe e, portanto, retorna um 404, que é um código de status HTTP diferente de 2xx.

A guia de resumo Carregamentos especulativos mostra um relatório de Status de carregamento especulativo desta página para mostrar se uma pré-busca ou pré-renderização foi usada para a página ou não.

Para uma página pré-buscada, você verá uma mensagem de êxito quando essa página for acessada:

Guia de carregamentos especulativos do Chrome DevTools mostrando uma pré-busca bem-sucedida
Guia de carregamentos especulativos do Chrome DevTools mostrando uma pré-busca bem-sucedida

Especulações sem correspondência

Quando uma navegação acontece em uma página com regras de especulação que não resultam no uso de uma pré-busca ou pré-renderização, uma seção adicional da guia mostra mais detalhes sobre o motivo pelo qual o URL não corresponde a nenhum dos URLs de especulação. Isso é útil para identificar erros de digitação nas regras de especulação.

Guia de carregamentos especulativos do Chrome DevTools mostrando como o URL atual não corresponde a nenhum dos URLs nas regras de especulação da página anterior
URLs sem correspondência são destacados no DevTools

Por exemplo, aqui navegamos para next4.html, mas apenas next.html, next2.html ou next3.html são pré-buscas. Por isso, podemos notar que isso não corresponde a nenhuma dessas três regras.

As guias de carregamentos especulativos são muito úteis para depurar as regras de especulação e encontrar erros de sintaxe no JSON.

Quanto às pré-buscas, o painel Network provavelmente é um lugar mais familiar. Para o exemplo de falha na pré-busca, confira o erro 404 aqui:

Painel Network do Chrome DevTools mostrando uma pré-busca com falha
Painel Network do Chrome DevTools mostrando uma pré-busca com falha

No entanto, as guias Carregamentos especulativos se tornam muito mais úteis para regras de especulação de pré-renderização, que serão abordadas a seguir.

Regras de especulação para prerender

As regras de especulação de pré-renderização seguem a mesma sintaxe das regras de especulação de pré-busca. Exemplo:

<script type="speculationrules">
  {
    "prerender": [
      {
        "source": "list",
        "urls": ["next.html", "next2.html"]
      }
    ]
  }
</script>

Este conjunto de regras aciona um carregamento e uma renderização completos das páginas especificadas (sujeito a certas restrições). Isso pode proporcionar uma experiência de carregamento instantâneo, embora com custos extras de recursos.

No entanto, ao contrário das pré-buscas, elas não estão disponíveis no painel Rede, porque são buscadas e renderizadas em um processo de renderização separado no Chrome. Isso torna as guias de carregamentos especulativos mais importantes para depurar regras de especulação de pré-renderização.

Depurar prerender com as guias de carregamentos especulativos

As mesmas telas de carregamentos especulativos podem ser usadas para regras de especulação de pré-renderização, como demonstrado com uma página de demonstração semelhante que tenta pré-renderizar, em vez de pré-buscar as três páginas:

O Chrome DevTools Speculative carrega guias para uma página com regras de especulação de pré-renderização.
O Chrome DevTools speculative carrega guias para uma página com regras de especulação de pré-renderização

Aqui vemos novamente que um dos três URLs falhou na pré-renderização, e os desenvolvedores podem acessar os detalhes por URL na guia Especulações clicando no link 2 prontos, 1 falha.

No Chrome 121, lançamos o suporte a regras de documentos. Isso permite que o navegador extraia esses links dos mesmos links de origem na página, em vez de listar um conjunto específico de URLs:

<script type="speculationrules">
{
  "prerender": [
    {
      "source": "document",
      "where": {
        "and": [
          {"href_matches": "/*"},
          {"not": { "href_matches": "/not-safe-to-prerender/*"}}
        ]
      },
      "eagerness": "moderate"
    }
  ]
}
</script>

Este exemplo seleciona todos os mesmos links de origem, exceto aqueles que começam com /not-safe-to-prerender como candidatos de pré-renderização.

Ele também define o eagerness de pré-renderização como moderate, o que significa que as navegações são pré-renderizadas quando o usuário passa o cursor sobre o link ou recebe um clique.

Existem regras semelhantes no site de demonstração de regras especulativas, e o uso da nova seção Carregamentos especulativos mostra a utilidade dessa nova guia, já que todos os URLs qualificados que o navegador encontrou na página estão listados:

Guia &quot;Especulações&quot; do Chrome DevTools com vários URLs não acionados
Guia "Especulações" do Chrome DevTools com vários URLs não acionados

O Status é Não acionado porque o processo de pré-renderização não foi iniciado. No entanto, quando mantemos o ponteiro sobre os links, vemos a mudança de status conforme cada URL é pré-renderizado:

Guia &quot;Especulações&quot; do Chrome DevTools com páginas pré-renderizadas acionadas
Guia "Especulações" do Chrome DevTools com páginas pré-renderizadas acionadas

O Chrome definiu limites para pré-renderizações, incluindo um máximo de duas pré-renderizações para o preparo moderate. Portanto, depois de passar o cursor sobre o terceiro link, vemos o motivo da falha desse URL:

Guia &quot;Especulações&quot; do Chrome DevTools com pré-carregamentos com falha aparecendo
Guia "Especulações" do Chrome DevTools com pré-carregamentos com falha aparecendo

Depurar prerender com os outros painéis do DevTools

Ao contrário das pré-buscas, as páginas que foram pré-renderizadas não vão aparecer nos processos de renderização atuais nos painéis do DevTools, como o painel Network, porque elas são renderizadas nos próprios renderizadores em segundo plano.

No entanto, agora é possível alternar o renderizador usado pelos painéis do DevTools com o menu suspenso no menu suspenso no canto superior direito ou selecionando um URL na parte superior do painel e selecionando Inspecionar:

O Chrome DevTools agora permite trocar de renderizadores para os quais as informações são exibidas
O Chrome DevTools agora permite trocar de renderizadores para os quais as informações são exibidas

Esse menu suspenso e o valor selecionado também são compartilhados com todos os outros painéis, como o painel Rede, em que você pode conferir que a página solicitada é a pré-renderizada:

Painel &quot;Network&quot; do Chrome DevTools mostrando as solicitações de rede para a página pré-renderizada
Painel de rede do Chrome DevTools mostrando as solicitações de rede para a página pré-renderizada

Analisando os cabeçalhos HTTP desses recursos, vemos que todos serão definidos com o cabeçalho Sec-Purpose: prefetch;prerender:

Painel Network do Chrome DevTools mostrando o cabeçalho Sec-Purpose para uma página pré-renderizada
Painel Network do Chrome DevTools mostrando o cabeçalho Sec-Purpose para uma página pré-renderizada

Ou o painel Elements, em que é possível conferir o conteúdo da página, como na captura de tela abaixo, em que vemos que o elemento <h1> é para a página pré-renderizada:

Painel Elements do Chrome DevTools para a página pré-renderizada
Painel Elements do Chrome DevTools para a página pré-renderizada

Ou o painel Console, onde você pode ver os registros emitidos pela página pré-renderizada:

Painel do Console do Chrome DevTools mostrando a saída do console de uma página pré-renderizada
Painel do console do Chrome DevTools mostrando a saída do console de uma página pré-renderizada

Depurar regras de especulação na página pré-renderizada

As seções anteriores discutem como depurar páginas pré-renderizadas na página que inicia a pré-renderização. No entanto, também é possível que as próprias páginas pré-renderizadas forneçam informações de depuração, seja fazendo chamadas de análise ou registrando no console, o que pode ser visualizado conforme descrito na seção anterior.

Além disso, quando uma página pré-renderizada é ativada pelo usuário que está navegando até ela, a guia Carregamentos especulativos mostra esse status e se ela foi pré-renderizada ou não. Se não for possível pré-renderizar, uma explicação do motivo pelo qual isso aconteceu é fornecida:

Guia de carregamentos especulativos do Chrome DevTools mostrando uma página pré-renderizada bem-sucedida e com falha
Guia de carregamentos especulativos do Chrome DevTools mostrando uma página pré-renderizada bem-sucedida e com falha

Além disso, como é o caso das pré-buscas, navegar em uma página com regras de especulação que não correspondem à página atual vai tentar mostrar por que os URLs não correspondem às regras de especulação da página anterior na guia Carregamentos especulativos:

Guia de carregamentos especulativos do Chrome DevTools mostrando a incompatibilidade de URLs entre o URL atual e aqueles cobertos pela página anterior
O Chrome DevTools mostrando as incompatibilidades de URL

Conclusão

Nesta postagem, mostramos as várias maneiras como os desenvolvedores podem depurar a pré-busca e pré-renderizar regras de especulação. A equipe continua trabalhando em ferramentas para regras de especulação e gostaríamos de receber sugestões dos desenvolvedores sobre que outras maneiras seriam úteis para depurar essa nova API incrível. Incentivamos os desenvolvedores a informar um problema no Issue Tracker do Chrome em caso de solicitações de recursos ou bugs detectados.

Agradecimentos

Imagem do Thumbail por Nubelson Fernandes no Unsplash.