docs: add options snippets to api docs (#22098)

docs/src/api/params.md

@@ -252,8 +252,9 @@ Specify environment variables that will be visible to the browser. Defaults to `
       - `name` <[string]>
       - `value` <[string]>
 
-Populates context with given storage state. This option can be used to initialize context with logged-in information
+Learn more about [storage state and auth](../auth.md).
-obtained via [`method: BrowserContext.storageState`]. Either a path to the file with saved storage, or an object with the following fields:
+
+Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [`method: BrowserContext.storageState`]. Either a path to the file with saved storage, or an object with the following fields:
 
 ## csharp-java-context-option-storage-state
 * langs: csharp, java
@@ -307,7 +308,7 @@ When using [`method: Page.goto`], [`method: Page.route`], [`method: Page.waitFor
   - `height` <[int]> page height in pixels.
 
 Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. 
-Use `null` to disable the consistent viewport emulation.
+Use `null` to disable the consistent viewport emulation. Learn more about [viewport emulation](../emulation#viewport).
 
 :::note
 The `null` value opts out from the default presets, makes viewport depend on the
@@ -323,7 +324,7 @@ tests non-deterministic.
   - `height` <[int]> page height in pixels.
 
 Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.
-Use `ViewportSize.NoViewport` to disable the consistent viewport emulation.
+Use `ViewportSize.NoViewport` to disable the consistent viewport emulation. Learn more about [viewport emulation](../emulation.md#viewport).
 
 :::note
 The `ViewportSize.NoViewport` value opts out from the default presets,
@@ -488,7 +489,7 @@ Function to be evaluated in the main Electron process.
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
-Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `no_viewport` disables the fixed viewport.
+Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `no_viewport` disables the fixed viewport. Learn more about [viewport emulation](../emulation.md#viewport).
 
 ## python-context-option-no-viewport
 * langs: python
@@ -504,23 +505,22 @@ Specific user agent to use in this context.
 ## context-option-devicescalefactor
 - `deviceScaleFactor` <[float]>
 
-Specify device scale factor (can be thought of as dpr). Defaults to `1`.
+Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about [emulating devices with device scale factor](../emulation.md#devices).
 
 ## context-option-ismobile
 - `isMobile` <[boolean]>
 
-Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported
+Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device, so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more about [mobile emulation](../emulation.md#isMobile).
-in Firefox.
 
 ## context-option-hastouch
 - `hasTouch` <[boolean]>
 
-Specifies if viewport supports touch events. Defaults to false.
+Specifies if viewport supports touch events. Defaults to false. Learn more about [mobile emulation](../emulation.md#devices).
 
 ## context-option-javascriptenabled
 - `javaScriptEnabled` <[boolean]>
 
-Whether or not to enable JavaScript in the context. Defaults to `true`.
+Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about [disabling JavaScript](../emulation.md#javascript-enabled).
 
 ## context-option-timezoneid
 - `timezoneId` <[string]>
@@ -537,8 +537,7 @@ for a list of supported timezone IDs.
 ## context-option-locale
 - `locale` <[string]>
 
-Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language`
+Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules. Learn more about emulation in our [emulation guide](../emulation.md#locale--timezone).
-request header value as well as number and date formatting rules.
 
 ## context-option-permissions
 - `permissions` <[Array]<[string]>>
@@ -554,7 +553,7 @@ An object containing additional HTTP headers to be sent with every request.
 ## context-option-offline
 - `offline` <[boolean]>
 
-Whether to emulate network being offline. Defaults to `false`.
+Whether to emulate network being offline. Defaults to `false`. Learn more about [network emulation](../emulation.md#offline).
 
 ## context-option-httpcredentials
 - `httpCredentials` <[Object]>

docs/src/emulation.md

@@ -10,8 +10,7 @@ With Playwright you can test your app on any browser as well as emulate a real d
 
 Playwright comes with a [registry of device parameters](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json) using [`property: Playwright.devices`] for selected desktop, tablet and mobile devices. It can be used to simulate browser behavior for a specific device such as user agent, screen size, viewport and if it has touch enabled. All tests will run with the specified device parameters. 
 
-```js tab=js-test
+```js tab=js-test title="playwright.config.ts"
-// playwright.config.ts/js
 import { defineConfig, devices } from '@playwright/test'; // import devices
 
 export default defineConfig({
@@ -92,14 +91,14 @@ class Program
 }
 ```
 
+
 <img width="458" alt="playwright.dev website emulated for iPhone 13" src="https://user-images.githubusercontent.com/13063165/220411073-76fe59f9-9a2d-463d-8e30-c19a7deca133.png" />
 
 ## Viewport
 
 The viewport is included in the device but you can override it for some tests with [`method: Page.setViewportSize`].
 
-```js tab=js-test
+```js tab=js-test title="playwright.config.ts"
-// playwright.config.ts/js
 import { defineConfig } from '@playwright/test';
 export default defineConfig({
   use: {
@@ -118,8 +117,7 @@ const context = await browser.newContext({
 
 Test file:
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.use({ 
@@ -149,8 +147,7 @@ const context = await browser.newContext({
 
 The same works inside a test file.
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.describe('specific viewport block', () => {
@@ -233,14 +230,49 @@ await using var context = await browser.NewContextAsync(new()
 });
 ```
 
-<img width="1714" alt="website with set viewport" src="https://user-images.githubusercontent.com/13063165/220405141-a7446ee5-aa1e-42af-b8fc-7a281f901dc2.png" />
+## isMobile
+
+Whether the meta viewport tag is taken into account and touch events are enabled.
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    isMobile: false,
+  },
+});
+```
+
+```java
+BrowserContext context = browser.newContext(new Browser.NewContextOptions()
+  .isMobile(false));
+```
+
+```python async
+context = await browser.new_context(
+  isMobile=false
+)
+```
+
+```python sync
+context = browser.new_context(
+  isMobile=false
+)
+```
+
+```csharp
+await using var context = await browser.NewContextAsync(new()
+{
+    IsMobile = new IsMoble() { false }
+});
+```
 
 ## Locale & Timezone
 
 Emulate the user Locale and Timezone which can be set globally for all tests in the config and then overridden for particular tests.
 
-```js
+```js title="playwright.config.ts"
-// playwright.config.ts/js
 import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
@@ -254,8 +286,7 @@ export default defineConfig({
 });
 ```
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.use({ 
@@ -309,8 +340,7 @@ await using var context = await browser.NewContextAsync(new()
 
 Allow app to show system notifications.
 
-```js tab=js-test
+```js tab=js-test title="playwright.config.ts"
-// playwright.config.ts/js
 import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
@@ -346,8 +376,7 @@ context = browser.new_context(
 
 Allow notifications for a specific domain.
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test } from '@playwright/test';
 
 test.beforeEach(async ({ context }) => {
@@ -403,12 +432,12 @@ context.clear_permissions()
 ```csharp
 await context.ClearPermissionsAsync();
 ```
+
 ## Geolocation
 
 Grant `"geolocation"` permissions and set geolocation to a specific area.
 
-```js
+```js title="playwright.config.ts"
-// playwright.config.ts/js
 import { defineConfig } from '@playwright/test';
 
 export default defineConfig({
@@ -420,8 +449,7 @@ export default defineConfig({
 });
 ```
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.use({ 
@@ -474,8 +502,7 @@ await using var context = await browser.NewContextAsync(new()
 
 Change the location later:
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.use({ 
@@ -524,8 +551,7 @@ export default defineConfig({
 });
 ```
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.use({ 
@@ -638,8 +664,7 @@ await page.EmulateMediaAsync(new()
 
 The User Agent is included in the device and therefore you  will rarely need to change it however if you do need to test a different user agent you can override it with the `userAgent` property.
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.use({ userAgent: 'My user agent'});
@@ -675,12 +700,46 @@ context = browser.new_context(
 ```csharp
 var context = await browser.NewContextAsync(new() { UserAgent = "My User Agent" });
 ```
+
+## Offline
+
+Emulate the network being offline.
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    offline: true
+  },
+});
+```
+
+```java
+BrowserContext context = browser.newContext(new Browser.NewContextOptions()
+  .setOffline(true));
+```
+
+```python async
+context = await browser.new_context(
+  offline=True
+)
+```
+
+```python sync
+context = browser.new_context(
+  offline=True
+)
+```
+
+```csharp
+var context = await browser.NewContextAsync(new() { Offline = true });
+```
 ## JavaScript Enabled
 
 Emulate a user scenario where JavaScript is disabled.
 
-```js tab=js-test
+```js tab=js-test title="tests/example.spec.ts"
-// example.spec.ts/js
 import { test, expect } from '@playwright/test';
 
 test.use({ javaScriptEnabled: false });
@@ -695,3 +754,24 @@ const context = await browser.newContext({
   javaScriptEnabled: false
 });
 ```
+
+```java
+BrowserContext context = browser.newContext(new Browser.NewContextOptions()
+  .javaScriptEnabled(false));
+```
+
+```python async
+context = await browser.new_context(
+  javaScript_enabled=False
+)
+```
+
+```python sync
+context = browser.new_context(
+  javaScript_enabled=False
+)
+```
+
+```csharp
+var context = await browser.NewContextAsync(new() { JavaScriptEnabled = true });
+```

docs/src/test-api/class-testoptions.md

@@ -35,15 +35,42 @@ test('my portrait test', async ({ page }) => {
 ## property: TestOptions.acceptDownloads = %%-context-option-acceptdownloads-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    acceptDownloads: false,
+  },
+});
+```
+
 ## property: TestOptions.baseURL = %%-context-option-baseURL-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    baseURL: 'http://localhost:3000',
+  },
+});
+```
+
 ## property: TestOptions.browserName
 * since: v1.10
 - type: <[BrowserName]<"chromium"|"firefox"|"webkit">>
 
 Name of the browser that runs tests. Defaults to `'chromium'`. Most of the time you should set `browserName` in your [TestConfig]:
 
+**Usage**
+
 ```js
 // playwright.config.ts
 import { defineConfig, devices } from '@playwright/test';
@@ -63,17 +90,71 @@ Default timeout for each Playwright action in milliseconds, defaults to 0 (no ti
 
 This is a default timeout for all Playwright actions, same as configured via [`method: Page.setDefaultTimeout`].
 
+**Usage**
+
+```js
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). */
+    actionTimeout: 0,
+  },
+});
+```
+
 Learn more about [various timeouts](../test-timeouts.md).
 
 ## property: TestOptions.bypassCSP = %%-context-option-bypasscsp-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    bypassCSP: true,
+  }
+});
+```
+
 ## property: TestOptions.channel = %%-browser-option-channel-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'Microsoft Edge',
+      use: { 
+        ...devices['Desktop Edge'], 
+        channel: 'msedge' 
+      },
+    },
+  ]
+});
+```
 ## property: TestOptions.colorScheme = %%-context-option-colorscheme-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    colorScheme: 'dark',
+  },
+});
+```
+
 ## property: TestOptions.connectOptions
 * since: v1.10
 - type: <[void]|[Object]>
@@ -81,6 +162,21 @@ Learn more about [various timeouts](../test-timeouts.md).
   - `headers` ?<[void]|[Object]<[string], [string]>> Additional HTTP headers to be sent with web socket connect request. Optional.
   - `timeout` ?<[int]> Timeout in milliseconds for the connection to be established. Optional, defaults to no timeout.
 
+
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    connectOptions: {
+      wsEndpoint: 'ws://localhost:5678',
+    },
+  },
+});
+```
+
 When connect options are specified, default [`property: Fixtures.browser`], [`property: Fixtures.context`] and [`property: Fixtures.page`] use the remote browser instead of launching a browser locally, and any launch options like [`property: TestOptions.headless`] or [`property: TestOptions.channel`] are ignored.
 
 ## property: TestOptions.contextOptions
@@ -89,42 +185,202 @@ When connect options are specified, default [`property: Fixtures.browser`], [`pr
 
 Options used to create the context, as passed to [`method: Browser.newContext`]. Specific options like [`property: TestOptions.viewport`] take priority over this.
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    contextOptions: {
+      reducedMotion: 'reduce',
+    },
+  },
+});
+```
+
 ## property: TestOptions.deviceScaleFactor = %%-context-option-devicescalefactor-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    viewport: { width: 2560, height: 1440 },
+    deviceScaleFactor: 2,
+  },
+});
+```
+
 ## property: TestOptions.extraHTTPHeaders = %%-context-option-extrahttpheaders-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    extraHTTPHeaders: {
+      'X-My-Header': 'value',
+    },
+  },
+});
+```
+
 ## property: TestOptions.geolocation = %%-context-option-geolocation-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    geolocation: { longitude: 12.492507, latitude: 41.889938 },
+  },
+});
+```
+Learn more about [geolocation](../emulation.md#color-scheme-and-media).
+
 ## property: TestOptions.hasTouch = %%-context-option-hastouch-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    hasTouch: true
+  },
+});
+```
+
 ## property: TestOptions.headless = %%-browser-option-headless-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    headless: false
+  },
+});
+```
+
 ## property: TestOptions.httpCredentials = %%-context-option-httpcredentials-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    httpCredentials: {
+      username: 'user',
+      password: 'pass',
+    },
+  },
+});
+```
+
 ## property: TestOptions.ignoreHTTPSErrors = %%-context-option-ignorehttpserrors-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    ignoreHTTPSErrors: true,
+  },
+});
+```
+
 ## property: TestOptions.isMobile = %%-context-option-ismobile-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    isMobile: false,
+  },
+});
+```
+
 ## property: TestOptions.javaScriptEnabled = %%-context-option-javascriptenabled-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    javaScriptEnabled: false,
+  },
+});
+```
+
+
 ## property: TestOptions.launchOptions
 * since: v1.10
 - type: <[Object]>
 
 Options used to launch the browser, as passed to [`method: BrowserType.launch`]. Specific options [`property: TestOptions.headless`] and [`property: TestOptions.channel`] take priority over this.
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+      launchOptions: {
+        args: ['--start-maximized'],
+    },
+    }
+  ]
+});
+```
+
 ## property: TestOptions.locale = %%-context-option-locale-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    locale: 'it-IT',
+  },
+});
+```
+
 ## property: TestOptions.navigationTimeout
 * since: v1.10
 - type: <[int]>
@@ -133,17 +389,68 @@ Timeout for each navigation action in milliseconds. Defaults to 0 (no timeout).
 
 This is a default navigation timeout, same as configured via [`method: Page.setDefaultNavigationTimeout`].
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    navigationTimeout: 3000,
+  },
+});
+```
+
 Learn more about [various timeouts](../test-timeouts.md).
 
 ## property: TestOptions.offline = %%-context-option-offline-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    offline: true
+  },
+});
+```
+
 ## property: TestOptions.permissions = %%-context-option-permissions-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    permissions: ['notifications'],
+  },
+});
+```
+
 ## property: TestOptions.proxy = %%-browser-option-proxy-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    proxy: {
+      server: 'http://myproxy.com:3128',
+      bypass: 'localhost',
+    },
+  },
+});
+```
+
 ## property: TestOptions.screenshot
 * since: v1.10
 - type: <[Object]|[ScreenshotMode]<"off"|"on"|"only-on-failure">>
@@ -156,19 +463,67 @@ Whether to automatically capture a screenshot after each test. Defaults to `'off
 * `'on'`: Capture screenshot after each test.
 * `'only-on-failure'`: Capture screenshot after each test failure.
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    screenshot: 'only-on-failure',
+  },
+});
+```
+
 Learn more about [automatic screenshots](../test-configuration.md#automatic-screenshots).
 
 ## property: TestOptions.storageState = %%-js-python-context-option-storage-state-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    storageState: 'storage-state.json',
+  },
+});
+```
+
 ## property: TestOptions.testIdAttribute
 * since: v1.27
 
 Custom attribute to be used in [`method: Page.getByTestId`]. `data-testid` is used by default.
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    testIdAttribute: 'pw-test-id',
+  },
+});
+```
+
 ## property: TestOptions.timezoneId = %%-context-option-timezoneid-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    timezoneId: 'Europe/Rome',
+  },
+});
+```
+
 ## property: TestOptions.trace
 * since: v1.10
 - type: <[Object]|[TraceMode]<"off"|"on"|"retain-on-failure"|"on-first-retry">>
@@ -186,11 +541,35 @@ Whether to record trace for each test. Defaults to `'off'`.
 
 For more control, pass an object that specifies `mode` and trace features to enable.
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    trace: 'on-first-retry'
+  },
+});
+```
+
 Learn more about [recording trace](../test-configuration.md#record-test-trace).
 
 ## property: TestOptions.userAgent = %%-context-option-useragent-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    userAgent: 'some custom ua',
+  },
+});
+```
+
 ## property: TestOptions.video
 * since: v1.10
 - type: <[Object]|[VideoMode]<"off"|"on"|"retain-on-failure"|"on-first-retry">>
@@ -207,10 +586,46 @@ Whether to record video for each test. Defaults to `'off'`.
 
 To control video size, pass an object with `mode` and `size` properties. If video size is not specified, it will be equal to [`property: TestOptions.viewport`] scaled down to fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be scaled down if necessary to fit the specified size.
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    video: 'on-first-retry',
+  },
+});
+```
+
 Learn more about [recording video](../test-configuration.md#record-video).
 
 ## property: TestOptions.viewport = %%-context-option-viewport-%%
 * since: v1.10
 
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    viewport: { width: 100, height: 100 },
+  },
+});
+```
+
 ## property: TestOptions.serviceWorkers = %%-context-option-service-worker-policy-%%
 * since: v1.10
+
+**Usage**
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    serviceWorkers: 'allow'
+  },
+});
+```

packages/playwright-core/types/types.d.ts

@@ -12350,7 +12350,8 @@ export interface BrowserType<Unused = {}> {
     colorScheme?: null|"light"|"dark"|"no-preference";
 
     /**
-     * Specify device scale factor (can be thought of as dpr). Defaults to `1`.
+     * Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about
+     * [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices).
      */
     deviceScaleFactor?: number;
 
@@ -12424,7 +12425,8 @@ export interface BrowserType<Unused = {}> {
     handleSIGTERM?: boolean;
 
     /**
-     * Specifies if viewport supports touch events. Defaults to false.
+     * Specifies if viewport supports touch events. Defaults to false. Learn more about
+     * [mobile emulation](https://playwright.dev/docs/emulation#devices).
      */
     hasTouch?: boolean;
 
@@ -12463,19 +12465,22 @@ export interface BrowserType<Unused = {}> {
     ignoreHTTPSErrors?: boolean;
 
     /**
-     * Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not
+     * Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device,
-     * supported in Firefox.
+     * so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more
+     * about [mobile emulation](https://playwright.dev/docs/emulation#isMobile).
      */
     isMobile?: boolean;
 
     /**
-     * Whether or not to enable JavaScript in the context. Defaults to `true`.
+     * Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about
+     * [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled).
      */
     javaScriptEnabled?: boolean;
 
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
-     * `Accept-Language` request header value as well as number and date formatting rules.
+     * `Accept-Language` request header value as well as number and date formatting rules. Learn more about emulation in
+     * our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
      */
     locale?: string;
 
@@ -12485,7 +12490,8 @@ export interface BrowserType<Unused = {}> {
     logger?: Logger;
 
     /**
-     * Whether to emulate network being offline. Defaults to `false`.
+     * Whether to emulate network being offline. Defaults to `false`. Learn more about
+     * [network emulation](https://playwright.dev/docs/emulation#offline).
      */
     offline?: boolean;
 
@@ -12682,8 +12688,8 @@ export interface BrowserType<Unused = {}> {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
-     * viewport emulation.
+     * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
      *
      * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
      * by the operating system. It makes the execution of the tests non-deterministic.
@@ -13805,7 +13811,8 @@ export interface AndroidDevice {
     command?: string;
 
     /**
-     * Specify device scale factor (can be thought of as dpr). Defaults to `1`.
+     * Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about
+     * [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices).
      */
     deviceScaleFactor?: number;
 
@@ -13839,7 +13846,8 @@ export interface AndroidDevice {
     };
 
     /**
-     * Specifies if viewport supports touch events. Defaults to false.
+     * Specifies if viewport supports touch events. Defaults to false. Learn more about
+     * [mobile emulation](https://playwright.dev/docs/emulation#devices).
      */
     hasTouch?: boolean;
 
@@ -13864,19 +13872,22 @@ export interface AndroidDevice {
     ignoreHTTPSErrors?: boolean;
 
     /**
-     * Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not
+     * Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device,
-     * supported in Firefox.
+     * so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more
+     * about [mobile emulation](https://playwright.dev/docs/emulation#isMobile).
      */
     isMobile?: boolean;
 
     /**
-     * Whether or not to enable JavaScript in the context. Defaults to `true`.
+     * Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about
+     * [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled).
      */
     javaScriptEnabled?: boolean;
 
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
-     * `Accept-Language` request header value as well as number and date formatting rules.
+     * `Accept-Language` request header value as well as number and date formatting rules. Learn more about emulation in
+     * our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
      */
     locale?: string;
 
@@ -13886,7 +13897,8 @@ export interface AndroidDevice {
     logger?: Logger;
 
     /**
-     * Whether to emulate network being offline. Defaults to `false`.
+     * Whether to emulate network being offline. Defaults to `false`. Learn more about
+     * [network emulation](https://playwright.dev/docs/emulation#offline).
      */
     offline?: boolean;
 
@@ -14066,8 +14078,8 @@ export interface AndroidDevice {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
-     * viewport emulation.
+     * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
      *
      * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
      * by the operating system. It makes the execution of the tests non-deterministic.
@@ -15674,7 +15686,8 @@ export interface Browser extends EventEmitter {
     colorScheme?: null|"light"|"dark"|"no-preference";
 
     /**
-     * Specify device scale factor (can be thought of as dpr). Defaults to `1`.
+     * Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about
+     * [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices).
      */
     deviceScaleFactor?: number;
 
@@ -15708,7 +15721,8 @@ export interface Browser extends EventEmitter {
     };
 
     /**
-     * Specifies if viewport supports touch events. Defaults to false.
+     * Specifies if viewport supports touch events. Defaults to false. Learn more about
+     * [mobile emulation](https://playwright.dev/docs/emulation#devices).
      */
     hasTouch?: boolean;
 
@@ -15733,19 +15747,22 @@ export interface Browser extends EventEmitter {
     ignoreHTTPSErrors?: boolean;
 
     /**
-     * Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not
+     * Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device,
-     * supported in Firefox.
+     * so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more
+     * about [mobile emulation](https://playwright.dev/docs/emulation#isMobile).
      */
     isMobile?: boolean;
 
     /**
-     * Whether or not to enable JavaScript in the context. Defaults to `true`.
+     * Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about
+     * [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled).
      */
     javaScriptEnabled?: boolean;
 
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
-     * `Accept-Language` request header value as well as number and date formatting rules.
+     * `Accept-Language` request header value as well as number and date formatting rules. Learn more about emulation in
+     * our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
      */
     locale?: string;
 
@@ -15755,7 +15772,8 @@ export interface Browser extends EventEmitter {
     logger?: Logger;
 
     /**
-     * Whether to emulate network being offline. Defaults to `false`.
+     * Whether to emulate network being offline. Defaults to `false`. Learn more about
+     * [network emulation](https://playwright.dev/docs/emulation#offline).
      */
     offline?: boolean;
 
@@ -15899,6 +15917,8 @@ export interface Browser extends EventEmitter {
     serviceWorkers?: "allow"|"block";
 
     /**
+     * Learn more about [storage state and auth](https://playwright.dev/docs/auth).
+     *
      * Populates context with given storage state. This option can be used to initialize context with logged-in
      * information obtained via
      * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
@@ -15993,8 +16013,8 @@ export interface Browser extends EventEmitter {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
-     * viewport emulation.
+     * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
      *
      * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
      * by the operating system. It makes the execution of the tests non-deterministic.
@@ -16601,12 +16621,14 @@ export interface Electron {
 
     /**
      * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
-     * `Accept-Language` request header value as well as number and date formatting rules.
+     * `Accept-Language` request header value as well as number and date formatting rules. Learn more about emulation in
+     * our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
      */
     locale?: string;
 
     /**
-     * Whether to emulate network being offline. Defaults to `false`.
+     * Whether to emulate network being offline. Defaults to `false`. Learn more about
+     * [network emulation](https://playwright.dev/docs/emulation#offline).
      */
     offline?: boolean;
 
@@ -18798,7 +18820,8 @@ export interface BrowserContextOptions {
   colorScheme?: null|"light"|"dark"|"no-preference";
 
   /**
-   * Specify device scale factor (can be thought of as dpr). Defaults to `1`.
+   * Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about
+   * [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices).
    */
   deviceScaleFactor?: number;
 
@@ -18817,7 +18840,8 @@ export interface BrowserContextOptions {
   geolocation?: Geolocation;
 
   /**
-   * Specifies if viewport supports touch events. Defaults to false.
+   * Specifies if viewport supports touch events. Defaults to false. Learn more about
+   * [mobile emulation](https://playwright.dev/docs/emulation#devices).
    */
   hasTouch?: boolean;
 
@@ -18833,19 +18857,22 @@ export interface BrowserContextOptions {
   ignoreHTTPSErrors?: boolean;
 
   /**
-   * Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not
+   * Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device,
-   * supported in Firefox.
+   * so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more
+   * about [mobile emulation](https://playwright.dev/docs/emulation#isMobile).
    */
   isMobile?: boolean;
 
   /**
-   * Whether or not to enable JavaScript in the context. Defaults to `true`.
+   * Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about
+   * [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled).
    */
   javaScriptEnabled?: boolean;
 
   /**
    * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
-   * `Accept-Language` request header value as well as number and date formatting rules.
+   * `Accept-Language` request header value as well as number and date formatting rules. Learn more about emulation in
+   * our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
    */
   locale?: string;
 
@@ -18855,7 +18882,8 @@ export interface BrowserContextOptions {
   logger?: Logger;
 
   /**
-   * Whether to emulate network being offline. Defaults to `false`.
+   * Whether to emulate network being offline. Defaults to `false`. Learn more about
+   * [network emulation](https://playwright.dev/docs/emulation#offline).
    */
   offline?: boolean;
 
@@ -18999,6 +19027,8 @@ export interface BrowserContextOptions {
   serviceWorkers?: "allow"|"block";
 
   /**
+   * Learn more about [storage state and auth](https://playwright.dev/docs/auth).
+   *
    * Populates context with given storage state. This option can be used to initialize context with logged-in
    * information obtained via
    * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
@@ -19093,8 +19123,8 @@ export interface BrowserContextOptions {
   videosPath?: string;
 
   /**
-   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
-   * viewport emulation.
+   * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
    *
    * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
    * by the operating system. It makes the execution of the tests non-deterministic.

packages/playwright-test/types/test.d.ts

@@ -3344,6 +3344,8 @@ export interface PlaywrightWorkerOptions {
    * Name of the browser that runs tests. Defaults to `'chromium'`. Most of the time you should set `browserName` in
    * your [TestConfig]:
    *
+   * **Usage**
+   *
    * ```js
    * // playwright.config.ts
    * import { defineConfig, devices } from '@playwright/test';
@@ -3359,6 +3361,18 @@ export interface PlaywrightWorkerOptions {
   browserName: BrowserName;
   defaultBrowserType: BrowserName;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     headless: false
+   *   },
+   * });
+   * ```
+   *
    * Whether to run browser in headless mode. More details for
    * [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and
    * [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to `true` unless the
@@ -3366,6 +3380,24 @@ export interface PlaywrightWorkerOptions {
    */
   headless: boolean;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   projects: [
+   *     {
+   *       name: 'Microsoft Edge',
+   *       use: {
+   *         ...devices['Desktop Edge'],
+   *         channel: 'msedge'
+   *       },
+   *     },
+   *   ]
+   * });
+   * ```
+   *
    * Browser distribution channel.  Supported values are "chrome", "chrome-beta", "chrome-dev", "chrome-canary",
    * "msedge", "msedge-beta", "msedge-dev", "msedge-canary". Read more about using
    * [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge).
@@ -3377,9 +3409,42 @@ export interface PlaywrightWorkerOptions {
    * options [testOptions.headless](https://playwright.dev/docs/api/class-testoptions#test-options-headless) and
    * [testOptions.channel](https://playwright.dev/docs/api/class-testoptions#test-options-channel) take priority over
    * this.
+   *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   projects: [
+   *     {
+   *       name: 'chromium',
+   *       use: { ...devices['Desktop Chrome'] },
+   *       launchOptions: {
+   *         args: ['--start-maximized'],
+   *     },
+   *     }
+   *   ]
+   * });
+   * ```
+   *
    */
   launchOptions: LaunchOptions;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     connectOptions: {
+   *       wsEndpoint: 'ws://localhost:5678',
+   *     },
+   *   },
+   * });
+   * ```
+   *
    * When connect options are specified, default
    * [fixtures.browser](https://playwright.dev/docs/api/class-fixtures#fixtures-browser),
    * [fixtures.context](https://playwright.dev/docs/api/class-fixtures#fixtures-context) and
@@ -3395,6 +3460,18 @@ export interface PlaywrightWorkerOptions {
    * - `'on'`: Capture screenshot after each test.
    * - `'only-on-failure'`: Capture screenshot after each test failure.
    *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     screenshot: 'only-on-failure',
+   *   },
+   * });
+   * ```
+   *
    * Learn more about [automatic screenshots](https://playwright.dev/docs/test-configuration#automatic-screenshots).
    */
   screenshot: ScreenshotMode | { mode: ScreenshotMode } & Pick<PageScreenshotOptions, 'fullPage' | 'omitBackground'>;
@@ -3408,6 +3485,18 @@ export interface PlaywrightWorkerOptions {
    *
    * For more control, pass an object that specifies `mode` and trace features to enable.
    *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     trace: 'on-first-retry'
+   *   },
+   * });
+   * ```
+   *
    * Learn more about [recording trace](https://playwright.dev/docs/test-configuration#record-test-trace).
    */
   trace: TraceMode | /** deprecated */ 'retry-with-trace' | { mode: TraceMode, snapshots?: boolean, screenshots?: boolean, sources?: boolean };
@@ -3423,6 +3512,18 @@ export interface PlaywrightWorkerOptions {
    * down to fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual
    * picture of each page will be scaled down if necessary to fit the specified size.
    *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     video: 'on-first-retry',
+   *   },
+   * });
+   * ```
+   *
    * Learn more about [recording video](https://playwright.dev/docs/test-configuration#record-video).
    */
   video: VideoMode | /** deprecated */ 'retry-with-video' | { mode: VideoMode, size?: ViewportSize };
@@ -3469,70 +3570,282 @@ export type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
  */
 export interface PlaywrightTestOptions {
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     acceptDownloads: false,
+   *   },
+   * });
+   * ```
+   *
    * Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.
    */
   acceptDownloads: boolean;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     bypassCSP: true,
+   *   }
+   * });
+   * ```
+   *
    * Toggles bypassing page's Content-Security-Policy.
    */
   bypassCSP: boolean;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     colorScheme: 'dark',
+   *   },
+   * });
+   * ```
+   *
    * Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
    * [page.emulateMedia([options])](https://playwright.dev/docs/api/class-page#page-emulate-media) for more details.
    * Passing `null` resets emulation to system defaults. Defaults to `'light'`.
    */
   colorScheme: ColorScheme;
   /**
-   * Specify device scale factor (can be thought of as dpr). Defaults to `1`.
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     viewport: { width: 2560, height: 1440 },
+   *     deviceScaleFactor: 2,
+   *   },
+   * });
+   * ```
+   *
+   * Specify device scale factor (can be thought of as dpr). Defaults to `1`. Learn more about
+   * [emulating devices with device scale factor](https://playwright.dev/docs/emulation#devices).
    */
   deviceScaleFactor: number | undefined;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     extraHTTPHeaders: {
+   *       'X-My-Header': 'value',
+   *     },
+   *   },
+   * });
+   * ```
+   *
    * An object containing additional HTTP headers to be sent with every request.
    */
   extraHTTPHeaders: ExtraHTTPHeaders | undefined;
+  /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     geolocation: { longitude: 12.492507, latitude: 41.889938 },
+   *   },
+   * });
+   * ```
+   *
+   * Learn more about [geolocation](https://playwright.dev/docs/emulation#color-scheme-and-media).
+   */
   geolocation: Geolocation | undefined;
   /**
-   * Specifies if viewport supports touch events. Defaults to false.
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     hasTouch: true
+   *   },
+   * });
+   * ```
+   *
+   * Specifies if viewport supports touch events. Defaults to false. Learn more about
+   * [mobile emulation](https://playwright.dev/docs/emulation#devices).
    */
   hasTouch: boolean;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     httpCredentials: {
+   *       username: 'user',
+   *       password: 'pass',
+   *     },
+   *   },
+   * });
+   * ```
+   *
    * Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). If no
    * origin is specified, the username and password are sent to any servers upon unauthorized responses.
    */
   httpCredentials: HTTPCredentials | undefined;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     ignoreHTTPSErrors: true,
+   *   },
+   * });
+   * ```
+   *
    * Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
    */
   ignoreHTTPSErrors: boolean;
   /**
-   * Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not
+   * **Usage**
-   * supported in Firefox.
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     isMobile: false,
+   *   },
+   * });
+   * ```
+   *
+   * Whether the `meta viewport` tag is taken into account and touch events are enabled. isMobile is a part of device,
+   * so you don't actually need to set it manually. Defaults to `false` and is not supported in Firefox. Learn more
+   * about [mobile emulation](https://playwright.dev/docs/emulation#isMobile).
    */
   isMobile: boolean;
   /**
-   * Whether or not to enable JavaScript in the context. Defaults to `true`.
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     javaScriptEnabled: false,
+   *   },
+   * });
+   * ```
+   *
+   * Whether or not to enable JavaScript in the context. Defaults to `true`. Learn more about
+   * [disabling JavaScript](https://playwright.dev/docs/emulation#javascript-enabled).
    */
   javaScriptEnabled: boolean;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     locale: 'it-IT',
+   *   },
+   * });
+   * ```
+   *
    * Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value,
-   * `Accept-Language` request header value as well as number and date formatting rules.
+   * `Accept-Language` request header value as well as number and date formatting rules. Learn more about emulation in
+   * our [emulation guide](https://playwright.dev/docs/emulation#locale--timezone).
    */
   locale: string | undefined;
   /**
-   * Whether to emulate network being offline. Defaults to `false`.
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     offline: true
+   *   },
+   * });
+   * ```
+   *
+   * Whether to emulate network being offline. Defaults to `false`. Learn more about
+   * [network emulation](https://playwright.dev/docs/emulation#offline).
    */
   offline: boolean;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     permissions: ['notifications'],
+   *   },
+   * });
+   * ```
+   *
    * A list of permissions to grant to all pages in this context. See
    * [browserContext.grantPermissions(permissions[, options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions)
    * for more details.
    */
   permissions: string[] | undefined;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     proxy: {
+   *       server: 'http://myproxy.com:3128',
+   *       bypass: 'localhost',
+   *     },
+   *   },
+   * });
+   * ```
+   *
    * Network proxy settings.
    */
   proxy: Proxy | undefined;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     storageState: 'storage-state.json',
+   *   },
+   * });
+   * ```
+   *
+   * Learn more about [storage state and auth](https://playwright.dev/docs/auth).
+   *
    * Populates context with given storage state. This option can be used to initialize context with logged-in
    * information obtained via
    * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
@@ -3540,24 +3853,73 @@ export interface PlaywrightTestOptions {
    */
   storageState: StorageState | undefined;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     timezoneId: 'Europe/Rome',
+   *   },
+   * });
+   * ```
+   *
    * Changes the timezone of the context. See
    * [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1)
    * for a list of supported timezone IDs.
    */
   timezoneId: string | undefined;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     userAgent: 'some custom ua',
+   *   },
+   * });
+   * ```
+   *
    * Specific user agent to use in this context.
    */
   userAgent: string | undefined;
   /**
-   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+   * **Usage**
-   * viewport emulation.
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     viewport: { width: 100, height: 100 },
+   *   },
+   * });
+   * ```
+   *
+   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.  Use `null` to disable the consistent
+   * viewport emulation. Learn more about [viewport emulation](https://playwright.dev/docs/emulation#viewport).
    *
    * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
    * by the operating system. It makes the execution of the tests non-deterministic.
    */
   viewport: ViewportSize | null;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig, devices } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     /* Base URL to use in actions like `await page.goto('/')`. *\/
+   *     baseURL: 'http://localhost:3000',
+   *   },
+   * });
+   * ```
+   *
    * When using [page.goto(url[, options])](https://playwright.dev/docs/api/class-page#page-goto),
    * [page.route(url, handler[, options])](https://playwright.dev/docs/api/class-page#page-route),
    * [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url),
@@ -3579,6 +3941,21 @@ export interface PlaywrightTestOptions {
    * [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context). Specific
    * options like [testOptions.viewport](https://playwright.dev/docs/api/class-testoptions#test-options-viewport) take
    * priority over this.
+   *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     contextOptions: {
+   *       reducedMotion: 'reduce',
+   *     },
+   *   },
+   * });
+   * ```
+   *
    */
   contextOptions: BrowserContextOptions;
   /**
@@ -3587,6 +3964,19 @@ export interface PlaywrightTestOptions {
    * This is a default timeout for all Playwright actions, same as configured via
    * [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout).
    *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig, devices } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). *\/
+   *     actionTimeout: 0,
+   *   },
+   * });
+   * ```
+   *
    * Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts).
    */
   actionTimeout: number;
@@ -3596,10 +3986,34 @@ export interface PlaywrightTestOptions {
    * This is a default navigation timeout, same as configured via
    * [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout).
    *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     navigationTimeout: 3000,
+   *   },
+   * });
+   * ```
+   *
    * Learn more about [various timeouts](https://playwright.dev/docs/test-timeouts).
    */
   navigationTimeout: number;
   /**
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     serviceWorkers: 'allow'
+   *   },
+   * });
+   * ```
+   *
    * Whether to allow sites to register Service workers. Defaults to `'allow'`.
    * - `'allow'`: [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can be
    *   registered.
@@ -3610,6 +4024,19 @@ export interface PlaywrightTestOptions {
    * Custom attribute to be used in
    * [page.getByTestId(testId)](https://playwright.dev/docs/api/class-page#page-get-by-test-id). `data-testid` is used
    * by default.
+   *
+   * **Usage**
+   *
+   * ```js
+   * import { defineConfig } from '@playwright/test';
+   *
+   * export default defineConfig({
+   *   use: {
+   *     testIdAttribute: 'pw-test-id',
+   *   },
+   * });
+   * ```
+   *
    */
   testIdAttribute: string;
 }