Add getByRole in the browser module #4843

ankur22 · 2025-06-09T21:23:32Z

What?

This PR adds a long awaited feature which is page.getByRole. It makes working with selectors slightly simpler. More getBy* APIs are in the works.

Why?

It is a lot simpler to work with getByRole instead of XPath or CSS selectors in most cases.

Checklist

I have performed a self-review of my code.
I have commented on my code, particularly in hard-to-understand areas.
I have added tests for my changes.
I have run linter and tests locally (make check) and all pass.

Checklist: Documentation (only for k6 maintainers and if relevant)

Please do not merge this PR until the following items are filled out.

I have added the correct milestone and labels to the PR.
I have updated the release notes: link
I have updated or added an issue to the k6-documentation: grafana/k6-docs#NUMBER if applicable
I have updated or added an issue to the TypeScript definitions: grafana/k6-DefinitelyTyped#NUMBER if applicable

Related PR(s)/Issue(s)

#4764
#4320
#4248

ankur22 · 2025-06-09T21:24:28Z

internal/js/modules/k6/browser/common/js/injected_script.js

@@ -14,6 +14,1259 @@
 * limitations under the License.


The main implementation is in the injected_script.js file. The code was directly copied over from the compiled JS code from Playwright. I have added as many integration tests as possible to ensure that all the possible flows are accounted for. While i understand the jist of what is happening in the copied code, some of it is still a bit of a mystery as to why things are done this way. A lot of the code seems to be inherited behaviour from specifications, such as not being able to work with header or footer unless they're not encapsulated -- exact spec is unknown though.

Do we need to add the Playwright license and notice file in the browser module?

I don't think we need to add another license note, as we already have this one:

k6/internal/js/modules/k6/browser/common/js/injected_script.js

Lines 1 to 15 in 113abf5

/**

* Copyright (c) Microsoft Corporation.

*

* Licensed under the Apache License, Version 2.0 (the "License");

* you may not use this file except in compliance with the License.

* You may obtain a copy of the License at

*

* http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

ankur22 · 2025-06-09T21:34:01Z

internal/js/modules/k6/browser/common/js/injected_script.js

@@ -225,6 +1478,7 @@ class InjectedScript {
      css: new CSSQueryEngine(),
      text: new TextQueryEngine(),
      xpath: new XPathQueryEngine(),
+      'internal:role': createRoleEngine(true),


Sticking with how Playwright has labelled it. There is also a selector without internal which we could consider adding. It is so that users can query without the getByRole API, and directly do something like: page.locator('role=button');.

Yeah, I think that would be nice, specially because I think internal:role is particular to Playwright, while the other looks more like "the standard"?

Is there any reason why not doing so on this PR?
Does it require any changes beyond also adding that pair of keyword and engine? 🤔

Is there any reason why not doing so on this PR?

Mainly because I wanted to narrow the focus to working with the dedicated APIs that we have implemented getByRole instead of allowing for the manual creation of role selectors. It can get quite complicated to manually create a role selector with options. So it's an ease of use thing mainly.

Does it require any changes beyond also adding that pair of keyword and engine? 🤔

That's basically it, add another case for role without internal:.

I'd like to see how this is used and whether users ask us to open up to a manual way of writing role selectors.

ankur22 · 2025-06-10T11:24:21Z

internal/js/modules/k6/browser/tests/get_by_test.go

@@ -0,0 +1,775 @@
+package tests


Tests are failing on Windows for an unknown reason. I can run the same test in a script file and it works on Windows. I'm looking into it 😕

WINDOWS! WHY ART THOU SO ANNOYING! I WANT TO LOVE YOU BUT I CAN'T 😭

I tried to run some other tests which work with page.locator and they don't work! These tests are in keyboard_test.go, and at the top of the file there is this comment:

// practically none of this work on windows //go:build !windows

I will do the same for the new tests 😢

joanlopez · 2025-06-16T09:04:34Z

internal/js/modules/k6/browser/common/frame.go

@@ -1002,6 +1002,58 @@ func (f *Frame) getAttribute(selector, name string, opts *FrameBaseOptions) (str
 	return s, true, nil
 }

+// Locator creates and returns a new locator for this frame.


This GoDoc sentence looks like a leftover from copy-pasting 🤔

Updated in f490d70

joanlopez · 2025-06-16T09:06:29Z

internal/js/modules/k6/browser/common/frame.go

@@ -1002,6 +1002,58 @@ func (f *Frame) getAttribute(selector, name string, opts *FrameBaseOptions) (str
 	return s, true, nil
 }

+// Locator creates and returns a new locator for this frame.
+func (f *Frame) GetByRole(role string, opts *GetByRoleOptions) *Locator {
+	f.log.Debugf("Frame:Locator", "fid:%s furl:%q role:%q opts:%+v", f.ID(), f.url(""), role, opts)


Should we refer to the method name instead, to keep it consistent with the other methods? 🤔

Suggested change

f.log.Debugf("Frame:Locator", "fid:%s furl:%q role:%q opts:%+v", f.ID(), f.URL(), role, opts)

f.log.Debugf("Frame:GetByRole", "fid:%s furl:%q role:%q opts:%+v", f.ID(), f.URL(), role, opts)

Updated in f490d70

joanlopez · 2025-06-16T09:09:25Z

internal/js/modules/k6/browser/common/frame.go

+	if opts.Checked != nil {
+		properties["checked"] = fmt.Sprintf("%v", *opts.Checked)
+	}
+	if opts.Disabled != nil {
+		properties["disabled"] = fmt.Sprintf("%v", *opts.Disabled)
+	}
+	if opts.Selected != nil {
+		properties["selected"] = fmt.Sprintf("%v", *opts.Selected)
+	}
+	if opts.Expanded != nil {
+		properties["expanded"] = fmt.Sprintf("%v", *opts.Expanded)
+	}
+	if opts.IncludeHidden != nil {
+		properties["include-hidden"] = fmt.Sprintf("%v", *opts.IncludeHidden)


Why not using strconv.FormatBool instead of string formatting here? It's slightly more idiomatic, and perhaps even a bit faster, I guess. But maybe there's a reason not to.

PS: Same, whenever it applies, with the rest of the opts parsed on this method.

Yep, good spot. Changed in a098ac3

joanlopez · 2025-06-16T09:15:14Z

internal/js/modules/k6/browser/tests/get_by_test.go

+func stringPtr(s string) *string {
+	return &s
+}
+
+func boolPtr(b bool) *bool {
+	return &b
+}
+
+func int64Ptr(i int64) *int64 {
+	return &i
+}


I think nowadays, thanks to generics, this can be simplified into a single generic method, like:

func ptr[T any](v T) *T { return &v }

Thanks! Great idea. Updated in dfcd80f

inancgumus

I focused on the easy-to-review parts of this PR :-] I'll continue reviewing the rest tomorrow.

inancgumus · 2025-06-17T15:50:51Z

internal/js/modules/k6/browser/common/js/injected_script.js

@@ -14,6 +14,1259 @@
 * limitations under the License.


I don't think we need to add another license note, as we already have this one:

k6/internal/js/modules/k6/browser/common/js/injected_script.js

Lines 1 to 15 in 113abf5

/**

* Copyright (c) Microsoft Corporation.

*

* Licensed under the Apache License, Version 2.0 (the "License");

* you may not use this file except in compliance with the License.

* You may obtain a copy of the License at

*

* http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

internal/js/modules/k6/browser/common/locator_options.go

internal/js/modules/k6/browser/tests/get_by_test.go

AgnesToulet

I played a bit with it and everything seems to work great 👍 (plus the tests are covering a lot of use cases 🚀)

My main concern is about injected_script.js that is already big and will only grow bigger and bigger with the upcoming PRs.

AgnesToulet · 2025-07-07T09:40:56Z

internal/js/modules/k6/browser/common/js/injected_script.js

Could we split this file into multiple files and try to follow the Playwright structure as much as possible (same file names)? I think this would help with reviewing and also maintaining if any changes happen in Playwright in the future.

This JS version of PW's injected script is what is compiled from the type script injected scripts. I can see the benefit of splitting it if the files were easy to compare against PW, but it's something that seems to be available when installing it locally using node. Essentially, i feel it might be extra work to split the code into separate files, without the ability to be able to compare them against PW's changes, and so no real benefit.

If we split them and store them as separate files, we would also need to perform multiple requests to chrome to inject them one at a time during runtime, unless we had a job during CI/CD which combined them into a single file -- which is just another moving part, that could go wrong.

I toyed with the idea of copying the whole injected script from PW into k6 (not just take the parts we need to get the functionality working for the features we're implementing), so that it would make importing changes easier, but that didn't seem correct. At least with the selective approach has meant that I've been forced to understand what I've copied to help me get a good enough idea of what it is doing instead of no idea at all.

Ah, I looked only at the file name and didn't notice the extension was different. Thanks for the detailed answer.

I think it could still be worth it if we copy a lot more because JS and TS are fairly easy to compare (looking at the domUtils.ts file for example). But for now, it's true that, as we copy only what we need, it makes it harder to compare. Also, if we decide to do it, it should be its own PR so that's fine for this PR 👍

AgnesToulet · 2025-07-07T09:42:19Z

internal/js/modules/k6/browser/tests/get_by_test.go

+	// This tests all the options, and different attributes (such as explicit
+	// aria attributes vs the text value of an element) that can be used in
+	// the DOM with the same role.
+	t.Run("edge_cases", func(t *testing.T) {


We are not testing the exact attribute here, I think it would be nice to add one or two test for this use case.

Good spot! Added in a18bbd4

internal/js/modules/k6/browser/common/selectors.go

AgnesToulet

LGTM!

I basically copied the JS compiled injected script from PW, and pasted it into k6's injected script. It seems to work with basic role based selectors.

These tests include options and working with different attributes under-the-hood to do the same thing with a single option or role value.

It seems to be an issue with locator based APIs in integration tests, they just don't work. Locator based tests work perfectly when written and ran from a js test script.

The role based selector engine needs to work with ' and not " when it comes to the name option. This is automatically done for the user in the mapping layer, but in the integration test we need to ensure that we explicitly use ' and not ".

joanlopez

LGTM!

ankur22 requested a review from a team as a code owner June 9, 2025 21:23

ankur22 requested review from inancgumus and joanlopez and removed request for a team June 9, 2025 21:23

ankur22 commented Jun 9, 2025

View reviewed changes

ankur22 force-pushed the poc/role-based-selector-engine branch from f35ebc0 to a07de3f Compare June 9, 2025 21:31

ankur22 commented Jun 9, 2025

View reviewed changes

ankur22 force-pushed the poc/role-based-selector-engine branch 2 times, most recently from e684a3b to 7919b29 Compare June 9, 2025 21:42

ankur22 commented Jun 10, 2025

View reviewed changes

ankur22 force-pushed the poc/role-based-selector-engine branch from a766b35 to e172850 Compare June 10, 2025 14:19

ankur22 added this to the v1.1.0 milestone Jun 10, 2025

joanlopez reviewed Jun 16, 2025

View reviewed changes

ankur22 force-pushed the poc/role-based-selector-engine branch from 74171be to be4b038 Compare June 16, 2025 15:23

ankur22 requested a review from joanlopez June 16, 2025 15:52

inancgumus reviewed Jun 17, 2025

View reviewed changes

joanlopez modified the milestones: v1.1.0, v1.2.0 Jun 25, 2025

ankur22 force-pushed the poc/role-based-selector-engine branch from bb77825 to d12e198 Compare June 25, 2025 19:32

AgnesToulet reviewed Jul 7, 2025

View reviewed changes

internal/js/modules/k6/browser/common/selectors.go Show resolved Hide resolved

ankur22 force-pushed the poc/role-based-selector-engine branch from d12e198 to 4bcbad5 Compare July 7, 2025 13:18

AgnesToulet approved these changes Jul 8, 2025

View reviewed changes

ankur22 added 4 commits July 8, 2025 10:10

Add a role based selector engine

204150d

I basically copied the JS compiled injected script from PW, and pasted it into k6's injected script. It seems to work with basic role based selectors.

Add getByRole options

aef705d

Add getByRole in Frame

5f37df0

Add getByRole in Page

e250914

ankur22 added 20 commits July 8, 2025 10:11

Add getByRole in page mapping

1f08a1b

Update to internal:role

0d1f92f

Add tests for getByRole for edge cases

c05da70

These tests include options and working with different attributes under-the-hood to do the same thing with a single option or role value.

Add tests on getByRole with explicit roles in DOM

7787d4a

Add tests for getByRole with implicit elements

1d82f41

Add getByRole in page mapping test

e07a474

Update tests so they work on windows

59e9d19

Update test file to ignore build on windows

549cd37

It seems to be an issue with locator based APIs in integration tests, they just don't work. Locator based tests work perfectly when written and ran from a js test script.

Update from " to '

2109961

The role based selector engine needs to work with ' and not " when it comes to the name option. This is automatically done for the user in the mapping layer, but in the integration test we need to ensure that we explicitly use ' and not ".

Fix test after change from " to '

e0e95d0

Update comment and log for GetByRole

b0fc06a

Refactor GetByRole Locator builder

4be00ea

Refactor to use generics in test

12ca9bd

Fix for linter

2623eef

Move parsing logic to mapping for getByRole

c04bffb

Use new parsing function for getByRole

c2c2b9e

Remove old getByRole parser

4da19b4

Move ptr and rename it to toPtr

e30ef92

Fix linter error due to nil error

f21de4d

Add tests for exact option for getByRole

e8e574c

ankur22 force-pushed the poc/role-based-selector-engine branch from a18bbd4 to e8e574c Compare July 8, 2025 09:11

joanlopez approved these changes Jul 8, 2025

View reviewed changes

ankur22 merged commit faff94a into master Jul 9, 2025
76 of 84 checks passed

ankur22 deleted the poc/role-based-selector-engine branch July 9, 2025 14:42

mstoykov added the documentation-needed A PR which will need a separate PR for documentation label Aug 4, 2025

This was referenced Aug 6, 2025

Add type defs for page.getBy* API for k6 browser grafana/k6-DefinitelyTyped#89

Merged

Add getBy docs pages grafana/k6-docs#2023

Merged

BrewTestBot mentioned this pull request Aug 13, 2025

k6 1.2.1 Homebrew/homebrew-core#233339

Merged

	/**
	* Copyright (c) Microsoft Corporation.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	f.log.Debugf("Frame:Locator", "fid:%s furl:%q role:%q opts:%+v", f.ID(), f.URL(), role, opts)
	f.log.Debugf("Frame:GetByRole", "fid:%s furl:%q role:%q opts:%+v", f.ID(), f.URL(), role, opts)

Add getByRole in the browser module #4843

Add getByRole in the browser module #4843

Uh oh!

Conversation

ankur22 commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

Checklist

Checklist: Documentation (only for k6 maintainers and if relevant)

Related PR(s)/Issue(s)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ankur22 Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ankur22 Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ankur22 Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joanlopez Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joanlopez Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

inancgumus left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AgnesToulet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ankur22 Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AgnesToulet left a comment

Choose a reason for hiding this comment

Uh oh!

joanlopez left a comment

ankur22 commented Jun 9, 2025 •

edited

Loading

ankur22 Jun 9, 2025 •

edited

Loading

ankur22 Jul 9, 2025 •

edited

Loading

ankur22 Jun 10, 2025 •

edited

Loading

joanlopez Jun 16, 2025 •

edited

Loading

joanlopez Jun 16, 2025 •

edited

Loading

inancgumus left a comment •

edited

Loading

ankur22 Jul 7, 2025 •

edited

Loading