robingustafsson commented 2 years ago

We started the development of the first version on May 16th.

Strict forwarders (milestone: v0.7.0)

[x] #660

Strict forwarders (milestone: v0.4.0)

The locator methods that forward calls to the Frame methods with the strict mode on (meaning: only select a single element).

[x] #308
[x] #334
[x] #311
[x] #331
[x] #359
[x] #346
[x] #348
[x] #349
[x] #347
[x] #351
[x] #350
[x] #338
[x] #339
[x] #341
[x] #343
[x] #344
[x] #357
[x] #345
[x] #353
[x] #352
[x] #358
[x] #356
[x] #342
[x] #335
[x] #360

Just-in-time element finder methods

The locator methods wrap around existing ElementHandle methods. For example:

// locator method
async evaluate<R, Arg>(pageFunction: structs.PageFunctionOn, arg?: Arg, options?: TimeoutOptions): Promise<R> {
  return this._withElement(h => h.evaluate(pageFunction, arg), options?.timeout);
}

// wrapped method (jsHandle.ts)
async evaluate<R, Arg>(pageFunction: structs.PageFunctionOn, arg?: Arg): Promise < R > { ... }

_withElement queries the element using waitForSelector in the current frame and returns a disposed element handle:

  private async _withElement<R>(task: (handle: ElementHandle<SVGElement | HTMLElement>, timeout?: number) => Promise<R>, timeout?: number): Promise<R> {
    timeout = this._frame.page()._timeoutSettings.timeout({ timeout });
    const deadline = timeout ? monotonicTime() + timeout : 0;

    return this._frame._wrapApiCall<R>(async () => {
      const result = await this._frame._channel.waitForSelector({ selector: this._selector, strict: true, state: 'attached', timeout });
      const handle = ElementHandle.fromNullable(result.element) as ElementHandle<SVGElement | HTMLElement> | null;
      if (!handle)
        throw new Error(`Could not resolve ${this._selector} to DOM Element`);
      try {
        return await task(handle, deadline ? deadline - monotonicTime() : 0);
      } finally {
        await handle.dispose();
      }
    });
  }

Locator-specific methods

Allows users to move between the selected element.

[ ] #956
[ ] locator.page()
[ ] page.frameLocator(selector) — creates a new locator for a frame (usually for iframes)
[ ] locator.first()
[ ] locator.last()
[ ] locator.nth(index)
[ ] locator.count()
[ ] locator.allInnerTexts()
[ ] locator.allTextContents()
[ ] locator.elementHandles()
[ ] locator.evaluateAll(pageFunction[, arg])
[ ] #340
[ ] #337

Blocked (milestone: unknown)

[ ] #355 — Blocked 🚨
[ ] #336 — Blocked 🚨
[ ] #361 — Blocked 🚨
[ ] #354 — Blocked 🚨

Explanation

Add support for Locator, a way to capture a pointer to DOM element(s) without attaching to an actual DOM node as ElementHandle does. Sort of a just-in-time version of querying the DOM and getting an ElementHandle back to do actions on.

Relevant links:

Playwright docs: https://playwright.dev/docs/api/class-locator and https://playwright.dev/docs/api/class-page#page-locator

Below are the May 11th, 2022, findings for this feature.

Summary

The whole idea of locators is that you can carry on selectors with you—without dealing with actual elements. Locators enable the Page Object Model for reducing code duplication and improving test maintenance.

A locator is created with a selector for a specific frame. When you invoke one of the Locator methods, they query the frame and run the action. Since they query the frame, each call can resolve to a different DOM element.

Benefits:

Allows enabling working with dynamic web pages and SPAs like Swelte, React, Vue, etc.
Allows creating a Page Object Model (POM).
POM reduces code duplication.
POM improves test maintenance.

Good explanation of the strict mode and locators API:

Key knowledge

Each locator belongs to a single frame.
Every time locator is used for some action, an up-to-date DOM element is located on the page.
Locator is resolved to the element immediately before acting, so a series of actions on the same locator can be performed on different DOM elements. What would happen if the DOM structure between those actions changed.
PW recommends using ElementHandle in rare cases when you need to perform extensive DOM traversal on a static page. For all user actions and assertions, PW recommends using a locator instead.
The difference between the Locator and ElementHandle is that the latter points to a particular element, while Locator captures the logic of how to retrieve that element.
Locators are strict. All operations on locators that imply some target DOM element will throw an exception if more than one element matches the given selector.
In lazy-loaded pages, it can be useful to wait until an element is visible with locator.waitFor([options]).

inancgumus commented 2 years ago

I checked out the Playwright Locator API and its underlying code. It seems like we need to do this for every ElementHandle action, etc. It looks involved.

Maybe we should separate this issue into sub-issues and handle the main issue together?

Could you also check out the PW docs and tell me WDYT, @imiric?

imiric commented 2 years ago

Yeah, this seems more involved than I originally thought. We should definitely split it up somehow. Let's discuss it tomorrow.

We don't have to finish everything for v0.3.0, and we likely won't have time to, but we can release it gradually. It should be easier once we lay the groundwork and start ticking off each method.

inancgumus commented 2 years ago

My findings on this feature are in the description. I'll start working on this next week as there is some stuff that I'm trying to figure out.

inancgumus commented 2 years ago

TODO

I'm noticing a lot of repetitions.

I'll refactor this out after we upgrade to Go 1.18 (#279) and use generics/interface somehow (depending on which one is clearer).
~Additionally, I will rename strict_link.html to locator.html when I'm done.~

grafana / xk6-browser

Locator API #100

Strict forwarders (milestone: v0.7.0)

Strict forwarders (milestone: v0.4.0)

Just-in-time element finder methods

Locator-specific methods

Blocked (milestone: unknown)

Explanation

Summary

Key knowledge