Recommended Free Tools
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
From your project directory, run npx playwright test path/to/example.spec.ts, replacing the path with the file you want. Playwright treats the argument as a filter against test-file paths, so the path must match a file Playwright discovers. Add --project=chromium to limit the run to a configured project, or --debug to inspect it interactively.
Run one test file from the command line
Open a terminal in the project root—the directory from which your project’s Playwright configuration and package scripts are normally used—and pass the test file path to the Playwright test command:
npx playwright test tests/login.spec.tsUse the path as it appears relative to the current working directory. For example, if the file is tests/account/profile.test.ts, run:
npx playwright test tests/account/profile.test.tsThis selects a file, not an individual test inside that file. Playwright collects the matching file and ordinarily runs all tests in it. If no project is specified, the run includes all configured projects that apply to the selected tests.
#1 Best Overall
Use your package manager or project script when appropriate
npx is the direct example, but a repository may define a package-manager script or use another package manager. In that case, use the project’s documented test script and pass the file filter through it. For npm scripts, an argument separator is commonly needed so the script receives the path:
npm test -- tests/login.spec.tsThat command only works if the project’s test script invokes Playwright in a way that accepts forwarded arguments. Check the project’s package.json if the path is ignored or interpreted by the script rather than by Playwright.
Limit the run to a configured project
A Playwright project is a named configuration, commonly used for a browser or other test environment. To run the file only in a project named chromium, use:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →npx playwright test tests/login.spec.ts --project=chromiumReplace chromium with a project name that actually exists in the configuration. The option selects a configured project; it does not install a browser or create a project. Without --project, Playwright runs the selected tests across all applicable configured projects.
Projects can declare dependencies and teardown behavior. A selected project may therefore cause related setup or teardown projects to run. Add --no-deps only when you specifically want to skip project dependencies and teardowns and know the selected project can run without them:
npx playwright test tests/login.spec.ts --project=chromium --no-depsSkipping dependencies can leave required test data or services unprepared. If the test relies on project setup, do not use this option.
Debug the selected file or a particular location
To open Playwright Inspector for a file run, add --debug:
npx playwright test tests/login.spec.ts --debugTo target a source line while debugging, append a colon and line number to the file filter:
npx playwright test tests/login.spec.ts:42 --debugUse the line form when you want to investigate the test near that location rather than merely start the file’s normal run. The line number must refer to a location in the test file. Debug mode is an interactive workflow, so it is less suitable than a normal CLI run for unattended automation or a repeatable CI job.
Check which files Playwright will collect
If you want to verify selection before execution, add --list:
npx playwright test tests/login.spec.ts --listThis reports collected tests without running them. It is useful when a file filter appears to match nothing, or when you want to confirm that the intended file is included before spending time on execution.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →The non-option file argument is a filter matched against full test-file paths. It is not a promise that every string will be resolved as a literal filesystem path. Characters such as * and $ can have meaning to the shell or to pattern matching. Quote a path or filter when needed:
npx playwright test 'tests/ui flows/login.spec.ts'Quoting protects shell-sensitive characters and spaces from being interpreted before Playwright receives the argument. It does not change which files Playwright is configured to discover.
Choose between CLI, UI Mode, and VS Code
| Method | How to start a file run | Best fit |
|---|---|---|
| CLI | npx playwright test tests/login.spec.ts |
Repeatable terminal runs, scripts, and explicit project selection. |
| UI Mode | Run npx playwright test --ui, then select a file in the sidebar. |
Interactive exploration and choosing a file, group, or test visually. |
| VS Code extension | Use the run control beside a file in the editor. | Starting a file run while working in the editor. |
For a straightforward repeatable run, the CLI file filter is the most direct method. UI Mode and the VS Code extension provide graphical selection; use Inspector or UI Mode when the purpose is interactive investigation rather than just executing a file.
Why a file may not run
Playwright must both discover the file and match the filter you supplied. If the command returns no matching tests, check these points in order:
- Current directory: Confirm the terminal is at the intended project root and that the path is relative to that directory. A path correct from a nested folder may be wrong from the root, and vice versa.
- Exact name and extension: Check spelling, capitalization, directory names, and the actual filename. The default test-file pattern includes JavaScript or TypeScript files ending in
.specor.testwith supported module extensions. - Configured discovery rules: Inspect
testDir,testMatch, andtestIgnorein the applicableplaywright.config.*. They determine where Playwright scans, which files match, and which paths are excluded. A project can also define its own test directory and matching rules. - Project selection: If you used
--project, confirm that its name is present in the configuration and that its discovery settings include the file. - Shell interpretation: Quote filters containing spaces or special characters such as
*or$, then retry with--listto see what Playwright collects.
Common errors and practical fixes
“No tests found” or an empty collection
The filter may not match the full discovered file path, or the file may be outside the configured test directory or excluded by matching rules. Check the working directory and configuration, then run the command with --list. Avoid assuming that a file is eligible just because it ends in .spec.ts; project-specific discovery settings can change that.
The path contains spaces or wildcard characters
The shell may split or expand an unquoted argument. Quote it so Playwright receives the intended filter, for example npx playwright test 'tests/account setup/login.spec.ts'. If the filter still does not select the expected file, inspect the collected paths with --list.
The project name is rejected or selects nothing
--project accepts a configured project name, not a browser label that you assume exists. Check playwright.config.* for the exact name and its test-directory or match settings. Selecting a project also does not install its browser.
The test fails because setup did not run
A project dependency may be responsible for preparing the environment. If you added --no-deps, remove it and retry. Use that option only for a deliberate run in which the selected project does not need dependency setup or teardown.
Free tools Windows power users keep installed
One-click scans. No signup required.
The command runs more browsers than intended
If the configuration includes multiple projects, omitting --project can run the file in all applicable projects. Select one configured project explicitly when you need a single environment, or keep the broader run when cross-project coverage is the goal.
Performance, repeatability, and cost considerations
The file filter reduces the test scope, but it does not necessarily mean only one browser run: without a project selector, the file can still run in multiple configured projects. For a narrower diagnostic run, combine the file path with the project that reproduces the issue. That avoids unrelated project runs, while preserving any required setup.
For reliable comparisons, run from a consistent working directory and use the same configuration and project selection each time. Use --list to check collection separately from execution when investigating selection problems. A debug or UI session is valuable for interactive diagnosis, but use the normal command without those interactive modes when you need an ordinary repeatable run.
No universal runtime or monetary cost can be inferred from the file command alone: execution time depends on the tests and the configured projects and environment. The main avoidable waste is running a broader set of projects than intended or repeatedly investigating a discovery mismatch without first checking collection.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server, not a Playwright test runner: it cannot run or replace the Playwright command above. If your actual goal is to capture a page rather than execute tests, one GET request returns an image or PDF. See the ScreenshotNeo website and API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpWith a page-capture workflow, ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.
Sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Can I use a filename without a .spec or .test suffix?
The default discovery pattern covers JavaScript and TypeScript test files ending in .spec or .test, with supported module extensions. Your configuration can change that pattern.
How can I see the current Playwright CLI options?
Run npx playwright --help to retrieve the CLI’s available commands and arguments.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
