Cómo probar la integración de SeaText SPA antes de salir en vivo

Antes de que SeaText salga en vivo, pruébelo en un entorno de ensayo. El objetivo es simple: demostrar que el fragmento se carga, que el almacenamiento local funciona, que los cambios de idioma funcionan y que cada ruta se comporta correctamente. Esta guía le ofrece una lista de verificación práctica, un mapa de rutas y un script de muestra de Cypress.

Por qué es importante probar en ensayo

SeaText reescribe el texto de la página y crea variantes. Si el fragmento falla, los visitantes pueden ver el texto original, el texto traducido o una interfaz rota. Eso es difícil de diagnosticar en producción.

El ensayo le permite detectar estos problemas antes de que llegue el tráfico real. Puede probar la carga asíncrona, el almacenamiento local y el comportamiento entre orígenes de manera segura.

La documentación de SeaText señala tres riesgos específicos de SPA: carga asíncrona, permisos de almacenamiento local y problemas entre orígenes. Una prueba de ensayo debe cubrir los tres.

Sin ensayo, un error puede afectar a todos los visitantes. Con ensayo, puede corregirlo antes del lanzamiento.

Cómo funciona el fragmento de SeaText dentro de una SPA

SeaText es un fragmento de JavaScript. La documentación usa el marcador de posición SEATEXTCODEINTEGRATION. Lo inserta en el cuerpo de index.html o en la sección de inicialización equivalente de su marco SPA.

La etiqueta de script incluye el atributo async. Eso evita que el fragmento bloquee la representación de la página. Es una decisión de rendimiento, pero también significa que el script se ejecuta después de la primera pintura.

El script almacena una ID en el almacenamiento local. SeaText usa esa ID para reconocer visitas y aplicar la variante correcta. Si el almacenamiento local está bloqueado, ese reconocimiento falla.

Los marcos SPA como React, Vue y Angular montan la aplicación desde diferentes puntos de entrada. Debe encontrar el archivo correcto. La documentación dice que esto suele ser index.html o un archivo principal de JavaScript/TypeScript donde el marco se monta.

En una SPA, hacer clic en un enlace no recarga la página. El navegador intercambia componentes. SeaText debe seguir funcionando en esos intercambios. Por eso no puede probar solo una ruta.

Lista de verificación de prueba de ensayo paso a paso

Use este orden. Se mueve desde la configuración de compilación hasta las comprobaciones en tiempo de ejecución.

1. Defina su mapa de rutas. Anote cada URL de producción que use la SPA.
2. Compile la aplicación de la misma manera que compila para producción. Use las mismas variables de entorno cuando sea posible.
3. Inserte SEATEXTCODEINTEGRATION en el punto de entrada correcto.
4. Sirva la compilación de ensayo a través de HTTPS si es posible. SeaText puede comportarse de manera diferente en localhost.
5. Active el registro de depuración o detallado de SeaText si el panel lo ofrece.
6. Abra DevTools y revise la pestaña Red. Confirme que el script de SeaText devuelve 200.
7. Inspeccione la etiqueta de script. Debe incluir el atributo async.
8. Abra la Consola. Busque errores de CSP, CORS o JavaScript.
9. Abra la pestaña Aplicación. Confirme que el almacenamiento local tiene una ID de SeaText.
10. Navegue por cada ruta en el mapa de rutas. No use solo rutas típicas.
11. Simule un cambio de idioma en al menos una ruta profunda. El texto debe cambiar sin una recarga completa.
12. Revise el panel de SeaText. Confirme que se registraron variantes y eventos.

Trate cada comprobación como aprobado o reprobado. Si una falla, no pase al siguiente paso hasta que entienda por qué.

Lista de verificación de cobertura de rutas y script de muestra de Cypress

Un mapa de rutas es la lista de URLs que su SPA puede mostrar. Es la fuente de verdad para las pruebas. Comience con los enlaces en su navegación, luego agregue rutas de campañas y correos electrónicos.

No se detenga en inicio, producto y pago. Las rutas profundas a menudo ocultan problemas. Por ejemplo, una página de cuenta puede enviar encabezados adicionales que activan CORS.

Reemplace las rutas de ejemplo con las suyas. Lo importante es que cada ruta de producción aparezca en la prueba.

Después de la tabla, ejecute el script de Cypress a continuación. Visita cada ruta y verifica la solicitud de red de SeaText.

describe('Cobertura de rutas SPA de SeaText', () => {
  const rutas = ['/', '/productos/ejemplo', '/precios', '/pago', '/cuenta', '/blog/ejemplo', '/ruta-inexistente'];

  it('carga el script de SeaText en cada ruta', () => {
    cy.intercept('**/*seatext*').as('scriptSeatext');
    rutas.forEach(ruta => {
      cy.visit(Cypress.env('STAGING_URL') + ruta);
      cy.wait('@scriptSeatext').its('response.statusCode').should('eq', 200);
    });
  });

  it('almacena una ID de SeaText en el almacenamiento local', () => {
    cy.visit(Cypress.env('STAGING_URL'));
    cy.window().then(ventana => {
      const claves = Object.keys(ventana.localStorage).filter(k => k.toLowerCase().includes('seatext'));
      expect(claves.length).to.be.greaterThan(0);
    });
  });

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

Escenario hipotético: una ejecución de ensayo en React

Imagine a Lena, una desarrolladora frontend. Necesita lanzar una tienda React con SeaText. Comienza con una compilación de ensayo similar a producción.

Abre public/index.html e inserta SEATEXTCODEINTEGRATION antes de la etiqueta de cierre del cuerpo. Luego ejecuta npm run build y sirve la salida en https://staging.example.com.

En DevTools, filtra la pestaña Red por seatext. El script devuelve 200. La etiqueta de script en el panel Elementos tiene el atributo async.

Abre la pestaña Aplicación y encuentra una clave de almacenamiento local que contiene una ID de SeaText. Navega por el mapa de rutas. La ID permanece en el almacenamiento local en cada ruta.

Luego, hace clic en el botón de idioma español en una página de producto. El titular cambia a “¡Bienvenido!” sin recargar. La URL no cambia.

Luego ejecuta la suite de Cypress contra todas las rutas. Una ruta falla porque el servidor de ensayo devuelve un 404 para una ruta del lado del cliente. Corrige el respaldo del servidor para que sirva index.html y vuelve a ejecutar.

La suite pasa. El panel de SeaText muestra variantes registradas. Lena envía el fragmento.

Compensaciones y limitaciones

La carga asíncrona mejora el rendimiento, pero puede causar un breve retraso. Los usuarios pueden ver brevemente el texto original antes de que SeaText aplique los cambios. Es una compensación, no un error.

El almacenamiento local no está garantizado. Algunos navegadores lo bloquean en modo privado o cuando se restringe el almacenamiento de terceros. Su aplicación debe tener permiso para acceder al almacenamiento local.

Las solicitudes entre orígenes pueden fallar. Si su SPA llama a múltiples dominios, revise la consola para ver errores de CORS. La documentación de SeaText advierte sobre esto.

Las aplicaciones de ensayo a menudo usan Política de Seguridad de Contenido. Una CSP estricta puede bloquear el script de SeaText. Agregue el dominio necesario a su lista de permitidos y verifique.

Los puntos de entrada del marco no son idénticos. React, Vue y Angular tienen cada uno una estructura de archivos diferente. Confirme dónde inicializa su marco antes de pegar el fragmento.

El ensayo debe reflejar el enrutamiento de producción. Si el servidor de ensayo no devuelve index.html para rutas del lado del cliente, las pruebas de ruta fallan por la razón equivocada.

La salida de IA es variable. No escriba pruebas que esperen texto exacto para siempre. Afirme que los elementos de contenido existen y tienen texto.

Criterios de aprobación: todas las rutas devuelven 200 para el script, sin errores de consola, la ID de almacenamiento local aparece, el cambio de idioma funciona y el panel registra una variante. Si alguno de estos falla, bloquee el lanzamiento hasta que se corrija.

Depuración de fallas comunes

Use DevTools como su primera parada. Las pestañas Consola y Red generalmente indican el problema exacto.

• El script no se carga. Revise la pestaña Red para ver un 404 o una solicitud fallida. Verifique la URL del script, DNS y reglas de firewall.
• Falta la ID de almacenamiento local. Confirme que el script se ejecutó. Revise los permisos de almacenamiento y los modos de almacenamiento bloqueados.
• Aparece un error de CORS. Lea el mensaje completo de la consola. Revise los encabezados de respuesta para Access-Control-Allow-Origin.
• CSP bloquea el script. Busque un mensaje de Refused to load. Actualice la política de seguridad y vuelva a ejecutar.
• El cambio de idioma no hace nada. Confirme que el botón usa el selector esperado. Revise que la traducción esté activa para esa ruta.
• Las pruebas pasan en ensayo pero fallan en producción. Compare mapas de rutas, variables de entorno y configuraciones de compilación.
• El script se carga pero el texto nunca cambia. Abra el panel para ver si se registró una variante. Si no, revise la configuración del agente.

Preguntas frecuentes

• ¿El fragmento de SeaText necesita estar en cada archivo de página? No. Agrégalo una vez en el punto de entrada HTML o en el archivo de inicialización del marco.
• ¿Debo usar una compilación de producción para las pruebas de ensayo? Sí. Los comandos de compilación deben coincidir con producción.
• ¿Cómo sé que el script es asíncrono? Inspeccione la etiqueta de script en DevTools. Debe incluir el atributo async.
• ¿Por qué mi prueba de ruta devuelve un 404? El servidor de ensayo probablemente no tiene un respaldo SPA. Configúrelo para que sirva index.html para rutas del lado del cliente.
• ¿Puedo usar Playwright en lugar de Cypress? Sí. La cobertura de rutas y las comprobaciones son las mismas.
• ¿Qué pasa si una prueba pasa localmente pero falla en la canalización de ensayo? Compare URL, variables de entorno y la salida exacta de compilación.