Move Async API Handling to Mapping Layer

[inancgumus]

This issue concerns an architectural redesign for the upcoming Async API and improving the k6 browser Async API to Goja mapping.

The problems this issue solves

• Provide an easy switch to the k6 browser Async API.
• Increase developer productivity by clearly separating the k6 browser code and Goja (updates #271).
• Unlock merging of k6 browser to k6 core: Mapping Async APIs.

POC

Here's a POC for this issue.

Sub issues

• Planning and experimentation
• Expose VU to the mapping layer #702
• Map [Page|Frame].Goto promises and fix tests #705
• Map [Page|ElementHandle|Frame|Locator].Click promises and fix tests #707
• Map [Page|Frame].WaitForNavigation promises and fix tests #706
• Map [Page|Frame].WaitForFunction promises and fix tests #708
• Map Browser.On promises and fix tests #709
• Remove await method from testBrowser #723

---

Mapping Async APIs

The current problem is that when a function returns a value in a promise, we can't map the returned value in the mapping layer.

So the missing piece of the puzzle is:

• Mapping the returned value
• Putting the value in a promise
• Returning it to Goja in the mapping layer.

These all should happen in the mapping layer to correctly map the Async methods.

Example

• page.goto(...) returns a promise.
• And the promise resolves to aresponse object.
• The response object has a frame() method.
• Frame has a query method that we want to map to the $ wildcard.

But we can't map the returned response.frame() method in the mapping layer because the response object is returned in a promise. We can't get the response object in the mapping layer until the promise is resolved (happening on the Goja side).

To understand it better, let's take a look at the following.

For example, the following code works: We use the query method to get the element.

page.goto('https://test.k6.io/', { waitUntil: 'networkidle' }).then(response => {
  ...
  const f = response.frame();
  const el = f.query('a[href="/my_messages.php"]')
  console.log(el.textContent());
  ...
});

However, the following code does not work:

page.goto('https://test.k6.io/', { waitUntil: 'networkidle' }).then(response => {
  ...
  const f = response.frame();
  const el = f.$('a[href="/my_messages.php"]') // <- notice the wildcard: $
  console.log(el.textContent());
  ...
});

Without maping the $ to the query method, the above code won't work. Notice that the above code uses $ to get the element.

Currently, we couldn't map the response.frame() in the mapping layer. So why we can't map the response.frame().$ to the response.frame().query? It's because the response.frame() function returns a promise, and we can't get the response object in the mapping layer until the promise is resolved.

// `page.Goto(...) *goja.Promise` returns a promise, and we can't get the
// `response` object from the mapping layer until the promise is resolved.
func mapPage(rt *goja.Runtime, p api.Page) mapping {
  maps := mapping{
    ...
    // p.Goto(...) *goja.Promise
    // There is no way to extract the value from the
    // promise here without being messy.
    "goto":         p.Goto,
    ...
  }
  ...
}

Solution

Instead of page.goto returning a promise, we can directly make it return a response object. And then, we can map the response.frame() method in the mapping layer.

That means we must move the promise returning/handling functionality to the mapping layer. This will be critical when we fully switch to the Async API. Since we also need it now, we can start moving the promise returning/handling functionality to the mapping layer.

Doing so will also help us separate the Goja logic from our core logic. The code and tests will be easier to maintain and work with. And we'll be ready for the incoming Async/Promise support (#428). I'll send a POC soon.

Related: #661

[inancgumus]

Done done done 🥳