diff --git a/docs/sources/next/javascript-api/k6-experimental/browser/_index.md b/docs/sources/next/javascript-api/k6-experimental/browser/_index.md index da2d3de84c..dcb03ecb3c 100644 --- a/docs/sources/next/javascript-api/k6-experimental/browser/_index.md +++ b/docs/sources/next/javascript-api/k6-experimental/browser/_index.md @@ -39,6 +39,7 @@ The browser module is the entry point for all your tests, and it is what interac | Method | Description | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [browser.context()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/context) | Returns the current [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | +| [browser.closeContext()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/closecontext) | Closes the current [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | | [browser.isConnected](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/isconnected) | Indicates whether the [CDP](https://chromedevtools.github.io/devtools-protocol/) connection to the browser process is active or not. | | [browser.newContext([options])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/newcontext/) | Creates and returns a new [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | | [browser.newPage([options])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/newpage) | Creates a new [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) in a new [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext) and returns the page. Pages that have been opened ought to be closed using [`Page.close`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page/close). Pages left open could potentially distort the results of Web Vital metrics. | diff --git a/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/_index.md b/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/_index.md index 19f55be7d3..20bbae2cb9 100644 --- a/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/_index.md +++ b/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/_index.md @@ -17,7 +17,7 @@ If a [page](https://grafana.com/docs/k6//javascript-api/k6-experimen | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | [BrowserContext.addCookies()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/addcookies) | Adds [cookies](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/cookie) into the `BrowserContext`. | | [BrowserContext.clearCookies()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/clearcookies) | Clear the `BrowserContext`'s [cookies](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/cookie). | -| [BrowserContext.clearPermissions()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/clearpermissions) | Clears all permission overrides for the `BrowserContext`. | +| [BrowserContext.clearPermissions()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/clearpermissions) | Clears all permission overrides for the `BrowserContext`. | | [BrowserContext.cookies()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/cookies) | Returns a list of [cookies](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/cookie) from the `BrowserContext`. | | [BrowserContext.close()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/close) | Close the `BrowserContext` and all its [page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page)s. | | [BrowserContext.grantPermissions(permissions[, options])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/grantpermissions) | Grants specified permissions to the `BrowserContext`. | @@ -27,4 +27,4 @@ If a [page](https://grafana.com/docs/k6//javascript-api/k6-experimen | [BrowserContext.setDefaultTimeout(timeout)](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/setdefaulttimeout) | Sets the default maximum timeout for all methods accepting a timeout option in milliseconds. | | [BrowserContext.setGeolocation(geolocation)](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/setgeolocation) | Sets the `BrowserContext`'s geolocation. | | [BrowserContext.setOffline(offline)](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/setoffline) | Toggles the `BrowserContext`'s connectivity on/off. | -| [BrowserContext.waitForEvent(event[, optionsOrPredicate])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/waitforevent) | Waits for the event to fire and passes its value into the predicate function. | +| [BrowserContext.waitForEvent(event[, optionsOrPredicate])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext/waitforevent) | Waits for the event to fire and passes its value into the predicate function. | diff --git a/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/clearpermissions.md b/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/clearpermissions.md index c4f0b8e192..8c36aa6ec1 100644 --- a/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/clearpermissions.md +++ b/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/clearpermissions.md @@ -5,13 +5,6 @@ excerpt: 'Clears all permission overrides for the BrowserContext.' # clearPermissions() -{{% admonition type="caution" %}} - -This feature has known issues. -For details, refer to [issue #443](https://github.com/grafana/xk6-browser/issues/443). - - {{% /admonition %}} - Clears all permission overrides for the `BrowserContext`. ### Example diff --git a/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/waitforevent.md b/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/waitforevent.md index fead13c617..3723e5f02c 100644 --- a/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/waitforevent.md +++ b/docs/sources/next/javascript-api/k6-experimental/browser/browsercontext/waitforevent.md @@ -1,35 +1,70 @@ --- title: 'waitForEvent(event[, optionsOrPredicate])' -excerpt: 'Waits for event to fire and passes its value into the predicate function.' +excerpt: 'Waits for event to fire and returns its value.' --- -# waitForEvent(event[, optionsOrPredicate]) +Waits for the event to fire and returns its value. If a predicate function has been set it will pass the value to the predicate function, which must return `true` for the promise to resolve. -{{% admonition type="caution" %}} + -This method is a work in progress. -It requires async functionality and returning a `Promise` to be useful in scripts. -Refer to #447 for details. +| Parameter | Type | Default | Description | +|------------------------------|------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| event | string | `null` | Name of event to wait for. Currently the `'page'` event is the only one that is supported. | +| optionsOrPredicate | function\|object | `null` | Optional. If it's a function, the `'page'` event data will be passed to it and it must return `true` to continue. | +| optionsOrPredicate.predicate | function | `null` | Optional. Function that will be called when the `'page'` event is emitted. The event data will be passed to it and it must return `true` to continue. | +| optionsOrPredicate.timeout | number | `30000` | Optional. Maximum time to wait in milliseconds. | -Consider using the sync methods `Page.waitForNavigation()` and `Page.waitForSelector()` instead. + - {{% /admonition %}} +### Returns -Waits for the event to fire and passes its value into the predicate function. Returns the event data value when the predicate returns `true`. +| Type | Description | +|--------------------|-------------------------------------------------------------------------------------------------------| +| `Promise` | At the moment a [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) object is the only return value | - +### Example -| Parameter | Type | Default | Description | -| ---------------------------- | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| event | string | `null` | Name of event to wait for. **NOTE**: Currently this argument is disregarded, and `waitForEvent` will always wait for `'close'` or `'page'` events. | -| optionsOrPredicate | function\|object | `null` | Optional. If it's a function, the `'page'` event data will be passed to it and it must return `true` to continue. | -| optionsOrPredicate.predicate | function | `null` | Function that will be called when the `'page'` event is emitted. The event data will be passed to it and it must return `true` to continue. | -| optionsOrPredicate.timeout | number | `30000` | Maximum time to wait in milliseconds. Pass `0` to disable timeout. | + - +```javascript +import { browser } from 'k6/x/browser'; -### Returns +export const options = { + scenarios: { + browser: { + executor: 'shared-iterations', + options: { + browser: { + type: 'chromium', + }, + }, + }, + }, +} + +export default async function() { + const context = browser.newContext() + + // Call waitForEvent with a predicate which will return true once at least + // one page has been created. + let counter = 0 + const promise = context.waitForEvent("page", { predicate: page => { + if (++counter >= 1) { + return true + } + return false + } }) + + // Now we create a page. + const page = context.newPage() + + // Wait for the predicate to pass. + await promise + console.log('predicate passed') + + page.close() +}; + +``` -| Type | Description | -| ------ | ------------------------------------------------------------ | -| object | [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page/) object | + diff --git a/docs/sources/next/javascript-api/k6-experimental/browser/closecontext.md b/docs/sources/next/javascript-api/k6-experimental/browser/closecontext.md new file mode 100644 index 0000000000..bb4b11af44 --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/browser/closecontext.md @@ -0,0 +1,46 @@ +--- +title: 'closeContext()' +excerpt: 'Browser module: close context method' +--- + +Closes the current [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). If there is no active browser context, because none has been created yet or because it has been previously closed, this method throws an error. + + +### Example + +```javascript +import { browser } from 'k6/experimental/browser'; + +export const options = { + scenarios: { + browser: { + executor: 'shared-iterations', + options: { + browser: { + type: 'chromium', + }, + }, + }, + }, +} + +export default async function () { + const page1 = browser.newPage({ + isMobile: true, + }); // implicitly creates a new context + + await page1.goto('https:/test.k6.io/'); + page1.close(); + browser.closeContext(); // closes the context created on newPage + + const page2 = browser.newPage({ + isMobile: false, + }); // creates a new context with different settings + + await page2.goto('https://test.k6.io/'); + page2.close(); + browser.closeContext(); + + browser.closeContext(); // throws an error as browser has no active context +} +```