grafana/k6 · error

missing required argument 'altText'

Error message

missing required argument 'altText'

What it means

Thrown by page.getByAltText() in the k6 browser module (internal/js/modules/k6/browser/browser/page_mapping.go:182). The alt argument (string or RegExp matched against image alt attributes) is mandatory; the nullish guard rejects nil/undefined/null before parseGetByBaseOptions builds the selector. The error message uses the name 'altText' even though the JS parameter is just the first positional argument.

Solutions

1. Pass a string or RegExp: page.getByAltText('Company logo')
2. Default the value: const alt = img.alt ?? 'Company logo'
3. Skip the filter when optional: if (alt) loc = page.getByAltText(alt)
4. Validate fixture rows up front so missing alt fields fail before browser work starts

Example fix

// before
const logo = page.getByAltText(imgMeta.alt); // imgMeta.alt missing for one image

// after
const logo = page.getByAltText(imgMeta.alt ?? 'Company logo');

const alt = imgMeta.alt ?? 'Company logo';
if (alt === undefined || alt === null) throw new Error('altText is required');
const loc = page.getByAltText(alt);

function isNonEmptyStringOrRegExp(v) {
  return (typeof v === 'string' && v.length > 0) || v instanceof RegExp;
}
// usage: if (!isNonEmptyStringOrRegExp(alt)) throw new Error('altText must be a non-empty string or RegExp');

try {
  const loc = page.getByAltText(alt);
} catch (e) {
  if (/missing required argument 'altText'/.test(e.message)) throw new Error(`alt text missing for image ${imgMeta.src}`);
  throw e;
}

When it happens

Trigger: Calling page.getByAltText() with no arguments; passing undefined/null explicitly; passing an alt string read from a data fixture row that lacks the alt field.

Common situations: Image assertions driven by CMS/A11y exports with missing alt metadata; dynamic image filtering where some test rows have no alt text; scripts migrated from Playwright where the argument was dropped.

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 'label'
• missing required argument 'placeholder'
• missing required argument 'role'
• missing required argument 'testId'
• missing required argument 'text'

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

Appendix: source

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

				}
				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'")
			}
			plabel, popts := parseGetByBaseOptions(vu.Context(), label, true, opts)

			ml := mapLocator(vu, p.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'")

View on GitHub (pinned to 8d06114777)