Come testare l'integrazione SeaText SPA prima di andare in produzione

Prima che SeaText vada in produzione, testalo in un ambiente di staging. L'obiettivo è semplice: dimostrare che lo snippet si carica, che l'archiviazione locale funziona, che i cambi di lingua funzionano e che ogni rotta si comporta correttamente. Questa guida ti fornisce una checklist pratica, una mappa delle rotte e uno script Cypress di esempio.

Perché i test in staging sono importanti

SeaText riscrive il testo della pagina e crea varianti. Se lo snippet fallisce, i visitatori potrebbero vedere il testo originale, il testo tradotto o un'interfaccia rotta. Questo è difficile da diagnosticare in produzione.

Lo staging ti consente di individuare questi problemi prima che arrivi il traffico reale. Puoi testare il caricamento asincrono, l'archiviazione locale e il comportamento cross-origin in sicurezza.

La documentazione di SeaText evidenzia tre rischi specifici delle SPA: caricamento asincrono, permessi di archiviazione locale e problemi cross-origin. Un test in staging dovrebbe coprire tutti e tre.

Senza staging, un bug può influenzare ogni visitatore. Con lo staging, puoi risolverlo prima del lancio.

Come funziona lo snippet SeaText all'interno di una SPA

SeaText è uno snippet JavaScript. I documenti usano il segnaposto SEATEXTCODEINTEGRATION. Lo inserisci nel corpo di index.html o nella sezione di inizializzazione equivalente del tuo framework SPA.

Il tag script include l'attributo async. Questo impedisce allo snippet di bloccare il rendering della pagina. È una decisione di performance, ma significa anche che lo script viene eseguito dopo il primo paint.

Lo script memorizza un ID nell'archiviazione locale. SeaText usa quell'ID per riconoscere le visite e applicare la variante giusta. Se l'archiviazione locale è bloccata, quel riconoscimento fallisce.

I framework SPA come React, Vue e Angular montano l'app da punti di ingresso diversi. Devi trovare il file giusto. I documenti dicono che di solito è index.html o un file JavaScript/TypeScript principale dove il framework monta.

In una SPA, cliccare su un link non ricarica la pagina. Il browser sostituisce i componenti. SeaText deve continuare a funzionare attraverso questi scambi. Questo è il motivo per cui non puoi testare solo una rotta.

Checklist di test in staging passo dopo passo

Usa questo ordine. Si passa dalla configurazione di build ai controlli di runtime.

1. Definisci la tua mappa delle rotte. Annota ogni URL di produzione che la SPA usa.
2. Costruisci l'app nello stesso modo in cui la costruisci per la produzione. Usa le stesse variabili d'ambiente quando possibile.
3. Inserisci SEATEXTCODEINTEGRATION nel punto di ingresso corretto.
4. Servi la build di staging su HTTPS se possibile. SeaText potrebbe comportarsi diversamente su localhost.
5. Attiva il debug o la registrazione verbosa di SeaText se la dashboard lo offre.
6. Apri DevTools e controlla la scheda Network. Conferma che lo script SeaText restituisca 200.
7. Ispeziona il tag script. Dovrebbe includere l'attributo async.
8. Apri la Console. Cerca errori CSP, CORS o JavaScript.
9. Apri la scheda Application. Conferma che l'archiviazione locale abbia un ID SeaText.
10. Naviga attraverso ogni rotta nella mappa delle rotte. Non usare solo le rotte tipiche.
11. Simula un cambio di lingua su almeno una rotta profonda. Il testo dovrebbe cambiare senza un ricaricamento completo.
12. Rivedi la dashboard di SeaText. Conferma che varianti ed eventi siano stati registrati.

Tratta ogni controllo come un pass o fail. Se uno fallisce, non passare al passo successivo finché non capisci il perché.

Checklist di copertura delle rotte e script Cypress di esempio

Una mappa delle rotte è l'elenco degli URL che la tua SPA può mostrare. È la fonte di verità per i test. Inizia con i link nella tua navigazione, poi aggiungi le rotte da campagne ed email.

Non fermarti a home, prodotto e checkout. Le rotte profonde spesso nascondono problemi. Ad esempio, una pagina account potrebbe inviare header extra che attivano CORS.

Sostituisci le rotte di esempio con le tue. La cosa importante è che ogni rotta di produzione appaia nel test.

Dopo la tabella, esegui lo script Cypress qui sotto. Visita ogni rotta e controlla la richiesta di rete SeaText.

describe('Copertura rotte SeaText SPA', () => {
  const routes = ['/', '/prodotti/esempio', '/prezzi', '/checkout', '/account', '/blog/esempio', '/rotta-mancante'];

  it('carica lo script SeaText su ogni rotta', () => {
    cy.intercept('**/*seatext*').as('seatextScript');
    routes.forEach(route => {
      cy.visit(Cypress.env('STAGING_URL') + route);
      cy.wait('@seatextScript').its('response.statusCode').should('eq', 200);
    });
  });

  it('memorizza un ID SeaText nell\'archiviazione locale', () => {
    cy.visit(Cypress.env('STAGING_URL'));
    cy.window().then(win => {
      const keys = Object.keys(win.localStorage).filter(k => k.toLowerCase().includes('seatext'));
      expect(keys.length).to.be.greaterThan(0);
    });
  });

  it('aggiorna il testo al cambio di lingua', () => {
    cy.visit(Cypress.env('STAGING_URL'));
    cy.get('[data-seatext-lang=es]').click();
    cy.contains('¡Bienvenido!').should('be.visible');
  });
});

Scenario ipotetico: un run di staging React

Immagina Lena, una sviluppatrice frontend. Deve lanciare un negozio React con SeaText. Inizia con una build di staging simile alla produzione.

Apre public/index.html e inserisce SEATEXTCODEINTEGRATION prima del tag body di chiusura. Poi esegue npm run build e serve l'output su https://staging.example.com.

In DevTools, filtra la scheda Network per seatext. Lo script restituisce 200. Il tag script nel pannello Elements ha l'attributo async.

Apre la scheda Application e trova una chiave di archiviazione locale che contiene un ID SeaText. Naviga attraverso la mappa delle rotte. L'ID rimane nell'archiviazione locale su ogni rotta.

Successivamente, clicca il pulsante della lingua spagnola su una pagina prodotto. Il titolo cambia in “¡Bienvenido!” senza un ricaricamento. L'URL non cambia.

Poi esegue la suite Cypress su tutte le rotte. Una rotta fallisce perché il server di staging restituisce un 404 per una rotta lato client. Corregge il fallback del server per servire index.html e riesegue.

La suite passa. La dashboard di SeaText mostra varianti registrate. Lena pubblica lo snippet.

Compromessi e limitazioni

Il caricamento asincrono migliora le performance, ma può causare un breve ritardo. Gli utenti potrebbero vedere brevemente il testo originale prima che SeaText applichi le modifiche. Questo è un compromesso, non un bug.

L'archiviazione locale non è garantita. Alcuni browser la bloccano in modalità privata o quando lo storage di terze parti è limitato. La tua app deve avere il permesso di accedere all'archiviazione locale.

Le richieste cross-origin possono fallire. Se la tua SPA chiama più domini, controlla la console per errori CORS. La documentazione di SeaText avverte su questo.

Le app di staging spesso usano Content Security Policy. Una CSP rigorosa può bloccare lo script SeaText. Aggiungi il dominio necessario alla tua allowlist e verifica.

I punti di ingresso dei framework non sono identici. React, Vue e Angular hanno ciascuno una struttura di file diversa. Conferma dove il tuo framework inizializza prima di incollare lo snippet.

Lo staging deve rispecchiare il routing di produzione. Se il server di staging non restituisce index.html per le rotte lato client, i test delle rotte falliscono per il motivo sbagliato.

L'output AI è variabile. Non scrivere test che si aspettano un testo esatto per sempre. Afferma che gli elementi di contenuto esistono e hanno testo.

Criteri di superamento: tutte le rotte restituiscono 200 per lo script, nessun errore in console, l'ID nell'archiviazione locale appare, il cambio di lingua funziona e la dashboard registra una variante. Se uno di questi fallisce, blocca il lancio finché non viene risolto.

Debug dei guasti comuni

Usa DevTools come primo passo. Le schede Console e Network di solito indicano il problema esatto.

• Lo script non si carica. Controlla la scheda Network per un 404 o una richiesta fallita. Verifica l'URL dello script, il DNS e le regole del firewall.
• L'ID nell'archiviazione locale manca. Conferma che lo script sia stato eseguito. Controlla i permessi di archiviazione e le modalità di archiviazione bloccate.
• Errore CORS appare. Leggi il messaggio completo della console. Controlla gli header di risposta per Access-Control-Allow-Origin.
• La CSP blocca lo script. Cerca un messaggio Refused to load. Aggiorna la policy di sicurezza e riesegui.
• Il cambio di lingua non fa nulla. Conferma che il pulsante usi il selettore previsto. Controlla che la traduzione sia attiva per quella rotta.
• I test passano in staging ma falliscono in produzione. Confronta mappe delle rotte, variabili d'ambiente e impostazioni di build.
• Lo script si carica ma il testo non cambia mai. Apri la dashboard per vedere se una variante è stata registrata. In caso contrario, controlla la configurazione dell'agente.

FAQ

• Lo snippet SeaText deve essere su ogni file di pagina? No. Aggiungilo una volta al punto di ingresso HTML o al file di inizializzazione del framework.
• Dovrei usare una build di produzione per i test in staging? Sì. I comandi di build dovrebbero corrispondere alla produzione.
• Come faccio a sapere se lo script è asincrono? Ispeziona il tag script in DevTools. Dovrebbe includere l'attributo async.
• Perché il mio test di rotta restituisce un 404? Il server di staging probabilmente non ha un fallback SPA. Configuralo per servire index.html per le rotte lato client.
• Posso usare Playwright invece di Cypress? Sì. La copertura delle rotte e i controlli sono gli stessi.
• Cosa succede se un test passa localmente ma fallisce nella pipeline di staging? Confronta URL, variabili d'ambiente e l'output esatto della build.