How to Run a Specific Playwright Test File
Run one Playwright test file from the CLI, target a browser project, debug failures, and fix file discovery problems.
From your project directory, run:
npx playwright test path/to/example.spec.tsReplace the path with the file you want. Playwright treats the non-option argument as a filter against full test-file paths, so the path must match the file that Playwright discovers. The official CLI documentation describes this as running a single test file: Playwright command line reference.
Run one file step by step
- Open a terminal at the project root, where
playwright.config.ts(or another configured filename) is available. - Confirm the test file path. For example, a file at
tests/login.spec.tsis selected withtests/login.spec.ts. - Run the file command:
npx playwright test tests/login.spec.tsIf your project defines an npm, pnpm, Yarn, or Bun script, use that script when it adds required environment setup. Otherwise, npx playwright test uses the local Playwright installation.
Useful command variations
Run a JavaScript test file
npx playwright test tests/login.spec.jsRun a file in a nested directory
npx playwright test e2e/account/settings.spec.tsRun a configured browser project
npx playwright test tests/login.spec.ts --project=chromiumchromium must be the name of a project declared in your playwright.config.*. A project selector chooses an existing configuration; it does not install a browser or create a missing project. Without --project, Playwright runs the selected file in every configured project.
Debug the selected file
npx playwright test tests/login.spec.ts --debugTo focus the inspector near a source line, append a line number to the file filter:
npx playwright test tests/login.spec.ts:42 --debugThe line suffix helps target a particular test location; it is still a file-path filter, so quote the argument if your shell treats characters specially.
List tests without running them
npx playwright test tests/login.spec.ts --list--list collects and reports the tests that match without executing them. Use it before a long or expensive run to verify that the file and project selection are correct.
Skip project dependencies
npx playwright test tests/login.spec.ts --project=chromium --no-depsUse --no-deps only when you intentionally want to omit setup projects and their dependencies. A dependency may prepare data, start a service, or perform teardown needed by the selected project.
Run a single test inside the file
A file filter selects the file. To narrow execution further, add a test title filter:
npx playwright test tests/login.spec.ts -g "valid password"
# Equivalent long form:
npx playwright test tests/login.spec.ts --grep "valid password"This combines the file-path filter with a regular-expression match against test titles. Keep the file path and grep expression quoted when your shell can interpret spaces or metacharacters.
How file discovery affects selection
Playwright first discovers test files from configuration, then applies your command-line filter. If a file is not discovered, passing its path cannot run it. Check these settings in playwright.config.*:
| Setting | What it controls | What to check |
|---|---|---|
testDir |
Directory Playwright scans | Your file is below this directory |
testMatch |
Patterns that qualify as test files | The filename and extension match |
testIgnore |
Patterns excluded from discovery | The file is not ignored |
| projects | Browser and environment configurations | The requested project name exists |
By default, Playwright recognizes supported JavaScript and TypeScript test files whose names end in .spec or .test, but configuration can change the pattern. See the configuration documentation.
Interactive alternatives
UI Mode
npx playwright test --uiOpen UI Mode, then select a file, group, or test from the sidebar. This is useful when you want to inspect the test tree before choosing what to run.
VS Code extension
The Playwright VS Code extension adds run controls beside discovered tests and files. Use it when you prefer selecting a file graphically, while keeping the same project and configuration rules as the CLI.
Common errors and fixes
“No tests found”
- Run the command from the project root, or use the correct relative path.
- Check capitalization and spelling; path matching is against the full test-file path.
- Run
npx playwright test tests/login.spec.ts --listto see whether anything is collected. - Inspect
testDir,testMatch, andtestIgnore.
The file exists but is not selected
The file may not match the configured extension or pattern. Rename it to a supported .spec or .test filename, or update testMatch if the project intentionally uses another naming scheme.
“Project … not found”
--project accepts only a configured project name. Open playwright.config.*, copy the exact name, or omit the option to run all projects.
The command runs setup unexpectedly
A project dependency may be selected automatically. Remove --no-deps only when setup is required; add it when you deliberately want the selected project alone.
Shell characters change the result
The command-line argument is a regular-expression filter. Quote paths containing spaces, brackets, asterisks, dollar signs, or other shell metacharacters:
npx playwright test "tests/checkout [mobile].spec.ts"Debug mode does not open
Confirm that the file is collected first with --list, then rerun with --debug. A path that matches no discovered test cannot open a useful inspector session.
Performance and reliability considerations
- Reduce scope: A file filter avoids running unrelated files, but every test in that file and every selected project can still run.
- Choose one project: Add
--projectwhen a cross-browser run is unnecessary. - Keep dependencies intentional: Setup projects can add startup and teardown time; use
--no-depsonly when their work is not needed. - Verify collection first:
--listprevents waiting for a run that selected nothing. - Use the same working directory in CI: Relative paths depend on the directory from which the command starts.
- Prefer stable filters: A precise file path is easier to review and reproduce than a broad regular expression.
Running fewer tests can reduce execution time and resource use, but it does not change the test’s browser behavior, fixtures, retries, or web-server configuration. Those remain controlled by the selected project and Playwright configuration.
Or skip the browser setup
If your goal is a clean screenshot of a page rather than a browser test, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server also lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf.
See the ScreenshotNeo API documentation for options such as full-page capture, CSS selectors, device presets, dark mode, custom CSS and JavaScript, waits, request blocking, cookies, headers, caching, PDFs, and async jobs.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);There is a free plan with 1,000 screenshots per month and no card. Paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.
FAQ
What is the shortest command?
npx playwright test path/to/file.spec.ts.
Does a file run in every browser?
Yes, when multiple projects are configured and no --project option is supplied.
Can I run a file by line number?
Use the file path followed by :line, commonly with --debug, such as tests/login.spec.ts:42 --debug.
How do I know what Playwright collected?
Add --list; it reports collection without executing tests.
Why does changing the filename break the command?
The argument filters the discovered full path. Renaming or moving the file changes the path and may also make it fail testMatch.
