jestjs/jest · error · Error

Table headings do not conform to expected format: ${EXPECTE

Error message

Table headings do not conform to expected format:

${EXPECTED_COLOR('heading1 | headingN')}

Received:

${RECEIVED_COLOR(pretty(heads))}

What it means

extractValidTemplateHeadings matches the header block against a strict regex `^\n<heading>(|<heading>)*\n` (HEADINGS_FORMAT). If the headings string does not start with a newline or does not follow the `name | name` pipe-delimited shape, no match is produced and jest-each throws with the received text at validation.ts:90.

Source

Thrown at packages/jest-each/src/validation.ts:90

};

const pluralize = (word: string, count: number) =>
  word + (count === 1 ? '' : 's');

const START_OF_LINE = '^';
const NEWLINE = '\\n';
const HEADING = '\\s*[^\\s]+\\s*';
const PIPE = '\\|';
const REPEATABLE_HEADING = `(${PIPE}${HEADING})*`;
const HEADINGS_FORMAT = new RegExp(
  START_OF_LINE + NEWLINE + HEADING + REPEATABLE_HEADING + NEWLINE,
  'g',
);

export const extractValidTemplateHeadings = (headings: string): string => {
  const matches = headings.match(HEADINGS_FORMAT);
  if (matches === null) {
    throw new Error(
      `Table headings do not conform to expected format:\n\n${EXPECTED_COLOR(
        'heading1 | headingN',
      )}\n\nReceived:\n\n${RECEIVED_COLOR(pretty(headings))}`,
    );
  }

  return matches[0];
};

View on GitHub (pinned to f49721c78e)

Solutions

Use exactly the `heading1 | heading2` form with single-line tokens, no spaces inside tokens.
Keep the leading newline immediately after the backtick — the regex anchors on it.
Replace commas with pipes and remove spaces from column names.
If you need spaces in column names, switch to the array-of-objects form and reference fields by key.

Example fix

// before
it.each`
  first name, last name
  ${'Ada'} | ${'Lovelace'}
`(...);

// after
it.each`
  firstName | lastName
  ${'Ada'}  | ${'Lovelace'}
`('$firstName $lastName', ({firstName, lastName}) => {});

Defensive patterns

Strategy: validation

Validate before calling

const HEADINGS = /^\n\s*\S+(\s*\|\s*\S+)*\n/;
if (!HEADINGS.test(headerBlock)) throw new Error('invalid .each header format');

Type guard

const isValidHeadings = (h: string) => /^\n\s*\S+(\s*\|\s*\S+)*\n/.test(h);

Prevention

Use pipes and a leading newline in headers.
Avoid spaces inside column names; camelCase keys.
Switch to array-of-objects form for complex headers.

When it happens

Trigger: A tagged-template header that omits the leading newline, uses commas instead of pipes, has trailing spaces breaking the format, or contains a blank heading cell.

Common situations: Author writes `.each\`a, b\n...\`` (comma instead of pipe); edits the template and accidentally removes the leading newline; pastes a Markdown table header expecting tab-separation; includes a column name with a space which the `\S+`-based heading regex rejects.

Related errors

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/c3da7288856800a0.json. Report an issue: GitHub.