Comment tester l'intégration SeaText SPA avant la mise en ligne

Avant la mise en ligne de SeaText, testez-le dans un environnement de staging. L'objectif est simple : prouver que le snippet se charge, que le stockage local fonctionne, que les changements de langue fonctionnent et que chaque route se comporte correctement. Ce guide vous donne une liste de contrôle pratique, une carte des routes et un exemple de script Cypress.

Pourquoi les tests en staging sont importants

SeaText réécrit le contenu de la page et crée des variantes. Si le snippet échoue, les visiteurs peuvent voir le contenu original, le contenu traduit ou une interface cassée. C'est difficile à diagnostiquer en production.

Le staging vous permet de détecter ces problèmes avant l'arrivée du trafic réel. Vous pouvez tester le chargement asynchrone, le stockage local et le comportement inter-origines en toute sécurité.

La documentation SeaText souligne trois risques spécifiques aux SPA : le chargement asynchrone, les autorisations de stockage local et les problèmes inter-origines. Un test en staging devrait couvrir ces trois aspects.

Sans staging, un bug peut affecter chaque visiteur. Avec le staging, vous pouvez le corriger avant le lancement.

Comment le snippet SeaText fonctionne dans une SPA

SeaText est un snippet JavaScript. La documentation utilise le placeholder SEATEXTCODEINTEGRATION. Vous l'insérez dans le corps de index.html ou dans la section d'initialisation équivalente de votre framework SPA.

La balise script inclut l'attribut async. Cela évite que le snippet bloque le rendu de la page. C'est une décision de performance, mais cela signifie aussi que le script s'exécute après le premier rendu.

Le script stocke un identifiant dans le stockage local. SeaText utilise cet identifiant pour reconnaître les visites et appliquer la bonne variante. Si le stockage local est bloqué, cette reconnaissance échoue.

Les frameworks SPA tels que React, Vue et Angular montent l'application à partir de points d'entrée différents. Vous devez trouver le bon fichier. La documentation indique qu'il s'agit généralement de index.html ou d'un fichier JavaScript/TypeScript principal où le framework monte l'application.

Dans une SPA, cliquer sur un lien ne recharge pas la page. Le navigateur échange les composants. SeaText doit continuer à fonctionner lors de ces échanges. C'est pourquoi vous ne pouvez pas tester une seule route.

Liste de contrôle pour les tests en staging étape par étape

Utilisez cet ordre. Il passe de la configuration de build aux vérifications à l'exécution.

1. Définissez votre carte des routes. Notez chaque URL de production utilisée par la SPA.
2. Construisez l'application de la même manière que pour la production. Utilisez les mêmes variables d'environnement si possible.
3. Insérez SEATEXTCODEINTEGRATION dans le point d'entrée correct.
4. Servez le build de staging en HTTPS si possible. SeaText peut se comporter différemment sur localhost.
5. Activez le débogage ou la journalisation verbeuse de SeaText si le tableau de bord le propose.
6. Ouvrez DevTools et vérifiez l'onglet Réseau. Confirmez que le script SeaText renvoie 200.
7. Inspectez la balise script. Elle doit inclure l'attribut async.
8. Ouvrez la console. Recherchez les erreurs CSP, CORS ou JavaScript.
9. Ouvrez l'onglet Application. Confirmez que le stockage local contient un identifiant SeaText.
10. Naviguez à travers chaque route de la carte des routes. N'utilisez pas uniquement les routes typiques.
11. Simulez un changement de langue sur au moins une route profonde. Le contenu doit changer sans rechargement complet.
12. Consultez le tableau de bord SeaText. Confirmez que les variantes et les événements ont été enregistrés.

Traitez chaque vérification comme un succès ou un échec. Si l'une échoue, ne passez pas à l'étape suivante tant que vous n'avez pas compris pourquoi.

Liste de contrôle de couverture des routes et exemple de script Cypress

Une carte des routes est la liste des URL que votre SPA peut afficher. C'est la source de vérité pour les tests. Commencez par les liens de votre navigation, puis ajoutez les routes provenant des campagnes et des e-mails.

Ne vous arrêtez pas à l'accueil, au produit et au paiement. Les routes profondes cachent souvent des problèmes. Par exemple, une page de compte peut envoyer des en-têtes supplémentaires qui déclenchent des erreurs CORS.

Remplacez les routes d'exemple par les vôtres. L'important est que chaque route de production apparaisse dans le test.

Après le tableau, exécutez le script Cypress ci-dessous. Il visite chaque route et vérifie la requête réseau SeaText.

décrire('Couverture des routes SPA SeaText', () => {
  const routes = ['/', '/produits/exemple', '/tarifs', '/paiement', '/compte', '/blog/exemple', '/route-manquante'];

  it('charge le script SeaText sur chaque route', () => {
    cy.intercept('**/*seatext*').as('scriptSeatext');
    routes.forEach(route => {
      cy.visit(Cypress.env('URL_STAGING') + route);
      cy.wait('@scriptSeatext').its('response.statusCode').should('eq', 200);
    });
  });

  it('stocke un identifiant SeaText dans le stockage local', () => {
    cy.visit(Cypress.env('URL_STAGING'));
    cy.window().then(win => {
      const clés = Object.keys(win.localStorage).filter(k => k.toLowerCase().includes('seatext'));
      expect(clés.length).to.be.greaterThan(0);
    });
  });

  it('met à jour le contenu lors du changement de langue', () => {
    cy.visit(Cypress.env('URL_STAGING'));
    cy.get('[data-seatext-lang=es]').click();
    cy.contains('¡Bienvenido!').should('be.visible');
  });
});

Scénario hypothétique : un test de staging React

Imaginez Léna, une développeuse frontend. Elle doit lancer une boutique React avec SeaText. Elle commence par un build de staging similaire à la production.

Elle ouvre public/index.html et insère SEATEXTCODEINTEGRATION avant la balise body fermante. Elle exécute ensuite npm run build et sert la sortie à https://staging.example.com.

Dans DevTools, elle filtre l'onglet Réseau pour seatext. Le script renvoie 200. La balise script dans le panneau Éléments a l'attribut async.

Elle ouvre l'onglet Application et trouve une clé de stockage local contenant un identifiant SeaText. Elle navigue à travers la carte des routes. L'identifiant reste dans le stockage local sur chaque route.

Ensuite, elle clique sur le bouton de langue espagnole sur une page produit. Le titre change en « ¡Bienvenido! » sans rechargement. L'URL ne change pas.

Elle exécute ensuite la suite Cypress sur toutes les routes. Une route échoue car le serveur de staging renvoie une 404 pour une route côté client. Elle corrige le repli du serveur pour servir index.html et relance.

La suite passe. Le tableau de bord SeaText montre les variantes enregistrées. Léna met en ligne le snippet.

Compromis et limites

Le chargement asynchrone améliore les performances, mais peut provoquer un léger délai. Les utilisateurs peuvent brièvement voir le contenu original avant que SeaText applique les modifications. C'est un compromis, pas un bug.

Le stockage local n'est pas garanti. Certains navigateurs le bloquent en mode privé ou lorsque le stockage tiers est restreint. Votre application doit avoir la permission d'accéder au stockage local.

Les requêtes inter-origines peuvent échouer. Si votre SPA appelle plusieurs domaines, vérifiez la console pour les erreurs CORS. La documentation SeaText met en garde à ce sujet.

Les applications de staging utilisent souvent une politique de sécurité de contenu (CSP). Une CSP stricte peut bloquer le script SeaText. Ajoutez le domaine nécessaire à votre liste blanche et vérifiez.

Les points d'entrée des frameworks ne sont pas identiques. React, Vue et Angular ont chacun une structure de fichiers différente. Confirmez où votre framework s'initialise avant de coller le snippet.

Le staging doit refléter le routage de production. Si le serveur de staging ne renvoie pas index.html pour les routes côté client, les tests de route échouent pour la mauvaise raison.

La sortie de l'IA est variable. N'écrivez pas de tests qui attendent un contenu exact pour toujours. Vérifiez que les éléments de contenu existent et ont du texte.

Critères de réussite : toutes les routes renvoient 200 pour le script, aucune erreur console, l'identifiant de stockage local apparaît, le changement de langue fonctionne et le tableau de bord enregistre une variante. Si l'un de ces critères échoue, bloquez le lancement jusqu'à ce qu'il soit corrigé.

Débogage des échecs courants

Utilisez DevTools comme premier recours. Les onglets Console et Réseau indiquent généralement le problème exact.

• Le script ne se charge pas. Vérifiez l'onglet Réseau pour une 404 ou une requête échouée. Vérifiez l'URL du script, le DNS et les règles de pare-feu.
• L'identifiant de stockage local est manquant. Confirmez que le script s'est exécuté. Vérifiez les autorisations de stockage et les modes de stockage bloqués.
• Une erreur CORS apparaît. Lisez le message complet de la console. Vérifiez les en-têtes de réponse pour Access-Control-Allow-Origin.
• La CSP bloque le script. Recherchez un message Refusé de charger. Mettez à jour la politique de sécurité et relancez.
• Le changement de langue ne fait rien. Confirmez que le bouton utilise le sélecteur attendu. Vérifiez que la traduction est active pour cette route.
• Les tests passent en staging mais échouent en production. Comparez les cartes des routes, les variables d'environnement et les paramètres de build.
• Le script se charge mais le contenu ne change jamais. Ouvrez le tableau de bord pour voir si une variante a été enregistrée. Sinon, vérifiez la configuration de l'agent.

FAQ

• Le snippet SeaText doit-il être sur chaque fichier de page ? Non. Ajoutez-le une fois dans le point d'entrée HTML ou dans le fichier d'initialisation du framework.
• Dois-je utiliser un build de production pour les tests en staging ? Oui. Les commandes de build doivent correspondre à la production.
• Comment savoir si le script est asynchrone ? Inspectez la balise script dans DevTools. Elle doit inclure l'attribut async.
• Pourquoi mon test de route renvoie-t-il une 404 ? Le serveur de staging n'a probablement pas de repli SPA. Configurez-le pour servir index.html pour les routes côté client.
• Puis-je utiliser Playwright au lieu de Cypress ? Oui. La couverture des routes et les vérifications sont les mêmes.
• Que faire si un test passe localement mais échoue dans le pipeline de staging ? Comparez l'URL, les variables d'environnement et la sortie exacte du build.