Skip to content

Commit 376d2af

Browse files
inancgumusinancgumus
authored
Merge pull request #1292 from grafana/add/browser-v1-migration-guide
k6 browser v1 migration guide
2 parents 36a15be + d6c5aa2 commit 376d2af

File tree

1 file changed

+308
-0
lines changed

1 file changed

+308
-0
lines changed

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

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
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](#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)).
8+
9+
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).
10+
11+
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`.
12+
13+
<Blockquote mod="note" title="">
14+
15+
Users no longer need to use the `K6_BROWSER_ENABLED` flag when running browser tests with the `k6` command.
16+
17+
</Blockquote>
18+
19+
20+
## Before and after comparison
21+
22+
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.
23+
24+
<CodeGroup labels={["Before: The previous k6 browser API"]} lineNumbers={[true]}>
25+
26+
```javascript
27+
import { chromium } from 'k6/experimental/browser';
28+
29+
export default async function () {
30+
const browser = chromium.launch({
31+
headless: false,
32+
timeout: '60s',
33+
});
34+
const page = browser.newPage();
35+
36+
try {
37+
await page.goto('https://test.k6.io/');
38+
page.screenshot({ path: 'screenshot.png' });
39+
} finally {
40+
page.close();
41+
browser.close();
42+
}
43+
}
44+
```
45+
46+
</CodeGroup>
47+
48+
<CodeGroup labels={["After: The new k6 browser API"]} lineNumbers={[true]}>
49+
50+
```javascript
51+
import { browser } from 'k6/experimental/browser';
52+
53+
export const options = {
54+
scenarios: {
55+
ui: {
56+
executor: 'shared-iterations',
57+
options: {
58+
browser: {
59+
type: 'chromium',
60+
},
61+
},
62+
},
63+
}
64+
}
65+
66+
export default async function () {
67+
const page = browser.newPage();
68+
69+
try {
70+
await page.goto('https://test.k6.io/');
71+
page.screenshot({ path: 'screenshot.png' });
72+
} finally {
73+
page.close();
74+
}
75+
}
76+
```
77+
78+
</CodeGroup>
79+
80+
81+
## Key changes
82+
83+
The updated version introduces notable structural changes in its operation and API. Let's take a look at them.
84+
85+
* The [import path](#import-path) for the browser module has switched from `chromium` to [browser](/javascript-api/k6-experimental/browser/#browser-module-api).
86+
* [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.
87+
* [Scenario options](#scenario-options) must now be defined for running browser tests.
88+
* [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.
89+
* [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.
90+
91+
92+
93+
94+
## Import path
95+
96+
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.
97+
98+
<CodeGroup labels={["Before: Import Path"]} lineNumbers={[true]}>
99+
100+
```javascript
101+
import { chromium } from 'k6/experimental/browser';
102+
```
103+
104+
</CodeGroup>
105+
106+
<CodeGroup labels={["After: Import Path"]} lineNumbers={[true]}>
107+
108+
```javascript
109+
import { browser } from 'k6/experimental/browser';
110+
```
111+
112+
</CodeGroup>
113+
114+
115+
116+
117+
118+
## Browser options
119+
120+
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.
121+
122+
### Before:
123+
124+
<CodeGroup lineNumbers={[true]}>
125+
126+
<!-- eslint-skip -->
127+
128+
```javascript
129+
export default async function () {
130+
const browser = chromium.launch({
131+
headless: false,
132+
timeout: '60s',
133+
});
134+
}
135+
```
136+
137+
</CodeGroup>
138+
139+
### After:
140+
141+
<CodeGroup labels={["Bash", "Docker", "Windows: CMD", "Windows: PowerShell"]} lineNumbers={[false]}>
142+
143+
```bash
144+
$ K6_BROWSER_HEADLESS=false K6_BROWSER_TIMEOUT='60s' k6 run script.js
145+
```
146+
147+
```bash
148+
# When using the `k6:master-with-browser` Docker image, you need to add `--cap-add=SYS_ADMIN`
149+
# to grant further system permissions on the host for the Docker container.
150+
docker run --rm -i --cap-add=SYS_ADMIN -e K6_BROWSER_HEADLESS=false -e K6_BROWSER_TIMEOUT='60s' grafana/k6:master-with-browser run - <script.js
151+
```
152+
153+
```bash
154+
C:\k6> set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_TIMEOUT='60s' " && k6 run script.js
155+
```
156+
157+
```bash
158+
PS C:\k6> $env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_TIMEOUT='60s' ; k6 run script.js
159+
```
160+
161+
</CodeGroup>
162+
163+
164+
<Blockquote mod="note" title="">
165+
166+
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.
167+
168+
</Blockquote>
169+
170+
171+
172+
173+
## Scenario options
174+
175+
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.
176+
177+
178+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
179+
180+
<!-- eslint-skip -->
181+
182+
```javascript
183+
export const options = {
184+
scenarios: {
185+
ui: {
186+
executor: 'shared-iterations',
187+
options: {
188+
browser: {
189+
type: 'chromium',
190+
},
191+
},
192+
},
193+
}
194+
}
195+
```
196+
197+
</CodeGroup>
198+
199+
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.
200+
201+
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.
202+
203+
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.
204+
205+
206+
## Opening a new page
207+
208+
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.
209+
210+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
211+
212+
<!-- eslint-skip -->
213+
214+
```javascript
215+
export default async function () {
216+
const page = browser.newPage();
217+
// ...
218+
page.close();
219+
}
220+
```
221+
</CodeGroup>
222+
223+
<Blockquote mod="note" title="">
224+
225+
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.
226+
227+
</Blockquote>
228+
229+
230+
231+
232+
## Simplified resource management
233+
234+
As [mentioned earlier](#scenario-options), in the new API, there's a shift in how the browser's lifecycle is managed.
235+
236+
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.
237+
238+
<CodeGroup labels={["Before"]} lineNumbers={[true]}>
239+
240+
<!-- eslint-skip -->
241+
242+
```javascript
243+
page.close();
244+
browser.close();
245+
```
246+
247+
</CodeGroup>
248+
249+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
250+
251+
<!-- eslint-skip -->
252+
253+
```javascript
254+
page.close();
255+
```
256+
257+
</CodeGroup>
258+
259+
260+
261+
262+
## Browser context limit
263+
264+
The new browser implementation limits the usage to a single active [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) per iteration. This change enhances the prediction of resource requirements for a test run and promotes the use of [scenarios](/using-k6/scenarios/) to separate independent browser sessions.
265+
266+
* A new [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/) can be created either with the [browser.newContext()](/javascript-api/k6-experimental/browser/newcontext/) or [browser.newPage()](/javascript-api/k6-experimental/browser/newpage) methods.
267+
* 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.
268+
* Alongside these changes, the `browser.contexts()` method has been altered to [browser.context()](/javascript-api/k6-experimental/browser/context/) to retrieve the current [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/).
269+
270+
For instance, the code below will not function as intended, as it attempts to execute two simultaneous [BrowserContext](/javascript-api/k6-experimental/browser/browsercontext/)s within the same iteration.
271+
272+
<CodeGroup labels={["Incorrect usage"]} lineNumbers={[true]}>
273+
274+
<!-- eslint-skip -->
275+
276+
```javascript
277+
export default async function() {
278+
const context1 = browser.newContext();
279+
// Simultaneous browser contexts are not permitted!
280+
const context2 = browser.newContext();
281+
}
282+
```
283+
284+
</CodeGroup>
285+
286+
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.
287+
288+
<CodeGroup labels={["Correct usage"]} lineNumbers={[true]}>
289+
290+
<!-- eslint-skip -->
291+
292+
```javascript
293+
export default async function() {
294+
const context1 = browser.newContext();
295+
context1.close();
296+
297+
// Since the first browser context is closed, a new browser context can be created.
298+
const context2 = browser.newContext();
299+
context2.close()
300+
}
301+
```
302+
303+
</CodeGroup>
304+
305+
306+
These updates make the usage of our API more straightforward for users, aiding in more consistent and automatic resource management.
307+
308+
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!

0 commit comments

Comments
 (0)