Introduction: What Does the Playwright Cannot Find Module Error Mean?
The playwright cannot find module error fix problem occurs when Node.js cannot locate a package, file, or module required by your Playwright test.
You may see errors such as:
Error: Cannot find module ‘@playwright/test’
or:
Cannot find module ‘./pages/LoginPage’
Another common TypeScript message is:
Cannot find module ‘@playwright/test’ or its corresponding type declarations.
These errors do not always mean Playwright itself is broken.
The underlying cause could be:
- @playwright/test is not installed.
- node_modules is missing.
- The wrong directory is being used.
- package.json does not contain the dependency.
- An import path is incorrect.
- TypeScript cannot resolve the module.
- ESM/CommonJS configuration is inconsistent.
- A project was cloned without running npm install.
- CI/CD dependencies were not installed correctly.
- Node.js or npm versions are incompatible with the project.
This playwright cannot find module error fix tutorial explains how to identify the exact cause instead of repeatedly reinstalling everything.
Common Playwright Module Errors and Their Messages
| Error | Likely Cause |
| Cannot find module ‘@playwright/test’ | Playwright Test package missing |
| Cannot find module ‘./LoginPage’ | Incorrect local import |
| Cannot find module ‘playwright’ | playwright package missing |
| Cannot find module … or its corresponding type declarations | TypeScript resolution/package issue |
| ERR_MODULE_NOT_FOUND | ESM/module resolution problem |
| MODULE_NOT_FOUND | Node.js cannot locate requested module |
| Works locally, fails in CI | Dependencies not installed correctly |
The correct Playwright module error solution depends on which category the error belongs to.
1. Check Node.js and npm Versions
Start with:
node –version
npm –version
For example:
Node.js v22.x
npm 10.x
Also check your Playwright version:
npx playwright –version
Or:
npm list @playwright/test
If the command reports that the package is missing, continue with installation.
Problem → Cause → Diagnostic Step → Fix → Verification → Best Practice
Problem: Playwright cannot find the package.
Cause: The package is not installed in the current project.
Diagnostic Step:
npm list @playwright/test
Fix:
npm install -D @playwright/test
Verification:
npx playwright –version
Best Practice: Keep Node.js, npm, and Playwright versions consistent across development and CI environments.
2. Installing Playwright Correctly
For a new Playwright TypeScript project, you can use:
npm init playwright@latest
The setup wizard can create the Playwright project structure.
Alternatively, install the package manually:
npm install -D @playwright/test
Then install browsers:
A typical project may contain:
playwright-project/
├── tests/
│ └── example.spec.ts
├── playwright.config.ts
├── package.json
├── package-lock.json
└── tsconfig.json
A basic test is:
import { test, expect } from ‘@playwright/test’;
test(‘homepage test’, async ({ page }) => {
await page.goto(‘https://example.com’);
await expect(
page.getByRole(‘heading’, {
name: ‘Example Domain’
})
).toBeVisible();
});
Run it:
npx playwright test
3. Check package.json and Project Dependencies
Open package.json and verify that Playwright exists in devDependencies.
For example:
{
“devDependencies”: {
“@playwright/test”: “^1.55.0”
}
}
If the dependency is missing:
npm install -D @playwright/test
Then verify:
npm list @playwright/test
You should see the installed version.
Important distinction
There is a difference between:
Missing package
and:
Incorrect import
If this fails:
import { test } from ‘@playwright/test’;
the package may be missing.
But if this fails:
import LoginPage from ‘./pages/LoginPage’;
the problem is probably your local file path or module configuration.
4. Fix Incorrect Imports and Module Paths
Consider this structure:
tests/
login.spec.ts
pages/
LoginPage.ts
The correct import from tests/login.spec.ts may be:
import { LoginPage } from ‘../pages/LoginPage’;
A common mistake is:
import { LoginPage } from ‘./pages/LoginPage’;
because ./ points to the tests directory.
Problem → Cause → Diagnostic Step → Fix → Verification → Best Practice
Problem: Cannot find module ‘./pages/LoginPage’.
Cause: Incorrect relative path.
Diagnostic Step: Compare the import location with the actual directory structure.
Fix:
import { LoginPage } from ‘../pages/LoginPage’;
Verification:
npx playwright test
Best Practice: Keep a consistent project structure and avoid unnecessarily deep relative paths.
5. Fix TypeScript and tsconfig.json Issues
A basic Playwright TypeScript configuration can look like:
{
“compilerOptions”: {
“target”: “ES2022”,
“module”: “CommonJS”,
“moduleResolution”: “Node”,
“strict”: true,
“esModuleInterop”: true,
“skipLibCheck”: true
}
}
Then your test can use:
import { test, expect } from ‘@playwright/test’;
Cannot find module ‘@playwright/test’
first verify that the package actually exists.
Do not immediately modify paths, baseUrl, or other advanced TypeScript settings.
Best Practice
First determine whether the problem is:
- Missing npm package
- Incorrect local path
- TypeScript module resolution
- ESM/CommonJS mismatch
Only then change the appropriate configuration.
6. Handling node_modules and Lock-File Problems
A very common Playwright npm error occurs when package.json exists but node_modules does not.
For example:
package.json
package-lock.json
may exist after cloning a repository, but:
node_modules/
does not.
Run:
npm install
For CI environments, prefer:
npm ci
when a valid lock file is committed.
If the installation appears corrupted, you can recreate dependencies.
On macOS/Linux:
rm -rf node_modules
npm ci
On Windows PowerShell:
Remove-Item -Recurse -Force node_modules
npm ci
Then:
npx playwright –version
Best Practice
Do not delete package-lock.json as the first troubleshooting step. The lock file helps reproduce the intended dependency tree.
7. Fixing Playwright Errors After Cloning a Project
Suppose you clone:
git clone <repository>
cd playwright-project
Then immediately run:
npx playwright test
You may get:
Cannot find module ‘@playwright/test’
The likely reason is simple: dependencies have not been installed.
Run:
npm ci
or:
npm install
Then:
npx playwright install
Finally:
npx playwright test
Recommended workflow
Clone repository
↓
npm ci
↓
Install Playwright browsers if required
↓
This is one of the most common Playwright module not found after npm install troubleshooting scenarios.
8. Debugging ESM vs CommonJS Module Errors
Modern Node.js projects may use either CommonJS or ESM.
CommonJS:
{
“compilerOptions”: {
“module”: “CommonJS”
}
}
ESM projects may contain:
{
“type”: “module”
}
Mixing configurations carelessly can produce errors such as:
ERR_MODULE_NOT_FOUND
or unexpected import behavior.
For example:
import { test, expect } from ‘@playwright/test’;
is standard modern TypeScript syntax, but your project configuration still needs to be internally consistent.
Diagnostic checklist
Check:
package.json
tsconfig.json
playwright.config.ts
Node.js version
import/export syntax
Do not randomly switch between:
require()
and:
import …
until you understand which module system the project uses.
9. Real-World Playwright Cannot Find Module Examples
Example 1: @playwright/test Missing
Problem
Cannot find module ‘@playwright/test’
Cause
The package is not installed.
Diagnostic
npm list @playwright/test
Fix
npm install -D @playwright/test
Verification
npx playwright –version
Best Practice
Install Playwright as a project dependency instead of relying on a global installation.
Example 2: Page Object Import Failure
Problem
Cannot find module ‘./LoginPage’
Cause
The import path does not match the actual file location.
Incorrect
import { LoginPage } from ‘./LoginPage’;
Correct
If the page object is one directory above:
import { LoginPage } from ‘../pages/LoginPage’;
Verification
Confirm the actual file:
pages/LoginPage.ts
Best Practice
Check the relative path before changing TypeScript configuration.
Example 3: CI Module Error
Problem
Tests work locally but CI reports:
Cannot find module ‘@playwright/test’
Root Cause
CI checked out the source code but did not install dependencies.
Fix
name: Playwright Tests
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
– name: Checkout
uses: actions/checkout@v4
– name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
– name: Install dependencies
run: npm ci
– name: Install browsers
run: npx playwright install –with-deps
– name: Run tests
run: npx playwright test
Verification
Add:
– name: Check Playwright
run: npx playwright –version
This immediately shows whether Playwright is available in CI.
Common Mistakes and Solutions
| Mistake | Better Solution |
| Running tests before npm install | Install project dependencies |
| Using global Playwright | Install locally in the project |
| Incorrect relative import | Verify actual directory structure |
| Deleting lock file unnecessarily | Keep package-lock.json |
| Using npm install randomly in CI | Prefer reproducible npm ci |
| Ignoring Node.js version | Standardize Node versions |
| Mixing ESM and CommonJS | Use a consistent module strategy |
| Changing TypeScript paths immediately | First verify package/import path |
| Forgetting CI dependencies | Run npm ci in pipeline |
| Confusing browser installation with package installation | Install both when required |
Playwright Dependency-Management Best Practices
For reliable Playwright TypeScript projects:
- Install @playwright/test locally.
- Commit package.json.
- Commit package-lock.json.
- Use npm ci in CI/CD.
- Standardize Node.js versions.
- Keep Playwright versions controlled.
- Install required browsers.
- Avoid unnecessary global packages.
- Use consistent ESM/CommonJS settings.
- Keep imports simple and predictable.
- Verify dependencies after cloning.
- Cache npm dependencies carefully in CI.
- Reproduce CI module errors locally when possible.
A useful troubleshooting sequence is:
Check error
↓
Check Node/npm
↓
Check package.json
↓
npm list package
↓
Check node_modules
↓
Check import path
↓
Check tsconfig.json
↓
Check ESM/CommonJS
↓
Check CI installation
Playwright Cannot Find Module Interview Questions
Why does Playwright say Cannot Find Module?
Usually because the requested package or file cannot be resolved. Check whether the dependency is installed, whether the import path is correct, and whether TypeScript/Node module resolution is configured correctly.
How do you fix Cannot find module ‘@playwright/test’?
Run:
npm install -D @playwright/test
Then verify:
npx playwright –version
What is the difference between npm install and npm ci?
npm install installs dependencies and can update the lock file. npm ci performs a clean, reproducible installation based on the lock file and is commonly preferred in CI.
Why does Playwright work locally but fail in CI?
The CI environment may not install dependencies, may use a different Node.js version, may use a different working directory, or may have a different dependency lock state.
How do you debug a TypeScript module error?
Check the actual file path, import statement, tsconfig.json, package installation, module resolution, and ESM/CommonJS configuration.
Should Playwright be installed globally?
No. A project-local installation is preferable because the project’s package version is then explicit and reproducible.
FAQs
Why does Playwright say Cannot Find Module?
Node.js cannot locate the requested package or file. The most common causes are missing dependencies, incorrect import paths, or module-resolution configuration problems.
How do I fix Playwright Cannot Find Module error?
Check the package with npm list, install missing dependencies, verify imports, inspect tsconfig.json, and make sure CI runs npm ci.
Why does Playwright module not found after npm install?
The installation may have occurred in the wrong directory, failed partially, used an incompatible dependency state, or the import may refer to a different module.
How do I fix a Playwright TypeScript module error?
First determine whether the package is installed. Then check the import path and TypeScript module-resolution settings before changing advanced configuration.
Why does Playwright module error happen in CI?
CI may not have installed dependencies or may be using a different Node.js version, working directory, lock file, or module configuration.
Is Cannot find module a Playwright browser installation error?
Not necessarily. A missing @playwright/test package is different from a missing browser executable. Browser installation is a separate step.