Free tools Windows power users keep installed
One-click scans. No signup required.
test.use() lets you set Playwright Test options or fixtures for every test in one file or for tests inside a test.describe() group. Put the call at test-file or describe scope, before the tests that need it. Do not call it from beforeEach or beforeAll; Playwright reports that as an error. Keep shared defaults in playwright.config.ts, project-specific environments in a project’s use object, and use test.use() for narrow overrides.
This article follows the current Playwright documentation. Option names, defaults and availability can change, so check the Test API reference and TestOptions reference for the version installed in your project.
What test.use() configures
The API is a scoped configuration call:
test.use({ option: value });It can set Playwright options and override fixtures for a single test file or a test.describe() group. Tests run by the Playwright Test runner receive those settings when it creates their browser context or other runner resources. If your test explicitly creates a context and passes an option there, the explicit context option takes precedence.
Typical options include:
- Browser and launch:
browserName(chromium,firefoxorwebkit),channel,headlessandlaunchOptions. - Context and navigation:
baseURL,storageState,contextOptions,viewportanduserAgent. - Emulation:
locale,timezoneId,geolocation,permissionsandcolorScheme. - Network:
offline,proxy,extraHTTPHeaders,httpCredentialsandignoreHTTPSErrors. - Artifacts:
screenshot,videoandtrace.
Some settings are direct options while launch and context settings can be grouped under launchOptions and contextOptions. Use the versioned API reference for the complete type definitions.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall#1 Best Overall
Set options for one test file
Import test from @playwright/test and call test.use() before the tests:
import { test, expect } from '@playwright/test';
test.use({ locale: 'fr-FR' });
test('renders localized content', async ({ page }) => {
await page.goto('/');
await expect(page.locator('html')).toHaveAttribute('lang', 'fr');
});Every test in this file uses the French locale unless a narrower setting changes it. The same pattern works for a viewport, storage state, headers, color scheme, recording behavior or another supported option:
import { test } from '@playwright/test';
test.use({
baseURL: 'http://localhost:3000',
colorScheme: 'dark',
viewport: { width: 1280, height: 720 },
trace: 'on-first-retry'
});
test('dashboard', async ({ page }) => {
await page.goto('/dashboard');
});Use a file-level call when all tests in that file represent the same environment. Keeping the setting near the tests also makes the exception visible during code review.
Set options for a test.describe() group
Place the call inside a describe callback to scope it to that group:
import { test, expect } from '@playwright/test';
test.describe('French language pages', () => {
test.use({ locale: 'fr-FR' });
test('shows localized content', async ({ page }) => {
await page.goto('/');
await expect(page.locator('h1')).toContainText('Bonjour');
});
test('keeps the locale for checkout', async ({ page }) => {
await page.goto('/checkout');
});
});
test('English landing page', async ({ page }) => {
await page.goto('/');
});The standalone test is outside the group and does not inherit the group’s locale. Nested describes can provide progressively narrower settings; the innermost applicable scope is the one to use for that test.
Choose the right configuration scope
Playwright has three related but different places for configuration:
| Scope | Best use | Example |
|---|---|---|
Top-level use in playwright.config.ts |
Defaults shared by the test suite | baseURL, retry tracing, common headers |
Project-level use |
A distinct browser or environment in a project matrix | Desktop Chrome versus a mobile device, or a different locale |
test.use() |
A file or describe-group exception | One suite needing dark mode or a special storage state |
A representative configuration is:
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry'
},
projects: [
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
locale: 'de-DE'
}
}
]
});Global defaults apply broadly. A project defines a repeatable browser/environment variant and is the correct mechanism for actual multi-browser coverage. A local test.use() override does not replace the project matrix; it changes the selected project’s settings for the matching file or group.
Device presets and override order
Device descriptors contain several values, often including a viewport. Spread the descriptor first and put your explicit override afterward:
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'desktop-sized-mobile-emulation',
use: {
...devices['Pixel 5'],
viewport: { width: 1280, height: 720 }
}
}
]
});JavaScript object properties written later win. Reversing the order can silently restore the device’s viewport and make the configuration appear ineffective. The Emulation guide lists the available descriptors and related emulation settings.
Reset or remove an inherited setting
A narrower scope can restore an option to the value inherited from configuration by setting that option to undefined, as documented in the configuration guide:
test.use({ baseURL: undefined });That is not identical to every possible “unset” operation. The guide also shows a long-form fixture definition when the goal is to completely unset baseURL. Use the documented form that matches your intent and confirm the resulting value in the current Playwright version rather than assuming all undefined cases behave alike.
Why test.use() cannot go in hooks
test.use() describes the test definition before execution; hooks run as part of execution. Therefore this is invalid:
test.beforeEach(async () => {
test.use({ colorScheme: 'dark' }); // Error
});The API reference explicitly says it is an error to call test.use() inside beforeEach or beforeAll. Move the setting to file or describe scope. If the value must vary at runtime, use a fixture, create a context with explicit options, or split the cases into separate projects/groups. Do not try to mutate a context after the page has already been created and expect runner-level configuration to be reapplied.
Inheritance and explicit context creation
Contexts created through the Playwright instance used by the test runner inherit applicable use options. An explicit option passed while creating a context wins:
test.use({ locale: 'fr-FR' });
test('explicit context override', async ({ browser }) => {
const context = await browser.newContext({ locale: 'en-US' });
const page = await context.newPage();
await page.goto('http://localhost:3000');
await context.close();
});This pattern is useful for a deliberately different context in one test, but it also creates responsibility for closing that context and for supplying any values you still need, such as authentication state.
Common configuration recipes
Authenticated tests with storage state
test.use({ storageState: 'playwright/.auth/user.json' });
test('opens the account page', async ({ page }) => {
await page.goto('/account');
});Keep the state file out of source control when it contains credentials or session cookies. The path is resolved according to your project configuration and execution directory, so use a consistent path in CI.
Recommended Free Tools
Mobile-sized viewport and touch behavior
test.describe('mobile navigation', () => {
test.use({
viewport: { width: 390, height: 844 },
isMobile: true,
hasTouch: true
});
test('opens the menu', async ({ page }) => {
await page.goto('/');
await page.getByRole('button', { name: 'Menu' }).tap();
});
});Check the current option types before combining mobile flags; device descriptors can provide a safer, coherent starting point.
Network and permissions
test.describe('offline shell', () => {
test.use({
offline: true,
permissions: ['notifications']
});
test('shows cached content', async ({ page }) => {
await page.goto('/');
});
});Offline mode only makes sense after the application has a cache or service-worker path that the test prepares. Otherwise a navigation failure is the expected result, not a Playwright defect.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
“It has no effect”
- Confirm the call is imported from the same
testobject used to declare the tests. - Check that the call appears before the test definitions and is not inside a hook.
- Look for a project-level setting or explicit
browser.newContext()option overriding it. - When using a device preset, put your override after the spread.
Tests use the wrong browser
test.use({ browserName: 'firefox' }) changes the browser for the applicable scope, but project matrices remain the clearer way to run the same tests across Chromium, Firefox and WebKit. Verify the selected project with your runner command and inspect project-specific use values.
Navigation ignores baseURL
baseURL affects relative URLs such as page.goto('/settings'). An absolute URL bypasses it. Also check whether a file-level reset or a project configuration changed the inherited value.
Locale or timezone assertions fail in CI
Set locale and timezoneId explicitly rather than relying on the machine running the tests. If the application formats dates server-side, align its server configuration as well; browser context emulation cannot change server-generated text.
Tracing or screenshots are missing
Artifact options control when Playwright records output. For example, trace: 'on-first-retry' does not create a trace for every successful first attempt. Check the option’s current allowed values and the runner’s output directory.
Performance, reliability and maintenance
- Prefer a shared configuration default over repeating the same
test.use()call in many files. - Use projects for browser coverage instead of conditionally changing
browserNameat runtime. This keeps reports and CI jobs predictable. - Keep high-cost artifacts such as video enabled only where they answer a debugging need.
- Use stable, checked-in device and locale choices so a developer laptop and CI worker create comparable contexts.
- Review option names after Playwright upgrades; the API reference includes version-sensitive types and defaults.
Or skip the browser setup
If your goal is simply to obtain a clean website image rather than run an interactive Playwright test, ScreenshotNeo provides a one-request screenshot API. It accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result.
Use the API documentation at screenshotneo.com/docs/ for all options. A cURL request is:
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)
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}`);ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I call test.use() for just one test?
Put that test in its own test.describe() group and call test.use() inside the group, or create an explicit browser context with the desired option in the test.
Does test.use() replace playwright.config.ts?
No. Configuration and project use values establish defaults and environments; test.use() provides a narrower file- or group-level override.
How do I run the same tests in multiple browsers?
Define separate Playwright projects with different browser or device settings. Use test.use() for local exceptions within each project.
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 →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.
