Skip to content

Commit b779df1

Browse files
inancgumusinancgumus
committed
Add scenarios notice in context limit
1 parent fa7a3cc commit b779df1

File tree

1 file changed

+274
-0
lines changed

1 file changed

+274
-0
lines changed

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

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
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).
8+
9+
The new version abstracts away the handling of the browser lifecycle and instead takes care of allocating and deallocating browser resources for you. To enable this, a newly required field is introduced to define the browser within the `scenario`.
10+
11+
Previously, users were responsible for establishing and shutting down the browser instance. However, with the current changes, the API has concealed the intricacies of `browserType`, and so the `chromium` named export has been removed from `k6/experimental/browser`, which has been replaced with `browser`.
12+
13+
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!
14+
15+
<Blockquote mod="note" title="">
16+
17+
Users no longer need to use the `K6_BROWSER_ENABLED` flag when running browser tests with the `k6` command.
18+
19+
</Blockquote>
20+
21+
22+
## Before and after comparison
23+
24+
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.
25+
26+
<CodeGroup labels={["Before: The previous k6 browser API"]} lineNumbers={[true]}>
27+
28+
```javascript
29+
import { chromium } from 'k6/experimental/browser';
30+
31+
export default async function () {
32+
const browser = chromium.launch({
33+
headless: false,
34+
timeout: '60s',
35+
});
36+
const page = browser.newPage();
37+
38+
try {
39+
await page.goto('https://test.k6.io/');
40+
page.screenshot({ path: 'screenshot.png' });
41+
} finally {
42+
page.close();
43+
browser.close();
44+
}
45+
}
46+
```
47+
48+
</CodeGroup>
49+
50+
<CodeGroup labels={["After: The new k6 browser API"]} lineNumbers={[true]}>
51+
52+
```javascript
53+
import { browser } from 'k6/experimental/browser';
54+
55+
export const options = {
56+
scenarios: {
57+
ui: {
58+
executor: 'shared-iterations',
59+
options: {
60+
browser: {
61+
type: 'chromium',
62+
},
63+
},
64+
},
65+
}
66+
}
67+
68+
export default async function () {
69+
const page = browser.newPage();
70+
71+
try {
72+
await page.goto('https://test.k6.io/');
73+
page.screenshot({ path: 'screenshot.png' });
74+
} finally {
75+
page.close();
76+
}
77+
}
78+
```
79+
80+
</CodeGroup>
81+
82+
83+
## Key changes
84+
85+
The updated version introduces notable structural changes in its operation and API. Let's take a look at them.
86+
87+
* The [import path](#import-path) for the browser module has switched from `chromium` to [browser](/javascript-api/k6-experimental/browser/#browser-module-api).
88+
* 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.
89+
* [Scenario options](#scenario-options) must now be defined for running browser tests.
90+
* [Simplified resource management](#simplified-resource-management). The browser module now handles the startup and shutdown of browser processes automatically. `browser.launch()`, `browser.connect()`, and `browser.close()` methods are no longer necessary, as these methods have been removed.
91+
* [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.
92+
93+
94+
95+
96+
## Import path
97+
98+
Changes have been made to how 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 relied on `chromium.launch()` for accessing the running browser. Now, a simple import of the [browser](/javascript-api/k6-experimental/browser/#browser-module-api) is sufficient.
99+
100+
<CodeGroup labels={["Before: Import Path"]} lineNumbers={[true]}>
101+
102+
```javascript
103+
import { chromium } from 'k6/experimental/browser';
104+
```
105+
106+
</CodeGroup>
107+
108+
<CodeGroup labels={["After: Import Path"]} lineNumbers={[true]}>
109+
110+
```javascript
111+
import { browser } from 'k6/experimental/browser';
112+
```
113+
114+
</CodeGroup>
115+
116+
117+
118+
119+
120+
## Browser options
121+
122+
In k6 v0.46.0, the need to manually start a browser via `browser.launch()` or `browser.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.
123+
124+
### Before:
125+
126+
<CodeGroup lineNumbers={[true]}>
127+
128+
<!-- eslint-skip -->
129+
130+
```javascript
131+
export default async function () {
132+
const browser = chromium.launch({
133+
headless: false,
134+
timeout: '60s',
135+
});
136+
}
137+
```
138+
139+
</CodeGroup>
140+
141+
### After:
142+
143+
<CodeGroup labels={["Bash", "Docker", "Windows: CMD", "Windows: PowerShell"]} lineNumbers={[false]}>
144+
145+
```bash
146+
$ K6_BROWSER_HEADLESS=false K6_BROWSER_TIMEOUT='60s' k6 run script.js
147+
```
148+
149+
```bash
150+
# When using the `k6:master-with-browser` Docker image, you need to add `--cap-add=SYS_ADMIN`
151+
# to grant further system permissions on the host for the Docker container.
152+
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
153+
```
154+
155+
```bash
156+
C:\k6> set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_TIMEOUT='60s' " && k6 run script.js
157+
```
158+
159+
```bash
160+
PS C:\k6> $env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_TIMEOUT='60s' ; k6 run script.js
161+
```
162+
163+
</CodeGroup>
164+
165+
166+
<Blockquote mod="note" title="">
167+
168+
The following browser options are no longer supported: `devtools`, `env`, and `proxy` since they weren't providing much value. `slowMo` has been removed for now, but we are working on adding it back in.
169+
170+
</Blockquote>
171+
172+
173+
174+
175+
## Scenario options
176+
177+
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.
178+
179+
180+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
181+
182+
<!-- eslint-skip -->
183+
184+
```javascript
185+
export const options = {
186+
scenarios: {
187+
ui: {
188+
executor: 'shared-iterations',
189+
options: {
190+
browser: {
191+
type: 'chromium',
192+
},
193+
},
194+
},
195+
}
196+
}
197+
```
198+
199+
</CodeGroup>
200+
201+
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.
202+
203+
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.
204+
205+
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.
206+
207+
208+
## Opening a new page
209+
210+
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.
211+
212+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
213+
214+
<!-- eslint-skip -->
215+
216+
```javascript
217+
export default async function () {
218+
const page = browser.newPage();
219+
// ...
220+
page.close();
221+
}
222+
```
223+
</CodeGroup>
224+
225+
<Blockquote mod="note" title="">
226+
227+
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.
228+
229+
</Blockquote>
230+
231+
232+
233+
234+
## Simplified resource management
235+
236+
As [mentioned earlier](#scenario-options), in the new API, there's a shift in how the browser's lifecycle is managed.
237+
238+
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.
239+
240+
<CodeGroup labels={["Before"]} lineNumbers={[true]}>
241+
242+
<!-- eslint-skip -->
243+
244+
```javascript
245+
page.close();
246+
browser.close();
247+
```
248+
249+
</CodeGroup>
250+
251+
<CodeGroup labels={["After"]} lineNumbers={[true]}>
252+
253+
<!-- eslint-skip -->
254+
255+
```javascript
256+
page.close();
257+
```
258+
259+
</CodeGroup>
260+
261+
262+
263+
264+
## Browser context limit
265+
266+
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.
267+
268+
Please click on the links below to see usage examples.
269+
270+
* 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.
271+
* 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.
272+
* 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/).
273+
274+
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)