From b4acc56d630c6f3e5aca5856a8931f691b6f3e1c Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Tue, 12 May 2020 15:46:19 -0700 Subject: [PATCH] docs(api.md): elaborate on visibility options in waitForSelector (#2208) Fixes #2202 --- docs/api.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/api.md b/docs/api.md index 20484e9a6c..9301b37603 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1811,14 +1811,16 @@ return finalResponse.ok(); #### page.waitForSelector(selector[, options]) - `selector` <[string]> A selector of an element to wait for - `options` <[Object]> - - `state` <"attached"|"detached"|"visible"|"hidden"> Wait for element to become visible (`visible`), hidden (`hidden`), present in dom (`attached`) or not present in dom (`detached`). Defaults to `visible`. + - `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either: + - `'attached'` - wait for element to be present in DOM. + - `'detached'` - wait for element to not be present in DOM. + - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. + - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods. - returns: <[Promise]> Promise which resolves when element specified by selector satisfies `state` option. Resolves to `null` if waiting for `hidden` or `detached`. Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. -Element is considered `visible` when it has non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. Element is considired `hidden` when it is not `visible` as defined above. - This method works across navigations: ```js const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. @@ -2435,14 +2437,16 @@ const [response] = await Promise.all([ #### frame.waitForSelector(selector[, options]) - `selector` <[string]> A selector of an element to wait for - `options` <[Object]> - - `state` <"attached"|"detached"|"visible"|"hidden"> Wait for element to become visible (`visible`), hidden (`hidden`), present in dom (`attached`) or not present in dom (`detached`). Defaults to `visible`. + - `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either: + - `'attached'` - wait for element to be present in DOM. + - `'detached'` - wait for element to not be present in DOM. + - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. + - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods. - returns: <[Promise]> Promise which resolves when element specified by selector satisfies `state` option. Resolves to `null` if waiting for `hidden` or `detached`. Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. -Element is considered `visible` when it has non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. Element is considired `hidden` when it is not `visible` as defined above. - This method works across navigations: ```js const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.