grafana/k6 · error

missing required argument 'altText'

Error message

missing required argument 'altText'

What it means

FrameLocator.getByAltText(altText) in the k6 browser module requires a non-nullish first argument; the JS-to-Go mapping layer in frame_locator_mapping.go rejects it before any CDP traffic. 'Nullish' means the argument is absent, null, or undefined (sobek delivers missing arguments as Undefined). The alt text (string or RegExp) is the only way the locator identifies img/area elements, so the call is mandatory, mirroring Playwright's API contract.

Source

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

package browser

import (
	"errors"

	"github.com/grafana/sobek"
	"go.k6.io/k6/v2/internal/js/modules/k6/browser/common"
	k6common "go.k6.io/k6/v2/js/common"
)

// mapFrameLocator API to the JS module.
func mapFrameLocator(vu moduleVU, fl *common.FrameLocator) mapping {
	rt := vu.Runtime()
	return mapping{
		"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, fl.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, 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'")

View on GitHub (pinned to 93accf6570)

Solutions

1. Pass a string or RegExp as the first argument, e.g. frameLocator.getByAltText('company-logo')
2. If the value comes from test data, default or validate it before the call (const alt = row.alt ?? 'fallback')
3. Fix the variable name or data field that is resolving to undefined
4. When matching variable alt attributes, pass a RegExp instead of dropping the argument

Example fix

// before
const logo = page.frameLocator('#ad-frame').getByAltText(altTextVar); // altTextVar is undefined

// after
const altTextVar = 'hero-banner';
const logo = page.frameLocator('#ad-frame').getByAltText(altTextVar);

const alt = data.alt;
if (alt === undefined || alt === null) throw new Error('data.alt is required for getByAltText');
frameLocator.getByAltText(alt);

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

try {
  loc = frameLocator.getByAltText(maybeAlt);
} catch (e) {
  if (/missing required argument 'altText'/.test(String(e.message))) {
    throw new Error(`altText missing for frameLocator.getByAltText; source data: ${JSON.stringify(data)}`);
  }
  throw e;
}

When it happens

Trigger: Calling page.frameLocator('#iframe').getByAltText() with no argument, passing null or undefined explicitly, or passing a variable that is undefined due to a typo or a missing field in test data (e.g. dataset?.altName).

Common situations: Data-driven scripts where some rows lack an alt-text field, ported Playwright tests with a helper that omits the argument, or refactorings that rename the variable being passed.

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/e03f1d3ac8fe859a. Report an issue: GitHub.