Skip to content

Commit 8365ae5

Browse files
inancgumusinancgumus
committed
Add k6 browser migration guide for k6 v0.46
1 parent 5921afb commit 8365ae5

File tree

1 file changed

+249
-0
lines changed

1 file changed

+249
-0
lines changed

‎src/data/markdown/translated-guides/en/03 Using k6 browser/04 Migrating to k6 v0-46.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
---
2+
title: 'Migrating to k6 v0.46'
3+
excerpt: 'A migration guide to ease the process of transitioning to the new k6 browser module version'
4+
slug: '/using-k6-browser/migrating-to-k6-v0-46/'
5+
---
6+
7+
This guide outlines the key changes users will need to make when moving their existing k6 browser test scripts to the new browser module (bundled up with the k6 version 0.46). The updated version makes the browser module easier to use, with structural changes that reduce the need for manual setup, enhance scenario definitions, and make the code more straightforward.
8+
9+
For all the details, check the complete changelog for the [k6 version 0.46](https://github.com/grafana/k6/releases/tag/v0.46.0).
10+
11+
<Blockquote mod="note" title="">
12+
13+
Users no longer need to use the `K6_BROWSER_ENABLED` flag when running browser tests with the `k6` command.
14+
15+
</Blockquote>
16+
17+
18+
## Key Changes in the New API
19+
20+
The updated k6 browser API introduces notable structural changes in its operation and API.
21+
22+
* [Scenario options](#scenario-options) must now be defined for running browser tests.
23+
* The [import path](#import-path) for the browser module has switched from `chromium` to [browser](/javascript-api/k6-experimental/browser/#browser-module-api).
24+
* 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.
25+
* [Simplified resource management](#simplified-resource-management). The browser now starts automatically, managed by the browser module itself. There's no need to use `browser.close()` anymore.
26+
* [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.
27+
28+
29+
30+
## Before and after comparison
31+
32+
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.
33+
34+
<CodeGroup labels={["Before: The previous k6 browser API"]} lineNumbers={[true]}>
35+
36+
```javascript
37+
import { chromium } from 'k6/experimental/browser';
38+
39+
export default async function () {
40+
const browser = chromium.launch({
41+
headless: false,
42+
timeout: '60s',
43+
});
44+
const page = browser.newPage();
45+
46+
try {
47+
await page.goto('https://test.k6.io/');
48+
page.screenshot({ path: 'screenshot.png' });
49+
} finally {
50+
page.close();
51+
browser.close();
52+
}
53+
}
54+
```
55+
56+
</CodeGroup>
57+
58+
<CodeGroup labels={["After: The new k6 browser API"]} lineNumbers={[true]}>
59+
60+
```javascript
61+
import { browser } from 'k6/experimental/browser';
62+
63+
export const options = {
64+
scenarios: {
65+
ui: {
66+
executor: 'shared-iterations',
67+
options: {
68+
browser: {
69+
type: 'chromium',
70+
},
71+
},
72+
},
73+
},
74+
thresholds: {
75+
checks: ["rate==1.0"]
76+
}
77+
}
78+
79+
export default async function () {
80+
const page = browser.newPage();
81+
82+
try {
83+
await page.goto('https://test.k6.io/');
84+
page.screenshot({ path: 'screenshot.png' });
85+
} finally {
86+
page.close();
87+
}
88+
}
89+
```
90+
91+
</CodeGroup>
92+
93+
94+
95+
96+
97+
## Import Path
98+
99+
Changes have been made to the way the [browser module](/javascript-api/k6-experimental/browser/) is imported. With the browser type (i.e., `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/). In the past, users would rely on `chromium.launch()` for accessing the running browser. Now, a simple import of the [browser](/javascript-api/k6-experimental/browser/#browser-module-api) sufficient.
100+
101+
<CodeGroup labels={["Before: Import Path"]} lineNumbers={[true]}>
102+
103+
```javascript
104+
import { chromium } from 'k6/experimental/browser';
105+
```
106+
107+
</CodeGroup>
108+
109+
<CodeGroup labels={["After: Import Path"]} lineNumbers={[true]}>
110+
111+
```javascript
112+
import { browser } from 'k6/experimental/browser';
113+
```
114+
115+
</CodeGroup>
116+
117+
118+
119+
120+
121+
## Browser options
122+
123+
In the updated version, the need to manually start a browser and set its configuration has been removed, and this part can simply be omitted from test scripts.
124+
125+
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.
126+
127+
128+
<CodeGroup labels={["Before"]} lineNumbers={[true]}>
129+
130+
<!-- eslint-skip -->
131+
132+
```javascript
133+
export default async function () {
134+
const browser = chromium.launch({
135+
headless: false,
136+
timeout: '60s',
137+
});
138+
}
139+
```
140+
141+
</CodeGroup>
142+
143+
<Blockquote mod="note" title="">
144+
145+
The following browser options are no longer supported: `slowMo`, `devtools`, `env`, and `proxy`.
146+
147+
</Blockquote>
148+
149+
150+
151+
152+
## Scenario options
153+
154+
In the new update, users must set the browser type as an option 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.
155+
156+
This change helps identify the test as a browser test and allows 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 be automatically started at the beginning and closed at the end of each test iteration.
157+
158+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
159+
160+
<!-- eslint-skip -->
161+
162+
```javascript
163+
export const options = {
164+
scenarios: {
165+
ui: {
166+
executor: 'shared-iterations',
167+
options: {
168+
browser: {
169+
type: 'chromium',
170+
},
171+
},
172+
},
173+
},
174+
thresholds: {
175+
checks: ["rate==1.0"]
176+
}
177+
}
178+
```
179+
180+
</CodeGroup>
181+
182+
183+
184+
185+
## Opening a new page
186+
187+
You can open a new page by using the imported [browser](/javascript-api/k6-experimental/browser/#browser-module-api) object.
188+
189+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
190+
191+
<!-- eslint-skip -->
192+
193+
```javascript
194+
export default async function () {
195+
const page = browser.newPage();
196+
// ...
197+
page.close();
198+
}
199+
```
200+
</CodeGroup>
201+
202+
<Blockquote mod="note" title="">
203+
204+
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.
205+
206+
</Blockquote>
207+
208+
209+
210+
211+
## Simplified resource management
212+
213+
As [mentioned earlier](#scenario-options), in the new API, there's a shift in how the browser's lifecycle is managed. Previously, users were required to handle the creation and closing of the browser instance using methods like `chromium.launch()` and `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, streamlining the process.
214+
215+
Since the browser lifecycle is automaticaly 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.
216+
217+
<CodeGroup labels={["Before"]} lineNumbers={[true]}>
218+
219+
<!-- eslint-skip -->
220+
221+
```javascript
222+
page.close();
223+
browser.close();
224+
```
225+
226+
</CodeGroup>
227+
228+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
229+
230+
<!-- eslint-skip -->
231+
232+
```javascript
233+
page.close();
234+
```
235+
236+
</CodeGroup>
237+
238+
239+
240+
241+
## Browser context limit
242+
243+
Since the browser lifecycle is now being managed by the [browser module](/javascript-api/k6-experimental/browser/), the new browser implementation limits the use to a single active [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) per iteration. This change supports better prediction of resource requirements for a test run and allows for more controlled management of [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/)s.
244+
245+
If a new [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) needs to be created, the existing one must be closed first using the [browserContext.close()](/javascript-api/k6-experimental/browser/browsercontext/close) method. And, a new one can be created either with the [browser.newContext()](/javascript-api/k6-experimental/browser/newcontext/) or [browser.newPage()](/javascript-api/k6-experimental/browser/newpage) methods.
246+
247+
Alongside these changes, the method `browser.contexts()` has been altered to [browser.context()](/javascript-api/k6-experimental/browser/context/) to retrieve the current [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/).
248+
249+
These updates make the usage of our API more straightforward for users, aiding in more consistent and automatic resource management.

0 commit comments

Comments
 (0)