grafana/k6 · error

missing required argument 'role'

Error message

missing required argument 'role'

What it means

Thrown by the Page mapping's getByRole method in k6's browser module. The ARIA role is the mandatory first argument; the mapping rejects nullish values with k6common.IsNullish before parsing role options and calling p.GetByRole. Note that any non-nullish value is coerced with role.String(), so only null/undefined hit this error.

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 := popts.Parse(vu.Context(), 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 93accf6570)

Solutions

1. Always pass the role string first: page.getByRole('button', { name: 'Submit' })
2. If role is dynamic, guard it: role ? page.getByRole(role, opts) : failFast()
3. Remember options like name/exact go in the SECOND argument, never replace the first

Example fix

// before
page.getByRole({ name: 'Submit' });

// after
page.getByRole('button', { name: 'Submit' });

if (typeof role !== 'string' || role.length === 0) {
  throw new Error(`page.getByRole: 'role' string is required, got ${role}`);
}
const loc = page.getByRole(role, opts);

function isRole(v) {
  return typeof v === 'string' && v.length > 0;
}

try {
  page.getByRole(role);
} catch (e) {
  if (!e.message.includes("missing required argument 'role'")) throw e;
  throw new Error(`role must be first arg; name goes in opts`);
}

When it happens

Trigger: page.getByRole() with no arguments; page.getByRole(null); passing opts in the first position by mistake: page.getByRole({ name: 'Submit' }).

Common situations: Copy-pasting Playwright examples and trimming the role; building the role from a variable that is unset; assuming name alone identifies the element (name belongs in opts, role must still be first).

Related errors

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

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