Playwright’s --debug mode sets the default timeout to zero, so a setup or test that times out in a normal run may appear to stop timing out when you debug it. That does not prove the underlying delay is fixed. First identify which timeout actually fired and whether your “global setup” is a globalSetup callback or a setup project.
Why a timeout can disappear in debug mode
npx playwright test --debug starts the Playwright Inspector, runs headed with one worker, stops after one failure, and sets the default timeout to zero. Removing the normal timeout can let a slow or stuck operation continue instead of producing the same timeout error. Debug mode is useful for seeing where execution pauses, but its different timeout behavior means a run that no longer times out has not necessarily been fixed.
Use the Inspector to step through actions and review actionability logs, then repeat the run under the original command and timeout settings. The second run tells you whether the change solved the problem or merely removed the deadline.
Identify which timeout expired
Playwright has several timeout scopes. The word “global” in a setup description or error does not by itself mean the whole-run globalTimeout expired. Match the complete error message to the operation and scope before changing a number.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
| Scope | Documented default or behavior | Where to investigate |
|---|---|---|
| Test | 30 seconds per test | Test configuration, project configuration, test.setTimeout, hooks, and fixtures. The test budget includes the test function, fixture setup, and beforeEach. |
| Assertion | 5 seconds per expect |
The assertion’s own timeout and the surrounding test’s remaining time. |
| Whole run | globalTimeout is unlimited/disabled by default |
Config and the CLI’s --global-timeout setting. It applies to the suite as a whole. |
| Action or navigation | No timeout by default | Per-action settings and use.actionTimeout or navigationTimeout. |
| Fixture | Usually shares the test timeout; a slow fixture can have its own timeout | Fixture setup and teardown duration, plus any fixture-specific budget. |
| Debug run | Default timeout is set to zero | Compare the debug run with the ordinary run; they do not have the same timeout conditions. |
These are documented defaults, not guarantees about a particular repository’s effective configuration. Config files, project overrides, test-level settings, and the installed Playwright version can change what applies. Check the version and resolved local configuration before treating a default as your actual limit.
Check what “global setup” means in this project
Config-level globalSetup
A globalSetup file exports one function that receives the full Playwright config and runs once before tests. It is a callback rather than a regular test project. It can return a teardown function; alternatively, teardown can be configured separately. The global setup guide also describes passing data such as tokens through environment variables.
This form can be appropriate for one-time work that does not need test-runner fixtures or setup traces. Its limited runner visibility matters during diagnosis: the callback does not appear in HTML reports and does not support setup tracing or fixtures in the documented comparison. Add explicit logging around each awaited phase so you can identify the last completed operation.
A setup project with project dependencies
A setup project runs setup tests before projects that depend on it. The tests use normal test-runner behavior, appear in reports, and can be recorded in traces; fixtures are available. Playwright recommends project dependencies when those reporting and tracing features are useful. The project approach improves observability, but it cannot make blocked or slow setup code finish by itself.
Recommended Free Tools
For example, the configuration shape is:
import { defineConfig } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'setup',
testMatch: /.*.setup.ts/,
},
{
name: 'chromium',
use: { browserName: 'chromium' },
dependencies: ['setup'],
},
],
});Put setup work in a matching test file such as auth.setup.ts, using the project’s configured fixtures and test-runner APIs. Adapt the project names and matching pattern to your repository; the snippet shows the dependency relationship, not a complete authentication implementation.
Be aware that --no-deps deliberately skips project dependencies. If setup is dependency-based, that flag can make it look as though setup did not run. Do not use it while checking whether the dependency setup project executed.
A practical diagnosis sequence
- Capture the exact error. Record the full timeout text, the operation named in it, and whether the failure occurs before tests, inside a setup test, in a fixture or hook, during an assertion, or at an action/navigation.
- Establish the setup mechanism. Inspect Playwright config for
globalSetupor a project withdependencies. Note any--no-depsflag in the command or CI configuration. - Find the applicable budget. Check test, assertion, action/navigation, fixture, and whole-run settings independently. Raising
globalTimeoutdoes not raise a test timeout, and raising the test timeout does not change an assertion’s own limit. - Expose progress. For a callback, log entry and completion around each awaited phase, including external service and browser waits. For a setup project, inspect its report entry and trace. The last completed log or trace step narrows the stalled operation; it does not, by itself, establish why that operation stalled.
- Use debug mode to inspect, not to certify. Run
npx playwright test --debugto observe execution in Inspector. Once you know where it pauses, rerun normally to confirm behavior against the original timeout. - Change only the relevant setting or operation. If a fixture legitimately needs longer, a fixture-specific timeout may be preferable to increasing every test’s budget. If an external wait never completes, investigate that wait and its own failure handling rather than giving the whole suite an arbitrary longer deadline.
Choosing a setup design that is easier to debug
| Need | Better fit | Trade-off |
|---|---|---|
| One-time callback work with no need for runner traces or fixtures | Config-level globalSetup |
It is not represented as a setup test in the HTML report and does not provide setup tracing or fixtures in the documented comparison; add explicit progress logging. |
| Setup that benefits from reports, traces, fixtures, and ordinary project behavior | Setup project with dependent projects | It remains ordinary test-runner work: slow or blocked setup still needs diagnosis, and --no-deps skips it. |
For either design, define what successful completion means and log phase boundaries. Keep setup failures distinct from downstream test failures where possible: otherwise a later browser test may be the first visible symptom of an earlier setup problem.
Common timeout symptoms and fixes
- It hangs in debug but does not report a timeout. Debug mode’s zero default timeout can explain the missing timeout report. Use Inspector to locate the wait, then test the fix without
--debug. - The whole run stops at a configured deadline. Check
globalTimeoutin config and--global-timeouton the command line. This budget covers the suite, not just setup. - A setup test fails at the test limit. Inspect its fixtures, hooks, and awaited operations. If one fixture is predictably slow, consider its own larger timeout rather than changing all tests.
- An assertion expires while setup or a test continues. Check the assertion’s timeout separately from the test’s remaining budget; changing the run-wide timeout does not change the assertion setting.
- A click or navigation waits indefinitely in an ordinary run. Actions and navigations have no timeout by default. Check the relevant per-operation setting and
use.actionTimeoutornavigationTimeout. - Setup appears not to have run. Determine whether it is a dependency project and whether the command includes
--no-deps. For a callback, add logs at the callback entry and around awaited work. - There is no useful report or trace for setup. If the setup is a config callback, that is a visibility limitation of this approach. A setup project makes setup tests reportable and traceable.
Or skip the browser setup
If your task is to capture a website screenshot rather than run browser-based setup or tests, ScreenshotNeo offers a one-request screenshot API. It does not fix a Playwright timeout or replace Playwright test setup. The example below saves a WebP response; see the ScreenshotNeo API documentation for request options.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteBest Value
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webp- Cookie/consent banners are accepted and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
- Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
- An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
- The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Playwright’s globalSetup have a timeout of its own?
The documented defaults distinguish callback execution from test and whole-run timeout settings; the exact effective limit depends on the project’s configuration and installed version. Check the actual error and local configuration rather than assuming a setting named globalTimeout governs every setup operation.
Can I trace a config-level global setup callback?
The documented comparison says config-level globalSetup does not support setup tracing. A setup project is the runner-managed alternative when setup traces and report entries are needed.
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.
