grafana/k6 · error

missing required argument 'altText'

Error message

missing required argument 'altText'

What it means

Frame.getByAltText(altText) on a k6 browser Frame requires a non-nullish first argument; the mapping layer in frame_mapping.go throws before any CDP call. 'Nullish' covers a missing argument, null, and undefined (sobek passes Undefined for omitted JS arguments). The alt text (string or RegExp) is the locator's only input, matching Playwright's contract.

Source

Thrown at internal/js/modules/k6/browser/browser/frame_mapping.go:140

		"getAttribute": func(selector, name string, opts sobek.Value) (*sobek.Promise, error) {
			popts := common.NewFrameBaseOptions(f.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 := f.GetAttribute(selector, name, popts)
				if err != nil {
					return nil, err //nolint:wrapcheck
				}
				if !ok {
					return nil, nil //nolint:nilnil
				}
				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, f.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, f.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: frame.getByAltText('main-logo')
2. Validate/default data-sourced values before the call
3. Fix the typo or missing field producing undefined
4. Use a RegExp for versioned image alt text, e.g. getByAltText(/^logo-v\d+$/)

Example fix

// before
const frame = page.frame(page.url());
const img = frame.getByAltText(altVar); // altVar is undefined

// after
const altVar = 'hero image';
const img = frame.getByAltText(altVar);

if (!isTextSelector(altVar)) throw new Error('alt text is required before frame.getByAltText');
frame.getByAltText(altVar);

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

try {
  loc = frame.getByAltText(maybeAlt);
} catch (e) {
  if (/missing required argument 'altText'/.test(String(e.message))) {
    throw new Error(`altText missing on frame ${frame.url()}`);
  }
  throw e;
}

When it happens

Trigger: Calling frame.getByAltText() where frame came from page.frame() or page.frames(), passing null/undefined, or forwarding an undefined variable from a test-data row.

Common situations: Multi-frame SPA tests where selectors live in data files, ported Playwright specs with helper indirection, or destructuring mistakes that leave the alt variable undefined.

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@93accf6570 (2026-08-15). Data as JSON: /api/errors/bb75fae544172db2. Report an issue: GitHub.