diff --git a/dotnet/docs/actionability.mdx b/dotnet/docs/actionability.mdx index 6d852566b9d1c..f7e79f75bae9b 100644 --- a/dotnet/docs/actionability.mdx +++ b/dotnet/docs/actionability.mdx @@ -8,7 +8,7 @@ import HTMLCard from '@site/src/components/HTMLCard'; Playwright performs a range of actionability checks on the elements before making actions to ensure these actions behave as expected. It auto-waits for all the relevant checks to pass and only then performs the requested action. If the required checks do not pass within the given `timeout`, action fails with the `TimeoutError`. -For example, for [Page.ClickAsync(selector, options)](/api/class-page.mdx#page-click), Playwright will ensure that: +For example, for [Page.ClickAsync();](/api/class-page.mdx#page-click), Playwright will ensure that: - element is [Attached] to the DOM - element is [Visible] - element is [Stable], as in not animating or completed animation @@ -45,29 +45,29 @@ Here is the complete list of actionability checks performed for each action: ## Forcing actions -Some actions like [Page.ClickAsync(selector, options)](/api/class-page.mdx#page-click) support `force` option that disables non-essential actionability checks, for example passing truthy `force` to [Page.ClickAsync(selector, options)](/api/class-page.mdx#page-click) method will not check that the target element actually receives click events. +Some actions like [Page.ClickAsync();](/api/class-page.mdx#page-click) support `force` option that disables non-essential actionability checks, for example passing truthy `force` to [Page.ClickAsync();](/api/class-page.mdx#page-click) method will not check that the target element actually receives click events. ## Assertions You can check the actionability state of the element using one of the following methods as well. This is typically not necessary, but it helps writing assertive tests that ensure that after certain actions, elements reach actionable state: -- [ElementHandle.IsCheckedAsync()](/api/class-elementhandle.mdx#element-handle-is-checked) -- [ElementHandle.IsDisabledAsync()](/api/class-elementhandle.mdx#element-handle-is-disabled) -- [ElementHandle.IsEditableAsync()](/api/class-elementhandle.mdx#element-handle-is-editable) -- [ElementHandle.IsEnabledAsync()](/api/class-elementhandle.mdx#element-handle-is-enabled) -- [ElementHandle.IsHiddenAsync()](/api/class-elementhandle.mdx#element-handle-is-hidden) -- [ElementHandle.IsVisibleAsync()](/api/class-elementhandle.mdx#element-handle-is-visible) -- [Page.IsCheckedAsync(selector, options)](/api/class-page.mdx#page-is-checked) -- [Page.IsDisabledAsync(selector, options)](/api/class-page.mdx#page-is-disabled) -- [Page.IsEditableAsync(selector, options)](/api/class-page.mdx#page-is-editable) -- [Page.IsEnabledAsync(selector, options)](/api/class-page.mdx#page-is-enabled) -- [Page.IsHiddenAsync(selector, options)](/api/class-page.mdx#page-is-hidden) -- [Page.IsVisibleAsync(selector, options)](/api/class-page.mdx#page-is-visible) -- [Locator.IsCheckedAsync(options)](/api/class-locator.mdx#locator-is-checked) -- [Locator.IsDisabledAsync(options)](/api/class-locator.mdx#locator-is-disabled) -- [Locator.IsEditableAsync(options)](/api/class-locator.mdx#locator-is-editable) -- [Locator.IsEnabledAsync(options)](/api/class-locator.mdx#locator-is-enabled) -- [Locator.IsHiddenAsync(options)](/api/class-locator.mdx#locator-is-hidden) -- [Locator.IsVisibleAsync(options)](/api/class-locator.mdx#locator-is-visible) +- [ElementHandle.IsCheckedAsync();](/api/class-elementhandle.mdx#element-handle-is-checked) +- [ElementHandle.IsDisabledAsync();](/api/class-elementhandle.mdx#element-handle-is-disabled) +- [ElementHandle.IsEditableAsync();](/api/class-elementhandle.mdx#element-handle-is-editable) +- [ElementHandle.IsEnabledAsync();](/api/class-elementhandle.mdx#element-handle-is-enabled) +- [ElementHandle.IsHiddenAsync();](/api/class-elementhandle.mdx#element-handle-is-hidden) +- [ElementHandle.IsVisibleAsync();](/api/class-elementhandle.mdx#element-handle-is-visible) +- [Page.IsCheckedAsync();](/api/class-page.mdx#page-is-checked) +- [Page.IsDisabledAsync();](/api/class-page.mdx#page-is-disabled) +- [Page.IsEditableAsync();](/api/class-page.mdx#page-is-editable) +- [Page.IsEnabledAsync();](/api/class-page.mdx#page-is-enabled) +- [Page.IsHiddenAsync();](/api/class-page.mdx#page-is-hidden) +- [Page.IsVisibleAsync();](/api/class-page.mdx#page-is-visible) +- [Locator.IsCheckedAsync();](/api/class-locator.mdx#locator-is-checked) +- [Locator.IsDisabledAsync();](/api/class-locator.mdx#locator-is-disabled) +- [Locator.IsEditableAsync();](/api/class-locator.mdx#locator-is-editable) +- [Locator.IsEnabledAsync();](/api/class-locator.mdx#locator-is-enabled) +- [Locator.IsHiddenAsync();](/api/class-locator.mdx#locator-is-hidden) +- [Locator.IsVisibleAsync();](/api/class-locator.mdx#locator-is-visible)
@@ -95,7 +95,7 @@ Element is considered editable when it is [enabled] and does not have `readonly` Element is considered receiving pointer events when it is the hit target of the pointer event at the action point. For example, when clicking at the point `(10;10)`, Playwright checks whether some other element (usually an overlay) will instead capture the click at `(10;10)`. -For example, consider a scenario where Playwright will click `Sign Up` button regardless of when the [Page.ClickAsync(selector, options)](/api/class-page.mdx#page-click) call was made: +For example, consider a scenario where Playwright will click `Sign Up` button regardless of when the [Page.ClickAsync();](/api/class-page.mdx#page-click) call was made: - page is checking that user name is unique and `Sign Up` button is disabled; - after checking with the server, the disabled `Sign Up` button is replaced with another one that is now enabled. diff --git a/dotnet/docs/api-testing.mdx b/dotnet/docs/api-testing.mdx index d2df374f951bd..de808c90375be 100644 --- a/dotnet/docs/api-testing.mdx +++ b/dotnet/docs/api-testing.mdx @@ -381,7 +381,7 @@ The following test creates a new issue via user interface in the browser and the ## Reuse authentication state -Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). Playwright provides [ApiRequestContext.StorageStateAsync(options)](/api/class-apirequestcontext.mdx#api-request-context-storage-state) method that can be used to retrieve storage state from an authenticated context and then create new contexts with that state. +Web apps use cookie-based or token-based authentication, where authenticated state is stored as [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). Playwright provides [ApiRequestContext.StorageStateAsync();](/api/class-apirequestcontext.mdx#api-request-context-storage-state) method that can be used to retrieve storage state from an authenticated context and then create new contexts with that state. Storage state is interchangeable between [BrowserContext] and [APIRequestContext]. You can use it to log in via API calls and then create a new context with cookies already there. The following code snippet retrieves state from an authenticated [APIRequestContext] and creates a new [BrowserContext] with that state. diff --git a/dotnet/docs/api/class-accessibility.mdx b/dotnet/docs/api/class-accessibility.mdx index 09a28d92f59b9..9ff7b0bbd55f2 100644 --- a/dotnet/docs/api/class-accessibility.mdx +++ b/dotnet/docs/api/class-accessibility.mdx @@ -17,17 +17,12 @@ Rendering engines of Chromium, Firefox and WebKit have a concept of "accessibili Most of the accessibility tree gets filtered out when converting from internal browser AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing only the "interesting" nodes of the tree. -- [Accessibility.SnapshotAsync(options)](/api/class-accessibility.mdx#accessibility-snapshot) +--- -## Accessibility.SnapshotAsync(options) {#accessibility-snapshot} +## SnapshotAsync {#accessibility-snapshot} Added in: v1.8 -- `options` <`AccessibilitySnapshotOptions?`> - - `InterestingOnly`# - - `Root`# -- returns:# - **DEPRECATED** This method is deprecated. Please use other libraries such as [Axe](https://www.deque.com/axe/) if you need to test page accessibility. See our Node.js [guide](https://playwright.dev/docs/accessibility-testing) for integration with Axe. Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. @@ -50,6 +45,19 @@ var accessibilitySnapshot = await page.Accessibility.SnapshotAsync(); Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(accessibilitySnapshot)); ``` +#### Usage + +```csharp +await Accessibility.SnapshotAsync(options); +``` + +#### Parameters +- `options` <`AccessibilitySnapshotOptions?`> + - `InterestingOnly` <[bool]?> Prune uninteresting nodes from the tree. Defaults to `true`.# + - `Root` <[ElementHandle]?> The root DOM element for the snapshot. Defaults to the whole page.# + +#### Returns +- <[JsonElement]?># [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" diff --git a/dotnet/docs/api/class-apirequest.mdx b/dotnet/docs/api/class-apirequest.mdx index e47508ba19e65..9f9ca1cb6ec3a 100644 --- a/dotnet/docs/api/class-apirequest.mdx +++ b/dotnet/docs/api/class-apirequest.mdx @@ -9,34 +9,43 @@ import HTMLCard from '@site/src/components/HTMLCard'; Exposes API that can be used for the Web API testing. This class is used for creating [APIRequestContext] instance which in turn can be used for sending web requests. An instance of this class can be obtained via [Playwright.APIRequest](/api/class-playwright.mdx#playwright-request). For more information see [APIRequestContext]. -- [ApiRequest.NewContextAsync(options)](/api/class-apirequest.mdx#api-request-new-context) +--- -## ApiRequest.NewContextAsync(options) {#api-request-new-context} +## NewContextAsync {#api-request-new-context} Added in: v1.16 +Creates new instances of [APIRequestContext]. + +#### Usage + +```csharp +await ApiRequest.NewContextAsync(options); +``` + +#### Parameters - `options` <`ApiRequestNewContextOptions?`> - - `BaseURL`# + - `BaseURL` <[string]?> Methods like [ApiRequestContext.GetAsync();](/api/class-apirequestcontext.mdx#api-request-context-get) take the base URL into consideration by using the [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL. Examples:# * baseURL: `http://localhost:3000` and sending request to `/bar.html` results in `http://localhost:3000/bar.html` * baseURL: `http://localhost:3000/foo/` and sending request to `./bar.html` results in `http://localhost:3000/foo/bar.html` * baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in `http://localhost:3000/bar.html` - - `ExtraHTTPHeaders`# - - `HttpCredentials`# + - `ExtraHTTPHeaders` <[IDictionary]?<[string], [string]>> An object containing additional HTTP headers to be sent with every request.# + - `HttpCredentials` <HttpCredentials?> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).# - `Username` <[string]> - `Password` <[string]> - - `IgnoreHTTPSErrors`# - - `Proxy`# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `Proxy` <Proxy?> Network proxy settings.# - `Server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - `Bypass` <[string]?> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - `Username` <[string]?> Optional username to use if HTTP proxy requires authentication. - `Password` <[string]?> Optional password to use if HTTP proxy requires authentication. - - `StorageState`# - - `StorageStatePath`# - - `Timeout`# - - `UserAgent`# -- returns:# + - `StorageState` <[string]?> Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync();](/api/class-browsercontext.mdx#browser-context-storage-state) or [ApiRequestContext.StorageStateAsync();](/api/class-apirequestcontext.mdx#api-request-context-storage-state). Either a path to the file with saved storage, or the value returned by one of [BrowserContext.StorageStateAsync();](/api/class-browsercontext.mdx#browser-context-storage-state) or [ApiRequestContext.StorageStateAsync();](/api/class-apirequestcontext.mdx#api-request-context-storage-state) methods.# + - `StorageStatePath` <[string]?> Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync();](/api/class-browsercontext.mdx#browser-context-storage-state). Path to the file with saved storage state. Added in: v1.18# + - `Timeout` <[double]?> Maximum time in milliseconds to wait for the response. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# + - `UserAgent` <[string]?> Specific user agent to use in this context.# -Creates new instances of [APIRequestContext]. +#### Returns +- <[APIRequestContext]># [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" diff --git a/dotnet/docs/api/class-apirequestcontext.mdx b/dotnet/docs/api/class-apirequestcontext.mdx index 94fc78d92e2e0..083a586fb128f 100644 --- a/dotnet/docs/api/class-apirequestcontext.mdx +++ b/dotnet/docs/api/class-apirequestcontext.mdx @@ -8,86 +8,88 @@ import HTMLCard from '@site/src/components/HTMLCard'; This API is used for the Web API testing. You can use it to trigger API endpoints, configure micro-services, prepare environment or the service to your e2e test. -Each Playwright browser context has associated with it [APIRequestContext] instance which shares cookie storage with the browser context and can be accessed via [BrowserContext.APIRequest](/api/class-browsercontext.mdx#browser-context-request) or [Page.APIRequest](/api/class-page.mdx#page-request). It is also possible to create a new APIRequestContext instance manually by calling [ApiRequest.NewContextAsync(options)](/api/class-apirequest.mdx#api-request-new-context). +Each Playwright browser context has associated with it [APIRequestContext] instance which shares cookie storage with the browser context and can be accessed via [BrowserContext.APIRequest](/api/class-browsercontext.mdx#browser-context-request) or [Page.APIRequest](/api/class-page.mdx#page-request). It is also possible to create a new APIRequestContext instance manually by calling [ApiRequest.NewContextAsync();](/api/class-apirequest.mdx#api-request-new-context). **Cookie management** [APIRequestContext] returned by [BrowserContext.APIRequest](/api/class-browsercontext.mdx#browser-context-request) and [Page.APIRequest](/api/class-page.mdx#page-request) shares cookie storage with the corresponding [BrowserContext]. Each API request will have `Cookie` header populated with the values from the browser context. If the API response contains `Set-Cookie` header it will automatically update [BrowserContext] cookies and requests made from the page will pick them up. This means that if you log in using this API, your e2e test will be logged in and vice versa. -If you want API requests to not interfere with the browser cookies you should create a new [APIRequestContext] by calling [ApiRequest.NewContextAsync(options)](/api/class-apirequest.mdx#api-request-new-context). Such `APIRequestContext` object will have its own isolated cookie storage. +If you want API requests to not interfere with the browser cookies you should create a new [APIRequestContext] by calling [ApiRequest.NewContextAsync();](/api/class-apirequest.mdx#api-request-new-context). Such `APIRequestContext` object will have its own isolated cookie storage. -- [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data) -- [ApiRequestContext.DeleteAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-delete) -- [ApiRequestContext.DisposeAsync()](/api/class-apirequestcontext.mdx#api-request-context-dispose) -- [ApiRequestContext.FetchAsync(urlOrRequest, options)](/api/class-apirequestcontext.mdx#api-request-context-fetch) -- [ApiRequestContext.GetAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-get) -- [ApiRequestContext.HeadAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-head) -- [ApiRequestContext.PatchAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-patch) -- [ApiRequestContext.PostAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-post) -- [ApiRequestContext.PutAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-put) -- [ApiRequestContext.StorageStateAsync(options)](/api/class-apirequestcontext.mdx#api-request-context-storage-state) +--- -## ApiRequestContext.CreateFormData {#api-request-context-create-form-data} +## CreateFormData {#api-request-context-create-form-data} Added in: v1.23 -- returns:# - Creates a new [FormData] instance which is used for providing form and multipart data when making HTTP requests. -## ApiRequestContext.DeleteAsync(url, options) {#api-request-context-delete} +#### Usage + +```csharp +ApiRequestContext.CreateFormData +``` + +#### Returns +- <[FormData]># + +--- + +## DeleteAsync {#api-request-context-delete} Added in: v1.16 -- `url`# +Sends HTTP(S) [DELETE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. + +#### Usage + +```csharp +await ApiRequestContext.DeleteAsync(url, options); +``` + +#### Parameters +- `url` <[string]> Target URL.# - `options` <`ApiRequestContextDeleteOptions?`> - - `Data|DataByte|DataObject`# - - `FailOnStatusCode`# - - `Form`# + - `Data|DataByte|DataObject` <[string]?|[byte][]?|[object]?> Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type` header will be set to `application/octet-stream` if not explicitly set. Added in: v1.17# + - `FailOnStatusCode` <[bool]?> Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.# + - `Form` <[FormData]?> Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded` unless explicitly provided. Added in: v1.17# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Headers`# - - `IgnoreHTTPSErrors`# - - `MaxRedirects`# - - `Multipart`# + - `Headers` <[IDictionary]?<[string], [string]>> Allows to set HTTP headers.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `MaxRedirects` <[int]?> Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is exceeded. Defaults to `20`. Pass `0` to not follow redirects. Added in: v1.26# + - `Multipart` <[FormData]?> Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file name, mime-type and its content. Added in: v1.17# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Params`# - - `Timeout`# -- returns:# + - `Params` <[IDictionary]?<[string], [object]>> Query parameters to be sent with the URL.# + - `Timeout` <[double]?> Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# -Sends HTTP(S) [DELETE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. +#### Returns +- <[APIResponse]># -## ApiRequestContext.DisposeAsync() {#api-request-context-dispose} +--- + +## DisposeAsync {#api-request-context-dispose} Added in: v1.16 -- returns:# +All responses returned by [ApiRequestContext.GetAsync();](/api/class-apirequestcontext.mdx#api-request-context-get) and similar methods are stored in the memory, so that you can later call [ApiResponse.BodyAsync();](/api/class-apiresponse.mdx#api-response-body). This method discards all stored responses, and makes [ApiResponse.BodyAsync();](/api/class-apiresponse.mdx#api-response-body) throw "Response disposed" error. -All responses returned by [ApiRequestContext.GetAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-get) and similar methods are stored in the memory, so that you can later call [ApiResponse.BodyAsync()](/api/class-apiresponse.mdx#api-response-body). This method discards all stored responses, and makes [ApiResponse.BodyAsync()](/api/class-apiresponse.mdx#api-response-body) throw "Response disposed" error. +#### Usage -## ApiRequestContext.FetchAsync(urlOrRequest, options) {#api-request-context-fetch} +```csharp +await ApiRequestContext.DisposeAsync(); +``` -Added in: v1.16 +#### Returns +- <[void]># -- `urlOrRequest`# -- `options` <`ApiRequestContextFetchOptions?`> - - `Data|DataByte|DataObject`# - - `FailOnStatusCode`# - - `Form`# +--- - An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Headers`# - - `IgnoreHTTPSErrors`# - - `MaxRedirects`# - - `Method`# - - `Multipart`# +## FetchAsync {#api-request-context-fetch} - An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Params`# - - `Timeout`# -- returns:# +Added in: v1.16 Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. @@ -115,26 +117,38 @@ multipart.Set("fileField", file); await Request.FetchAsync("https://example.com/api/uploadScript", new() { Method = "post", Multipart = multipart }); ``` -## ApiRequestContext.GetAsync(url, options) {#api-request-context-get} +#### Usage -Added in: v1.16 +```csharp +await ApiRequestContext.FetchAsync(urlOrRequest, options); +``` -- `url`# -- `options` <`ApiRequestContextGetOptions?`> - - `Data|DataByte|DataObject`# - - `FailOnStatusCode`# - - `Form`# +#### Parameters +- `urlOrRequest` <[string]|[Request]> Target URL or Request to get all parameters from.# +- `options` <`ApiRequestContextFetchOptions?`> + - `Data|DataByte|DataObject` <[string]?|[byte][]?|[object]?> Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type` header will be set to `application/octet-stream` if not explicitly set.# + - `FailOnStatusCode` <[bool]?> Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.# + - `Form` <[FormData]?> Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded` unless explicitly provided.# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Headers`# - - `IgnoreHTTPSErrors`# - - `MaxRedirects`# - - `Multipart`# + - `Headers` <[IDictionary]?<[string], [string]>> Allows to set HTTP headers.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `MaxRedirects` <[int]?> Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is exceeded. Defaults to `20`. Pass `0` to not follow redirects. Added in: v1.26# + - `Method` <[string]?> If set changes the fetch method (e.g. [PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) or [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)). If not specified, GET method is used.# + - `Multipart` <[FormData]?> Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file name, mime-type and its content.# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Params`# - - `Timeout`# -- returns:# + - `Params` <[IDictionary]?<[string], [object]>> Query parameters to be sent with the URL.# + - `Timeout` <[double]?> Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# + +#### Returns +- <[APIResponse]># + +--- + +## GetAsync {#api-request-context-get} + +Added in: v1.16 Sends HTTP(S) [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. @@ -149,72 +163,105 @@ var params = new Dictionary() await request.GetAsync("https://example.com/api/getText", new() { Params = params }); ``` -## ApiRequestContext.HeadAsync(url, options) {#api-request-context-head} +#### Usage -Added in: v1.16 +```csharp +await ApiRequestContext.GetAsync(url, options); +``` -- `url`# -- `options` <`ApiRequestContextHeadOptions?`> - - `Data|DataByte|DataObject`# - - `FailOnStatusCode`# - - `Form`# +#### Parameters +- `url` <[string]> Target URL.# +- `options` <`ApiRequestContextGetOptions?`> + - `Data|DataByte|DataObject` <[string]?|[byte][]?|[object]?> Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type` header will be set to `application/octet-stream` if not explicitly set. Added in: v1.26# + - `FailOnStatusCode` <[bool]?> Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.# + - `Form` <[FormData]?> Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded` unless explicitly provided. Added in: v1.26# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Headers`# - - `IgnoreHTTPSErrors`# - - `MaxRedirects`# - - `Multipart`# + - `Headers` <[IDictionary]?<[string], [string]>> Allows to set HTTP headers.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `MaxRedirects` <[int]?> Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is exceeded. Defaults to `20`. Pass `0` to not follow redirects. Added in: v1.26# + - `Multipart` <[FormData]?> Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file name, mime-type and its content. Added in: v1.26# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Params`# - - `Timeout`# -- returns:# + - `Params` <[IDictionary]?<[string], [object]>> Query parameters to be sent with the URL.# + - `Timeout` <[double]?> Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# -Sends HTTP(S) [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. +#### Returns +- <[APIResponse]># + +--- -## ApiRequestContext.PatchAsync(url, options) {#api-request-context-patch} +## HeadAsync {#api-request-context-head} Added in: v1.16 -- `url`# -- `options` <`ApiRequestContextPatchOptions?`> - - `Data|DataByte|DataObject`# - - `FailOnStatusCode`# - - `Form`# +Sends HTTP(S) [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. + +#### Usage + +```csharp +await ApiRequestContext.HeadAsync(url, options); +``` + +#### Parameters +- `url` <[string]> Target URL.# +- `options` <`ApiRequestContextHeadOptions?`> + - `Data|DataByte|DataObject` <[string]?|[byte][]?|[object]?> Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type` header will be set to `application/octet-stream` if not explicitly set. Added in: v1.26# + - `FailOnStatusCode` <[bool]?> Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.# + - `Form` <[FormData]?> Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded` unless explicitly provided. Added in: v1.26# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Headers`# - - `IgnoreHTTPSErrors`# - - `MaxRedirects`# - - `Multipart`# + - `Headers` <[IDictionary]?<[string], [string]>> Allows to set HTTP headers.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `MaxRedirects` <[int]?> Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is exceeded. Defaults to `20`. Pass `0` to not follow redirects. Added in: v1.26# + - `Multipart` <[FormData]?> Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file name, mime-type and its content. Added in: v1.26# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Params`# - - `Timeout`# -- returns:# + - `Params` <[IDictionary]?<[string], [object]>> Query parameters to be sent with the URL.# + - `Timeout` <[double]?> Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# -Sends HTTP(S) [PATCH](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. +#### Returns +- <[APIResponse]># -## ApiRequestContext.PostAsync(url, options) {#api-request-context-post} +--- + +## PatchAsync {#api-request-context-patch} Added in: v1.16 -- `url`# -- `options` <`ApiRequestContextPostOptions?`> - - `Data|DataByte|DataObject`# - - `FailOnStatusCode`# - - `Form`# +Sends HTTP(S) [PATCH](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. + +#### Usage + +```csharp +await ApiRequestContext.PatchAsync(url, options); +``` + +#### Parameters +- `url` <[string]> Target URL.# +- `options` <`ApiRequestContextPatchOptions?`> + - `Data|DataByte|DataObject` <[string]?|[byte][]?|[object]?> Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type` header will be set to `application/octet-stream` if not explicitly set.# + - `FailOnStatusCode` <[bool]?> Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.# + - `Form` <[FormData]?> Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded` unless explicitly provided.# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Headers`# - - `IgnoreHTTPSErrors`# - - `MaxRedirects`# - - `Multipart`# + - `Headers` <[IDictionary]?<[string], [string]>> Allows to set HTTP headers.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `MaxRedirects` <[int]?> Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is exceeded. Defaults to `20`. Pass `0` to not follow redirects. Added in: v1.26# + - `Multipart` <[FormData]?> Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file name, mime-type and its content.# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Params`# - - `Timeout`# -- returns:# + - `Params` <[IDictionary]?<[string], [object]>> Query parameters to be sent with the URL.# + - `Timeout` <[double]?> Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# + +#### Returns +- <[APIResponse]># + +--- + +## PostAsync {#api-request-context-post} + +Added in: v1.16 Sends HTTP(S) [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. @@ -251,38 +298,86 @@ multipart.Set("fileField", file); await request.PostAsync("https://example.com/api/uploadScript", new() { Multipart = multipart }); ``` -## ApiRequestContext.PutAsync(url, options) {#api-request-context-put} +#### Usage + +```csharp +await ApiRequestContext.PostAsync(url, options); +``` + +#### Parameters +- `url` <[string]> Target URL.# +- `options` <`ApiRequestContextPostOptions?`> + - `Data|DataByte|DataObject` <[string]?|[byte][]?|[object]?> Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type` header will be set to `application/octet-stream` if not explicitly set.# + - `FailOnStatusCode` <[bool]?> Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.# + - `Form` <[FormData]?> Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded` unless explicitly provided.# + + An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). + - `Headers` <[IDictionary]?<[string], [string]>> Allows to set HTTP headers.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `MaxRedirects` <[int]?> Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is exceeded. Defaults to `20`. Pass `0` to not follow redirects. Added in: v1.26# + - `Multipart` <[FormData]?> Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file name, mime-type and its content.# + + An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). + - `Params` <[IDictionary]?<[string], [object]>> Query parameters to be sent with the URL.# + - `Timeout` <[double]?> Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# + +#### Returns +- <[APIResponse]># + +--- + +## PutAsync {#api-request-context-put} Added in: v1.16 -- `url`# +Sends HTTP(S) [PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. + +#### Usage + +```csharp +await ApiRequestContext.PutAsync(url, options); +``` + +#### Parameters +- `url` <[string]> Target URL.# - `options` <`ApiRequestContextPutOptions?`> - - `Data|DataByte|DataObject`# - - `FailOnStatusCode`# - - `Form`# + - `Data|DataByte|DataObject` <[string]?|[byte][]?|[object]?> Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type` header will be set to `application/octet-stream` if not explicitly set.# + - `FailOnStatusCode` <[bool]?> Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.# + - `Form` <[FormData]?> Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded` unless explicitly provided.# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Headers`# - - `IgnoreHTTPSErrors`# - - `MaxRedirects`# - - `Multipart`# + - `Headers` <[IDictionary]?<[string], [string]>> Allows to set HTTP headers.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `MaxRedirects` <[int]?> Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is exceeded. Defaults to `20`. Pass `0` to not follow redirects. Added in: v1.26# + - `Multipart` <[FormData]?> Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data` unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream) or as file-like object containing file name, mime-type and its content.# An instance of [FormData] can be created via [ApiRequestContext.CreateFormData](/api/class-apirequestcontext.mdx#api-request-context-create-form-data). - - `Params`# - - `Timeout`# -- returns:# + - `Params` <[IDictionary]?<[string], [object]>> Query parameters to be sent with the URL.# + - `Timeout` <[double]?> Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# -Sends HTTP(S) [PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) request and returns its response. The method will populate request cookies from the context and update context cookies from the response. The method will automatically follow redirects. +#### Returns +- <[APIResponse]># -## ApiRequestContext.StorageStateAsync(options) {#api-request-context-storage-state} +--- + +## StorageStateAsync {#api-request-context-storage-state} Added in: v1.16 +Returns storage state for this request context, contains current cookies and local storage snapshot if it was passed to the constructor. + +#### Usage + +```csharp +await ApiRequestContext.StorageStateAsync(options); +``` + +#### Parameters - `options` <`ApiRequestContextStorageStateOptions?`> - - `Path`# -- returns:# + - `Path` <[string]?> The file path to save the storage state to. If `path` is a relative path, then it is resolved relative to current working directory. If no path is provided, storage state is still returned, but won't be saved to the disk.# -Returns storage state for this request context, contains current cookies and local storage snapshot if it was passed to the constructor. +#### Returns +- <[string]># [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" diff --git a/dotnet/docs/api/class-apiresponse.mdx b/dotnet/docs/api/class-apiresponse.mdx index 11c0d4a200b63..68248bdbb1743 100644 --- a/dotnet/docs/api/class-apiresponse.mdx +++ b/dotnet/docs/api/class-apiresponse.mdx @@ -6,104 +6,183 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import HTMLCard from '@site/src/components/HTMLCard'; -[APIResponse] class represents responses returned by [ApiRequestContext.GetAsync(url, options)](/api/class-apirequestcontext.mdx#api-request-context-get) and similar methods. +[APIResponse] class represents responses returned by [ApiRequestContext.GetAsync();](/api/class-apirequestcontext.mdx#api-request-context-get) and similar methods. -- [ApiResponse.BodyAsync()](/api/class-apiresponse.mdx#api-response-body) -- [ApiResponse.DisposeAsync()](/api/class-apiresponse.mdx#api-response-dispose) -- [ApiResponse.Headers](/api/class-apiresponse.mdx#api-response-headers) -- [ApiResponse.HeadersArray](/api/class-apiresponse.mdx#api-response-headers-array) -- [ApiResponse.JsonAsync()](/api/class-apiresponse.mdx#api-response-json) -- [ApiResponse.Ok](/api/class-apiresponse.mdx#api-response-ok) -- [ApiResponse.Status](/api/class-apiresponse.mdx#api-response-status) -- [ApiResponse.StatusText](/api/class-apiresponse.mdx#api-response-status-text) -- [ApiResponse.TextAsync()](/api/class-apiresponse.mdx#api-response-text) -- [ApiResponse.Url](/api/class-apiresponse.mdx#api-response-url) +--- -## ApiResponse.BodyAsync() {#api-response-body} +## BodyAsync {#api-response-body} Added in: v1.16 -- returns:# - Returns the buffer with response body. -## ApiResponse.DisposeAsync() {#api-response-dispose} +#### Usage -Added in: v1.16 +```csharp +await ApiResponse.BodyAsync(); +``` -- returns:# +#### Returns +- <[byte][]># -Disposes the body of this response. If not called then the body will stay in memory until the context closes. +--- -## ApiResponse.Headers {#api-response-headers} +## DisposeAsync {#api-response-dispose} Added in: v1.16 -- returns:# +Disposes the body of this response. If not called then the body will stay in memory until the context closes. + +#### Usage + +```csharp +await ApiResponse.DisposeAsync(); +``` + +#### Returns +- <[void]># + +--- + +## Headers {#api-response-headers} + +Added in: v1.16 An object with all the response HTTP headers associated with this response. -## ApiResponse.HeadersArray {#api-response-headers-array} +#### Usage + +```csharp +ApiResponse.Headers +``` + +#### Returns +- <[IDictionary]<[string], [string]>># + +--- + +## HeadersArray {#api-response-headers-array} Added in: v1.16 -- returns:# +An array with all the request HTTP headers associated with this response. Header names are not lower-cased. Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times. + +#### Usage + +```csharp +ApiResponse.HeadersArray +``` + +#### Returns +- <[IEnumerable]<`HttpHeader`>># - `name` <[string]> Name of the header. - `value` <[string]> Value of the header. -An array with all the request HTTP headers associated with this response. Header names are not lower-cased. Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times. +--- -## ApiResponse.JsonAsync() {#api-response-json} +## JsonAsync {#api-response-json} Added in: v1.16 -- returns:# - Returns the JSON representation of response body. This method will throw if the response body is not parsable via `JSON.parse`. -## ApiResponse.Ok {#api-response-ok} +#### Usage -Added in: v1.16 +```csharp +await ApiResponse.JsonAsync(); +``` -- returns:# +#### Returns +- <[JsonElement]?># -Contains a boolean stating whether the response was successful (status in the range 200-299) or not. +--- -## ApiResponse.Status {#api-response-status} +## Ok {#api-response-ok} Added in: v1.16 -- returns:# +Contains a boolean stating whether the response was successful (status in the range 200-299) or not. -Contains the status code of the response (e.g., 200 for a success). +#### Usage + +```csharp +ApiResponse.Ok +``` + +#### Returns +- <[bool]># + +--- -## ApiResponse.StatusText {#api-response-status-text} +## Status {#api-response-status} Added in: v1.16 -- returns:# +Contains the status code of the response (e.g., 200 for a success). + +#### Usage -Contains the status text of the response (e.g. usually an "OK" for a success). +```csharp +ApiResponse.Status +``` -## ApiResponse.TextAsync() {#api-response-text} +#### Returns +- <[int]># + +--- + +## StatusText {#api-response-status-text} Added in: v1.16 -- returns:# +Contains the status text of the response (e.g. usually an "OK" for a success). -Returns the text representation of response body. +#### Usage + +```csharp +ApiResponse.StatusText +``` -## ApiResponse.Url {#api-response-url} +#### Returns +- <[string]># + +--- + +## TextAsync {#api-response-text} Added in: v1.16 -- returns:# +Returns the text representation of response body. + +#### Usage + +```csharp +await ApiResponse.TextAsync(); +``` + +#### Returns +- <[string]># + +--- + +## Url {#api-response-url} + +Added in: v1.16 Contains the URL of the response. +#### Usage + +```csharp +ApiResponse.Url +``` + +#### Returns +- <[string]># + [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" [APIRequestContext]: /api/class-apirequestcontext.mdx "APIRequestContext" diff --git a/dotnet/docs/api/class-browser.mdx b/dotnet/docs/api/class-browser.mdx index 9c3257b3e4162..013d48ad20140 100644 --- a/dotnet/docs/api/class-browser.mdx +++ b/dotnet/docs/api/class-browser.mdx @@ -8,7 +8,7 @@ import HTMLCard from '@site/src/components/HTMLCard'; * extends: [EventEmitter] -A Browser is created via [BrowserType.LaunchAsync(options)](/api/class-browsertype.mdx#browser-type-launch). An example of using a [Browser] to create a [Page]: +A Browser is created via [BrowserType.LaunchAsync();](/api/class-browsertype.mdx#browser-type-launch). An example of using a [Browser] to create a [Page]: ```csharp using Microsoft.Playwright; @@ -22,54 +22,72 @@ await browser.CloseAsync(); ``` -- [event Browser.Disconnected](/api/class-browser.mdx#browser-event-disconnected) -- [Browser.BrowserType](/api/class-browser.mdx#browser-browser-type) -- [Browser.CloseAsync()](/api/class-browser.mdx#browser-close) -- [Browser.Contexts](/api/class-browser.mdx#browser-contexts) -- [Browser.IsConnected](/api/class-browser.mdx#browser-is-connected) -- [Browser.NewContextAsync(options)](/api/class-browser.mdx#browser-new-context) -- [Browser.NewPageAsync(options)](/api/class-browser.mdx#browser-new-page) -- [Browser.Version](/api/class-browser.mdx#browser-version) +--- -## event Browser.Disconnected {#browser-event-disconnected} +## event Disconnected {#browser-event-disconnected} Added in: v1.8 -- type: <[Browser]> - Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following: * Browser application is closed or crashed. -* The [Browser.CloseAsync()](/api/class-browser.mdx#browser-close) method was called. +* The [Browser.CloseAsync();](/api/class-browser.mdx#browser-close) method was called. -## Browser.BrowserType {#browser-browser-type} +#### Usage -Added in: v1.23 +```csharp +Browser.Disconnected += async data => {}; +``` + +#### Event data +- <[Browser]> -- returns:# +--- + +## BrowserType {#browser-browser-type} + +Added in: v1.23 Get the browser type (chromium, firefox or webkit) that the browser belongs to. -## Browser.CloseAsync() {#browser-close} +#### Usage -Added in: v1.8 +```csharp +Browser.BrowserType +``` + +#### Returns +- <[BrowserType]># + +--- + +## CloseAsync {#browser-close} -- returns:# +Added in: v1.8 -In case this browser is obtained using [BrowserType.LaunchAsync(options)](/api/class-browsertype.mdx#browser-type-launch), closes the browser and all of its pages (if any were opened). +In case this browser is obtained using [BrowserType.LaunchAsync();](/api/class-browsertype.mdx#browser-type-launch), closes the browser and all of its pages (if any were opened). In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the browser server. :::note -This is similar to force quitting the browser. Therefore, you should call [BrowserContext.CloseAsync()](/api/class-browsercontext.mdx#browser-context-close) on any [BrowserContext]'s you explicitly created earlier with [Browser.NewContextAsync(options)](/api/class-browser.mdx#browser-new-context) **before** calling [Browser.CloseAsync()](/api/class-browser.mdx#browser-close). +This is similar to force quitting the browser. Therefore, you should call [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) on any [BrowserContext]'s you explicitly created earlier with [Browser.NewContextAsync();](/api/class-browser.mdx#browser-new-context) **before** calling [Browser.CloseAsync();](/api/class-browser.mdx#browser-close). ::: The [Browser] object itself is considered to be disposed and cannot be used anymore. -## Browser.Contexts {#browser-contexts} +#### Usage -Added in: v1.8 +```csharp +await Browser.CloseAsync(); +``` + +#### Returns +- <[void]># + +--- -- returns:# +## Contexts {#browser-contexts} + +Added in: v1.8 Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts. @@ -81,44 +99,91 @@ var context = await browser.NewContextAsync(); System.Console.WriteLine(browser.Contexts.Count); // prints "1" ``` -## Browser.IsConnected {#browser-is-connected} +#### Usage -Added in: v1.8 +```csharp +Browser.Contexts +``` + +#### Returns +- <[IEnumerable]<[BrowserContext]>># -- returns:# +--- + +## IsConnected {#browser-is-connected} + +Added in: v1.8 Indicates that the browser is connected. -## Browser.NewContextAsync(options) {#browser-new-context} +#### Usage + +```csharp +Browser.IsConnected +``` + +#### Returns +- <[bool]># + +--- + +## NewContextAsync {#browser-new-context} Added in: v1.8 +Creates a new browser context. It won't share cookies/cache with other browser contexts. + +:::note +If directly using this method to create [BrowserContext]s, it is best practice to explicitly close the returned context via [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) when your code is done with the [BrowserContext], and before calling [Browser.CloseAsync();](/api/class-browser.mdx#browser-close). This will ensure the `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved. +::: + +```csharp +using var playwright = await Playwright.CreateAsync(); +var browser = await playwright.Firefox.LaunchAsync(); +// Create a new incognito browser context. +var context = await browser.NewContextAsync(); +// Create a new page in a pristine context. +var page = await context.NewPageAsync(); ; +await page.GotoAsync("https://www.bing.com"); + +// Gracefully close up everything +await context.CloseAsync(); +await browser.CloseAsync(); +``` + +#### Usage + +```csharp +await Browser.NewContextAsync(options); +``` + +#### Parameters - `options` <`BrowserNewContextOptions?`> - - `AcceptDownloads`# - - `BaseURL`# + - `AcceptDownloads` <[bool]?> Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.# + - `BaseURL` <[string]?> When using [Page.GotoAsync();](/api/class-page.mdx#page-goto), [Page.RouteAsync();](/api/class-page.mdx#page-route), [Page.WaitForURLAsync();](/api/class-page.mdx#page-wait-for-url), [Page.RunAndWaitForRequestAsync();](/api/class-page.mdx#page-wait-for-request), or [Page.RunAndWaitForResponseAsync();](/api/class-page.mdx#page-wait-for-response) it takes the base URL in consideration by using the [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL. Examples:# * baseURL: `http://localhost:3000` and navigating to `/bar.html` results in `http://localhost:3000/bar.html` * baseURL: `http://localhost:3000/foo/` and navigating to `./bar.html` results in `http://localhost:3000/foo/bar.html` * baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in `http://localhost:3000/bar.html` - - `BypassCSP`# - - `ColorScheme`# - - `DeviceScaleFactor`# - - `ExtraHTTPHeaders`# - - `ForcedColors`# - - `Geolocation`# + - `BypassCSP` <[bool]?> Toggles bypassing page's Content-Security-Policy.# + - `ColorScheme` <`enum ColorScheme { Light, Dark, NoPreference, Null }?`> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'light'`.# + - `DeviceScaleFactor` <[double]?> Specify device scale factor (can be thought of as dpr). Defaults to `1`.# + - `ExtraHTTPHeaders` <[IDictionary]?<[string], [string]>> An object containing additional HTTP headers to be sent with every request.# + - `ForcedColors` <`enum ForcedColors { Active, None, Null }?`> Emulates `'forced-colors'` media feature, supported values are `'active'`, `'none'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'none'`.# + - `Geolocation` <Geolocation?># - `Latitude` <[double]> Latitude between -90 and 90. - `Longitude` <[double]> Longitude between -180 and 180. - `Accuracy` <[double]?> Non-negative accuracy value. Defaults to `0`. - - `HasTouch`# - - `HttpCredentials`# + - `HasTouch` <[bool]?> Specifies if viewport supports touch events. Defaults to false.# + - `HttpCredentials` <HttpCredentials?> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).# - `Username` <[string]> - `Password` <[string]> - - `IgnoreHTTPSErrors`# - - `IsMobile`# - - `JavaScriptEnabled`# - - `Locale`# - - `Offline`# - - `Permissions`# - - `Proxy`# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `IsMobile` <[bool]?> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.# + - `JavaScriptEnabled` <[bool]?> Whether or not to enable JavaScript in the context. Defaults to `true`.# + - `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.# + - `Offline` <[bool]?> Whether to emulate network being offline. Defaults to `false`.# + - `Permissions` <[IEnumerable]?<[string]>> A list of permissions to grant to all pages in this context. See [BrowserContext.GrantPermissionsAsync();](/api/class-browsercontext.mdx#browser-context-grant-permissions) for more details.# + - `Proxy` <Proxy?> Network proxy settings to use with this context.# - `Server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - `Bypass` <[string]?> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - `Username` <[string]?> Optional username to use if HTTP proxy requires authentication. @@ -130,82 +195,77 @@ Indicates that the browser is connected. For Chromium on Windows the browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example `launch({ proxy: { server: 'http://per-context' } })`. ::: - - `RecordHarContent`# - - `RecordHarMode`# - - `RecordHarOmitContent`# - - `RecordHarPath`# - - `RecordHarUrlFilter|RecordHarUrlFilterRegex`# - - `RecordVideoDir`# - - `RecordVideoSize`# + - `RecordHarContent` <`enum HarContentPolicy { Omit, Embed, Attach }?`> Optional setting to control resource content management. If `omit` is specified, content is not persisted. If `attach` is specified, resources are persisted as separate files and all of these files are archived along with the HAR file. Defaults to `embed`, which stores content inline the HAR file as per HAR specification.# + - `RecordHarMode` <`enum HarMode { Full, Minimal }?`> When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page, cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `full`.# + - `RecordHarOmitContent` <[bool]?> Optional setting to control whether to omit request content from the HAR. Defaults to `false`.# + - `RecordHarPath` <[string]?> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into the specified HAR file on the filesystem. If not specified, the HAR is not recorded. Make sure to call [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) for the HAR to be saved.# + - `RecordHarUrlFilter|RecordHarUrlFilterRegex` <[string]?|[Regex]?># + - `RecordVideoDir` <[string]?> Enables video recording for all pages into the specified directory. If not specified videos are not recorded. Make sure to call [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) for videos to be saved.# + - `RecordVideoSize` <RecordVideoSize?> Dimensions of the recorded videos. If not specified the size will be equal to `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.# - `Width` <[int]> Video frame width. - `Height` <[int]> Video frame height. - - `ReducedMotion`# - - `ScreenSize`# + - `ReducedMotion` <`enum ReducedMotion { Reduce, NoPreference, Null }?`> Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'no-preference'`.# + - `ScreenSize` <ScreenSize?> Emulates consistent window screen size available inside web page via `window.screen`. Is only used when the `viewport` is set.# - `Width` <[int]> page width in pixels. - `Height` <[int]> page height in pixels. - - `ServiceWorkers`# + - `ServiceWorkers` <`enum ServiceWorkerPolicy { Allow, Block }?`> 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. * `'block'`: Playwright will block all registration of Service Workers. - - `StorageState`# - - `StorageStatePath`# - - `StrictSelectors`# - - `TimezoneId`# - - `UserAgent`# - - `ViewportSize`# + - `StorageState` <[string]?> Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync();](/api/class-browsercontext.mdx#browser-context-storage-state).# + - `StorageStatePath` <[string]?> Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync();](/api/class-browsercontext.mdx#browser-context-storage-state). Path to the file with saved storage state. Added in: v1.9# + - `StrictSelectors` <[bool]?> If specified, enables strict selectors mode for this context. In the strict selectors mode all operations on selectors that imply single target DOM element will throw when more than one element matches the selector. See [Locator] to learn more about the strict mode.# + - `TimezoneId` <[string]?> 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.# + - `UserAgent` <[string]?> Specific user agent to use in this context.# + - `ViewportSize` <ViewportSize?> Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the default viewport.# - `Width` <[int]> page width in pixels. - `Height` <[int]> page height in pixels. -- returns:# -Creates a new browser context. It won't share cookies/cache with other browser contexts. +#### Returns +- <[BrowserContext]># -:::note -If directly using this method to create [BrowserContext]s, it is best practice to explicitly close the returned context via [BrowserContext.CloseAsync()](/api/class-browsercontext.mdx#browser-context-close) when your code is done with the [BrowserContext], and before calling [Browser.CloseAsync()](/api/class-browser.mdx#browser-close). This will ensure the `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved. -::: +--- -```csharp -using var playwright = await Playwright.CreateAsync(); -var browser = await playwright.Firefox.LaunchAsync(); -// Create a new incognito browser context. -var context = await browser.NewContextAsync(); -// Create a new page in a pristine context. -var page = await context.NewPageAsync(); ; -await page.GotoAsync("https://www.bing.com"); +## NewPageAsync {#browser-new-page} -// Gracefully close up everything -await context.CloseAsync(); -await browser.CloseAsync(); -``` +Added in: v1.8 -## Browser.NewPageAsync(options) {#browser-new-page} +Creates a new page in a new browser context. Closing this page will close the context as well. -Added in: v1.8 +This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and testing frameworks should explicitly create [Browser.NewContextAsync();](/api/class-browser.mdx#browser-new-context) followed by the [BrowserContext.NewPageAsync();](/api/class-browsercontext.mdx#browser-context-new-page) to control their exact life times. + +#### Usage +```csharp +await Browser.NewPageAsync(options); +``` + +#### Parameters - `options` <`BrowserNewPageOptions?`> - - `AcceptDownloads`# - - `BaseURL`# + - `AcceptDownloads` <[bool]?> Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.# + - `BaseURL` <[string]?> When using [Page.GotoAsync();](/api/class-page.mdx#page-goto), [Page.RouteAsync();](/api/class-page.mdx#page-route), [Page.WaitForURLAsync();](/api/class-page.mdx#page-wait-for-url), [Page.RunAndWaitForRequestAsync();](/api/class-page.mdx#page-wait-for-request), or [Page.RunAndWaitForResponseAsync();](/api/class-page.mdx#page-wait-for-response) it takes the base URL in consideration by using the [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL. Examples:# * baseURL: `http://localhost:3000` and navigating to `/bar.html` results in `http://localhost:3000/bar.html` * baseURL: `http://localhost:3000/foo/` and navigating to `./bar.html` results in `http://localhost:3000/foo/bar.html` * baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in `http://localhost:3000/bar.html` - - `BypassCSP`# - - `ColorScheme`# - - `DeviceScaleFactor`# - - `ExtraHTTPHeaders`# - - `ForcedColors`# - - `Geolocation`# + - `BypassCSP` <[bool]?> Toggles bypassing page's Content-Security-Policy.# + - `ColorScheme` <`enum ColorScheme { Light, Dark, NoPreference, Null }?`> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'light'`.# + - `DeviceScaleFactor` <[double]?> Specify device scale factor (can be thought of as dpr). Defaults to `1`.# + - `ExtraHTTPHeaders` <[IDictionary]?<[string], [string]>> An object containing additional HTTP headers to be sent with every request.# + - `ForcedColors` <`enum ForcedColors { Active, None, Null }?`> Emulates `'forced-colors'` media feature, supported values are `'active'`, `'none'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'none'`.# + - `Geolocation` <Geolocation?># - `Latitude` <[double]> Latitude between -90 and 90. - `Longitude` <[double]> Longitude between -180 and 180. - `Accuracy` <[double]?> Non-negative accuracy value. Defaults to `0`. - - `HasTouch`# - - `HttpCredentials`# + - `HasTouch` <[bool]?> Specifies if viewport supports touch events. Defaults to false.# + - `HttpCredentials` <HttpCredentials?> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).# - `Username` <[string]> - `Password` <[string]> - - `IgnoreHTTPSErrors`# - - `IsMobile`# - - `JavaScriptEnabled`# - - `Locale`# - - `Offline`# - - `Permissions`# - - `Proxy`# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `IsMobile` <[bool]?> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.# + - `JavaScriptEnabled` <[bool]?> Whether or not to enable JavaScript in the context. Defaults to `true`.# + - `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.# + - `Offline` <[bool]?> Whether to emulate network being offline. Defaults to `false`.# + - `Permissions` <[IEnumerable]?<[string]>> A list of permissions to grant to all pages in this context. See [BrowserContext.GrantPermissionsAsync();](/api/class-browsercontext.mdx#browser-context-grant-permissions) for more details.# + - `Proxy` <Proxy?> Network proxy settings to use with this context.# - `Server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - `Bypass` <[string]?> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - `Username` <[string]?> Optional username to use if HTTP proxy requires authentication. @@ -217,44 +277,51 @@ await browser.CloseAsync(); For Chromium on Windows the browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example `launch({ proxy: { server: 'http://per-context' } })`. ::: - - `RecordHarContent`# - - `RecordHarMode`# - - `RecordHarOmitContent`# - - `RecordHarPath`# - - `RecordHarUrlFilter|RecordHarUrlFilterRegex`# - - `RecordVideoDir`# - - `RecordVideoSize`# + - `RecordHarContent` <`enum HarContentPolicy { Omit, Embed, Attach }?`> Optional setting to control resource content management. If `omit` is specified, content is not persisted. If `attach` is specified, resources are persisted as separate files and all of these files are archived along with the HAR file. Defaults to `embed`, which stores content inline the HAR file as per HAR specification.# + - `RecordHarMode` <`enum HarMode { Full, Minimal }?`> When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page, cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `full`.# + - `RecordHarOmitContent` <[bool]?> Optional setting to control whether to omit request content from the HAR. Defaults to `false`.# + - `RecordHarPath` <[string]?> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into the specified HAR file on the filesystem. If not specified, the HAR is not recorded. Make sure to call [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) for the HAR to be saved.# + - `RecordHarUrlFilter|RecordHarUrlFilterRegex` <[string]?|[Regex]?># + - `RecordVideoDir` <[string]?> Enables video recording for all pages into the specified directory. If not specified videos are not recorded. Make sure to call [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) for videos to be saved.# + - `RecordVideoSize` <RecordVideoSize?> Dimensions of the recorded videos. If not specified the size will be equal to `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.# - `Width` <[int]> Video frame width. - `Height` <[int]> Video frame height. - - `ReducedMotion`# - - `ScreenSize`# + - `ReducedMotion` <`enum ReducedMotion { Reduce, NoPreference, Null }?`> Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'no-preference'`.# + - `ScreenSize` <ScreenSize?> Emulates consistent window screen size available inside web page via `window.screen`. Is only used when the `viewport` is set.# - `Width` <[int]> page width in pixels. - `Height` <[int]> page height in pixels. - - `ServiceWorkers`# + - `ServiceWorkers` <`enum ServiceWorkerPolicy { Allow, Block }?`> 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. * `'block'`: Playwright will block all registration of Service Workers. - - `StorageState`# - - `StorageStatePath`# - - `StrictSelectors`# - - `TimezoneId`# - - `UserAgent`# - - `ViewportSize`# + - `StorageState` <[string]?> Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync();](/api/class-browsercontext.mdx#browser-context-storage-state).# + - `StorageStatePath` <[string]?> Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [BrowserContext.StorageStateAsync();](/api/class-browsercontext.mdx#browser-context-storage-state). Path to the file with saved storage state. Added in: v1.9# + - `StrictSelectors` <[bool]?> If specified, enables strict selectors mode for this context. In the strict selectors mode all operations on selectors that imply single target DOM element will throw when more than one element matches the selector. See [Locator] to learn more about the strict mode.# + - `TimezoneId` <[string]?> 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.# + - `UserAgent` <[string]?> Specific user agent to use in this context.# + - `ViewportSize` <ViewportSize?> Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the default viewport.# - `Width` <[int]> page width in pixels. - `Height` <[int]> page height in pixels. -- returns:# -Creates a new page in a new browser context. Closing this page will close the context as well. +#### Returns +- <[Page]># -This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and testing frameworks should explicitly create [Browser.NewContextAsync(options)](/api/class-browser.mdx#browser-new-context) followed by the [BrowserContext.NewPageAsync()](/api/class-browsercontext.mdx#browser-context-new-page) to control their exact life times. +--- -## Browser.Version {#browser-version} +## Version {#browser-version} Added in: v1.8 -- returns:# - Returns the browser version. +#### Usage + +```csharp +Browser.Version +``` + +#### Returns +- <[string]># + [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" [APIRequestContext]: /api/class-apirequestcontext.mdx "APIRequestContext" diff --git a/dotnet/docs/api/class-browsercontext.mdx b/dotnet/docs/api/class-browsercontext.mdx index f654bfa49db65..7b2b326b06d67 100644 --- a/dotnet/docs/api/class-browsercontext.mdx +++ b/dotnet/docs/api/class-browsercontext.mdx @@ -12,7 +12,7 @@ BrowserContexts provide a way to operate multiple independent browser sessions. If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser context. -Playwright allows creating "incognito" browser contexts with [Browser.NewContextAsync(options)](/api/class-browser.mdx#browser-new-context) method. "Incognito" browser contexts don't write any browsing data to disk. +Playwright allows creating "incognito" browser contexts with [Browser.NewContextAsync();](/api/class-browser.mdx#browser-new-context) method. "Incognito" browser contexts don't write any browsing data to disk. ```csharp using var playwright = await Playwright.CreateAsync(); @@ -27,56 +27,33 @@ await context.CloseAsync(); ``` -- [event BrowserContext.Close](/api/class-browsercontext.mdx#browser-context-event-close) -- [event BrowserContext.Page](/api/class-browsercontext.mdx#browser-context-event-page) -- [event BrowserContext.Request](/api/class-browsercontext.mdx#browser-context-event-request) -- [event BrowserContext.RequestFailed](/api/class-browsercontext.mdx#browser-context-event-request-failed) -- [event BrowserContext.RequestFinished](/api/class-browsercontext.mdx#browser-context-event-request-finished) -- [event BrowserContext.Response](/api/class-browsercontext.mdx#browser-context-event-response) -- [BrowserContext.AddCookiesAsync(cookies)](/api/class-browsercontext.mdx#browser-context-add-cookies) -- [BrowserContext.AddInitScriptAsync(script)](/api/class-browsercontext.mdx#browser-context-add-init-script) -- [BrowserContext.APIRequest](/api/class-browsercontext.mdx#browser-context-request) -- [BrowserContext.Browser](/api/class-browsercontext.mdx#browser-context-browser) -- [BrowserContext.ClearCookiesAsync()](/api/class-browsercontext.mdx#browser-context-clear-cookies) -- [BrowserContext.ClearPermissionsAsync()](/api/class-browsercontext.mdx#browser-context-clear-permissions) -- [BrowserContext.CloseAsync()](/api/class-browsercontext.mdx#browser-context-close) -- [BrowserContext.CookiesAsync(urls)](/api/class-browsercontext.mdx#browser-context-cookies) -- [BrowserContext.ExposeBindingAsync(name, callback, options)](/api/class-browsercontext.mdx#browser-context-expose-binding) -- [BrowserContext.ExposeFunctionAsync(name, callback)](/api/class-browsercontext.mdx#browser-context-expose-function) -- [BrowserContext.GrantPermissionsAsync(permissions, options)](/api/class-browsercontext.mdx#browser-context-grant-permissions) -- [BrowserContext.NewPageAsync()](/api/class-browsercontext.mdx#browser-context-new-page) -- [BrowserContext.Pages](/api/class-browsercontext.mdx#browser-context-pages) -- [BrowserContext.RouteAsync(url, handler, options)](/api/class-browsercontext.mdx#browser-context-route) -- [BrowserContext.RouteFromHARAsync(har, options)](/api/class-browsercontext.mdx#browser-context-route-from-har) -- [BrowserContext.RunAndWaitForPageAsync(action, options)](/api/class-browsercontext.mdx#browser-context-wait-for-page) -- [BrowserContext.SetDefaultNavigationTimeout(timeout)](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout) -- [BrowserContext.SetDefaultTimeout(timeout)](/api/class-browsercontext.mdx#browser-context-set-default-timeout) -- [BrowserContext.SetExtraHTTPHeadersAsync(headers)](/api/class-browsercontext.mdx#browser-context-set-extra-http-headers) -- [BrowserContext.SetGeolocationAsync(geolocation)](/api/class-browsercontext.mdx#browser-context-set-geolocation) -- [BrowserContext.SetOfflineAsync(offline)](/api/class-browsercontext.mdx#browser-context-set-offline) -- [BrowserContext.StorageStateAsync(options)](/api/class-browsercontext.mdx#browser-context-storage-state) -- [BrowserContext.Tracing](/api/class-browsercontext.mdx#browser-context-tracing) -- [BrowserContext.UnrouteAsync(url, handler)](/api/class-browsercontext.mdx#browser-context-unroute) -- [BrowserContext.WaitForPageAsync(action, options)](/api/class-browsercontext.mdx#browser-context-wait-for-page) - -## event BrowserContext.Close {#browser-context-event-close} +--- -Added in: v1.8 +## event Close {#browser-context-event-close} -- type: <[BrowserContext]> +Added in: v1.8 Emitted when Browser context gets closed. This might happen because of one of the following: * Browser context is closed. * Browser application is closed or crashed. -* The [Browser.CloseAsync()](/api/class-browser.mdx#browser-close) method was called. +* The [Browser.CloseAsync();](/api/class-browser.mdx#browser-close) method was called. -## event BrowserContext.Page {#browser-context-event-page} +#### Usage -Added in: v1.8 +```csharp +BrowserContext.Close += async data => {}; +``` + +#### Event data +- <[BrowserContext]> -- type: <[Page]> +--- -The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will also fire for popup pages. See also [event Page.Popup](/api/class-page.mdx#page-event-popup) to receive events about popups relevant to a specific page. +## event Page {#browser-context-event-page} + +Added in: v1.8 + +The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will also fire for popup pages. See also [Page.Popup](/api/class-page.mdx#page-event-popup) to receive events about popups relevant to a specific page. The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is done and its response has started loading in the popup. @@ -89,52 +66,112 @@ Console.WriteLine(await popup.EvaluateAsync("location.href")); ``` :::note -Use [Page.WaitForLoadStateAsync(state, options)](/api/class-page.mdx#page-wait-for-load-state) to wait until the page gets to a particular state (you should not need it in most cases). +Use [Page.WaitForLoadStateAsync();](/api/class-page.mdx#page-wait-for-load-state) to wait until the page gets to a particular state (you should not need it in most cases). ::: -## event BrowserContext.Request {#browser-context-event-request} +#### Usage + +```csharp +BrowserContext.Page += async data => {}; +``` + +#### Event data +- <[Page]> + +--- + +## event Request {#browser-context-event-request} Added in: v1.12 -- type: <[Request]> +Emitted when a request is issued from any pages created through this context. The [request] object is read-only. To only listen for requests from a particular page, use [Page.Request](/api/class-page.mdx#page-event-request). -Emitted when a request is issued from any pages created through this context. The [request] object is read-only. To only listen for requests from a particular page, use [event Page.Request](/api/class-page.mdx#page-event-request). +In order to intercept and mutate requests, see [BrowserContext.RouteAsync();](/api/class-browsercontext.mdx#browser-context-route) or [Page.RouteAsync();](/api/class-page.mdx#page-route). -In order to intercept and mutate requests, see [BrowserContext.RouteAsync(url, handler, options)](/api/class-browsercontext.mdx#browser-context-route) or [Page.RouteAsync(url, handler, options)](/api/class-page.mdx#page-route). +#### Usage -## event BrowserContext.RequestFailed {#browser-context-event-request-failed} +```csharp +BrowserContext.Request += async data => {}; +``` -Added in: v1.12 +#### Event data +- <[Request]> -- type: <[Request]> +--- -Emitted when a request fails, for example by timing out. To only listen for failed requests from a particular page, use [event Page.RequestFailed](/api/class-page.mdx#page-event-request-failed). +## event RequestFailed {#browser-context-event-request-failed} + +Added in: v1.12 + +Emitted when a request fails, for example by timing out. To only listen for failed requests from a particular page, use [Page.RequestFailed](/api/class-page.mdx#page-event-request-failed). :::note -HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [event BrowserContext.RequestFinished](/api/class-browsercontext.mdx#browser-context-event-request-finished) event and not with [event BrowserContext.RequestFailed](/api/class-browsercontext.mdx#browser-context-event-request-failed). +HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [BrowserContext.RequestFinished](/api/class-browsercontext.mdx#browser-context-event-request-finished) event and not with [BrowserContext.RequestFailed](/api/class-browsercontext.mdx#browser-context-event-request-failed). ::: -## event BrowserContext.RequestFinished {#browser-context-event-request-finished} +#### Usage + +```csharp +BrowserContext.RequestFailed += async data => {}; +``` + +#### Event data +- <[Request]> + +--- + +## event RequestFinished {#browser-context-event-request-finished} Added in: v1.12 -- type: <[Request]> +Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. To listen for successful requests from a particular page, use [Page.RequestFinished](/api/class-page.mdx#page-event-request-finished). + +#### Usage + +```csharp +BrowserContext.RequestFinished += async data => {}; +``` -Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. To listen for successful requests from a particular page, use [event Page.RequestFinished](/api/class-page.mdx#page-event-request-finished). +#### Event data +- <[Request]> -## event BrowserContext.Response {#browser-context-event-response} +--- + +## event Response {#browser-context-event-response} Added in: v1.12 -- type: <[Response]> +Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. To listen for response events from a particular page, use [Page.Response](/api/class-page.mdx#page-event-response). -Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. To listen for response events from a particular page, use [event Page.Response](/api/class-page.mdx#page-event-response). +#### Usage -## BrowserContext.AddCookiesAsync(cookies) {#browser-context-add-cookies} +```csharp +BrowserContext.Response += async data => {}; +``` + +#### Event data +- <[Response]> + +--- + +## AddCookiesAsync {#browser-context-add-cookies} Added in: v1.8 -- `cookies`# +Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [BrowserContext.CookiesAsync();](/api/class-browsercontext.mdx#browser-context-cookies). + +```csharp +await context.AddCookiesAsync(new[] { cookie1, cookie2 }); +``` + +#### Usage + +```csharp +await BrowserContext.AddCookiesAsync(cookies); +``` + +#### Parameters +- `cookies` <[IEnumerable]<`Cookie`>># - `Name` <[string]> - `Value` <[string]> - `Url` <[string]?> either url or domain / path are required. Optional. @@ -144,21 +181,16 @@ Emitted when [response] status and headers are received for a request. For a suc - `HttpOnly` <[bool]?> Optional. - `Secure` <[bool]?> Optional. - `SameSite` <`enum SameSiteAttribute { Strict, Lax, None }?`> Optional. -- returns:# -Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [BrowserContext.CookiesAsync(urls)](/api/class-browsercontext.mdx#browser-context-cookies). +#### Returns +- <[void]># -```csharp -await context.AddCookiesAsync(new[] { cookie1, cookie2 }); -``` +--- -## BrowserContext.AddInitScriptAsync(script) {#browser-context-add-init-script} +## AddInitScriptAsync {#browser-context-add-init-script} Added in: v1.8 -- `script`# -- returns:# - Adds a script which would be evaluated in one of the following scenarios: * Whenever a page is created in the browser context or is navigated. * Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame. @@ -177,30 +209,60 @@ await context.AddInitScriptAsync(new BrowserContextAddInitScriptOptions { Script ``` :::note -The order of evaluation of multiple scripts installed via [BrowserContext.AddInitScriptAsync(script)](/api/class-browsercontext.mdx#browser-context-add-init-script) and [Page.AddInitScriptAsync(script)](/api/class-page.mdx#page-add-init-script) is not defined. +The order of evaluation of multiple scripts installed via [BrowserContext.AddInitScriptAsync();](/api/class-browsercontext.mdx#browser-context-add-init-script) and [Page.AddInitScriptAsync();](/api/class-page.mdx#page-add-init-script) is not defined. ::: -## BrowserContext.Browser {#browser-context-browser} +#### Usage -Added in: v1.8 +```csharp +await BrowserContext.AddInitScriptAsync(script); +``` -- returns:# +#### Parameters +- `script` <[string]|[string]> Script to be evaluated in all pages in the browser context.# -Returns the browser instance of the context. If it was launched as a persistent context null gets returned. +#### Returns +- <[void]># + +--- -## BrowserContext.ClearCookiesAsync() {#browser-context-clear-cookies} +## Browser {#browser-context-browser} Added in: v1.8 -- returns:# +Returns the browser instance of the context. If it was launched as a persistent context null gets returned. -Clears context cookies. +#### Usage -## BrowserContext.ClearPermissionsAsync() {#browser-context-clear-permissions} +```csharp +BrowserContext.Browser +``` + +#### Returns +- <[Browser]?># + +--- + +## ClearCookiesAsync {#browser-context-clear-cookies} Added in: v1.8 -- returns:# +Clears context cookies. + +#### Usage + +```csharp +await BrowserContext.ClearCookiesAsync(); +``` + +#### Returns +- <[void]># + +--- + +## ClearPermissionsAsync {#browser-context-clear-permissions} + +Added in: v1.8 Clears all permission overrides for the browser context. @@ -213,11 +275,20 @@ await context.GrantPermissionsAsync(new[] { "clipboard-read" }); await context.ClearPermissionsAsync(); ``` -## BrowserContext.CloseAsync() {#browser-context-close} +#### Usage -Added in: v1.8 +```csharp +await BrowserContext.ClearPermissionsAsync(); +``` + +#### Returns +- <[void]># -- returns:# +--- + +## CloseAsync {#browser-context-close} + +Added in: v1.8 Closes the browser context. All the pages that belong to the browser context will be closed. @@ -225,12 +296,34 @@ Closes the browser context. All the pages that belong to the browser context wil The default browser context cannot be closed. ::: -## BrowserContext.CookiesAsync(urls) {#browser-context-cookies} +#### Usage + +```csharp +await BrowserContext.CloseAsync(); +``` + +#### Returns +- <[void]># + +--- + +## CookiesAsync {#browser-context-cookies} Added in: v1.8 -- `urls`# -- returns:# +If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs are returned. + +#### Usage + +```csharp +await BrowserContext.CookiesAsync(urls); +``` + +#### Parameters +- `urls` <[string]?|[IEnumerable]?<[string]>> Optional list of URLs.# + +#### Returns +- <[IEnumerable]<`Cookie`>># - `name` <[string]> - `value` <[string]> - `domain` <[string]> @@ -240,23 +333,17 @@ The default browser context cannot be closed. - `secure` <[bool]> - `sameSite` <`enum SameSiteAttribute { Strict, Lax, None }`> -If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs are returned. +--- -## BrowserContext.ExposeBindingAsync(name, callback, options) {#browser-context-expose-binding} +## ExposeBindingAsync {#browser-context-expose-binding} Added in: v1.8 -- `name`# -- `callback`# -- `options` <`BrowserContextExposeBindingOptions?`> - - `Handle`# -- returns:# - The method adds a function called `name` on the `window` object of every frame in every page in the context. When called, the function executes `callback` and returns a [Promise] which resolves to the return value of `callback`. If the `callback` returns a [Promise], it will be awaited. The first argument of the `callback` function contains information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`. -See [Page.ExposeBindingAsync(name, callback, options)](/api/class-page.mdx#page-expose-binding) for page-only version. +See [Page.ExposeBindingAsync();](/api/class-page.mdx#page-expose-binding) for page-only version. An example of exposing page URL to all frames in all pages in the context: @@ -301,19 +388,32 @@ await page.ClickAsync("div"); Assert.AreEqual("Click me", await result.Task); ``` -## BrowserContext.ExposeFunctionAsync(name, callback) {#browser-context-expose-function} +#### Usage -Added in: v1.8 +```csharp +await BrowserContext.ExposeBindingAsync(name, callback, options); +``` + +#### Parameters +- `name` <[string]> Name of the function on the window object.# +- `callback` <[Action]> Callback function that will be called in the Playwright's context.# +- `options` <`BrowserContextExposeBindingOptions?`> + - `Handle` <[bool]?> Whether to pass the argument as a handle, instead of passing by value. When passing a handle, only one argument is supported. When passing by value, multiple arguments are supported.# + +#### Returns +- <[void]># -- `name`# -- `callback`# -- returns:# +--- + +## ExposeFunctionAsync {#browser-context-expose-function} + +Added in: v1.8 The method adds a function called `name` on the `window` object of every frame in every page in the context. When called, the function executes `callback` and returns a [Promise] which resolves to the return value of `callback`. If the `callback` returns a [Promise], it will be awaited. -See [Page.ExposeFunctionAsync(name, callback)](/api/class-page.mdx#page-expose-function) for page-only version. +See [Page.ExposeFunctionAsync();](/api/class-page.mdx#page-expose-function) for page-only version. An example of adding a `sha256` function to all pages in the context: @@ -352,11 +452,35 @@ class BrowserContextExamples } ``` -## BrowserContext.GrantPermissionsAsync(permissions, options) {#browser-context-grant-permissions} +#### Usage + +```csharp +await BrowserContext.ExposeFunctionAsync(name, callback); +``` + +#### Parameters +- `name` <[string]> Name of the function on the window object.# +- `callback` <[Action]> Callback function that will be called in the Playwright's context.# + +#### Returns +- <[void]># + +--- + +## GrantPermissionsAsync {#browser-context-grant-permissions} Added in: v1.8 -- `permissions`# +Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified. + +#### Usage + +```csharp +await BrowserContext.GrantPermissionsAsync(permissions, options); +``` + +#### Parameters +- `permissions` <[IEnumerable]<[string]>> A permission or an array of permissions to grant. Permissions can be one of the following values:# * `'geolocation'` * `'midi'` * `'midi-sysex'` (system-exclusive midi) @@ -373,41 +497,55 @@ class BrowserContextExamples * `'clipboard-write'` * `'payment-handler'` - `options` <`BrowserContextGrantPermissionsOptions?`> - - `Origin`# -- returns:# + - `Origin` <[string]?> The [origin] to grant permissions to, e.g. "https://example.com".# -Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified. +#### Returns +- <[void]># -## BrowserContext.NewPageAsync() {#browser-context-new-page} +--- -Added in: v1.8 +## NewPageAsync {#browser-context-new-page} -- returns:# +Added in: v1.8 Creates a new page in the browser context. -## BrowserContext.Pages {#browser-context-pages} +#### Usage -Added in: v1.8 +```csharp +await BrowserContext.NewPageAsync(); +``` -- returns:# +#### Returns +- <[Page]># -Returns all open pages in the context. +--- -## BrowserContext.RouteAsync(url, handler, options) {#browser-context-route} +## Pages {#browser-context-pages} Added in: v1.8 -- `url`# -- `handler`# -- `options` <`BrowserContextRouteOptions?`> - - `Times`# -- returns:# +Returns all open pages in the context. + +#### Usage + +```csharp +BrowserContext.Pages +``` + +#### Returns +- <[IEnumerable]<[Page]>># + +--- + +## RouteAsync {#browser-context-route} + +Added in: v1.8 Routing provides the capability to modify network requests that are made by any page in the browser context. Once route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted. :::note -[BrowserContext.RouteAsync(url, handler, options)](/api/class-browsercontext.mdx#browser-context-route) will not intercept requests intercepted by Service Worker. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`. +[BrowserContext.RouteAsync();](/api/class-browsercontext.mdx#browser-context-route) will not intercept requests intercepted by Service Worker. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`. ::: An example of a naive handler that aborts all image requests: @@ -442,107 +580,184 @@ await page.RouteAsync("/api/**", async r => }); ``` -Page routes (set up with [Page.RouteAsync(url, handler, options)](/api/class-page.mdx#page-route)) take precedence over browser context routes when request matches both handlers. +Page routes (set up with [Page.RouteAsync();](/api/class-page.mdx#page-route)) take precedence over browser context routes when request matches both handlers. -To remove a route with its handler you can use [BrowserContext.UnrouteAsync(url, handler)](/api/class-browsercontext.mdx#browser-context-unroute). +To remove a route with its handler you can use [BrowserContext.UnrouteAsync();](/api/class-browsercontext.mdx#browser-context-unroute). :::note Enabling routing disables http cache. ::: -## BrowserContext.RouteFromHARAsync(har, options) {#browser-context-route-from-har} +#### Usage + +```csharp +await BrowserContext.RouteAsync(url, handler, options); +``` + +#### Parameters +- `url` <[string]|[Regex]|[Func]<[string], bool>> A glob pattern, regex pattern or predicate receiving [URL] to match while routing. When a `baseURL` via the context options was provided and the passed URL is a path, it gets merged via the [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor.# +- `handler` <[Action]<[Route]>> handler function to route the request.# +- `options` <`BrowserContextRouteOptions?`> + - `Times` <[int]?> How often a route should be used. By default it will be used every time. Added in: v1.15# + +#### Returns +- <[void]># + +--- + +## RouteFromHARAsync {#browser-context-route-from-har} Added in: v1.23 -- `har`# +If specified the network requests that are made in the context will be served from the HAR file. Read more about [Replaying from HAR](../network.mdx#replaying-from-har). + +Playwright will not serve requests intercepted by Service Worker from the HAR file. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`. + +#### Usage + +```csharp +await BrowserContext.RouteFromHARAsync(har, options); +``` + +#### Parameters +- `har` <[string]> Path to a [HAR](http://www.softwareishard.com/blog/har-12-spec) file with prerecorded network data. If `path` is a relative path, then it is resolved relative to the current working directory.# - `options` <`BrowserContextRouteFromHAROptions?`> - - `NotFound`# + - `NotFound` <`enum HarNotFound { Abort, Fallback }?`> If set to 'abort' any request not found in the HAR file will be aborted.# * If set to 'fallback' falls through to the next route handler in the handler chain. Defaults to abort. - - `Update`# - - `Url|UrlRegex`# -- returns:# + - `Update` <[bool]?> If specified, updates the given HAR with the actual network information instead of serving from file. The file is written to disk when [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) is called.# + - `Url|UrlRegex` <[string]?|[Regex]?> A glob pattern, regular expression or predicate to match the request URL. Only requests with URL matching the pattern will be served from the HAR file. If not specified, all requests are served from the HAR file.# -If specified the network requests that are made in the context will be served from the HAR file. Read more about [Replaying from HAR](../network.mdx#replaying-from-har). +#### Returns +- <[void]># -Playwright will not serve requests intercepted by Service Worker from the HAR file. See [this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using request interception by setting `Browser.newContext.serviceWorkers` to `'block'`. +--- -## BrowserContext.RunAndWaitForPageAsync(action, options) {#browser-context-wait-for-page} +## RunAndWaitForPageAsync {#browser-context-wait-for-page} Added in: v1.9 +Performs action and waits for a new [Page] to be created in the context. If predicate is provided, it passes [Page] value into the `predicate` function and waits for `predicate(event)` to return a truthy value. Will throw an error if the context closes before new [Page] is created. + +#### Usage + +```csharp +await BrowserContext.RunAndWaitForPageAsync(action, options); +``` + +#### Parameters - `options` <`BrowserContextRunAndWaitForPageOptions?`> - - `Predicate`# - - `Timeout`# -- `action`# -- returns:# + - `Predicate` <[Func]<[Page]?, bool>> Receives the [Page] object and resolves to truthy value when the waiting should resolve.# + - `Timeout` <[double]?> Maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout();](/api/class-browsercontext.mdx#browser-context-set-default-timeout).# +- `action` <[Func]<[Task]>> Action that triggers the event. Added in: v1.12# -Performs action and waits for a new [Page] to be created in the context. If predicate is provided, it passes [Page] value into the `predicate` function and waits for `predicate(event)` to return a truthy value. Will throw an error if the context closes before new [Page] is created. +#### Returns +- <[Page]># + +--- -## BrowserContext.WaitForPageAsync(action, options) {#browser-context-wait-for-page} +## WaitForPageAsync {#browser-context-wait-for-page} Added in: v1.9 -- `action`# -- returns:# - Performs action and waits for a new [Page] to be created in the context. If predicate is provided, it passes [Page] value into the `predicate` function and waits for `predicate(event)` to return a truthy value. Will throw an error if the context closes before new [Page] is created. -## BrowserContext.SetDefaultNavigationTimeout(timeout) {#browser-context-set-default-navigation-timeout} +#### Usage -Added in: v1.8 +```csharp +await BrowserContext.WaitForPageAsync(action, options); +``` + +#### Parameters +- `action` <[Func]<[Task]>> Action that triggers the event. Added in: v1.12# + +#### Returns +- <[Page]># + +--- + +## SetDefaultNavigationTimeout {#browser-context-set-default-navigation-timeout} -- `timeout`# -- returns:# +Added in: v1.8 This setting will change the default maximum navigation time for the following methods and related shortcuts: -* [Page.GoBackAsync(options)](/api/class-page.mdx#page-go-back) -* [Page.GoForwardAsync(options)](/api/class-page.mdx#page-go-forward) -* [Page.GotoAsync(url, options)](/api/class-page.mdx#page-goto) -* [Page.ReloadAsync(options)](/api/class-page.mdx#page-reload) -* [Page.SetContentAsync(html, options)](/api/class-page.mdx#page-set-content) -* [Page.RunAndWaitForNavigationAsync(action, options)](/api/class-page.mdx#page-wait-for-navigation) +* [Page.GoBackAsync();](/api/class-page.mdx#page-go-back) +* [Page.GoForwardAsync();](/api/class-page.mdx#page-go-forward) +* [Page.GotoAsync();](/api/class-page.mdx#page-goto) +* [Page.ReloadAsync();](/api/class-page.mdx#page-reload) +* [Page.SetContentAsync();](/api/class-page.mdx#page-set-content) +* [Page.RunAndWaitForNavigationAsync();](/api/class-page.mdx#page-wait-for-navigation) :::note -[Page.SetDefaultNavigationTimeout(timeout)](/api/class-page.mdx#page-set-default-navigation-timeout) and [Page.SetDefaultTimeout(timeout)](/api/class-page.mdx#page-set-default-timeout) take priority over [BrowserContext.SetDefaultNavigationTimeout(timeout)](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout). +[Page.SetDefaultNavigationTimeout();](/api/class-page.mdx#page-set-default-navigation-timeout) and [Page.SetDefaultTimeout();](/api/class-page.mdx#page-set-default-timeout) take priority over [BrowserContext.SetDefaultNavigationTimeout();](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout). ::: -## BrowserContext.SetDefaultTimeout(timeout) {#browser-context-set-default-timeout} +#### Usage -Added in: v1.8 +```csharp +BrowserContext.SetDefaultNavigationTimeout(timeout); +``` + +#### Parameters +- `timeout` <[double]> Maximum navigation time in milliseconds# + +#### Returns +- <[void]># -- `timeout`# -- returns:# +--- + +## SetDefaultTimeout {#browser-context-set-default-timeout} + +Added in: v1.8 This setting will change the default maximum time for all the methods accepting `timeout` option. :::note -[Page.SetDefaultNavigationTimeout(timeout)](/api/class-page.mdx#page-set-default-navigation-timeout), [Page.SetDefaultTimeout(timeout)](/api/class-page.mdx#page-set-default-timeout) and [BrowserContext.SetDefaultNavigationTimeout(timeout)](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout) take priority over [BrowserContext.SetDefaultTimeout(timeout)](/api/class-browsercontext.mdx#browser-context-set-default-timeout). +[Page.SetDefaultNavigationTimeout();](/api/class-page.mdx#page-set-default-navigation-timeout), [Page.SetDefaultTimeout();](/api/class-page.mdx#page-set-default-timeout) and [BrowserContext.SetDefaultNavigationTimeout();](/api/class-browsercontext.mdx#browser-context-set-default-navigation-timeout) take priority over [BrowserContext.SetDefaultTimeout();](/api/class-browsercontext.mdx#browser-context-set-default-timeout). ::: -## BrowserContext.SetExtraHTTPHeadersAsync(headers) {#browser-context-set-extra-http-headers} +#### Usage -Added in: v1.8 +```csharp +BrowserContext.SetDefaultTimeout(timeout); +``` + +#### Parameters +- `timeout` <[double]> Maximum time in milliseconds# + +#### Returns +- <[void]># -- `headers`# -- returns:# +--- + +## SetExtraHTTPHeadersAsync {#browser-context-set-extra-http-headers} + +Added in: v1.8 -The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged with page-specific extra HTTP headers set with [Page.SetExtraHTTPHeadersAsync(headers)](/api/class-page.mdx#page-set-extra-http-headers). If page overrides a particular header, page-specific header value will be used instead of the browser context header value. +The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged with page-specific extra HTTP headers set with [Page.SetExtraHTTPHeadersAsync();](/api/class-page.mdx#page-set-extra-http-headers). If page overrides a particular header, page-specific header value will be used instead of the browser context header value. :::note -[BrowserContext.SetExtraHTTPHeadersAsync(headers)](/api/class-browsercontext.mdx#browser-context-set-extra-http-headers) does not guarantee the order of headers in the outgoing requests. +[BrowserContext.SetExtraHTTPHeadersAsync();](/api/class-browsercontext.mdx#browser-context-set-extra-http-headers) does not guarantee the order of headers in the outgoing requests. ::: -## BrowserContext.SetGeolocationAsync(geolocation) {#browser-context-set-geolocation} +#### Usage -Added in: v1.8 +```csharp +await BrowserContext.SetExtraHTTPHeadersAsync(headers); +``` -- `geolocation`# - - `Latitude` <[double]> Latitude between -90 and 90. - - `Longitude` <[double]> Longitude between -180 and 180. - - `Accuracy` <[double]?> Non-negative accuracy value. Defaults to `0`. -- returns:# +#### Parameters +- `headers` <[IDictionary]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings.# + +#### Returns +- <[void]># + +--- + +## SetGeolocationAsync {#browser-context-set-geolocation} + +Added in: v1.8 Sets the context's geolocation. Passing `null` or `undefined` emulates position unavailable. @@ -555,49 +770,115 @@ await context.SetGeolocationAsync(new Geolocation() ``` :::note -Consider using [BrowserContext.GrantPermissionsAsync(permissions, options)](/api/class-browsercontext.mdx#browser-context-grant-permissions) to grant permissions for the browser context pages to read its geolocation. +Consider using [BrowserContext.GrantPermissionsAsync();](/api/class-browsercontext.mdx#browser-context-grant-permissions) to grant permissions for the browser context pages to read its geolocation. ::: -## BrowserContext.SetOfflineAsync(offline) {#browser-context-set-offline} +#### Usage + +```csharp +await BrowserContext.SetGeolocationAsync(geolocation); +``` + +#### Parameters +- `geolocation` <Geolocation?># + - `Latitude` <[double]> Latitude between -90 and 90. + - `Longitude` <[double]> Longitude between -180 and 180. + - `Accuracy` <[double]?> Non-negative accuracy value. Defaults to `0`. + +#### Returns +- <[void]># + +--- + +## SetOfflineAsync {#browser-context-set-offline} Added in: v1.8 -- `offline`# -- returns:# +#### Usage -## BrowserContext.StorageStateAsync(options) {#browser-context-storage-state} +```csharp +await BrowserContext.SetOfflineAsync(offline); +``` + +#### Parameters +- `offline` <[bool]> Whether to emulate network being offline for the browser context.# + +#### Returns +- <[void]># + +--- + +## StorageStateAsync {#browser-context-storage-state} Added in: v1.8 +Returns storage state for this browser context, contains current cookies and local storage snapshot. + +#### Usage + +```csharp +await BrowserContext.StorageStateAsync(options); +``` + +#### Parameters - `options` <`BrowserContextStorageStateOptions?`> - - `Path`# -- returns:# + - `Path` <[string]?> The file path to save the storage state to. If `path` is a relative path, then it is resolved relative to current working directory. If no path is provided, storage state is still returned, but won't be saved to the disk.# -Returns storage state for this browser context, contains current cookies and local storage snapshot. +#### Returns +- <[string]># + +--- -## BrowserContext.UnrouteAsync(url, handler) {#browser-context-unroute} +## UnrouteAsync {#browser-context-unroute} Added in: v1.8 -- `url`# -- `handler`# -- returns:# +Removes a route created with [BrowserContext.RouteAsync();](/api/class-browsercontext.mdx#browser-context-route). When `handler` is not specified, removes all routes for the `url`. -Removes a route created with [BrowserContext.RouteAsync(url, handler, options)](/api/class-browsercontext.mdx#browser-context-route). When `handler` is not specified, removes all routes for the `url`. +#### Usage -## BrowserContext.APIRequest {#browser-context-request} +```csharp +await BrowserContext.UnrouteAsync(url, handler); +``` -Added in: v1.16 +#### Parameters +- `url` <[string]|[Regex]|[Func]<[string], bool>> A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [BrowserContext.RouteAsync();](/api/class-browsercontext.mdx#browser-context-route).# +- `handler` <[Action]<[Route]?>> Optional handler function used to register a routing with [BrowserContext.RouteAsync();](/api/class-browsercontext.mdx#browser-context-route).# -- type: <[APIRequestContext]> +#### Returns +- <[void]># + +--- + +## APIRequest {#browser-context-request} + +Added in: v1.16 API testing helper associated with this context. Requests made with this API will use context cookies. -## BrowserContext.Tracing {#browser-context-tracing} +#### Usage + +```csharp +BrowserContext.APIRequest +``` + +#### Type +- <[APIRequestContext]> + +--- + +## Tracing {#browser-context-tracing} Added in: v1.12 -- type: <[Tracing]> +#### Usage + +```csharp +BrowserContext.Tracing +``` + +#### Type +- <[Tracing]> [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" diff --git a/dotnet/docs/api/class-browsertype.mdx b/dotnet/docs/api/class-browsertype.mdx index 9fb5ba99b8d06..7f69fe4f1a54b 100644 --- a/dotnet/docs/api/class-browsertype.mdx +++ b/dotnet/docs/api/class-browsertype.mdx @@ -28,36 +28,35 @@ class BrowserTypeExamples ``` -- [BrowserType.ConnectAsync(wsEndpoint, options)](/api/class-browsertype.mdx#browser-type-connect) -- [BrowserType.ConnectOverCDPAsync(endpointURL, options)](/api/class-browsertype.mdx#browser-type-connect-over-cdp) -- [BrowserType.ExecutablePath](/api/class-browsertype.mdx#browser-type-executable-path) -- [BrowserType.LaunchAsync(options)](/api/class-browsertype.mdx#browser-type-launch) -- [BrowserType.LaunchPersistentContextAsync(userDataDir, options)](/api/class-browsertype.mdx#browser-type-launch-persistent-context) -- [BrowserType.Name](/api/class-browsertype.mdx#browser-type-name) +--- -## BrowserType.ConnectAsync(wsEndpoint, options) {#browser-type-connect} +## ConnectAsync {#browser-type-connect} Added in: v1.8 -- `wsEndpoint`# +This method attaches Playwright to an existing browser instance. When connecting to another browser launched via `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is compatible with 1.2.x). + +#### Usage + +```csharp +await BrowserType.ConnectAsync(wsEndpoint, options); +``` + +#### Parameters +- `wsEndpoint` <[string]> A browser websocket endpoint to connect to. Added in: v1.10# - `options` <`BrowserTypeConnectOptions?`> - - `Headers`# - - `SlowMo`# - - `Timeout`# -- returns:# + - `Headers` <[IDictionary]?<[string], [string]>> Additional HTTP headers to be sent with web socket connect request. Optional. Added in: v1.11# + - `SlowMo` <[double]?> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0. Added in: v1.10# + - `Timeout` <[double]?> Maximum time in milliseconds to wait for the connection to be established. Defaults to `0` (no timeout). Added in: v1.10# -This method attaches Playwright to an existing browser instance. When connecting to another browser launched via `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is compatible with 1.2.x). +#### Returns +- <[Browser]># -## BrowserType.ConnectOverCDPAsync(endpointURL, options) {#browser-type-connect-over-cdp} +--- -Added in: v1.9 +## ConnectOverCDPAsync {#browser-type-connect-over-cdp} -- `endpointURL`# -- `options` <`BrowserTypeConnectOverCDPOptions?`> - - `Headers`# - - `SlowMo`# - - `Timeout`# -- returns:# +Added in: v1.9 This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol. @@ -73,42 +72,44 @@ var defaultContext = browser.Contexts[0]; var page = defaultContext.Pages[0]; ``` -## BrowserType.ExecutablePath {#browser-type-executable-path} +#### Usage -Added in: v1.8 +```csharp +await BrowserType.ConnectOverCDPAsync(endpointURL, options); +``` -- returns:# +#### Parameters +- `endpointURL` <[string]> A CDP websocket endpoint or http url to connect to. For example `http://localhost:9222/` or `ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4`. Added in: v1.11# +- `options` <`BrowserTypeConnectOverCDPOptions?`> + - `Headers` <[IDictionary]?<[string], [string]>> Additional HTTP headers to be sent with connect request. Optional. Added in: v1.11# + - `SlowMo` <[double]?> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0. Added in: v1.11# + - `Timeout` <[double]?> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. Added in: v1.11# -A path where Playwright expects to find a bundled browser executable. +#### Returns +- <[Browser]># -## BrowserType.LaunchAsync(options) {#browser-type-launch} +--- + +## ExecutablePath {#browser-type-executable-path} Added in: v1.8 -- `options` <`BrowserTypeLaunchOptions?`> - - `Args`# - - `Channel`# - - `ChromiumSandbox`# - - `Devtools`# - - `DownloadsPath`# - - `Env`# - - `ExecutablePath`# - - `FirefoxUserPrefs`# - - `HandleSIGHUP`# - - `HandleSIGINT`# - - `HandleSIGTERM`# - - `Headless`# - - `IgnoreAllDefaultArgs`# - - `IgnoreDefaultArgs`# - - `Proxy`# - - `Server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - - `Bypass` <[string]?> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - - `Username` <[string]?> Optional username to use if HTTP proxy requires authentication. - - `Password` <[string]?> Optional password to use if HTTP proxy requires authentication. - - `SlowMo`# - - `Timeout`# - - `TracesDir`# -- returns:# +A path where Playwright expects to find a bundled browser executable. + +#### Usage + +```csharp +BrowserType.ExecutablePath +``` + +#### Returns +- <[string]># + +--- + +## LaunchAsync {#browser-type-launch} + +Added in: v1.8 Returns the browser instance. @@ -126,93 +127,147 @@ var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions > > Stock browsers like Google Chrome and Microsoft Edge are suitable for tests that require proprietary media codecs for video playback. See [this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for other differences between Chromium and Chrome. [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. -## BrowserType.LaunchPersistentContextAsync(userDataDir, options) {#browser-type-launch-persistent-context} +#### Usage + +```csharp +await BrowserType.LaunchAsync(options); +``` + +#### Parameters +- `options` <`BrowserTypeLaunchOptions?`> + - `Args` <[IEnumerable]?<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).# + - `Channel` <[string]?> 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](../browsers.mdx#google-chrome--microsoft-edge).# + - `ChromiumSandbox` <[bool]?> Enable Chromium sandboxing. Defaults to `false`.# + - `Devtools` <[bool]?> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.# + - `DownloadsPath` <[string]?> If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed. In either case, the downloads are deleted when the browser context they were created in is closed.# + - `Env` <[IDictionary]?<[string], [string]>> Specify environment variables that will be visible to the browser. Defaults to `process.env`.# + - `ExecutablePath` <[string]?> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to the current working directory. Note that Playwright only works with the bundled Chromium, Firefox or WebKit, use at your own risk.# + - `FirefoxUserPrefs` <[IDictionary]?<[string], [object]>> Firefox user preferences. Learn more about the Firefox user preferences at [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).# + - `HandleSIGHUP` <[bool]?> Close the browser process on SIGHUP. Defaults to `true`.# + - `HandleSIGINT` <[bool]?> Close the browser process on Ctrl-C. Defaults to `true`.# + - `HandleSIGTERM` <[bool]?> Close the browser process on SIGTERM. Defaults to `true`.# + - `Headless` <[bool]?> 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 `devtools` option is `true`.# + - `IgnoreAllDefaultArgs` <[bool]?> If `true`, Playwright does not pass its own configurations args and only uses the ones from `args`. Dangerous option; use with care. Defaults to `false`. Added in: v1.9# + - `IgnoreDefaultArgs` <[IEnumerable]?<[string]>> If `true`, Playwright does not pass its own configurations args and only uses the ones from `args`. Dangerous option; use with care.# + - `Proxy` <Proxy?> Network proxy settings.# + - `Server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. + - `Bypass` <[string]?> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. + - `Username` <[string]?> Optional username to use if HTTP proxy requires authentication. + - `Password` <[string]?> Optional password to use if HTTP proxy requires authentication. + - `SlowMo` <[double]?> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on.# + - `Timeout` <[double]?> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# + - `TracesDir` <[string]?> If specified, traces are saved into this directory.# + +#### Returns +- <[Browser]># + +--- + +## LaunchPersistentContextAsync {#browser-type-launch-persistent-context} Added in: v1.8 -- `userDataDir`# +Returns the persistent browser context instance. + +Launches browser that uses persistent storage located at `userDataDir` and returns the only context. Closing this context will automatically close the browser. + +#### Usage + +```csharp +await BrowserType.LaunchPersistentContextAsync(userDataDir, options); +``` + +#### Parameters +- `userDataDir` <[string]> Path to a User Data Directory, which stores browser session data like cookies and local storage. More details for [Chromium](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md#introduction) and [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile). Note that Chromium's user data directory is the **parent** directory of the "Profile Path" seen at `chrome://version`. Pass an empty string to use a temporary directory instead.# - `options` <`BrowserTypeLaunchPersistentContextOptions?`> - - `AcceptDownloads`# - - `Args`# - - `BaseURL`# + - `AcceptDownloads` <[bool]?> Whether to automatically download all the attachments. Defaults to `true` where all the downloads are accepted.# + - `Args` <[IEnumerable]?<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).# + - `BaseURL` <[string]?> When using [Page.GotoAsync();](/api/class-page.mdx#page-goto), [Page.RouteAsync();](/api/class-page.mdx#page-route), [Page.WaitForURLAsync();](/api/class-page.mdx#page-wait-for-url), [Page.RunAndWaitForRequestAsync();](/api/class-page.mdx#page-wait-for-request), or [Page.RunAndWaitForResponseAsync();](/api/class-page.mdx#page-wait-for-response) it takes the base URL in consideration by using the [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL. Examples:# * baseURL: `http://localhost:3000` and navigating to `/bar.html` results in `http://localhost:3000/bar.html` * baseURL: `http://localhost:3000/foo/` and navigating to `./bar.html` results in `http://localhost:3000/foo/bar.html` * baseURL: `http://localhost:3000/foo` (without trailing slash) and navigating to `./bar.html` results in `http://localhost:3000/bar.html` - - `BypassCSP`# - - `Channel`# - - `ChromiumSandbox`# - - `ColorScheme`# - - `DeviceScaleFactor`# - - `Devtools`# - - `DownloadsPath`# - - `Env`# - - `ExecutablePath`# - - `ExtraHTTPHeaders`# - - `ForcedColors`# - - `Geolocation`# + - `BypassCSP` <[bool]?> Toggles bypassing page's Content-Security-Policy.# + - `Channel` <[string]?> 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](../browsers.mdx#google-chrome--microsoft-edge).# + - `ChromiumSandbox` <[bool]?> Enable Chromium sandboxing. Defaults to `false`.# + - `ColorScheme` <`enum ColorScheme { Light, Dark, NoPreference, Null }?`> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'light'`.# + - `DeviceScaleFactor` <[double]?> Specify device scale factor (can be thought of as dpr). Defaults to `1`.# + - `Devtools` <[bool]?> **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is `true`, the `headless` option will be set `false`.# + - `DownloadsPath` <[string]?> If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed. In either case, the downloads are deleted when the browser context they were created in is closed.# + - `Env` <[IDictionary]?<[string], [string]>> Specify environment variables that will be visible to the browser. Defaults to `process.env`.# + - `ExecutablePath` <[string]?> Path to a browser executable to run instead of the bundled one. If `executablePath` is a relative path, then it is resolved relative to the current working directory. Note that Playwright only works with the bundled Chromium, Firefox or WebKit, use at your own risk.# + - `ExtraHTTPHeaders` <[IDictionary]?<[string], [string]>> An object containing additional HTTP headers to be sent with every request.# + - `ForcedColors` <`enum ForcedColors { Active, None, Null }?`> Emulates `'forced-colors'` media feature, supported values are `'active'`, `'none'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'none'`.# + - `Geolocation` <Geolocation?># - `Latitude` <[double]> Latitude between -90 and 90. - `Longitude` <[double]> Longitude between -180 and 180. - `Accuracy` <[double]?> Non-negative accuracy value. Defaults to `0`. - - `HandleSIGHUP`# - - `HandleSIGINT`# - - `HandleSIGTERM`# - - `HasTouch`# - - `Headless`# - - `HttpCredentials`# + - `HandleSIGHUP` <[bool]?> Close the browser process on SIGHUP. Defaults to `true`.# + - `HandleSIGINT` <[bool]?> Close the browser process on Ctrl-C. Defaults to `true`.# + - `HandleSIGTERM` <[bool]?> Close the browser process on SIGTERM. Defaults to `true`.# + - `HasTouch` <[bool]?> Specifies if viewport supports touch events. Defaults to false.# + - `Headless` <[bool]?> 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 `devtools` option is `true`.# + - `HttpCredentials` <HttpCredentials?> Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).# - `Username` <[string]> - `Password` <[string]> - - `IgnoreAllDefaultArgs`# - - `IgnoreDefaultArgs`# - - `IgnoreHTTPSErrors`# - - `IsMobile`# - - `JavaScriptEnabled`# - - `Locale`# - - `Offline`# - - `Permissions`# - - `Proxy`# + - `IgnoreAllDefaultArgs` <[bool]?> If `true`, Playwright does not pass its own configurations args and only uses the ones from `args`. Dangerous option; use with care. Defaults to `false`. Added in: v1.9# + - `IgnoreDefaultArgs` <[IEnumerable]?<[string]>> If `true`, Playwright does not pass its own configurations args and only uses the ones from `args`. Dangerous option; use with care.# + - `IgnoreHTTPSErrors` <[bool]?> Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.# + - `IsMobile` <[bool]?> Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox.# + - `JavaScriptEnabled` <[bool]?> Whether or not to enable JavaScript in the context. Defaults to `true`.# + - `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.# + - `Offline` <[bool]?> Whether to emulate network being offline. Defaults to `false`.# + - `Permissions` <[IEnumerable]?<[string]>> A list of permissions to grant to all pages in this context. See [BrowserContext.GrantPermissionsAsync();](/api/class-browsercontext.mdx#browser-context-grant-permissions) for more details.# + - `Proxy` <Proxy?> Network proxy settings.# - `Server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - `Bypass` <[string]?> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - `Username` <[string]?> Optional username to use if HTTP proxy requires authentication. - `Password` <[string]?> Optional password to use if HTTP proxy requires authentication. - - `RecordHarContent`# - - `RecordHarMode`# - - `RecordHarOmitContent`# - - `RecordHarPath`# - - `RecordHarUrlFilter|RecordHarUrlFilterRegex`# - - `RecordVideoDir`# - - `RecordVideoSize`# + - `RecordHarContent` <`enum HarContentPolicy { Omit, Embed, Attach }?`> Optional setting to control resource content management. If `omit` is specified, content is not persisted. If `attach` is specified, resources are persisted as separate files and all of these files are archived along with the HAR file. Defaults to `embed`, which stores content inline the HAR file as per HAR specification.# + - `RecordHarMode` <`enum HarMode { Full, Minimal }?`> When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page, cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `full`.# + - `RecordHarOmitContent` <[bool]?> Optional setting to control whether to omit request content from the HAR. Defaults to `false`.# + - `RecordHarPath` <[string]?> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into the specified HAR file on the filesystem. If not specified, the HAR is not recorded. Make sure to call [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) for the HAR to be saved.# + - `RecordHarUrlFilter|RecordHarUrlFilterRegex` <[string]?|[Regex]?># + - `RecordVideoDir` <[string]?> Enables video recording for all pages into the specified directory. If not specified videos are not recorded. Make sure to call [BrowserContext.CloseAsync();](/api/class-browsercontext.mdx#browser-context-close) for videos to be saved.# + - `RecordVideoSize` <RecordVideoSize?> Dimensions of the recorded videos. If not specified the size will be equal to `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.# - `Width` <[int]> Video frame width. - `Height` <[int]> Video frame height. - - `ReducedMotion`# - - `ScreenSize`# + - `ReducedMotion` <`enum ReducedMotion { Reduce, NoPreference, Null }?`> Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. See [Page.EmulateMediaAsync();](/api/class-page.mdx#page-emulate-media) for more details. Passing `'null'` resets emulation to system defaults. Defaults to `'no-preference'`.# + - `ScreenSize` <ScreenSize?> Emulates consistent window screen size available inside web page via `window.screen`. Is only used when the `viewport` is set.# - `Width` <[int]> page width in pixels. - `Height` <[int]> page height in pixels. - - `ServiceWorkers`# + - `ServiceWorkers` <`enum ServiceWorkerPolicy { Allow, Block }?`> 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. * `'block'`: Playwright will block all registration of Service Workers. - - `SlowMo`# - - `StrictSelectors`# - - `Timeout`# - - `TimezoneId`# - - `TracesDir`# - - `UserAgent`# - - `ViewportSize`# + - `SlowMo` <[double]?> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on.# + - `StrictSelectors` <[bool]?> If specified, enables strict selectors mode for this context. In the strict selectors mode all operations on selectors that imply single target DOM element will throw when more than one element matches the selector. See [Locator] to learn more about the strict mode.# + - `Timeout` <[double]?> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.# + - `TimezoneId` <[string]?> 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.# + - `TracesDir` <[string]?> If specified, traces are saved into this directory.# + - `UserAgent` <[string]?> Specific user agent to use in this context.# + - `ViewportSize` <ViewportSize?> Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the default viewport.# - `Width` <[int]> page width in pixels. - `Height` <[int]> page height in pixels. -- returns:# -Returns the persistent browser context instance. +#### Returns +- <[BrowserContext]># -Launches browser that uses persistent storage located at `userDataDir` and returns the only context. Closing this context will automatically close the browser. +--- -## BrowserType.Name {#browser-type-name} +## Name {#browser-type-name} Added in: v1.8 -- returns:# - Returns browser name. For example: `'chromium'`, `'webkit'` or `'firefox'`. +#### Usage + +```csharp +BrowserType.Name +``` + +#### Returns +- <[string]># + [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" [APIRequestContext]: /api/class-apirequestcontext.mdx "APIRequestContext" diff --git a/dotnet/docs/api/class-consolemessage.mdx b/dotnet/docs/api/class-consolemessage.mdx index 3f85421117d4b..0a0b9bb1f3d32 100644 --- a/dotnet/docs/api/class-consolemessage.mdx +++ b/dotnet/docs/api/class-consolemessage.mdx @@ -6,7 +6,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import HTMLCard from '@site/src/components/HTMLCard'; -[ConsoleMessage] objects are dispatched by page via the [event Page.Console](/api/class-page.mdx#page-event-console) event. For each console messages logged in the page there will be corresponding event in the Playwright context. +[ConsoleMessage] objects are dispatched by page via the [Page.Console](/api/class-page.mdx#page-event-console) event. For each console messages logged in the page there will be corresponding event in the Playwright context. ```csharp // Listen for all System.out.printlns @@ -29,43 +29,74 @@ await message.Args.ElementAt(1).JsonValueAsync(); // 42 ``` -- [ConsoleMessage.Args](/api/class-consolemessage.mdx#console-message-args) -- [ConsoleMessage.Location](/api/class-consolemessage.mdx#console-message-location) -- [ConsoleMessage.Text](/api/class-consolemessage.mdx#console-message-text) -- [ConsoleMessage.Type](/api/class-consolemessage.mdx#console-message-type) +--- -## ConsoleMessage.Args {#console-message-args} +## Args {#console-message-args} Added in: v1.8 -- returns:# +List of arguments passed to a `console` function call. See also [Page.Console](/api/class-page.mdx#page-event-console). -List of arguments passed to a `console` function call. See also [event Page.Console](/api/class-page.mdx#page-event-console). +#### Usage -## ConsoleMessage.Location {#console-message-location} +```csharp +ConsoleMessage.Args +``` -Added in: v1.8 +#### Returns +- <[IEnumerable]<[JSHandle]>># -- returns:# +--- + +## Location {#console-message-location} + +Added in: v1.8 URL of the resource followed by 0-based line and column numbers in the resource formatted as `URL:line:column`. -## ConsoleMessage.Text {#console-message-text} +#### Usage -Added in: v1.8 +```csharp +ConsoleMessage.Location +``` -- returns:# +#### Returns +- <[string]># -The text of the console message. +--- -## ConsoleMessage.Type {#console-message-type} +## Text {#console-message-text} Added in: v1.8 -- returns:# +The text of the console message. + +#### Usage + +```csharp +ConsoleMessage.Text +``` + +#### Returns +- <[string]># + +--- + +## Type {#console-message-type} + +Added in: v1.8 One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'`, `'dir'`, `'dirxml'`, `'table'`, `'trace'`, `'clear'`, `'startGroup'`, `'startGroupCollapsed'`, `'endGroup'`, `'assert'`, `'profile'`, `'profileEnd'`, `'count'`, `'timeEnd'`. +#### Usage + +```csharp +ConsoleMessage.Type +``` + +#### Returns +- <[string]># + [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" [APIRequestContext]: /api/class-apirequestcontext.mdx "APIRequestContext" diff --git a/dotnet/docs/api/class-dialog.mdx b/dotnet/docs/api/class-dialog.mdx index 4225ee1a0e3bd..54b01ceb7127b 100644 --- a/dotnet/docs/api/class-dialog.mdx +++ b/dotnet/docs/api/class-dialog.mdx @@ -6,7 +6,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import HTMLCard from '@site/src/components/HTMLCard'; -[Dialog] objects are dispatched by page via the [event Page.Dialog](/api/class-page.mdx#page-event-dialog) event. +[Dialog] objects are dispatched by page via the [Page.Dialog](/api/class-page.mdx#page-event-dialog) event. An example of using `Dialog` class: @@ -34,57 +34,98 @@ class DialogExample ``` :::note -Dialogs are dismissed automatically, unless there is a [event Page.Dialog](/api/class-page.mdx#page-event-dialog) listener. When listener is present, it **must** either [Dialog.AcceptAsync(promptText)](/api/class-dialog.mdx#dialog-accept) or [Dialog.DismissAsync()](/api/class-dialog.mdx#dialog-dismiss) the dialog - otherwise the page will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the dialog, and actions like click will never finish. +Dialogs are dismissed automatically, unless there is a [Page.Dialog](/api/class-page.mdx#page-event-dialog) listener. When listener is present, it **must** either [Dialog.AcceptAsync();](/api/class-dialog.mdx#dialog-accept) or [Dialog.DismissAsync();](/api/class-dialog.mdx#dialog-dismiss) the dialog - otherwise the page will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the dialog, and actions like click will never finish. ::: -- [Dialog.AcceptAsync(promptText)](/api/class-dialog.mdx#dialog-accept) -- [Dialog.DefaultValue](/api/class-dialog.mdx#dialog-default-value) -- [Dialog.DismissAsync()](/api/class-dialog.mdx#dialog-dismiss) -- [Dialog.Message](/api/class-dialog.mdx#dialog-message) -- [Dialog.Type](/api/class-dialog.mdx#dialog-type) +--- -## Dialog.AcceptAsync(promptText) {#dialog-accept} +## AcceptAsync {#dialog-accept} Added in: v1.8 -- `promptText`# -- returns:# - Returns when the dialog has been accepted. -## Dialog.DefaultValue {#dialog-default-value} +#### Usage -Added in: v1.8 +```csharp +await Dialog.AcceptAsync(promptText); +``` -- returns:# +#### Parameters +- `promptText` <[string]?> A text to enter in prompt. Does not cause any effects if the dialog's `type` is not prompt. Optional.# -If dialog is prompt, returns default prompt value. Otherwise, returns empty string. +#### Returns +- <[void]># + +--- -## Dialog.DismissAsync() {#dialog-dismiss} +## DefaultValue {#dialog-default-value} Added in: v1.8 -- returns:# +If dialog is prompt, returns default prompt value. Otherwise, returns empty string. -Returns when the dialog has been dismissed. +#### Usage -## Dialog.Message {#dialog-message} +```csharp +Dialog.DefaultValue +``` + +#### Returns +- <[string]># + +--- + +## DismissAsync {#dialog-dismiss} Added in: v1.8 -- returns:# +Returns when the dialog has been dismissed. -A message displayed in the dialog. +#### Usage + +```csharp +await Dialog.DismissAsync(); +``` + +#### Returns +- <[void]># -## Dialog.Type {#dialog-type} +--- + +## Message {#dialog-message} Added in: v1.8 -- returns:# +A message displayed in the dialog. + +#### Usage + +```csharp +Dialog.Message +``` + +#### Returns +- <[string]># + +--- + +## Type {#dialog-type} + +Added in: v1.8 Returns dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`. +#### Usage + +```csharp +Dialog.Type +``` + +#### Returns +- <[string]># + [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" [APIRequestContext]: /api/class-apirequestcontext.mdx "APIRequestContext" diff --git a/dotnet/docs/api/class-download.mdx b/dotnet/docs/api/class-download.mdx index 6309486586ad5..5f3e05a3ee7bd 100644 --- a/dotnet/docs/api/class-download.mdx +++ b/dotnet/docs/api/class-download.mdx @@ -6,7 +6,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import HTMLCard from '@site/src/components/HTMLCard'; -[Download] objects are dispatched by page via the [event Page.Download](/api/class-page.mdx#page-event-download) event. +[Download] objects are dispatched by page via the [Page.Download](/api/class-page.mdx#page-event-download) event. All the downloaded files belonging to the browser context are deleted when the browser context is closed. @@ -21,91 +21,164 @@ Console.WriteLine(await download.PathAsync()); ``` -- [Download.CancelAsync()](/api/class-download.mdx#download-cancel) -- [Download.CreateReadStreamAsync()](/api/class-download.mdx#download-create-read-stream) -- [Download.DeleteAsync()](/api/class-download.mdx#download-delete) -- [Download.FailureAsync()](/api/class-download.mdx#download-failure) -- [Download.Page](/api/class-download.mdx#download-page) -- [Download.PathAsync()](/api/class-download.mdx#download-path) -- [Download.SaveAsAsync(path)](/api/class-download.mdx#download-save-as) -- [Download.SuggestedFilename](/api/class-download.mdx#download-suggested-filename) -- [Download.Url](/api/class-download.mdx#download-url) +--- -## Download.CancelAsync() {#download-cancel} +## CancelAsync {#download-cancel} Added in: v1.13 -- returns:# - Cancels a download. Will not fail if the download is already finished or canceled. Upon successful cancellations, `download.failure()` would resolve to `'canceled'`. -## Download.CreateReadStreamAsync() {#download-create-read-stream} +#### Usage -Added in: v1.8 +```csharp +await Download.CancelAsync(); +``` -- returns:# +#### Returns +- <[void]># -Returns readable stream for current download or `null` if download failed. +--- -## Download.DeleteAsync() {#download-delete} +## CreateReadStreamAsync {#download-create-read-stream} Added in: v1.8 -- returns:# +Returns readable stream for current download or `null` if download failed. -Deletes the downloaded file. Will wait for the download to finish if necessary. +#### Usage -## Download.FailureAsync() {#download-failure} +```csharp +await Download.CreateReadStreamAsync(); +``` + +#### Returns +- <[Stream]?># + +--- + +## DeleteAsync {#download-delete} Added in: v1.8 -- returns:# +Deletes the downloaded file. Will wait for the download to finish if necessary. + +#### Usage + +```csharp +await Download.DeleteAsync(); +``` + +#### Returns +- <[void]># + +--- + +## FailureAsync {#download-failure} + +Added in: v1.8 Returns download error if any. Will wait for the download to finish if necessary. -## Download.Page {#download-page} +#### Usage -Added in: v1.12 +```csharp +await Download.FailureAsync(); +``` + +#### Returns +- <[string]?># + +--- -- returns:# +## Page {#download-page} + +Added in: v1.12 Get the page that the download belongs to. -## Download.PathAsync() {#download-path} +#### Usage -Added in: v1.8 +```csharp +Download.Page +``` + +#### Returns +- <[Page]># -- returns:# +--- + +## PathAsync {#download-path} + +Added in: v1.8 Returns path to the downloaded file in case of successful download. The method will wait for the download to finish if necessary. The method throws when connected remotely. Note that the download's file name is a random GUID, use [Download.SuggestedFilename](/api/class-download.mdx#download-suggested-filename) to get suggested file name. -## Download.SaveAsAsync(path) {#download-save-as} +#### Usage -Added in: v1.8 +```csharp +await Download.PathAsync(); +``` -- `path`# -- returns:# +#### Returns +- <[string]?># -Copy the download to a user-specified path. It is safe to call this method while the download is still in progress. Will wait for the download to finish if necessary. +--- -## Download.SuggestedFilename {#download-suggested-filename} +## SaveAsAsync {#download-save-as} Added in: v1.8 -- returns:# +Copy the download to a user-specified path. It is safe to call this method while the download is still in progress. Will wait for the download to finish if necessary. -Returns suggested filename for this download. It is typically computed by the browser from the [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header or the `download` attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different browsers can use different logic for computing it. +#### Usage + +```csharp +await Download.SaveAsAsync(path); +``` + +#### Parameters +- `path` <[string]> Path where the download should be copied.# + +#### Returns +- <[void]># -## Download.Url {#download-url} +--- + +## SuggestedFilename {#download-suggested-filename} Added in: v1.8 -- returns:# +Returns suggested filename for this download. It is typically computed by the browser from the [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header or the `download` attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different browsers can use different logic for computing it. + +#### Usage + +```csharp +Download.SuggestedFilename +``` + +#### Returns +- <[string]># + +--- + +## Url {#download-url} + +Added in: v1.8 Returns downloaded url. +#### Usage + +```csharp +Download.Url +``` + +#### Returns +- <[string]># + [Accessibility]: /api/class-accessibility.mdx "Accessibility" [APIRequest]: /api/class-apirequest.mdx "APIRequest" [APIRequestContext]: /api/class-apirequestcontext.mdx "APIRequestContext" diff --git a/dotnet/docs/api/class-elementhandle.mdx b/dotnet/docs/api/class-elementhandle.mdx index e470113e2a7a5..c4011bd303481 100644 --- a/dotnet/docs/api/class-elementhandle.mdx +++ b/dotnet/docs/api/class-elementhandle.mdx @@ -8,7 +8,7 @@ import HTMLCard from '@site/src/components/HTMLCard'; * extends: [JSHandle] -ElementHandle represents an in-page DOM element. ElementHandles can be created with the [Page.QuerySelectorAsync(selector, options)](/api/class-page.mdx#page-query-selector) method. +ElementHandle represents an in-page DOM element. ElementHandles can be created with the [Page.QuerySelectorAsync();](/api/class-page.mdx#page-query-selector) method. :::caution Discouraged The use of ElementHandle is discouraged, use [Locator] objects and web-first assertions instead. @@ -19,9 +19,9 @@ var handle = await page.QuerySelectorAsync("a"); await handle.ClickAsync(); ``` -ElementHandle prevents DOM element from garbage collection unless the handle is disposed with [JsHandle.DisposeAsync()](/api/class-jshandle.mdx#js-handle-dispose). ElementHandles are auto-disposed when their origin frame gets navigated. +ElementHandle prevents DOM element from garbage collection unless the handle is disposed with [JsHandle.DisposeAsync();](/api/class-jshandle.mdx#js-handle-dispose). ElementHandles are auto-disposed when their origin frame gets navigated. -ElementHandle instances can be used as an argument in [Page.EvalOnSelectorAsync(selector, expression, arg, options)](/api/class-page.mdx#page-eval-on-selector) and [Page.EvaluateAsync(expression, arg)](/api/class-page.mdx#page-evaluate) methods. +ElementHandle instances can be used as an argument in [Page.EvalOnSelectorAsync();](/api/class-page.mdx#page-eval-on-selector) and [Page.EvaluateAsync();](/api/class-page.mdx#page-evaluate) methods. The difference between the [Locator] and ElementHandle is that the ElementHandle points to a particular element, while [Locator] captures the logic of how to retrieve an element. @@ -42,60 +42,11 @@ await locator.ClickAsync(); ``` -- [ElementHandle.BoundingBoxAsync()](/api/class-elementhandle.mdx#element-handle-bounding-box) -- [ElementHandle.CheckAsync(options)](/api/class-elementhandle.mdx#element-handle-check) -- [ElementHandle.ClickAsync(options)](/api/class-elementhandle.mdx#element-handle-click) -- [ElementHandle.ContentFrameAsync()](/api/class-elementhandle.mdx#element-handle-content-frame) -- [ElementHandle.DblClickAsync(options)](/api/class-elementhandle.mdx#element-handle-dblclick) -- [ElementHandle.DispatchEventAsync(type, eventInit)](/api/class-elementhandle.mdx#element-handle-dispatch-event) -- [ElementHandle.EvalOnSelectorAllAsync(selector, expression, arg)](/api/class-elementhandle.mdx#element-handle-eval-on-selector-all) -- [ElementHandle.EvalOnSelectorAsync(selector, expression, arg)](/api/class-elementhandle.mdx#element-handle-eval-on-selector) -- [ElementHandle.FillAsync(value, options)](/api/class-elementhandle.mdx#element-handle-fill) -- [ElementHandle.FocusAsync()](/api/class-elementhandle.mdx#element-handle-focus) -- [ElementHandle.GetAttributeAsync(name)](/api/class-elementhandle.mdx#element-handle-get-attribute) -- [ElementHandle.HoverAsync(options)](/api/class-elementhandle.mdx#element-handle-hover) -- [ElementHandle.InnerHTMLAsync()](/api/class-elementhandle.mdx#element-handle-inner-html) -- [ElementHandle.InnerTextAsync()](/api/class-elementhandle.mdx#element-handle-inner-text) -- [ElementHandle.InputValueAsync(options)](/api/class-elementhandle.mdx#element-handle-input-value) -- [ElementHandle.IsCheckedAsync()](/api/class-elementhandle.mdx#element-handle-is-checked) -- [ElementHandle.IsDisabledAsync()](/api/class-elementhandle.mdx#element-handle-is-disabled) -- [ElementHandle.IsEditableAsync()](/api/class-elementhandle.mdx#element-handle-is-editable) -- [ElementHandle.IsEnabledAsync()](/api/class-elementhandle.mdx#element-handle-is-enabled) -- [ElementHandle.IsHiddenAsync()](/api/class-elementhandle.mdx#element-handle-is-hidden) -- [ElementHandle.IsVisibleAsync()](/api/class-elementhandle.mdx#element-handle-is-visible) -- [ElementHandle.OwnerFrameAsync()](/api/class-elementhandle.mdx#element-handle-owner-frame) -- [ElementHandle.PressAsync(key, options)](/api/class-elementhandle.mdx#element-handle-press) -- [ElementHandle.QuerySelectorAllAsync(selector)](/api/class-elementhandle.mdx#element-handle-query-selector-all) -- [ElementHandle.QuerySelectorAsync(selector)](/api/class-elementhandle.mdx#element-handle-query-selector) -- [ElementHandle.ScreenshotAsync(options)](/api/class-elementhandle.mdx#element-handle-screenshot) -- [ElementHandle.ScrollIntoViewIfNeededAsync(options)](/api/class-elementhandle.mdx#element-handle-scroll-into-view-if-needed) -- [ElementHandle.SelectOptionAsync(values, options)](/api/class-elementhandle.mdx#element-handle-select-option) -- [ElementHandle.SelectTextAsync(options)](/api/class-elementhandle.mdx#element-handle-select-text) -- [ElementHandle.SetCheckedAsync(checked, options)](/api/class-elementhandle.mdx#element-handle-set-checked) -- [ElementHandle.SetInputFilesAsync(files, options)](/api/class-elementhandle.mdx#element-handle-set-input-files) -- [ElementHandle.TapAsync(options)](/api/class-elementhandle.mdx#element-handle-tap) -- [ElementHandle.TextContentAsync()](/api/class-elementhandle.mdx#element-handle-text-content) -- [ElementHandle.TypeAsync(text, options)](/api/class-elementhandle.mdx#element-handle-type) -- [ElementHandle.UncheckAsync(options)](/api/class-elementhandle.mdx#element-handle-uncheck) -- [ElementHandle.WaitForElementStateAsync(state, options)](/api/class-elementhandle.mdx#element-handle-wait-for-element-state) -- [ElementHandle.WaitForSelectorAsync(selector, options)](/api/class-elementhandle.mdx#element-handle-wait-for-selector) -- [JsHandle.AsElement()](/api/class-jshandle.mdx#js-handle-as-element) -- [JsHandle.DisposeAsync()](/api/class-jshandle.mdx#js-handle-dispose) -- [JsHandle.EvaluateAsync(expression, arg)](/api/class-jshandle.mdx#js-handle-evaluate) -- [JsHandle.EvaluateHandleAsync(expression, arg)](/api/class-jshandle.mdx#js-handle-evaluate-handle) -- [JsHandle.GetPropertiesAsync()](/api/class-jshandle.mdx#js-handle-get-properties) -- [JsHandle.GetPropertyAsync(propertyName)](/api/class-jshandle.mdx#js-handle-get-property) -- [JsHandle.JsonValueAsync()](/api/class-jshandle.mdx#js-handle-json-value) - -## ElementHandle.BoundingBoxAsync() {#element-handle-bounding-box} +--- -Added in: v1.8 +## BoundingBoxAsync {#element-handle-bounding-box} -- returns:# - - `x` <[double]> the x coordinate of the element in pixels. - - `y` <[double]> the y coordinate of the element in pixels. - - `width` <[double]> the width of the element in pixels. - - `height` <[double]> the height of the element in pixels. +Added in: v1.8 This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window. @@ -110,19 +61,24 @@ var box = await elementHandle.BoundingBoxAsync(); await page.Mouse.ClickAsync(box.X + box.Width / 2, box.Y + box.Height / 2); ``` -## ElementHandle.CheckAsync(options) {#element-handle-check} +#### Usage -Added in: v1.8 +```csharp +await ElementHandle.BoundingBoxAsync(); +``` -- `options` <`ElementHandleCheckOptions?`> - - `Force`# - - `NoWaitAfter`# - - `Position`# - - `X` <[double]> - - `Y` <[double]> - - `Timeout`# - - `Trial`# -- returns:# +#### Returns +- <BoundingBox?># + - `x` <[double]> the x coordinate of the element in pixels. + - `y` <[double]> the y coordinate of the element in pixels. + - `width` <[double]> the width of the element in pixels. + - `height` <[double]> the height of the element in pixels. + +--- + +## CheckAsync {#element-handle-check} + +Added in: v1.8 This method checks the element by performing the following steps: 1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately. @@ -136,23 +92,30 @@ If the element is detached from the DOM at any moment during the action, this me When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError]. Passing zero timeout disables this. -## ElementHandle.ClickAsync(options) {#element-handle-click} +#### Usage -Added in: v1.8 +```csharp +await ElementHandle.CheckAsync(options); +``` -- `options` <`ElementHandleClickOptions?`> - - `Button`# - - `ClickCount`# - - `Delay`# - - `Force`# - - `Modifiers`# - - `NoWaitAfter`# - - `Position`# +#### Parameters +- `options` <`ElementHandleCheckOptions?`> + - `Force` <[bool]?> Whether to bypass the [actionability](../actionability.mdx) checks. Defaults to `false`.# + - `NoWaitAfter` <[bool]?> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.# + - `Position` <Position?> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. Added in: v1.11# - `X` <[double]> - `Y` <[double]> - - `Timeout`# - - `Trial`# -- returns:# + - `Timeout` <[double]?> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout();](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout();](/api/class-page.mdx#page-set-default-timeout) methods.# + - `Trial` <[bool]?> When set, this method only performs the [actionability](../actionability.mdx) checks and skips the action. Defaults to `false`. Useful to wait until the element is ready for the action without performing it. Added in: v1.11# + +#### Returns +- <[void]># + +--- + +## ClickAsync {#element-handle-click} + +Added in: v1.8 This method clicks the element by performing the following steps: 1. Wait for [actionability](../actionability.mdx) checks on the element, unless `force` option is set. @@ -164,30 +127,51 @@ If the element is detached from the DOM at any moment during the action, this me When all steps combined have not finished during the specified `timeout`, this method throws a [TimeoutError]. Passing zero timeout disables this. -## ElementHandle.ContentFrameAsync() {#element-handle-content-frame} +#### Usage -Added in: v1.8 +```csharp +await ElementHandle.ClickAsync(options); +``` -- returns:# +#### Parameters +- `options` <`ElementHandleClickOptions?`> + - `Button` <`enum MouseButton { Left, Right, Middle }?`> Defaults to `left`.# + - `ClickCount` <[int]?> defaults to 1. See [UIEvent.detail].# + - `Delay` <[double]?> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.# + - `Force` <[bool]?> Whether to bypass the [actionability](../actionability.mdx) checks. Defaults to `false`.# + - `Modifiers` <[IEnumerable]?<`enum KeyboardModifier { Alt, Control, Meta, Shift }`>> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.# + - `NoWaitAfter` <[bool]?> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.# + - `Position` <Position?> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.# + - `X` <[double]> + - `Y` <[double]> + - `Timeout` <[double]?> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout();](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout();](/api/class-page.mdx#page-set-default-timeout) methods.# + - `Trial` <[bool]?> When set, this method only performs the [actionability](../actionability.mdx) checks and skips the action. Defaults to `false`. Useful to wait until the element is ready for the action without performing it. Added in: v1.11# -Returns the content frame for element handles referencing iframe nodes, or `null` otherwise +#### Returns +- <[void]># + +--- -## ElementHandle.DblClickAsync(options) {#element-handle-dblclick} +## ContentFrameAsync {#element-handle-content-frame} Added in: v1.8 -- `options` <`ElementHandleDblClickOptions?`> - - `Button`# - - `Delay`# - - `Force`# - - `Modifiers`# - - `NoWaitAfter`# - - `Position`# - - `X` <[double]> - - `Y` <[double]> - - `Timeout`# - - `Trial`# -- returns:# +Returns the content frame for element handles referencing iframe nodes, or `null` otherwise + +#### Usage + +```csharp +await ElementHandle.ContentFrameAsync(); +``` + +#### Returns +- <[Frame]?># + +--- + +## DblClickAsync {#element-handle-dblclick} + +Added in: v1.8 This method double clicks the element by performing the following steps: 1. Wait for [actionability](../actionability.mdx) checks on the element, unless `force` option is set. @@ -203,13 +187,33 @@ When all steps combined have not finished during the specified `timeout`, this m `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event. ::: -## ElementHandle.DispatchEventAsync(type, eventInit) {#element-handle-dispatch-event} +#### Usage -Added in: v1.8 +```csharp +await ElementHandle.DblClickAsync(options); +``` + +#### Parameters +- `options` <`ElementHandleDblClickOptions?`> + - `Button` <`enum MouseButton { Left, Right, Middle }?`> Defaults to `left`.# + - `Delay` <[double]?> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.# + - `Force` <[bool]?> Whether to bypass the [actionability](../actionability.mdx) checks. Defaults to `false`.# + - `Modifiers` <[IEnumerable]?<`enum KeyboardModifier { Alt, Control, Meta, Shift }`>> Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.# + - `NoWaitAfter` <[bool]?> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.# + - `Position` <Position?> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.# + - `X` <[double]> + - `Y` <[double]> + - `Timeout` <[double]?> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [BrowserContext.SetDefaultTimeout();](/api/class-browsercontext.mdx#browser-context-set-default-timeout) or [Page.SetDefaultTimeout();](/api/class-page.mdx#page-set-default-timeout) methods.# + - `Trial` <[bool]?> When set, this method only performs the [actionability](../actionability.mdx) checks and skips the action. Defaults to `false`. Useful to wait until the element is ready for the action without performing it. Added in: v1.11# + +#### Returns +- <[void]># -- `type`# -- `eventInit`# -- returns:# +--- + +## DispatchEventAsync {#element-handle-dispatch-event} + +Added in: v1.8 The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element, `click` is dispatched. This is equivalent to calling [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click). @@ -238,20 +242,30 @@ await elementHandle.DispatchEventAsync("dragstart", new DictionaryAdded in: v1.9 +```csharp +await ElementHandle.DispatchEventAsync(type, eventInit); +``` -- `selector`# -- `expression`# -- `arg`# -- returns:# +#### Parameters +- `type` <[string]> DOM event type: `"click"`, `"dragstart"`, etc.# +- `eventInit` <[EvaluationArgument]?> Optional event-specific initialization properties.# + +#### Returns +- <[void]># + +--- + +## EvalOnSelectorAsync {#element-handle-eval-on-selector} + +Added in: v1.9 Returns the return value of `expression`. The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first argument to `expression`. See [Working with selectors](../selectors.mdx) for more details. If no elements match the selector, the method throws an error. -If `expression` returns a [Promise], then [ElementHandle.EvalOnSelectorAsync(selector, expression, arg)](/api/class-elementhandle.mdx#element-handle-eval-on-selector) would wait for the promise to resolve and return its value. +If `expression` returns a [Promise], then [ElementHandle.EvalOnSelectorAsync();](/api/class-elementhandle.mdx#element-handle-eval-on-selector) would wait for the promise to resolve and return its value. Examples: @@ -261,20 +275,31 @@ Assert.AreEqual("100", await tweetHandle.EvalOnSelectorAsync(".like", "node => n Assert.AreEqual("10", await tweetHandle.EvalOnSelectorAsync(".retweets", "node => node.innerText")); ``` -## ElementHandle.EvalOnSelectorAllAsync(selector, expression, arg) {#element-handle-eval-on-selector-all} +#### Usage -Added in: v1.9 +```csharp +await ElementHandle.EvalOnSelectorAsync(selector, expression, arg); +``` + +#### Parameters +- `selector` <[string]> A selector to query for. See [working with selectors](../selectors.mdx) for more details.# +- `expression` <[string]> JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.# +- `arg` <[EvaluationArgument]?> Optional argument to pass to `expression`.# + +#### Returns +- <[object]># + +--- -- `selector`# -- `expression`# -- `arg`# -- returns:# +## EvalOnSelectorAllAsync {#element-handle-eval-on-selector-all} + +Added in: v1.9 Returns the return value of `expression`. The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array of matched elements as a first argument to `expression`. See [Working with selectors](../selectors.mdx) for more details. -If `expression` returns a [Promise], then [ElementHandle.EvalOnSelectorAllAsync(selector, expression, arg)](/api/class-elementhandle.mdx#element-handle-eval-on-selector-all) would wait for the promise to resolve and return its value. +If `expression` returns a [Promise], then [ElementHandle.EvalOnSelectorAllAsync();](/api/class-elementhandle.mdx#element-handle-eval-on-selector-all) would wait for the promise to resolve and return its value. Examples: @@ -290,54 +315,90 @@ var feedHandle = await page.QuerySelectorAsync(".feed"); Assert.AreEqual(new [] { "Hello!", "Hi!" }, await feedHandle.EvalOnSelectorAllAsync(".tweet", "nodes => nodes.map(n => n.innerText)")); ``` -## ElementHandle.FillAsync(value, options) {#element-handle-fill} +#### Usage -Added in: v1.8 +```csharp +await ElementHandle.EvalOnSelectorAllAsync(selector, expression, arg); +``` -- `value`