Browser v2: Async APIs

[sniku]

Migrate to Async

Beta Give feedback

No tasks being tracked yet.

Nice to have

Beta Give feedback

1. Add async check helper jslib.k6.io#125
   3 of 4
   documentation-needed enhancement +2
   

Migration is complete - Document the changes

Beta Give feedback

No tasks being tracked yet.

Done Done

Beta Give feedback

1. Async API Rollout #1362
   10 of 10
   async +1
   
2. Migrate Frame APIs to async #1302
   7 of 7
   async breaking +2
   
3. Move Async API Handling to Mapping Layer #683
   async compatibility dx epic mapping next refactor +7
   
4. Helpers to streamline working with event loop #463
   async enhancement refactor tests +4
   
5. Async Click #439
   async feature +2
   
6. Async WaitForNavigation #440
   async feature +2
   
7. Async Tap #1251
   5 of 5
   async breaking +2
   
8. Async goto #583
   +0
9. Migrate Browser APIs to async #1294
   7 of 7
   async breaking +2
   
10. Migrate BrowserContext APIs to async #1295
    6 of 6
    async breaking browser context +3
    
11. Migrate ElementHandle APIs to async #1296
    7 of 7
    async breaking +2
    
12. Migrate JSHandle APIs to async #1303
    5 of 5
    async breaking +2
    
13. Migrate Keyboard APIs to async #1304
    6 of 6
    async breaking +2
    
14. Migrate Locator APIs to async #1305
    7 of 7
    async breaking +2
    
15. Migrate Mouse APIs to async #1306
    6 of 6
    async breaking +2
    
16. Migrate Page APIs to async #1307
    9 of 9
    async breaking +2
    
17. Migrate Request APIs to async #1308
    9 of 9
    async breaking +2
    
18. Migrate Response APIs to async #1309
    4 of 4
    async breaking +2
    
19. Precalculate the browser version information to prevent I/O calls #1359
    3 of 3
    enhancement +1
    
20. Add test helpers for async VU execution #1321
    async productivity refactor tests +4
    
21. Split mappings to prepare for async migration #1298
    async refactor +2
    
22. Browser: k6-browser v2.0.0 Migration Guide for the Async API k6-docs#1600
    2 of 2
    Area: browser +1
    

---

What

This issue has been repurposed to initiate and follow the progress of migrating most of the browser APIs to async (promise based).

A recent example is this issue where touchscreen.tap was migrated to async:

From:

page.touchscreen.tap(...);

To:

await page.touchscreen.tap(...);

Why

1. Most browser APIs use some form of long-running IO operation (networking) to perform the requested action on the web browser against the website under test. We need to avoid blocking JavaScript's runtime event loop for such operations.
2. We're going to add more asynchronous event-based APIs (such as page.on) that our current synchronous APIs would block.
3. To align with how developers expect to work with JavaScript APIs.
4. To have better compatibility with Playwright.

How

We have detailed exactly which APIs will most likely need to be migrated across in the comment within this issue. For most of the APIs we can take a look at the comment and migrate the APIs that are listed there. It's worth noting that it's still best to double check whether the API needs to be migrated especially ones which k6 browser implements but aren't provided by Playwright, for example page.throttleCPU.

NOT Implemented In PW

If an API is not implemented in PW, then you should be able to answer yes to one of the questions in the list below to determine whether it should be async or not, for example browser.context is not in PW, and it doesn't do any IO or long running tasks, therefore it can stay as a synchronous API.

1. Does the API perform a network call or other IO operations, this includes a CDP request to Chrome?
2. Does the API perform long running task?

Implemented in PW

Is the API in the list in this comment and is implemented in PW?

If the answer is yes, then it can be migrated to async.

Goja, docs and type defs

Initially we're only interested in moving the API to async, and not worrying about goja, doc and type definitions updates. Doc and type definition updates will be deferred to after the implementation work and before the release. We're hoping that the goja refactoring/abstraction work can also be shifted to a later point, but we may find that some APIs will also need goja to be refactored out of them to prevent panics and race conditions.

[ankur22]

It's worth noting that the browser module already has APIs (as of v0.51.0) that are already async:

• browserContext.waitForevent
• elementHandle.click
• elementHandle.tap
• frame.click
• frame.goto
• frame.tap
• frame.waitForFunction
• frame.waitForNavigation
• locator.click
• locator.tap
• page.click
• page.goto
• page.tap
• page.waitForFunction
• page.waitForNavigation

Even though we have these, the changes we are making will still affect all users and their scripts since APIs such as browser.newPage are required for all browser tests.

[ankur22]

Showcasing what to to expect when migrating your sync script to async with the fillform.js example:

NOTE: The changes required to work with check. Just like group, check doesn't work with async APIs.