grafana/k6 · error

missing required argument 'role'

Error message

missing required argument 'role'

What it means

Thrown by page.getByRole() in the k6 browser module (internal/js/modules/k6/browser/browser/page_mapping.go:173). The role argument is mandatory and is converted with role.String() into an ARIA role selector; the nullish guard fails immediately for nil/undefined/null because no CDP query can be built. A role that is present but not a real ARIA role passes this check and instead yields a locator matching nothing.

Solutions

1. Pass a valid ARIA role string: page.getByRole('button'), page.getByRole('link', { name: 'Sign in' })
2. Default dynamic roles: const role = cfg.role ?? 'button'
3. Verify the role against the standard ARIA role list before passing it
4. Log the role value just before the call to locate the undefined producer

Example fix

// before
const btn = page.getByRole(SEL.submit.role); // SEL.submit undefined

// after
const btn = page.getByRole(SEL?.submit?.role ?? 'button', { name: 'Submit' });

const role = SEL?.submit?.role ?? 'button';
if (role === undefined || role === null) throw new Error('role is required');
const loc = page.getByRole(role);

const ARIA_ROLES = new Set(['button', 'link', 'textbox', 'checkbox', 'radio', 'heading', 'listitem', 'list', 'navigation', 'menuitem', 'option', 'img']);
function isRole(v) { return typeof v === 'string' && ARIA_ROLES.has(v); }
// usage: if (!isRole(role)) throw new Error(`invalid or missing ARIA role: ${role}`);

try {
  const loc = page.getByRole(role);
} catch (e) {
  if (/missing required argument 'role'/.test(e.message)) throw new Error('getByRole called without a role — check your selector config');
  throw e;
}

When it happens

Trigger: Calling page.getByRole() with zero arguments; passing undefined/null explicitly; passing a role variable that a helper function failed to populate (e.g. mapEntry lookup miss).

Common situations: Role-driven selectors parameterized from scenario env or data files with missing values; refactoring a selector helper so the role parameter stopped being forwarded; ported Playwright snippets with the first argument omitted.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• missing required argument 'altText'
• missing required argument 'label'
• missing required argument 'placeholder'
• missing required argument 'role'
• missing required argument 'testId'

AI-assisted analysis of grafana/k6@8d06114777 (2026-08-18). Data as JSON: /api/errors/5b3a9865f4b5303f. Report an issue: GitHub.

Appendix: source

Thrown at internal/js/modules/k6/browser/browser/page_mapping.go:173

		"getAttribute": func(selector string, name string, opts sobek.Value) (*sobek.Promise, error) {
			popts := common.NewFrameBaseOptions(p.MainFrame().Timeout())
			if err := parseFrameBaseOptions(popts, rt, opts); err != nil {
				return nil, fmt.Errorf("parsing getAttribute options: %w", err)
			}
			return promise(vu, func() (any, error) {
				s, ok, err := p.GetAttribute(selector, name, popts)
				if err != nil {
					return nil, err //nolint:wrapcheck
				}
				if !ok {
					return nil, nil //nolint:nilnil
				}
				return s, nil
			}), nil
		},
		"getByRole": func(role sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(role) {
				return nil, errors.New("missing required argument 'role'")
			}
			popts := parseGetByRoleOptions(vu.Context(), opts)

			ml := mapLocator(vu, p.GetByRole(role.String(), popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByAltText": func(alt sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(alt) {
				return nil, errors.New("missing required argument 'altText'")
			}
			palt, popts := parseGetByBaseOptions(vu.Context(), alt, false, opts)

			ml := mapLocator(vu, p.GetByAltText(palt, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByLabel": func(label sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(label) {
				return nil, errors.New("missing required argument 'label'")

View on GitHub (pinned to 8d06114777)