What causes "missing required argument 'testId'" in grafana/k6?

Pass the test id string or RegExp: frameLocator.getByTestId('submit-button')

missing required argument 'testId'

Error message

missing required argument 'testId'

What it means

FrameLocator.getByTestId(testId) in the k6 browser module requires a non-nullish argument; the mapping rejects absent, null, or undefined values before calling parseStringOrRegex. The test id (string or RegExp) is matched against the data-testid attribute (configurable) and is the only input to this locator. Playwright has the same contract.

Source

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

				return nil, errors.New("missing required argument 'placeholder'")
			}
			pplaceholder, popts := parseGetByBaseOptions(vu.Context(), placeholder, false, opts)

			ml := mapLocator(vu, fl.GetByPlaceholder(pplaceholder, popts))
			return rt.ToValue(ml).ToObject(rt), 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, fl.GetByRole(role.String(), popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByTestId": func(testID sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(testID) {
				return nil, errors.New("missing required argument 'testId'")
			}
			ptestID := parseStringOrRegex(testID, false)

			ml := mapLocator(vu, fl.GetByTestID(ptestID))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByText": func(text sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(text) {
				return nil, errors.New("missing required argument 'text'")
			}
			ptext, popts := parseGetByBaseOptions(vu.Context(), text, true, opts)

			ml := mapLocator(vu, fl.GetByText(ptext, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByTitle": func(title sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(title) {
				return nil, errors.New("missing required argument 'title'")

View on GitHub (pinned to 93accf6570)

Solutions

Pass the test id string or RegExp: frameLocator.getByTestId('submit-button')
Import/define the test-id constant and verify it is not undefined before use
Fix renamed constants or missing exports in the selector module
Use a RegExp for ids with generated suffixes, e.g. getByTestId(/^row-\d+$/)

Example fix

// before
import { IDs } from './ids.js';
const el = page.frameLocator('#f').getByTestId(IDs.submit); // IDs.submit is undefined

// after
import { IDs } from './ids.js';
const el = page.frameLocator('#f').getByTestId('submit-button');

Defensive patterns

Strategy: validation

Validate before calling

const id = TID.submit;
if (!isTextSelector(id)) throw new Error(`TID.submit is not a valid testId`);
frameLocator.getByTestId(id);

Type guard

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

Try / catch

try {
  loc = frameLocator.getByTestId(maybeId);
} catch (e) {
  if (/missing required argument 'testId'/.test(String(e.message))) {
    throw new Error(`testId missing; selectors module may be stale after rename`);
  }
  throw e;
}

Prevention

Export a frozen selectors object and add a unit check that every used key is a non-empty string
Avoid dynamic property access (TID[name]) without a fallback; check the key exists first
Use RegExp test ids for generated attributes instead of building strings that can become undefined
Re-run the page-object smoke test after renaming any selector constant

When it happens

Trigger: Calling page.frameLocator('iframe').getByTestId() with no argument, passing null/undefined, or forwarding a test-id constant that is undefined because it was renamed or never exported.

Common situations: Shared selector-constant modules where an id was renamed, codegen output pasted incompletely, or data-driven assertions missing the id column.

Related errors

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