Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the BrowserType class in its own page and document the top level module properties on the landing page #788

Merged
merged 8 commits into from
Sep 8, 2022
Merged

Document the BrowserType class in its own page and document the top level module properties on the landing page #788

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
cabe871
Add locator under browser level APIs
ankur22 Sep 5, 2022
c7e2566
Add the BrowserType class docs back in
ankur22 Sep 5, 2022
b92884a
Apply suggestions from code review
ankur22 Sep 6, 2022
62cdb40
Remove the supported devices list
ankur22 Sep 6, 2022
4a94205
Add all the methods for BrowserType
ankur22 Sep 6, 2022
bba96df
Add how to run the example section
ankur22 Sep 6, 2022
b01db6f
Remove nested options
ankur22 Sep 7, 2022
cbdbfaa
Remove extra /
ankur22 Sep 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions src/data/markdown/docs/30 xk6-browser/01 xk6-browser/03 BrowserType.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: "BrowserType"
excerpt: "xk6-browser: BrowserType Class"
---

The `BrowserType` is the entry point into launching a browser process; `chromium` is currently the only supported `BrowserType`. To use it, import `chromium` from the top level module `k6/x/browser`.

| Method | Description |
|-----------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| browserType.connect([options]) <BWIPT id="17"/> | Connect attaches k6 browser to an existing browser instance. |
| [browserType.executablePath()](/javascript-api/xk6-browser/browsertype/executablepath/) | Returns the path where the extension expects to find the browser executable. |
| [browserType.launch([options])](/javascript-api/xk6-browser/browsertype/launch/) | Launches a new browser process. |
| browserType.launchPersistentContext(userDataDir, [options]) <BWIPT id="16"/> | Launches the browser with persistent storage. |
| [browserType.name()](/javascript-api/xk6-browser/browsertype/name/) | Returns the name of the `BrowserType`; currently it will return `chromium`. |


## Example

<CodeGroup labels={[]}>

<!-- eslint-skip -->

```javascript
import { chromium } from 'k6/x/browser';

export default function () {
const browser = chromium.launch();
const context = browser.newContext();
const page = context.newPage();

page.goto('http://whatsmyuseragent.org/');
page.screenshot({ path: `example-chromium.png` });

page.close();
browser.close();
}
```

</CodeGroup>

28 changes: 28 additions & 0 deletions ...ta/markdown/docs/30 xk6-browser/01 xk6-browser/03 BrowserType/executablePath.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: 'executablePath()'
excerpt: 'xk6-browser: BrowserType.executablePath method'
---

Returns the path where the extension expects to find the browser executable.


### Returns

| Type | Description |
|--------|--------------------------------------|
| string | The expected browser executable path |


## Example

<!-- eslint-skip -->

```javascript
import { chromium } from 'k6/x/browser';

export default function () {
const execPath = chromium.executablePath();
console.log(execPath);
...
}
```
59 changes: 59 additions & 0 deletions ...markdown/docs/30 xk6-browser/01 xk6-browser/03 BrowserType/launch--options--.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: 'launch([options])'
excerpt: 'xk6-browser: BrowserType.launch method'
---

Launches a new browser process.

| Parameter | Type | Default | Description |
|-------------------|----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| args | string[] | `null` | Extra command line arguments to include when launching browser process. See [this link](https://peter.sh/experiments/chromium-command-line-switches/) for a list of Chromium arguments. Note that arguments should not start with `--` (see the [example](#example)). |
| debug | boolean | `false` | All CDP messages and internal fine grained logs will be logged if set to `true`. |
| devtools | boolean | `false` | Open up developer tools in the browser by default. |
| env | string[] | `null` | Environment variables to set before launching browser process. |
| executablePath | string | `null` | Override search for browser executable in favor of specified absolute path. |
| headless | boolean | `true` | Show browser GUI or not. |
| ignoreDefaultArgs | string[] | `null` | Ignore any of the default arguments included when launching browser process. |
| proxy | string | `null` | Specify to set browser's proxy configuration. |
| slowMo | string | `null` | Slow down input actions and navigation by the specified time e.g. `'500ms'`. |
| timeout | string | `'30s'` | Default timeout to use for various actions and navigation. |


### Returns

| Type | Description |
|--------|--------------------------------------------------------|
| object | [Browser](/javascript-api/xk6-browser/browser/) object |


## Example

<CodeGroup labels={[]}>

<!-- eslint-skip -->

```javascript
import { chromium } from 'k6/x/browser';

export default function () {
const browser = chromium.launch({
args: ['show-property-changed-rects'],
debug: true,
devtools: true,
executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
headless: false,
slowMo: '500ms',
timeout: '30s',
});
const context = browser.newContext();
const page = context.newPage();

page.goto('http://whatsmyuseragent.org/');
page.screenshot({ path: `example-chromium.png` });

page.close();
browser.close();
}
```

</CodeGroup>
28 changes: 28 additions & 0 deletions src/data/markdown/docs/30 xk6-browser/01 xk6-browser/03 BrowserType/name.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: 'name()'
excerpt: 'xk6-browser: BrowserType.name method'
---

Returns the name of the `BrowserType`; currently it will return `chromium`.


### Returns

| Type | Description |
|--------|------------------------------|
| string | Currently returns `chromium` |


## Example

<!-- eslint-skip -->

```javascript
import { chromium } from 'k6/x/browser';

export default function () {
const name = chromium.name();
console.log(name);
...
}
```
0 ...owser/01 xk6-browser/03-element-handle.md → ...owser/01 xk6-browser/04-element-handle.md
View file
Open in desktop
File renamed without changes.
0 ...30 xk6-browser/01 xk6-browser/04-frame.md → ...30 xk6-browser/01 xk6-browser/05-frame.md
View file
Open in desktop
File renamed without changes.
0 ...k6-browser/01 xk6-browser/05-js-handle.md → ...k6-browser/01 xk6-browser/06-js-handle.md
View file
Open in desktop
File renamed without changes.
0 ...xk6-browser/01 xk6-browser/06-keyboard.md → ...xk6-browser/01 xk6-browser/08-keyboard.md
View file
Open in desktop
File renamed without changes.
0 ...30 xk6-browser/01 xk6-browser/08-mouse.md → ...30 xk6-browser/01 xk6-browser/09-mouse.md
View file
Open in desktop
File renamed without changes.
0 .../30 xk6-browser/01 xk6-browser/09-page.md → .../30 xk6-browser/01 xk6-browser/10-page.md
View file
Open in desktop
File renamed without changes.
0 ... xk6-browser/01 xk6-browser/10-request.md → ... xk6-browser/01 xk6-browser/11-request.md
View file
Open in desktop
File renamed without changes.
0 ...xk6-browser/01 xk6-browser/11-response.md → ...xk6-browser/01 xk6-browser/12-response.md
View file
Open in desktop
File renamed without changes.
0 ...-browser/01 xk6-browser/12-touchscreen.md → ...-browser/01 xk6-browser/13-touchscreen.md
View file
Open in desktop
File renamed without changes.
80 changes: 51 additions & 29 deletions src/data/markdown/docs/30 xk6-browser/30 xk6-browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,29 +19,9 @@ If you're more adventurous or want to get the latest changes of the xk6-browser

<InstallationInstructions extensionUrl="github.com/grafana/xk6-browser"/>

## Launch Chromium

The first step is to launch a `chromium` [Browser](/javascript-api/xk6-browser/browser) (which is currently the only available browser type). After the browser starts, you can interact with it using the [browser-level APIs](#browser-level-apis).

| Method | Description |
|----------------------------|----------------------------------------------------------------------------------|
| chromium | Import module from `'k6/x/browser'` |
| chromium.launch([options]) | You can see a list of all possible `options` in [the options heading](#options). |

### Options

| Method | Type | Default | Description |
|-------------------|----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| args | string[] | `null` | Extra command line arguments to include when launching browser process. See [this link](https://peter.sh/experiments/chromium-command-line-switches/) for a list of Chromium arguments. Note that arguments should not start with `--` (see the [example](#example)). |
| debug | boolean | `false` | All CDP messages and internal fine grained logs will be logged if set to `true`. |
| devtools | boolean | `false` | Open up developer tools in the browser by default. |
| env | string[] | `null` | Environment variables to set before launching browser process. |
| executablePath | string | `null` | Override search for browser executable in favor of specified absolute path. |
| headless | boolean | `true` | Show browser GUI or not. |
| ignoreDefaultArgs | string[] | `null` | Ignore any of the default arguments included when launching browser process. |
| proxy | string | `null` | Specify to set browser's proxy config. |
| slowMo | string | `null` | Slow down input actions and navigation by the specified time e.g. `'500ms'`. |
| timeout | string | `'30s'` | Default timeout to use for various actions and navigation. |
## Your First Test

The first step is to import the `chromium` [BrowserType](/javascript-api/xk6-browser/browsertype), and use its `launch` method to start up a Chromium [Browser](/javascript-api/xk6-browser/browser) process (which is currently the only available `BrowserType`). After it starts, you can interact with it using the [browser-level APIs](#browser-level-apis).

### Example

Expand All @@ -54,18 +34,13 @@ import { chromium } from 'k6/x/browser';

export default function () {
const browser = chromium.launch({
args: ['show-property-changed-rects'],
debug: true,
devtools: true,
executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
headless: false,
slowMo: '500ms',
timeout: '30s',
});

const context = browser.newContext();
const page = context.newPage();
page.goto('http://whatsmyuseragent.org/');
page.goto('https://test.k6.io/browser.php/');
page.screenshot({ path: `example-chromium.png` });

page.close();
Expand All @@ -75,6 +50,51 @@ export default function () {

</CodeGroup>

### Running the Example Test

If you have downloaded the pre-built binary you will find the binary named `xk6-browser`. Using the [example](#example), create a new file (such as `browser_test.js`) in the same directory as the pre-built binary, and paste the example in that file. Now run:

```
xk6-browser run browser_test.js
```

## Module Properties

Listed in the table are the importable properties from the top level module (`'k6/x/browser'`).

| Property | Description |
|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chromium | A [BrowserType](/javascript-api/xk6-browser/browsertype) to launch tests in a Chromium-based browser. |
| devices | Returns predefined emulation settings for many end-user devices that can be used to simulate browser behavior on a mobile device. See the [devices example](#devices-example) below. |
| version | Returns the version number of xk6-browser. |

### Devices Example

<CodeGroup labels={[]}>

<!-- eslint-skip -->

```javascript
import { chromium, devices } from 'k6/x/browser';

export default function () {
const browser = chromium.launch({ headless: false });
const iphoneX = devices['iPhone X'];
const context = browser.newContext(iphoneX);
const page = context.newPage();

page.goto('https://test.k6.io/browser.php/', {
waitUntil: 'networkidle',
});
ankur22 marked this conversation as resolved.
Show resolved Hide resolved

page.close();
browser.close();
}
```

</CodeGroup>


## Browser-level APIs

`xk6-browser` uses [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP) to instrument and interact with the browser. The `xk6-browser` APIs aims for rough compatibility with the [Playwright API for NodeJS](https://playwright.dev/docs/api/class-playwright).
Expand All @@ -85,10 +105,12 @@ Note that because k6 does not run in NodeJS, `xk6-browser` APIs will slightly di
|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Browser](/javascript-api/xk6-browser/browser/) <BWIPT /> | The entry point for all tests and used to launch [BrowserContext](/javascript-api/xk6-browser/browsercontext/)s and [Page](/javascript-api/xk6-browser/page/)s. |
| [BrowserContext](/javascript-api/xk6-browser/browsercontext/) <BWIPT /> | Enables independent browser sessions with separate [Page](/javascript-api/xk6-browser/page/)s, cache, and cookies. |
| [BrowserType](/javascript-api/xk6-browser/browsertype/) | The `BrowserType` is the entry point into launching a browser process; `chromium` is currently the only supported `BrowserType`. |
| [ElementHandle](/javascript-api/xk6-browser/elementhandle/) <BWIPT /> | Represents an in-page DOM element. |
| [Frame](/javascript-api/xk6-browser/frame/) <BWIPT /> | Access and interact with the [`Page`](/javascript-api/xk6-browser/page/).'s `Frame`s. |
| [JSHandle](/javascript-api/xk6-browser/jshandle) | Represents an in-page JavaScript object. |
| [Keyboard](/javascript-api/xk6-browser/keyboard/) | Used to simulate the keyboard interactions with the associated [`Page`](/javascript-api/xk6-browser/page/). |
| [Locator](/javascript-api/xk6-browser/locator/) | The Locator API makes it easier to work with dynamically changing elements. |
| [Mouse](/javascript-api/xk6-browser/mouse/) | Used to simulate the mouse interactions with the associated [`Page`](/javascript-api/xk6-browser/page/). |
| [Page](/javascript-api/xk6-browser/page/) <BWIPT /> | Provides methods to interact with a single tab in a [`Browser`](/javascript-api/xk6-browser/browser/). |
| [Request](/javascript-api/xk6-browser/request/) <BWIPT /> | Used to keep track of the request the [`Page`](/javascript-api/xk6-browser/page/) makes. |
Expand Down