Node Modules y npm Explicados para Ingenieros QA

Cuando clonas un repositorio de tests de Playwright y obtienes Cannot find module '@playwright/test', olvidaste ejecutar npm install: node_modules nunca se commitea al control de versiones porque puede alcanzar varios cientos de megabytes, y npm install lo regenera desde package.json en segundos. El error relacionado, Executable doesn't exist at /home/user/.cache/ms-playwright/chromium-XXX, significa que los binarios del navegador están desactualizados y necesitas ejecutar npx playwright install. Esta guía cubre qué controlan package.json, package-lock.json y node_modules, los comandos que vas a ejecutar regularmente, y la sintaxis de prefijos de versión que determina cuándo npm actualiza un paquete automáticamente.

Qué es npm

1. Mantiene un registro de paquetes de JavaScript (más de 2 millones)

2. Descarga paquetes de ese registro en tu proyecto

3. Registra qué paquetes necesita tu proyecto

Cuando alguien escribe código útil (como el framework Playwright), lo publica como paquete en npm. Cualquier otra persona puede instalar ese paquete en lugar de escribir el mismo código desde cero.

Playwright, TypeScript, ESLint, Faker.js, dotenv: todos son paquetes de npm que potencian tu setup de automatización de tests.

El archivo package.json

Todo proyecto de Node.js tiene un archivo package.json. Es el descriptor del proyecto: dice qué es, qué necesita y cómo ejecutarlo.

Un package.json típico de un proyecto de Playwright:

{
  "name": "mis-tests-playwright",
  "version": "1.0.0",
  "scripts": {
    "test": "npx playwright test",
    "test:headed": "npx playwright test --headed",
    "test:ui": "npx playwright test --ui"
  },
  "devDependencies": {
    "@playwright/test": "^1.44.0",
    "typescript": "^5.4.5"
  }
}

Secciones clave

• name: el nombre de tu proyecto
• scripts: comandos que puedes ejecutar con npm run
• devDependencies: paquetes necesarios para el desarrollo (herramientas de testing, linters)
• dependencies: paquetes necesarios para ejecutar la app en producción (no relevante para proyectos solo de tests)

dependencies vs. devDependencies

| | dependencies | devDependencies |

|-|----------------|------------------|

| Cuándo se usa | En producción (para ejecutar la app) | Solo en desarrollo (build, testing, linting) |

| Ejemplo | express, react, axios | playwright, typescript, eslint |

| Flag de instalación | npm install nombre-paquete | npm install -D nombre-paquete |

Para repositorios de automatización QA, casi todo va en devDependencies. Estás construyendo herramientas de testing, no una aplicación de producción.

La carpeta node_modules

Cuando ejecutas npm install, npm:

1. Lee package.json

2. Descarga todos los paquetes listados desde el registro de npm

3. Los pone en node_modules/

4. También instala TODAS SUS dependencias (y las dependencias de esas dependencias...)

Por eso node_modules puede tener miles de archivos incluso para un proyecto con 3 dependencias directas. Playwright, por ejemplo, trae decenas de paquetes de los que depende internamente.

Verifica tu .gitignore:

node_modules/

Esta línea tiene que estar. Si no está, agrégala.

package-lock.json

Cuando npm instala paquetes, también crea o actualiza package-lock.json. Este archivo registra las versiones exactas de cada paquete instalado (incluyendo las dependencias transitivas).

Por qué importa

Los comandos npm esenciales

# Instalar todas las dependencias listadas en package.json
npm install

# Instalar un paquete específico y agregarlo a devDependencies
npm install -D @faker-js/faker

# Instalar un paquete específico y agregarlo a dependencies
npm install dotenv

# Eliminar un paquete
npm uninstall @faker-js/faker

# Actualizar todos los paquetes a sus últimas versiones compatibles
npm update

# Verificar paquetes con vulnerabilidades de seguridad conocidas
npm audit

# Corregir vulnerabilidades de seguridad automáticamente (donde sea posible)
npm audit fix

# Ejecutar un script definido en package.json
npm run test
npm run test:headed

# Listar todos los paquetes instalados
npm list --depth=0

# Ver la versión de un paquete específico
npm list playwright

El comando npx

# Ejecutar el test runner de Playwright (usa la versión local en node_modules)
npx playwright test

# Instalar los navegadores de Playwright
npx playwright install

# Abrir el modo UI de Playwright
npx playwright test --ui

# Ejecutar codegen
npx playwright codegen https://lab.becomeqa.com

Cuando ejecutas npx playwright test, encuentra Playwright dentro de la carpeta node_modules/.bin/ de tu proyecto y lo ejecuta. Eso garantiza que estés usando la versión específica de Playwright del proyecto, no una instalada globalmente.

Configurar un proyecto de Playwright desde cero

# Crear y entrar a un nuevo directorio
mkdir mi-proyecto-tests && cd mi-proyecto-tests

# Inicializar un proyecto npm (crea package.json)
npm init -y

# Instalar Playwright
npm init playwright@latest

# Listo: Playwright se instala a sí mismo con sus dependencias

O si estás agregando Playwright a un proyecto existente:

npm install -D @playwright/test
npx playwright install

Errores comunes y cómo resolverlos

Error "Cannot find module"

Error: Cannot find module '@playwright/test'

Navegadores de Playwright desactualizados

Error: Executable doesn't exist at /home/user/.cache/ms-playwright/chromium-XXX

Vulnerabilidades de seguridad

found 3 vulnerabilities (1 moderate, 2 high)

Conflictos en node_modules después de un git pull

Si alguien actualizó las dependencias, tu node_modules local puede estar desactualizado:

rm -rf node_modules
npm install

Es la opción nuclear pero siempre funciona.

Por qué las versiones tienen ^ y ~

En package.json:

"@playwright/test": "^1.44.0"

| Símbolo | Significado | Ejemplo |

|---------|-------------|---------|

| ^1.44.0 | Compatible con 1.44.0 (actualiza minor y patch) | Acepta 1.45.0, 1.50.0 pero no 2.0.0 |

| ~1.44.0 | Aproximadamente 1.44.0 (solo actualiza patch) | Acepta 1.44.1, 1.44.9 pero no 1.45.0 |

| 1.44.0 | Exactamente 1.44.0 | Sin actualizaciones |

Para proyectos de automatización de tests, ^ (caret) es el estándar. Te mantiene actualizado con mejoras menores mientras te protege de cambios mayores que rompen compatibilidad.

Lo que necesitás saber como ingeniero QA

Necesitas saber

• Qué hace npm install y cuándo ejecutarlo (siempre después de clonar, después de que alguien actualice package.json)
• Qué contiene package.json y cómo leerlo
• La diferencia entre dependencies y devDependencies
• Cómo funciona npm run test (ejecuta el script test de package.json)
• Por qué node_modules no se commitea a git

No necesitas saber

Publicar paquetes en npm, cómo funciona el registro de paquetes internamente, o las diferencias entre Yarn y pnpm (gestores de paquetes alternativos que hacen lo mismo: Playwright funciona con cualquiera de ellos).