|
| 1 | +--- |
| 2 | +title: 'waitForSelector(selector[, options])' |
| 3 | +description: 'Browser module: frame.waitForSelector(selector[, options]) method' |
| 4 | +--- |
| 5 | + |
| 6 | +# waitForSelector(selector[, options]) |
| 7 | + |
| 8 | +{{% admonition type="note" %}} |
| 9 | + |
| 10 | +Use web assertions that assert visibility or a locator-based [`locator.waitFor([options])`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/waitfor/) instead. |
| 11 | + |
| 12 | +{{% /admonition %}} |
| 13 | + |
| 14 | +Returns when element specified by selector satisfies `state` option. |
| 15 | + |
| 16 | +<TableWithNestedRows> |
| 17 | + |
| 18 | +| Parameter | Type | Default | Description | |
| 19 | +| --------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 20 | +| selector | string | `''` | A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. | |
| 21 | +| options | object | `null` | | |
| 22 | +| options.state | string | `visible` | Can be either `attached`, `detached`, `visible`, `hidden` See [Element states](#element-states) for more details. | |
| 23 | +| options.strict | boolean | `false` | When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception. | |
| 24 | +| options.timeout | number | `30000` | Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on [BrowserContext](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/browsercontext/) or [Page](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/). | |
| 25 | + |
| 26 | +</TableWithNestedRows> |
| 27 | + |
| 28 | +### Element states |
| 29 | + |
| 30 | +Element states can be either: |
| 31 | + |
| 32 | +- `'attached'` - wait for element to be present in DOM. |
| 33 | +- `'detached'` - wait for element to not be present in DOM. |
| 34 | +- `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. |
| 35 | +- `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. |
| 36 | + |
| 37 | +### Returns |
| 38 | + |
| 39 | +| Type | Description | |
| 40 | +| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 41 | +| `Promise<ElementHandle \| null>` | A Promise that fulfills with the [ElementHandle](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/keyboard/) when a matching element is found, or `null` if the element is not found. | |
0 commit comments