Skip to content

Commit

Permalink
Merge pull request #1299 from grafana/chore/k6-browser-migration-guide
Browse files Browse the repository at this point in the history 
Updates to k6 browser migration guide
  • Loading branch information
@heitortsergent
heitortsergent authored Aug 17, 2023
2 parents 1be4116 + b6e3123 commit e86f4da
Showing 1 changed file with 38 additions and 74 deletions.
112 changes: 38 additions & 74 deletions ...a/markdown/translated-guides/en/03 Using k6 browser/04 Migrating to k6 v0-46.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,27 @@ excerpt: 'A migration guide to ease the process of transitioning to the new k6 b
slug: '/using-k6-browser/migrating-to-k6-v0-46/'
---

This guide outlines [the key changes](#key-changes) users will need to make when moving their existing k6 browser test scripts to the new browser module (bundled up with [k6 version 0.46](https://github.com/grafana/k6/releases/tag/v0.46.0)).
This guide outlines the key changes you will need to make when moving your existing k6 browser test scripts to the new [k6 browser module](/javascript-api/k6-experimental/browser/) (bundled with [k6 version 0.46](https://github.com/grafana/k6/releases/tag/v0.46.0)).

The latest release simplifies the management of the browser lifecycle by automatically providing and releasing browser resources for users. To facilitate this, a new mandatory field is introduced to define the browser type within [scenario options](#scenario-options).
## Key changes

The updated version introduces notable structural changes in its operation and API, including breaking changes:

Previously, users had to launch and close the browser processes themselves. With the recent updates, the API has abstracted the details of `browserType` (i.e., `chromium`). Consequently, the `chromium` named export, previously found in `k6/experimental/browser`, has been replaced with `browser`.
* The [import path](#import-path) for the browser module has switched from `chromium` to [`browser`](/javascript-api/k6-experimental/browser/#browser-module-api).
* [Simplified resource management](#simplified-resource-management). The browser module now handles the startup and shutdown of browser processes automatically. The `chromium.launch()`, `chromium.connect()`, and `browser.close()` methods are no longer necessary and have been removed.
* [Browser options](#browser-options) can now only be set using [environment variables](/javascript-api/k6-experimental/browser/#browser-module-options).
* [Scenario options](#scenario-options) must now be defined for running browser tests.
* [Single browser context per iteration](#browser-context-limit). You can now only run a single [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) at a time in the same iteration.

<Blockquote mod="note" title="">

Users no longer need to use the `K6_BROWSER_ENABLED` flag when running browser tests with the `k6` command.
You no longer need to use the `K6_BROWSER_ENABLED` flag when running browser tests with the `k6` command.

</Blockquote>


## Before and after comparison

Let's start with an overview of the primary differences between the previous and new versions of the k6 browser API. Subsequent sections will delve into each difference in detail.
Let's start with an overview of the main differences between the previous and new versions of the k6 browser API.

<CodeGroup labels={["Before: The previous k6 browser API"]} lineNumbers={[true]}>

Expand Down Expand Up @@ -77,23 +82,9 @@ export default async function () {

</CodeGroup>


## Key changes

The updated version introduces notable structural changes in its operation and API. Let's take a look at them.

* The [import path](#import-path) for the browser module has switched from `chromium` to [browser](/javascript-api/k6-experimental/browser/#browser-module-api).
* [Browser options](#browser-options) can now only be set using certain [environment variables](/javascript-api/k6-experimental/browser/#browser-module-options). The `launch()` method, used earlier for this purpose, has been removed.
* [Scenario options](#scenario-options) must now be defined for running browser tests.
* [Simplified resource management](#simplified-resource-management). The browser module now handles the startup and shutdown of browser processes automatically. `chromium.launch()`, `chromium.connect()`, and `browser.close()` methods are no longer necessary, as these methods have been removed.
* [Single browser context per iteration](#browser-context-limit). Users can now only run a single [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) at a time in the same iteration.




## Import path

Changes have been made to how the [browser module](/javascript-api/k6-experimental/browser/) is imported. With the browser type (specifically `chromium`) now set in [scenario options](#scenario-options), users should directly import the [browser](/javascript-api/k6-experimental/browser/#browser-module-api) object from the [browser module](/javascript-api/k6-experimental/browser/). Previously, users relied on `chromium.launch()` for accessing a running browser. Now, a simple import of the [browser](/javascript-api/k6-experimental/browser/#browser-module-api) is sufficient.
With the browser type (specifically `chromium`) now set in [scenario options](#scenario-options), you should directly import the [browser](/javascript-api/k6-experimental/browser/#browser-module-api) object from the [browser module](/javascript-api/k6-experimental/browser/).

<CodeGroup labels={["Before: Import Path"]} lineNumbers={[true]}>

Expand All @@ -111,15 +102,17 @@ import { browser } from 'k6/experimental/browser';

</CodeGroup>

## Simplified resource management

The browser lifecycle is now automatically managed by the browser module, and so the `chromium.launch()`, `chromium.connect()`, and `browser.close()` methods are no longer necessary and have been removed.


Now, all that is needed is to specify the `browser.type` within the [scenario options](#scenario-options). If the option is set, a browser instance will automatically start at the beginning and close at the end of each test iteration.

## Browser options

In k6 v0.46.0, the need to manually start a browser via `chromium.launch()` or `chromium.connect()` and set its configuration through these methods has been removed, so this part can simply be omitted from test scripts. Users can still change some browser settings by using environment variables. For more information, refer to the [browser module options](/javascript-api/k6-experimental/browser/#browser-module-options) documentation.
With the removal of the `chromium.launch()` and `chromium.connect()` methods, setting browsers options is now done by using environment variables. For more information, refer to [Browser Module Options](/javascript-api/k6-experimental/browser/#browser-module-options).

### Before:
Before:

<CodeGroup lineNumbers={[true]}>

Expand All @@ -136,7 +129,7 @@ export default async function () {

</CodeGroup>

### After:
After:

<CodeGroup labels={["Bash", "Docker", "Windows: CMD", "Windows: PowerShell"]} lineNumbers={[false]}>

Expand All @@ -160,20 +153,15 @@ PS C:\k6> $env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_TIMEOUT='60s' ; k6

</CodeGroup>


<Blockquote mod="note" title="">

The following browser options are no longer supported: `devtools`, `env`, and `proxy` since they weren't providing much value. Although `slowMo` has been temporarily removed, we're working on reintroducing it.
The following browser options are no longer supported: `devtools`, `env`, and `proxy` since they weren't providing much value. `slowMo` has been temporarily removed, and we're working on reintroducing it.

</Blockquote>




## Scenario options

In k6 v0.46.0, users must set the [executor](/using-k6/scenarios/executors/) and browser type as options in a [k6 scenario](/using-k6/scenarios/) definition. Specifically, the `browser.type` option should be set to `chromium`, as Chromium is the only browser supported.

You must now set the [executor](/using-k6/scenarios/executors/) and browser type as options in a [scenario](/using-k6/scenarios/) definition. Specifically, the `browser.type` option should be set to `chromium`, as Chromium is the only browser supported.

<CodeGroup labels={["After"]} lineNumbers={[true]}>

Expand All @@ -196,68 +184,45 @@ export const options = {

</CodeGroup>

Previously, users were required to handle the creation and closing of the browser instance using `chromium.launch()` or `chromium.connect()` for creation, and the `browser.close()` method for releasing resources before ending the iteration. This repetitive code has been eliminated.

Now, all that is needed is to specify the browser type within the [scenario options](#scenario-options). A browser instance will be automatically created and closed for each iteration by the browser module, streamlining the process.

This change allows to identify the test as a browser test and provides automatic control of the browser's lifecycle. Users no longer need to start or stop the browser manually through the browser API. If the `browser.type` option is set in the scenario options, a browser instance will automatically start at the beginning and close at the end of each test iteration.

## Opening and closing a page

## Opening a new page
You can open a new page by using the imported [browser](/javascript-api/k6-experimental/browser/#browser-module-api) object's [browser.newPage()](/javascript-api/k6-experimental/browser/newpage) method. You can still use the [Page](/javascript-api/k6-experimental/browser/page/) object as before.

Users can open a new page by using the imported [browser](/javascript-api/k6-experimental/browser/#browser-module-api) object's [browser.newPage()](/javascript-api/k6-experimental/browser/newpage) method. Users can still use the [Page](/javascript-api/k6-experimental/browser/page/) object as before.

<CodeGroup labels={["After"]} lineNumbers={[true]}>
<CodeGroup labels={["Before"]} lineNumbers={[true]}>

<!-- eslint-skip -->

```javascript
export default async function () {
const browser = chromium.launch();
const page = browser.newPage();
// ...
page.close();
browser.close();
}
```
</CodeGroup>

<Blockquote mod="note" title="">

Closing of the page is critical for the calculation of accurate Web Vital metrics. See the [browser metrics](/using-k6-browser/browser-metrics/) for more details.

</Blockquote>




## Simplified resource management

As [mentioned earlier](#scenario-options), in the new API, there's a shift in how the browser's lifecycle is managed.

Since the browser lifecycle is automatically managed by the browser module, the closing of the browser has been simplified. The explicit `browser.close()` call has been removed. Simply close the page using the [page.close()](/javascript-api/k6-experimental/browser/page/close/) method as in the example below.

<CodeGroup labels={["Before"]} lineNumbers={[true]}>

<!-- eslint-skip -->

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

</CodeGroup>

<CodeGroup labels={["After"]} lineNumbers={[true]}>

<!-- eslint-skip -->

```javascript
page.close();
export default async function () {
const page = browser.newPage();
// ...
page.close();
}
```

</CodeGroup>

The `browser.close()` method has been removed, so you can remove that from your scripts and use [`page.close()`](/javascript-api/k6-experimental/browser/page/close/) once you're done using the page object.

<Blockquote mod="note" title="">

Closing of the page is critical for the calculation of accurate Web Vital metrics. See the [browser metrics](/using-k6-browser/browser-metrics/) for more details.

</Blockquote>

## Browser context limit

Expand All @@ -283,7 +248,7 @@ export default async function() {

</CodeGroup>

On the other hand, the subsequent example will function correctly by closing the initial [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) prior to establishing a new one.
On the other hand, the next example will function correctly by closing the initial [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) prior to establishing a new one.

<CodeGroup labels={["Correct usage"]} lineNumbers={[true]}>

Expand All @@ -302,7 +267,6 @@ export default async function() {

</CodeGroup>

These updates make the usage of the API more straightforward for users, aiding in more consistent and automatic resource management.

These updates make the usage of our API more straightforward for users, aiding in more consistent and automatic resource management.

For all the details, make sure to review the complete changelog for [k6 version 0.46](https://github.com/grafana/k6/releases/tag/v0.46.0). For more information watch [k6 Office Hours #98](https://www.youtube.com/watch?v=fK6Hpvt0pY0), where we discuss the latest changes in k6 browser, and, as always, ask in [the community forum](https://community.grafana.com/c/grafana-k6/k6-browser/79) if you need our help!
For all the details, make sure to review the complete changelog for [k6 version 0.46](https://github.com/grafana/k6/releases/tag/v0.46.0). For more information watch [k6 Office Hours #98](https://www.youtube.com/watch?v=fK6Hpvt0pY0), where we discuss the latest changes in k6 browser, and, as always, ask in [the community forum](https://community.grafana.com/c/grafana-k6/k6-browser/79) if you need help!

0 comments on commit e86f4da

Please sign in to comment.