fix(getByRole): name and exact (#18719 )

Following the `getByText()` and other methods:

- By default, matching is substring and case-insensitive. Before, it was
only case-insensitive, but not substring.
- With new option `exact: true`, matching is full string and
case-sensitive.
- Matching always normalizes whitespace.
- Codegen generates `exact: false` by default.
- `internal:role` treats `[name="foo"i]` as non-exact match.

Various fixes:
- Updated `getByRole` docs to match the reality.
- Locator generator edge cases.

2022-11-11 15:58:36 -08:00

5.8 KiB

Raw Blame History

class: FrameLocator

since: v1.17

FrameLocator represents a view to the iframe on the page. It captures the logic sufficient to retrieve the iframe and locate elements in that iframe. FrameLocator can be created with either [method: Page.frameLocator] or [method: Locator.frameLocator] method.

const locator = page.frameLocator('#my-frame').getByText('Submit');
await locator.click();

Locator locator = page.frameLocator("#my-frame").getByText("Submit");
locator.click();

locator = page.frame_locator("#my-frame").get_by_text("Submit")
await locator.click()

locator = page.frame_locator("my-frame").get_by_text("Submit")
locator.click()

var locator = page.FrameLocator("#my-frame").GetByText("Submit");
await locator.ClickAsync();

Strictness

Frame locators are strict. This means that all operations on frame locators will throw if more than one element matches a given selector.

// Throws if there are several frames in DOM:
await page.frameLocator('.result-frame').getByRole('button').click();

// Works because we explicitly tell locator to pick the first frame:
await page.frameLocator('.result-frame').first().getByRole('button').click();

# Throws if there are several frames in DOM:
await page.frame_locator('.result-frame').get_by_role('button').click()

# Works because we explicitly tell locator to pick the first frame:
await page.frame_locator('.result-frame').first.get_by_role('button').click()

# Throws if there are several frames in DOM:
page.frame_locator('.result-frame').get_by_role('button').click()

# Works because we explicitly tell locator to pick the first frame:
page.frame_locator('.result-frame').first.get_by_role('button').click()

// Throws if there are several frames in DOM:
page.frame_locator(".result-frame").getByRole("button").click();

// Works because we explicitly tell locator to pick the first frame:
page.frame_locator(".result-frame").first().getByRole("button").click();

// Throws if there are several frames in DOM:
await page.FrameLocator(".result-frame").GetByRole("button").ClickAsync();

// Works because we explicitly tell locator to pick the first frame:
await page.FrameLocator(".result-frame").First.getByRole("button").ClickAsync();

Converting Locator to FrameLocator

If you have a [Locator] object pointing to an iframe it can be converted to [FrameLocator] using :scope CSS selector:

const frameLocator = locator.frameLocator(':scope');

Locator frameLocator = locator.frameLocator(':scope');

frameLocator = locator.frame_locator(":scope")

frameLocator = locator.frame_locator(":scope")

var frameLocator = locator.FrameLocator(":scope");

method: FrameLocator.first

since: v1.17

returns: <[FrameLocator]>

Returns locator to the first matching frame.

method: FrameLocator.frameLocator

since: v1.17

returns: <[FrameLocator]>

When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.

param: FrameLocator.frameLocator.selector = %%-find-selector-%%

since: v1.17

method: FrameLocator.getByAltText

since: v1.27

returns: <[Locator]>

%%-template-locator-get-by-alt-text-%%

param: FrameLocator.getByAltText.text = %%-locator-get-by-text-text-%%

option: FrameLocator.getByAltText.exact = %%-locator-get-by-text-exact-%%

method: FrameLocator.getByLabel

since: v1.27

returns: <[Locator]>

%%-template-locator-get-by-label-text-%%

param: FrameLocator.getByLabel.text = %%-locator-get-by-text-text-%%

option: FrameLocator.getByLabel.exact = %%-locator-get-by-text-exact-%%

method: FrameLocator.getByPlaceholder

since: v1.27

returns: <[Locator]>

%%-template-locator-get-by-placeholder-text-%%

param: FrameLocator.getByPlaceholder.text = %%-locator-get-by-text-text-%%

option: FrameLocator.getByPlaceholder.exact = %%-locator-get-by-text-exact-%%

method: FrameLocator.getByRole

since: v1.27

returns: <[Locator]>

%%-template-locator-get-by-role-%%

param: FrameLocator.getByRole.role = %%-locator-get-by-role-role-%%

option: FrameLocator.getByRole.-inline- = %%-locator-get-by-role-option-list-v1.27-%%

since: v1.27

option: FrameLocator.getByRole.exact = %%-locator-get-by-role-option-exact-%%

method: FrameLocator.getByTestId

since: v1.27

returns: <[Locator]>

%%-template-locator-get-by-test-id-%%

param: FrameLocator.getByTestId.testId = %%-locator-get-by-test-id-test-id-%%

since: v1.27

method: FrameLocator.getByText

since: v1.27

returns: <[Locator]>

%%-template-locator-get-by-text-%%

param: FrameLocator.getByText.text = %%-locator-get-by-text-text-%%

option: FrameLocator.getByText.exact = %%-locator-get-by-text-exact-%%

method: FrameLocator.getByTitle

since: v1.27

returns: <[Locator]>

%%-template-locator-get-by-title-%%

param: FrameLocator.getByTitle.text = %%-locator-get-by-text-text-%%

option: FrameLocator.getByTitle.exact = %%-locator-get-by-text-exact-%%

method: FrameLocator.last

since: v1.17

returns: <[FrameLocator]>

Returns locator to the last matching frame.

method: FrameLocator.locator

since: v1.17

returns: <[Locator]>

%%-template-locator-locator-%%

param: FrameLocator.locator.selector = %%-find-selector-%%

since: v1.17

option: FrameLocator.locator.-inline- = %%-locator-options-list-v1.14-%%

since: v1.17

method: FrameLocator.nth

since: v1.17

returns: <[FrameLocator]>

Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.

param: FrameLocator.nth.index

since: v1.17

index <[int]>

5.8 KiB Raw Blame History