grafana/k6 · error

missing required argument 'role'

Error message

missing required argument 'role'

What it means

FrameLocator.getByRole(role, options) in the k6 browser module requires a non-nullish first argument naming an ARIA role; the mapping layer throws this error before parsing options or touching CDP. The role string (e.g. 'button', 'link', 'textbox') is the primary locator input — options like name or exact are secondary and cannot substitute for it. This matches Playwright, where the role argument is mandatory.

Source

Thrown at internal/js/modules/k6/browser/browser/frame_locator_mapping.go:44

				return nil, errors.New("missing required argument 'label'")
			}
			plabel, popts := parseGetByBaseOptions(vu.Context(), label, true, opts)

			ml := mapLocator(vu, fl.GetByLabel(plabel, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByPlaceholder": func(placeholder sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(placeholder) {
				return nil, errors.New("missing required argument 'placeholder'")
			}
			pplaceholder, popts := parseGetByBaseOptions(vu.Context(), placeholder, false, opts)

			ml := mapLocator(vu, fl.GetByPlaceholder(pplaceholder, popts))
			return rt.ToValue(ml).ToObject(rt), 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, fl.GetByRole(role.String(), popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByTestId": func(testID sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(testID) {
				return nil, errors.New("missing required argument 'testId'")
			}
			ptestID := parseStringOrRegex(testID, false)

			ml := mapLocator(vu, fl.GetByTestID(ptestID))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByText": func(text sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(text) {
				return nil, errors.New("missing required argument 'text'")

View on GitHub (pinned to 93accf6570)

Solutions

1. Pass an ARIA role string as the first argument: frameLocator.getByRole('button', { name: 'Submit' })
2. If the accessible name was meant as the criterion, keep role and pass name in options rather than dropping the role
3. Validate/default role variables from test data before the call
4. Check for typos in the variable or property name supplying the role

Example fix

// before
const btn = page.frameLocator('#frame').getByRole(undefined, { name: 'Submit' });

// after
const btn = page.frameLocator('#frame').getByRole('button', { name: 'Submit' });

const role = roles.submit; // 'button'
if (typeof role !== 'string' || role.length === 0) throw new Error('ARIA role is required for getByRole');
frameLocator.getByRole(role, opts);

const ARIA_ROLES = new Set(['button','link','textbox','checkbox','radio','heading','img','list','listitem','navigation','main','banner','contentinfo','form','table','row','cell','dialog','alert','search','tab','tablist','option','combobox','menuitem','progressbar','slider','switch']);
function isAriaRole(v) {
  return typeof v === 'string' && ARIA_ROLES.has(v);
}

try {
  loc = frameLocator.getByRole(maybeRole, opts);
} catch (e) {
  if (/missing required argument 'role'/.test(String(e.message))) {
    throw new Error('getByRole needs the role first; put accessible names in { name } options');
  }
  throw e;
}

When it happens

Trigger: Calling page.frameLocator('iframe').getByRole() with no role, passing null/undefined, or passing a role variable that resolves to undefined while intending to supply it via options ({ name: 'Submit' }) instead.

Common situations: Confusion between the role argument and the options.name parameter, data-driven role matrices with missing entries, or helper functions with an optional role parameter forwarded directly.

Related errors

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

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/0be0b374a76c656a. Report an issue: GitHub.