¿Cómo funciona internamente el mecanismo storageState en Playwright?

storageState extrae datos de dos subsistemas del navegador mediante CDP/BiDi: 1) Todas las cookies activas del BrowserContext (incluyendo flags HttpOnly, Secure, SameSite y atributos de expiración); 2) Claves y valores de localStorage por cada origen visitado. Al crear un nuevo contexto con la opción storageState, Playwright inyecta estos registros antes de cargar el primer documento, asegurando que las peticiones iniciales viajen con las cookies de sesión válidas.

¿Qué ocurre si auth.setup.ts falla con un error?

Gracias a dependencies: ['setup'], si el proyecto setup finaliza con un código de error, Playwright cancela de inmediato la ejecución de todos los proyectos dependientes, marcándolos como omitidos (skipped). Esto ahorra recursos de CI evitando cientos de fallos inevitables.

¿Cómo deben probarse los flujos de cierre de sesión (Logout) si el contexto usa un storageState global?

El test de logout carga una copia en memoria del storageState. Cuando el test pulsa 'Cerrar sesión', las cookies se eliminan exclusivamente dentro del BrowserContext aislado de esa prueba. El archivo .auth/*.json en disco no sufre alteraciones, por lo que las pruebas paralelas continúan ejecutándose sin interrupciones.

¿Por qué se prefiere la autenticación directa por API en auth.setup.ts frente a la automatización de formularios de UI?

Las llamadas API directas (mediante el fixture request de Playwright) se completan en 50–150 ms sin requerir motores de renderizado, análisis CSS o ejecución de bundles JS. El login por UI tarda 2–4 segundos y está expuesto a demoras de red y fallos por animaciones. Se puede validar el formulario de login con un único test E2E aislado, mientras el resto de la suite reutiliza sesiones generadas por la API rápida.

¿Cómo se mantiene el aislamiento de pruebas cuando múltiples workers paralelos comparten la misma sesión de usuario?

Si los tests son de solo lectura, compartir storageState es totalmente seguro. Cuando realizan mutaciones, se aplican dos estrategias: 1) Segmentar datos con prefijos únicos de entidad (ej. entity_workerId_timestamp); 2) Prescindir del storageState compartido en favor de fixtures de API dinámicas que crean usuarios efímeros antes del test y los eliminan durante el teardown.

¿storageState almacena datos de sessionStorage e IndexedDB?

Por defecto, storageState solo captura cookies y localStorage. sessionStorage está ligado al ciclo de vida de una pestaña específica y no se incluye. IndexedDB tampoco se serializa automáticamente. Para persistir sessionStorage o IndexedDB, se escribe un helper con page.evaluate() que serialice dichos datos a JSON y los restaure en un nuevo contexto mediante page.addInitScript().

¿Cómo se gestiona la autenticación de dos factores (2FA / TOTP) en suites automatizadas?

Existen tres enfoques habituales: 1) Configurar una cabecera de bypass o configuración en el servidor de pruebas que desactive MFA para cuentas dedicadas de E2E; 2) Generar contraseñas de un solo uso en tiempo real dentro del código del test mediante librerías como otplib y un secreto TOTP compartido; 3) Autenticar cuentas de servicio directamente mediante llamadas a la API de autenticación del backend omitiendo MFA.

Gestión de autenticación y Storage State — Pruebas y Automatización QA

Base arquitectónica#

En las aplicaciones empresariales modernas, la gran mayoría de los escenarios de usuario requieren autenticación. Si cada escenario de prueba repite los pasos de inicio de sesión a través de formularios gráficos dentro de un hook beforeEach, el pipeline de pruebas sufre una degradación catastrófica del rendimiento:

Sobrecarga criptográfica: Los algoritmos de hashing de contraseñas en el backend (Argon2, bcrypt) están diseñados intencionalmente para ser intensivos en cómputo (evaluar un único hash consume entre 100 y 300 ms de CPU en el servidor). En una suite de 300 pruebas, se desperdician hasta 90 segundos de tiempo de procesador puro únicamente recalculando contraseñas.
Latencia de renderizado de UI: Navegar a /login, renderizar el árbol del formulario, teclear caracteres, esperar respuestas de la API y gestionar redirecciones a /dashboard añade de 2 a 4 segundos a cada prueba.
Crecimiento lineal en CI: En una suite de 500 pruebas, el pipeline de CI pierde más de 25 minutos exclusivamente reenviando formularios de inicio de sesión.

text

+-----------------------------------------------------------------------------+
|               Antipatrón tradicional: Inicios de sesión repetitivos en UI   |
|                                                                             |
|  Test 1: [UI Login: 3s] -> [Lógica de Test: 1s] = 4s                        |
|  Test 2: [UI Login: 3s] -> [Lógica de Test: 0.5s] = 3.5s                    |
|  Test 3: [UI Login: 3s] -> [Lógica de Test: 2s] = 5s                        |
|  TOTAL para 100 tests: ~300 segundos (5 minutos) perdidos escribiendo claves|
+-----------------------------------------------------------------------------+

+-----------------------------------------------------------------------------+
|               Playwright 2026: Arquitectura de reutilización Storage State  |
|                                                                             |
|  Setup Project (1 vez): [API/UI Login: 1.5s] -> Persistencia en storageState|
|                                                      │                      |
|                       ┌──────────────────────────────┴────────────────┐     |
|                       ▼                                               ▼     |
|  Worker 1 (Contexto con storageState)        Worker 2 (Contexto con storageState)
|  Test 1: [Lógica de Test: 1s]                Test 2: [Lógica de Test: 0.5s]  |
|  Test 3: [Lógica de Test: 2s]                Test 4: [Lógica de Test: 1.2s]  |
|  TOTAL para 100 tests: ~35 segundos de tiempo de ejecución acumulado        |
+-----------------------------------------------------------------------------+

Playwright transforma radicalmente este paradigma separando la autenticación de la ejecución de escenarios mediante Storage State combinado con el grafo de Project Dependencies.

Modelo mental#

En el modelo de pruebas de Playwright, la ejecución autenticada se divide en dos fases operativas independientes:

Fase de preparación (Setup Phase): Un proyecto de configuración dedicado se ejecuta de forma previa y obligatoria antes de lanzar los workers de prueba. Completa la autenticación (mediante peticiones API ultrarrápidas o interacción de interfaz) y serializa el estado de la sesión (cookies y localStorage) en disco como un artefacto JSON.
Fase de ejecución paralela (Execution Phase): Los workers paralelos instancian sesiones aisladas de BrowserContext, hidratándolas inmediatamente con la instantánea en caché storageState.json. El contexto navega directamente a las rutas protegidas sin pasar por formularios de inicio de sesión.

text

+-----------------------------------------------------------------------------+
|                          1. SETUP PROJECT (setup)                           |
|                                                                             |
|   auth.setup.ts  ──► POST /api/auth/login ──► Obtener JWT + Set-Cookie      |
|                            │                                                |
|                            ▼                                                |
|   page.context().storageState({ path: '.auth/admin.json' })                 |
|   page.context().storageState({ path: '.auth/user.json' })                  |
+-----------------------------------------------------------------------------+
                                     │
                                     ▼ (Guardar instantáneas JSON en disco)
+-----------------------------------------------------------------------------+
|                      Directorio .auth/ (Ignorado en Git)                    |
|   - admin.json (Cookies + LocalStorage con rol de Administrador)            |
|   - user.json  (Cookies + LocalStorage con rol de Usuario Estándar)         |
+-----------------------------------------------------------------------------+
                                     │
            ┌────────────────────────┴────────────────────────┐
            ▼                                                 ▼
+------------------------------------+   +------------------------------------+
|  Project: "admin-tests"            |   |  Project: "customer-tests"         |
|  use: {                            |   |  use: {                            |
|    storageState: '.auth/admin.json'|   |    storageState: '.auth/user.json' |
|  }                                 |   |  }                                 |
|                                    |   |                                    |
|  Worker A: dashboard.spec.ts       |   |  Worker C: profile.spec.ts         |
|  Worker B: settings.spec.ts        |   |  Worker D: orders.spec.ts          |
+------------------------------------+   +------------------------------------+

Project: Unidad modular de configuración y ejecución.
Project Dependencies: Grafo de dependencias de tareas.
Role-Based Matrix: Matriz de sesiones basada en roles.

Sintaxis y API#

1. Estructura del archivo `storageState.json`#

El artefacto de estado cumple un esquema estricto que describe cookies y orígenes de almacenamiento:

json

{
  "cookies": [
    {
      "name": "session_token",
      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "domain": "localhost",
      "path": "/",
      "expires": 1789038400,
      "httpOnly": true,
      "secure": false,
      "sameSite": "Lax"
    }
  ],
  "origins": [
    {
      "origin": "http://localhost:3000",
      "localStorage": [
        {
          "name": "user_meta",
          "value": "{\"id\":\"usr_01\",\"role\":\"admin\",\"theme\":\"dark\"}"
        }
      ]
    }
  ]
}

2. Configuración del grafo de dependencias en `playwright.config.ts`#

typescriptplaywright.config.ts

import { defineConfig, devices } from '@playwright/test';
import path from 'path';

/** Rutas absolutas a los estados serializados por rol */
export const ADMIN_AUTH_FILE = path.join(__dirname, '.auth/admin.json');
export const USER_AUTH_FILE = path.join(__dirname, '.auth/user.json');

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? '100%' : undefined,

  projects: [
    // 1. Proyecto de inicialización: se ejecuta primero para generar las sesiones
    {
      name: 'setup',
      testMatch: /.*\.setup\.ts/,
    },

    // 2. Suite de pruebas con permisos de administrador
    {
      name: 'admin-chromium',
      testMatch: /.*admin.*\.spec\.ts/,
      use: {
        ...devices['Desktop Chrome'],
        storageState: ADMIN_AUTH_FILE,
      },
      dependencies: ['setup'], // Dependencia estricta del proyecto setup
    },

    // 3. Suite de pruebas con permisos de usuario estándar
    {
      name: 'user-chromium',
      testMatch: /.*user.*\.spec\.ts/,
      use: {
        ...devices['Desktop Chrome'],
        storageState: USER_AUTH_FILE,
      },
      dependencies: ['setup'],
    },

    // 4. Pruebas públicas sin autenticación (Invitado)
    {
      name: 'public-chromium',
      testMatch: /.*public.*\.spec\.ts/,
      use: {
        ...devices['Desktop Chrome'],
        // storageState omitido: contexto nuevo de incógnito
      },
    },
  ],
});

Aplicado en producción#

1. Autenticación de alta velocidad mediante API directa en `auth.setup.ts`#

Completar formularios mediante interfaces gráficas es entre 10 y 20 veces más lento que realizar llamadas HTTP directas. El proyecto setup alcanza una velocidad óptima autenticándose directamente contra la API de autenticación del backend utilizando el fixture request de Playwright, capturando cookies y escribiendo en storageState.

typescripte2e/auth.setup.ts

import { test as setup, expect } from '@playwright/test';
import { ADMIN_AUTH_FILE, USER_AUTH_FILE } from '../playwright.config';

setup.describe('Inicialización global de estados de sesión', () => {
  setup('autentica administrador mediante API y persiste el estado', async ({ request, page }) => {
    // 1. Envía petición HTTP POST directa al endpoint de login (sin renderizado de UI)
    const loginResponse = await request.post('/api/auth/login', {
      data: {
        email: process.env.E2E_ADMIN_EMAIL ?? '[email protected]',
        password: process.env.E2E_ADMIN_PASSWORD ?? 'SecureEnterprisePassword2026!',
      },
    });

    expect(loginResponse.ok()).toBeTruthy();
    const { token, user } = (await loginResponse.json()) as { token: string; user: { id: string; role: string } };

    // 2. Navega al dominio base para inicializar localStorage bajo el origen correcto
    await page.goto('/favicon.ico');

    // 3. Inyecta los tokens en localStorage mediante evaluate
    await page.evaluate(
      ({ authToken, userData }) => {
        localStorage.setItem('auth_token', authToken);
        localStorage.setItem('user_profile', JSON.stringify(userData));
      },
      { authToken: token, userData: user }
    );

    // 4. Guarda el estado consolidado (cookies de la respuesta + localStorage) en disco
    await page.context().storageState({ path: ADMIN_AUTH_FILE });
  });

  setup('autentica usuario estándar mediante formulario de UI (flujo de respaldo)', async ({ page }) => {
    // Flujo alternativo para proveedores que requieren tokens CSRF complejos o redirecciones externas
    await page.goto('/login');
    await page.getByLabel('Correo electrónico').fill(process.env.E2E_USER_EMAIL ?? '[email protected]');
    await page.getByLabel('Contraseña').fill(process.env.E2E_USER_PASSWORD ?? 'StandardPassword2026!');
    await page.getByRole('button', { name: 'Iniciar sesión' }).click();

    // Espera navegación al panel protegido
    await page.waitForURL('**/dashboard');
    await expect(page.getByRole('heading', { name: 'Mis cursos' })).toBeVisible();

    // Persiste el estado de sesión del usuario
    await page.context().storageState({ path: USER_AUTH_FILE });
  });
});

2. Acceso instantáneo a pantallas protegidas en pruebas de funcionalidades#

En las pruebas asignadas al proyecto admin-chromium, el contexto del navegador ya inicia completamente autenticado:

typescripte2e/specs/admin-settings.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Panel de control administrativo', () => {
  test('administrador puede configurar límites de asignación de tokens', async ({ page }) => {
    // La sesión ya está preautenticada: navega directamente a la ruta protegida
    await page.goto('/admin/security/token-limits');

    // Valida la presencia de controles privilegiados
    await expect(page.getByRole('heading', { name: 'Configuración de seguridad' })).toBeVisible();

    const limitInput = page.getByLabel('Máximo de tokens por worker');
    await limitInput.fill('64');
    await page.getByRole('button', { name: 'Guardar cambios' }).click();

    await expect(page.getByRole('status')).toHaveText('Configuración actualizada con éxito');
  });
});

3. Pruebas dinámicas con múltiples roles dentro de un mismo test#

Cuando se valida una matriz de control de acceso basada en roles (RBAC) donde un solo escenario comprueba interacciones entre distintos roles:

typescripte2e/fixtures/auth-fixtures.ts

import { test as base, type Page } from '@playwright/test';
import { ADMIN_AUTH_FILE, USER_AUTH_FILE } from '../../playwright.config';

export interface RoleFixtures {
  adminPage: Page;
  userPage: Page;
}

export const test = base.extend<RoleFixtures>({
  adminPage: async ({ browser }, use) => {
    const context = await browser.newContext({ storageState: ADMIN_AUTH_FILE });
    const page = await context.newPage();
    await use(page);
    await context.close();
  },

  userPage: async ({ browser }, use) => {
    const context = await browser.newContext({ storageState: USER_AUTH_FILE });
    const page = await context.newPage();
    await use(page);
    await context.close();
  },
});

export { expect } from '@playwright/test';

Errores comunes#

Ошибка: Confirmar artefactos storageState.json en el repositorio Git

Los artefactos de estado contienen tokens JWT activos, hashes de sesión y credenciales sensibles. Subir estos archivos compromete la seguridad y genera fallos a otros desarrolladores cuando los tokens expiran.

gitignore

# ❌ INCORRECTO: Ausencia de .auth en .gitignore
# ✅ CORRECTO: Añadir al .gitignore raíz del proyecto:
.auth/
playwright/.auth/

Ошибка: Mutación de estado de un usuario compartido entre workers paralelos

Si 20 pruebas paralelas comparten una única cuenta de administrador y un test muta preferencias globales (como cambiar el idioma a alemán o eliminar una organización), las otras 19 pruebas fallarán con condiciones de carrera impredecibles. Solución: Utilizar estados compartidos preautenticados estrictamente para escenarios de solo lectura (Read-Only). Para acciones destructivas (borrado de cuentas, mutaciones de facturación), generar usuarios efímeros (Ephemeral Users) mediante fixtures de API.

Ошибка: Expiración del token (TTL) durante ejecuciones prolongadas en CI

Si un JWT tiene una duración de 5 minutos y la suite de pruebas en CI tarda 12 minutos en completarse, las pruebas situadas al final de la cola fallarán con código 401 Unauthorized. Solución: Configurar un endpoint dedicado de pruebas con TTL extendido (por ejemplo, 2 horas) en entornos de no producción, o implementar la renovación de tokens (refresh token) dentro de un fixture.

Ошибка: Omisión de dependencies: ['setup'] en playwright.config.ts

Si no se indica dependencies: ['setup'], Playwright ejecutará las pruebas funcionales al mismo tiempo que auth.setup.ts. Los tests intentarán leer los archivos .auth/*.json antes de que existan y fallarán inmediatamente con ENOENT: no such file or directory.

Algoritmo paso a paso: Flujo del Storage State#

Ciclo de vida de Storage State en Playwright

Configurar proyecto SetupSetup Project

Declarar el proyecto setup en playwright.config.ts apuntando a auth.setup.ts.

Autenticación vía API o UIAuthenticate

Enviar petición HTTP a /api/auth/login o completar el formulario gráfico una única vez.

Serializar estado en .auth/*.jsonSerialize State

Llamar a page.context().storageState({ path: '.auth/role.json' }) para guardar cookies y almacenamiento.

Declarar dependencias de proyectosLink Dependencies

Configurar dependencies: ['setup'] y las opciones storageState en los proyectos de prueba.

Ejecución paralela de alta velocidadFast Parallel Run

Cientos de workers inician contextos preautenticados sin demoras en formularios de login.

Preguntas de entrevista#

Preguntas de entrevista7 preguntas

Temas relacionados#

Temas relacionados

Arquitectura Playwright 2026: CDP, aislamiento y Auto-waiting— Aislamiento de BrowserContext y mecánica de sesiones.Page Object Model (POM) y Clean Fixtures— Inyección de páginas basadas en roles mediante fixtures de test.extend.Mocking de red y simulación HAR en Playwright— Sustitución de endpoints de autenticación y simulación de fallos de red.Visual, Contract Testing & CI/CD— Optimización de colas paralelas y sharding en CI/CD.

Gestión de autenticación y Storage State

Base arquitectónica#

Modelo mental#

Sintaxis y API#

1. Estructura del archivo storageState.json#

2. Configuración del grafo de dependencias en playwright.config.ts#

Aplicado en producción#

1. Autenticación de alta velocidad mediante API directa en auth.setup.ts#

2. Acceso instantáneo a pantallas protegidas en pruebas de funcionalidades#

3. Pruebas dinámicas con múltiples roles dentro de un mismo test#

Errores comunes#

Ошибка: Confirmar artefactos storageState.json en el repositorio Git

Ошибка: Mutación de estado de un usuario compartido entre workers paralelos

Ошибка: Expiración del token (TTL) durante ejecuciones prolongadas en CI

Ошибка: Omisión de dependencies: ['setup'] en playwright.config.ts

Algoritmo paso a paso: Flujo del Storage State#

Preguntas de entrevista#

Temas relacionados#

Base arquitectónica#

Modelo mental#

Sintaxis y API#

1. Estructura del archivo storageState.json#

2. Configuración del grafo de dependencias en playwright.config.ts#

Aplicado en producción#

1. Autenticación de alta velocidad mediante API directa en auth.setup.ts#

2. Acceso instantáneo a pantallas protegidas en pruebas de funcionalidades#

3. Pruebas dinámicas con múltiples roles dentro de un mismo test#

Errores comunes#

Ошибка: Confirmar artefactos storageState.json en el repositorio Git

Ошибка: Mutación de estado de un usuario compartido entre workers paralelos

Ошибка: Expiración del token (TTL) durante ejecuciones prolongadas en CI

Ошибка: Omisión de dependencies: ['setup'] en playwright.config.ts

Algoritmo paso a paso: Flujo del Storage State#

Preguntas de entrevista#

Temas relacionados#

1. Estructura del archivo `storageState.json`#

2. Configuración del grafo de dependencias en `playwright.config.ts`#

1. Autenticación de alta velocidad mediante API directa en `auth.setup.ts`#

1. Estructura del archivo `storageState.json`#

2. Configuración del grafo de dependencias en `playwright.config.ts`#

1. Autenticación de alta velocidad mediante API directa en `auth.setup.ts`#