From 3a0f49acab80c69db07e3e570c9971d0f427ab37 Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Tue, 18 Apr 2023 19:04:13 +0200 Subject: [PATCH] docs: add options snippets to api docs (#22098) --- docs/src/api/params.md | 27 +- docs/src/emulation.md | 138 +++++-- docs/src/test-api/class-testoptions.md | 415 ++++++++++++++++++++ packages/playwright-core/types/types.d.ts | 106 ++++-- packages/playwright-test/types/test.d.ts | 445 +++++++++++++++++++++- 5 files changed, 1041 insertions(+), 90 deletions(-) diff --git a/docs/src/api/params.md b/docs/src/api/params.md index 5c56a7f6b4..55b60af35c 100644 --- a/docs/src/api/params.md +++ b/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 -obtained via [`method: BrowserContext.storageState`]. Either a path to the file with saved storage, or an object with the following fields: +Learn more about [storage state and auth](../auth.md). + +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 @@ -306,8 +307,8 @@ When using [`method: Page.goto`], [`method: Page.route`], [`method: Page.waitFor - `width` <[int]> page width in pixels. - `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. +Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. +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 -in Firefox. +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). ## 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` -request header value as well as number and date formatting rules. +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). ## 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]> diff --git a/docs/src/emulation.md b/docs/src/emulation.md index 40ebd0f5a7..b4c729746b 100644 --- a/docs/src/emulation.md +++ b/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 -// playwright.config.ts/js +```js tab=js-test title="playwright.config.ts" import { defineConfig, devices } from '@playwright/test'; // import devices export default defineConfig({ @@ -92,14 +91,14 @@ class Program } ``` + playwright.dev website emulated for iPhone 13 ## Viewport The viewport is included in the device but you can override it for some tests with [`method: Page.setViewportSize`]. -```js tab=js-test -// playwright.config.ts/js +```js tab=js-test title="playwright.config.ts" import { defineConfig } from '@playwright/test'; export default defineConfig({ use: { @@ -118,8 +117,7 @@ const context = await browser.newContext({ Test file: -```js tab=js-test -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" 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 -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" import { test, expect } from '@playwright/test'; test.describe('specific viewport block', () => { @@ -233,14 +230,49 @@ await using var context = await browser.NewContextAsync(new() }); ``` -website with set viewport +## 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 -// playwright.config.ts/js +```js title="playwright.config.ts" import { defineConfig } from '@playwright/test'; export default defineConfig({ @@ -254,8 +286,7 @@ export default defineConfig({ }); ``` -```js tab=js-test -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" 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 -// playwright.config.ts/js +```js tab=js-test title="playwright.config.ts" 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 -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" 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 -// playwright.config.ts/js +```js title="playwright.config.ts" import { defineConfig } from '@playwright/test'; export default defineConfig({ @@ -420,8 +449,7 @@ export default defineConfig({ }); ``` -```js tab=js-test -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" 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 -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" import { test, expect } from '@playwright/test'; test.use({ @@ -524,8 +551,7 @@ export default defineConfig({ }); ``` -```js tab=js-test -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" 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 -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" 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 -// example.spec.ts/js +```js tab=js-test title="tests/example.spec.ts" 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 }); +``` \ No newline at end of file diff --git a/docs/src/test-api/class-testoptions.md b/docs/src/test-api/class-testoptions.md index 1068ef86cd..586b60f292 100644 --- a/docs/src/test-api/class-testoptions.md +++ b/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' + }, +}); +``` diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 7278c3c0b2..0ae5533252 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -12350,7 +12350,8 @@ export interface BrowserType { 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 { 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 { ignoreHTTPSErrors?: boolean; /** - * Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not - * supported in Firefox. + * 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`. + * 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 { 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 { videosPath?: string; /** - * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent - * viewport emulation. + * 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. @@ -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 - * supported in Firefox. + * 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`. + * 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 - * viewport emulation. + * 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. @@ -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 - * supported in Firefox. + * 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`. + * 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 - * viewport emulation. + * 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. @@ -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 - * supported in Firefox. + * 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`. + * 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 - * viewport emulation. + * 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. diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index 8435aa44da..3a46308fee 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/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; @@ -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 - * supported in Firefox. + * **Usage** + * + * ```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 - * viewport emulation. + * **Usage** + * + * ```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; }