Como testar a integração SeaText SPA antes de entrar no ar

Antes de o SeaText entrar no ar, teste-o em um ambiente de staging. O objetivo é simples: provar que o snippet carrega, o armazenamento local funciona, as trocas de idioma funcionam e cada rota se comporta corretamente. Este guia fornece uma lista de verificação prática, um mapa de rotas e um script Cypress de exemplo.

Por que o teste de staging é importante

O SeaText reescreve o texto da página e cria variantes. Se o snippet falhar, os visitantes podem ver o texto original, o texto traduzido ou uma interface quebrada. Isso é difícil de diagnosticar em produção.

O staging permite que você detecte esses problemas antes que o tráfego real chegue. Você pode testar o carregamento assíncrono, o armazenamento local e o comportamento entre origens com segurança.

A documentação do SeaText aponta três riscos específicos de SPA: carregamento assíncrono, permissões de armazenamento local e problemas entre origens. Um teste de staging deve cobrir todos os três.

Sem staging, um bug pode afetar todos os visitantes. Com staging, você pode corrigi-lo antes do lançamento.

Como o snippet do SeaText funciona dentro de um SPA

O SeaText é um snippet JavaScript. A documentação usa o espaço reservado SEATEXTCODEINTEGRATION. Você o insere no corpo do index.html ou na seção de inicialização equivalente do seu framework SPA.

A tag de script inclui o atributo async. Isso impede que o snippet bloqueie a renderização da página. É uma decisão de desempenho, mas também significa que o script é executado após a primeira pintura.

O script armazena um ID no armazenamento local. O SeaText usa esse ID para reconhecer visitas e aplicar a variante correta. Se o armazenamento local for bloqueado, esse reconhecimento falha.

Frameworks SPA como React, Vue e Angular montam o aplicativo a partir de pontos de entrada diferentes. Você precisa encontrar o arquivo certo. A documentação diz que isso geralmente é index.html ou um arquivo principal JavaScript/TypeScript onde o framework monta.

Em um SPA, clicar em um link não recarrega a página. O navegador troca componentes. O SeaText deve continuar funcionando nessas trocas. É por isso que você não pode testar apenas uma rota.

Lista de verificação de teste de staging passo a passo

Use esta ordem. Ela vai da configuração de build às verificações em tempo de execução.

1. Defina seu mapa de rotas. Anote cada URL de produção que o SPA usa.
2. Compile o aplicativo da mesma forma que você compila para produção. Use as mesmas variáveis de ambiente quando possível.
3. Insira SEATEXTCODEINTEGRATION no ponto de entrada correto.
4. Sirva o build de staging via HTTPS, se possível. O SeaText pode se comportar de forma diferente em localhost.
5. Ative o log de depuração ou verboso do SeaText, se o painel oferecer.
6. Abra o DevTools e verifique a aba Network. Confirme que o script do SeaText retorna 200.
7. Inspecione a tag de script. Ela deve incluir o atributo async.
8. Abra o Console. Procure por erros de CSP, CORS ou JavaScript.
9. Abra a aba Application. Confirme que o armazenamento local tem um ID do SeaText.
10. Navegue por todas as rotas no mapa de rotas. Não use apenas rotas típicas.
11. Simule uma troca de idioma em pelo menos uma rota profunda. O texto deve mudar sem recarregar totalmente.
12. Revise o painel do SeaText. Confirme que variantes e eventos foram registrados.

Trate cada verificação como aprovação ou reprovação. Se uma falhar, não avance para a próxima etapa até entender o porquê.

Lista de verificação de cobertura de rotas e script Cypress de exemplo

Um mapa de rotas é a lista de URLs que seu SPA pode exibir. É a fonte da verdade para testes. Comece com os links na sua navegação e adicione rotas de campanhas e e-mails.

N

Substitua as rotas de exemplo pelas suas. O importante é que cada rota de produção apareça no teste.

Após a tabela, execute o script Cypress abaixo. Ele visita cada rota e verifica a solicitação de rede do SeaText.

describe('Cobertura de rotas SPA do SeaText', () => {
  const rotas = ['/', '/produtos/exemplo', '/precos', '/checkout', '/conta', '/blog/exemplo', '/rota-inexistente'];

  it('carrega o script do SeaText em cada rota', () => {
    cy.intercept('**/*seatext*').as('scriptSeatext');
    rotas.forEach(rota => {
      cy.visit(Cypress.env('STAGING_URL') + rota);
      cy.wait('@scriptSeatext').its('response.statusCode').should('eq', 200);
    });
  });

  it('armazena um ID do SeaText no armazenamento local', () => {
    cy.visit(Cypress.env('STAGING_URL'));
    cy.window().then(win => {
      const chaves = Object.keys(win.localStorage).filter(k => k.toLowerCase().includes('seatext'));
      expect(chaves.length).to.be.greaterThan(0);
    });
  });

  it('atualiza o texto na troca de idioma', () => {
    cy.visit(Cypress.env('STAGING_URL'));
    cy.get('[data-seatext-lang=es]').click();
    cy.contains('¡Bienvenido!').should('be.visible');
  });
});

Cenário hipotético: uma execução de staging em React

Imagine Lena, uma desenvolvedora frontend. Ela precisa lançar uma loja React com SeaText. Ela começa com um build de staging semelhante ao de produção.

Ela abre public/index.html e insere SEATEXTCODEINTEGRATION antes da tag de fechamento do corpo. Em seguida, executa npm run build e serve a saída em https://staging.example.com.

No DevTools, ela filtra a aba Network por seatext. O script retorna 200. A tag de script no painel Elements tem o atributo async.

Ela abre a aba Application e encontra uma chave de armazenamento local que contém um ID do SeaText. Ela navega pelo mapa de rotas. O ID permanece no armazenamento local em cada rota.

Em seguida, ela clica no botão de idioma espanhol em uma página de produto. O título muda para “¡Bienvenido!” sem recarregar. A URL não muda.

Ela então executa a suíte Cypress em todas as rotas. Uma rota falha porque o servidor de staging retorna 404 para uma rota do lado do cliente. Ela corrige o fallback do servidor para servir index.html e executa novamente.

A suíte passa. O painel do SeaText mostra variantes registradas. Lena envia o snippet.

Compensações e limitações

O carregamento assíncrono melhora o desempenho, mas pode causar um pequeno atraso. Os usuários podem ver brevemente o texto original antes que o SeaText aplique as alterações. Isso é uma compensação, não um bug.

O armazenamento local não é garantido. Alguns navegadores o bloqueiam no modo privado ou quando o armazenamento de terceiros é restrito. Seu aplicativo deve ter permissão para acessar o armazenamento local.

Solicitações entre origens podem falhar. Se seu SPA chama vários domínios, verifique o console para erros de CORS. A documentação do SeaText alerta sobre isso.

Aplicativos de staging geralmente usam Política de Segurança de Conteúdo (CSP). Uma CSP estrita pode bloquear o script do SeaText. Adicione o domínio necessário à sua lista de permissões e verifique.

Os pontos de entrada do framework não são idênticos. React, Vue e Angular têm estruturas de arquivo diferentes. Confirme onde seu framework inicializa antes de colar o snippet.

O staging deve espelhar o roteamento de produção. Se o servidor de staging não retornar index.html para rotas do lado do cliente, os testes de rota falham pelo motivo errado.

A saída de IA é variável. Não escreva testes que esperem texto exato para sempre. Afirme que os elementos de conteúdo existem e têm texto.

Critérios de aprovação: todas as rotas retornam 200 para o script, sem erros no console, ID do armazenamento local aparece, troca de idioma funciona e o painel registra uma variante. Se qualquer um falhar, bloqueie o lançamento até corrigir.

Depurando falhas comuns

Use o DevTools como primeiro passo. As abas Console e Network geralmente indicam o problema exato.

• Script não carrega. Verifique a aba Network para 404 ou solicitação falha. Verifique a URL do script, DNS e regras de firewall.
• ID do armazenamento local ausente. Confirme que o script foi executado. Verifique permissões de armazenamento e modos de armazenamento bloqueados.
• Erro de CORS aparece. Leia a mensagem completa do console. Verifique os cabeçalhos de resposta para Access-Control-Allow-Origin.
• CSP bloqueia o script. Procure por mensagem Refused to load. Atualize a política de segurança e execute novamente.
• Troca de idioma não faz nada. Confirme que o botão usa o seletor esperado. Verifique se a tradução está ativa para essa rota.
• Testes passam no staging, mas falham em produção. Compare mapas de rotas, variáveis de ambiente e configurações de build.
• O script carrega, mas o texto nunca muda. Abra o painel para ver se uma variante foi registrada. Se não, verifique a configuração do agente.

FAQ

• O snippet do SeaText precisa estar em todos os arquivos de página? Não. Adicione-o uma vez no ponto de entrada HTML ou no arquivo de inicialização do framework.
• Devo usar um build de produção para testes de staging? Sim. Os comandos de build devem corresponder à produção.
• Como sei que o script é assíncrono? Inspecione a tag de script no DevTools. Ela deve incluir o atributo async.
• Por que meu teste de rota retorna 404? O servidor de staging provavelmente não tem fallback SPA. Configure-o para servir index.html para rotas do lado do cliente.
• Posso usar Playwright em vez de Cypress? Sim. A cobertura de rotas e as verificações são as mesmas.
• E se um teste passar localmente, mas falhar no pipeline de staging? Compare URL, variáveis de ambiente e a saída exata do build.