grafana/k6 · error

missing required argument 'altText'

Error message

missing required argument 'altText'

What it means

Locator.getByAltText(altText) in the k6 browser module (chained on an existing Locator) requires a non-nullish first argument; the mapping in locator_mapping.go throws before any CDP activity. 'Nullish' includes missing, null, and undefined arguments. The alt text (string or RegExp) is the sole input used to narrow the locator to img/area descendants, matching Playwright's contract.

Source

Thrown at internal/js/modules/k6/browser/browser/locator_mapping.go:236

		"getAttribute": func(name string, opts sobek.Value) (*sobek.Promise, error) {
			copts := common.NewFrameBaseOptions(lo.Timeout())
			if err := copts.Parse(vu.Context(), opts); err != nil {
				return nil, fmt.Errorf("parsing get attribute options: %w", err)
			}
			return promise(vu, func() (any, error) {
				s, ok, err := lo.GetAttribute(name, copts)
				if err != nil {
					return nil, err //nolint:wrapcheck
				}
				if !ok {
					return nil, nil
				}
				return s, nil
			}), 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, lo.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, lo.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 93accf6570)

Solutions

1. Pass a string or RegExp: locator.getByAltText('badge-icon')
2. Validate/default the alt value before chaining; assert it is defined in the page-object constructor
3. Fix renamed or unexported selector constants
4. Use a RegExp for variable alt text, e.g. getByAltText(/^avatar-/)

Example fix

// before
const avatar = page.locator('.user-card').getByAltText(ALT.avatar); // ALT.avatar is undefined

// after
const avatar = page.locator('.user-card').getByAltText('user-avatar');

if (!isTextSelector(alt)) throw new Error('alt must be a non-empty string or RegExp before locator.getByAltText');
locator.getByAltText(alt);

function isTextSelector(v) {
  return (typeof v === 'string' && v.length > 0) || v instanceof RegExp;
}

try {
  sub = locator.getByAltText(maybeAlt);
} catch (e) {
  if (/missing required argument 'altText'/.test(String(e.message))) {
    throw new Error(`altText missing while building locator under ${selector}`);
  }
  throw e;
}

When it happens

Trigger: Calling page.locator('div').getByAltText() with no argument, passing null/undefined, or forwarding an undefined alt variable while chaining locators in a page object.

Common situations: Page-object chaining where the alt constant is missing from the selectors module, data-driven component tests with sparse fields, incomplete Playwright port.

Related errors

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

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