Estructura del proyecto Playwright

Después de inicializar correctamente un proyecto de Playwright, se generarán una serie de archivos y carpetas en el directorio de tu proyecto. Este capítulo explica en detalle el propósito de cada parte.

Resumen de la estructura del proyecto inicializado

Ejecutarnpm init playwright@latestDespués, se generará la siguiente estructura en el directorio del proyecto:

your-project/
├── playwright.config.ts      # Playwright 配置文件
├── package.json              # 项目依赖与脚本
├── package-lock.json         # 依赖锁定文件
├── tests/                    # 测试文件目录
│   └── example.spec.ts       # 示例测试文件
├── tests-examples/           # 更多示例测试（可选）
│   └── demo-todo-app.spec.ts
├── .github/                  # GitHub Actions 配置（可选）
│   └── workflows/
│       └── playwright.yml
└── node_modules/             # npm 依赖包

playwright.config.ts — Archivo de configuración

Este es el archivo de configuración principal de Playwright, que controla todos los aspectos de la ejecución de las pruebas.

Ejemplo

// Ruta del archivo: playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  // Directorio de archivos de prueba, ruta relativa a este archivo de configuración
  testDir: './tests',

  // Ejecutar todas las pruebas completamente en paralelo
  fullyParallel: true,

  // Si queda test.only en el código fuente, la compilación fallará en CI
  forbidOnly: !!process.env.CI,

  // Reintentar 2 veces tras un fallo en el entorno CI, sin reintentos en local
  retries: process.env.CI ? 2 : 0,

  // Usar un solo hilo en CI, usar el multihilo predeterminado en local
  workers: process.env.CI ? 1 : undefined,

  // Usar el reportero HTML
  reporter: 'html',

  // Configuración compartida por todas las pruebas
  use: {
    // URL base, basta con usar rutas relativas en las pruebas
    baseURL: 'http://localhost:3000',

    // Recopilar Trace al reintentar tras un fallo
    trace: 'on-first-retry',
  },

  // Configuración del proyecto para múltiples navegadores/dispositivos
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],

  // Iniciar el servidor de desarrollo local antes de que comiencen las pruebas (opcional)
  // webServer: {
  //   command: 'npm run start',
  //   url: 'http://localhost:3000',
  //   reuseExistingServer: !process.env.CI,
  // },
});

playwright.config.tsEs la entrada principal que controla el comportamiento de Playwright; el capítulo 15 explicará en detalle cada elemento de configuración.

package.json — Dependencias y scripts

Después de la inicialización,package.jsonse añadirá contenido relacionado con Playwright:

Ejemplo

{
  "devDependencies": {
    "@playwright/test": "^1.52.0"    // Playwright Test como dependencia de desarrollo
  },
  "scripts": {
    "test": "playwright test"         // Se puede ejecutar directamente con npm test
  }
}

También puedes añadir más scripts personalizados:

Ejemplo

{
  "scripts": {
    "test": "playwright test",
    "test:ui": "playwright test --ui",
    "test:headed": "playwright test --headed",
    "test:chromium": "playwright test --project=chromium",
    "test:debug": "playwright test --debug",
    "codegen": "playwright codegen"
  }
}

Directorio tests/ — Archivos de prueba

tests/El directorio es la ubicación predeterminada para los archivos de prueba (especificada por latestDirconfiguración).

El contenido del archivo de prueba de ejemplo inicializado es el siguiente:

Ejemplo

// Ruta del archivo: tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  // Navegar al sitio web oficial de Playwright
  await page.goto('https://playwright.dev/');

  // Verificar que el título de la página contiene "Playwright"
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  // Navegar al sitio web oficial de Playwright
  await page.goto('https://playwright.dev/');

  // Hacer clic en el enlace "Get started"
  await page.getByRole('link', { name: 'Get started' }).click();

  // Verificar que el título "Installation" aparece en la página
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Sugerencia para nombrar archivos de prueba: use el sufijo.spec.ts(TypeScript) o.spec.js(JavaScript).

Directorio tests-examples/ — Más ejemplos

Si elegiste incluir pruebas de ejemplo durante la inicialización,tests-examples/el directorio contendrá un ejemplo de prueba más completo:

demo-todo-app.spec.tsDemuestra un escenario de prueba completo de una aplicación Todo real, que incluye agregar tareas, cambiar el estado de completado, funciones de filtrado, etc.

Es una excelente referencia de aprendizaje; puedes ejecutarlo para ver el resultado:

npx playwright test tests-examples/

.github/workflows/ — Configuración de CI

Si elegiste agregar GitHub Actions durante la inicialización,.github/workflows/playwright.ymlel archivo se generará automáticamente.

Este flujo de trabajo ejecutará automáticamente las pruebas de Playwright cada vez que se haga push del código o se cree un PR.

Ubicación de almacenamiento del navegador

Los archivos binarios del navegador instalados por Playwright no están en el directorio del proyecto, sino en el directorio de caché del sistema operativo:

Sistema operativoRuta de almacenamiento del navegador
macOS
~/Library/Caches/ms-playwright/
Windows
%USERPROFILE%\AppData\Local\ms-playwright\
Linux
~/.cache/ms-playwright/

También puedes establecer una ruta de almacenamiento personalizada:

# 设置浏览器安装路径
export PLAYWRIGHT_BROWSERS_PATH=/your/custom/path
npx playwright install

node_modules/ — Paquetes de dependencias

Las dependencias principales de Playwright@playwright/testse instalan ennode_modules/.

Las dependencias incluyen el runtime completo de Playwright, incluida la capa de protocolo para comunicarse con el navegador.

Además de los paquetes de Node.js instalados mediante npm, Playwright también depende de los archivos binarios del navegador (almacenados en la caché del sistema); ambos son indispensables.

Otras extensiones