Node Modules e npm Explicados para Engenheiros QA

Quando você clona um repositório de testes Playwright e recebe Cannot find module '@playwright/test', esqueceu de rodar npm install. O node_modules nunca é commitado no controle de versão porque pode chegar a centenas de megabytes, e o npm install o regenera a partir do package.json em segundos. O erro relacionado, Executable doesn't exist at /home/user/.cache/ms-playwright/chromium-XXX, significa que os binários do navegador estão desatualizados e precisam de npx playwright install.

O que é o npm

O npm (Node Package Manager) é uma ferramenta que:

1. Mantém um registro de pacotes JavaScript (mais de 2 milhões deles)

2. Faz download de pacotes desse registro para o seu projeto

3. Rastreia quais pacotes o seu projeto precisa

Quando alguém escreve código útil (como o framework Playwright), publica como um pacote no npm. Qualquer outro desenvolvedor pode instalar esse pacote em vez de escrever o mesmo código do zero.

Playwright, TypeScript, ESLint, Faker.js, dotenv: todos são pacotes npm que sustentam o seu setup de automação de testes.

O arquivo package.json

Todo projeto Node.js tem um arquivo package.json. Ele é o descritor do projeto: diz o que o projeto é, o que ele precisa e como executá-lo.

Um package.json típico de projeto Playwright fica assim:

{
  "name": "meus-testes-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"
  }
}

• name: Nome do projeto
• scripts: Comandos que você pode executar com npm run
• devDependencies: Pacotes necessários para desenvolvimento (ferramentas de teste, linters)
• dependencies: Pacotes necessários para rodar o app em produção (não relevante para projetos só de testes)

dependencies vs. devDependencies

| | dependencies | devDependencies |

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

| Quando é usado | Em produção (rodando o app) | Só em desenvolvimento (build, testes, lint) |

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

| Flag de instalação | npm install nome-do-pacote | npm install -D nome-do-pacote |

Para repositórios de automação de QA, quase tudo vai em devDependencies. Você está criando ferramental de testes, não uma aplicação de produção.

A pasta node_modules

Quando você roda npm install, o npm:

1. Lê o package.json

2. Faz download de todos os pacotes listados do registro do npm

3. Os coloca em node_modules/

4. Também instala TODAS AS DEPENDÊNCIAS desses pacotes (e as dependências delas...)

É por isso que node_modules pode ter milhares de arquivos mesmo num projeto com apenas 3 dependências diretas. O Playwright, por exemplo, puxa dezenas de pacotes dos quais depende internamente.

Verifique seu .gitignore:

node_modules/

Essa linha precisa estar lá. Se não estiver, adicione.

package-lock.json

Quando o npm instala pacotes, ele também cria/atualiza o package-lock.json. Esse arquivo registra as versões exatas de cada pacote instalado, incluindo dependências transitivas.

Os comandos npm essenciais

# Instalar todas as dependências listadas no package.json
npm install

# Instalar um pacote específico e adicionar a devDependencies
npm install -D @faker-js/faker

# Instalar um pacote específico e adicionar a dependencies
npm install dotenv

# Remover um pacote
npm uninstall @faker-js/faker

# Atualizar todos os pacotes para as versões compatíveis mais recentes
npm update

# Verificar pacotes com vulnerabilidades de segurança conhecidas
npm audit

# Corrigir vulnerabilidades automaticamente (quando possível)
npm audit fix

# Rodar um script definido no package.json
npm run test
npm run test:headed

# Listar todos os pacotes instalados
npm list --depth=0

# Ver a versão de um pacote específico
npm list playwright

O comando npx

O npx executa um pacote npm sem instalá-lo globalmente. Você vai vê-lo o tempo todo com o Playwright:

# Rodar o test runner do Playwright (usa a versão local em node_modules)
npx playwright test

# Instalar navegadores do Playwright
npx playwright install

# Abrir o modo UI do Playwright
npx playwright test --ui

# Rodar o codegen
npx playwright codegen https://lab.becomeqa.com

Quando você roda npx playwright test, ele encontra o Playwright dentro da pasta node_modules/.bin/ local e o executa. Isso garante que você está usando a versão específica do projeto, não uma instalada globalmente.

Configurando um novo projeto Playwright do zero

# Criar e entrar em um novo diretório
mkdir meu-projeto-de-testes && cd meu-projeto-de-testes

# Inicializar projeto npm (cria o package.json)
npm init -y

# Instalar o Playwright
npm init playwright@latest

# Pronto — o Playwright se instala junto com suas dependências

Ou, se você está adicionando o Playwright a um projeto existente:

npm install -D @playwright/test
npx playwright install

Problemas comuns e soluções

Erro "Cannot find module"

Error: Cannot find module '@playwright/test'

Navegadores Playwright desatualizados

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

Vulnerabilidades de segurança

found 3 vulnerabilities (1 moderate, 2 high)

Conflitos em node_modules após git pull

Se alguém atualizou as dependências, seu node_modules local pode estar desatualizado:

rm -rf node_modules
npm install

É a solução radical, mas sempre funciona.

Por que as versões têm ^ e ~

No package.json:

"@playwright/test": "^1.44.0"

| Símbolo | Significado | Exemplo |

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

| ^1.44.0 | Compatível com 1.44.0 (atualiza minor e patch) | Aceita 1.45.0, 1.50.0, mas não 2.0.0 |

| ~1.44.0 | Aproximadamente 1.44.0 (atualiza só patch) | Aceita 1.44.1, 1.44.9, mas não 1.45.0 |

| 1.44.0 | Exatamente 1.44.0 | Sem atualizações |

Para projetos de automação de testes, ^ (caret) é o padrão. Mantém você atualizado com melhorias menores e protege contra mudanças incompatíveis em versões maiores.

O que um QA engineer precisa saber

• O que npm install faz e quando rodar (sempre após clonar, após alguém atualizar o package.json)
• O que o package.json contém e como lê-lo
• A diferença entre dependencies e devDependencies
• Como npm run test funciona (executa o script test do package.json)
• Por que node_modules não é commitado no git

• Como publicar pacotes no npm
• Como o registro de pacotes funciona internamente
• Yarn, pnpm (gerenciadores de pacotes alternativos) — fazem a mesma coisa, o Playwright funciona com qualquer um deles

Isso é suficiente para configurar projetos, instalar dependências, rodar testes e debugar os problemas de setup mais comuns que você vai encontrar.