jestjs/jest · error · ErrorWithStack

Todo must be called with only a description.

Error message

Todo must be called with only a description.

What it means

test.todo() is a placeholder API that only records a test name to be implemented later; it must not receive a test function or any extra arguments (packages/jest-circus/src/index.ts:173). The implementation throws when `rest.length > 0` (more than one argument) OR when testName is not a string, because a todo test has no body to run.

Source

Thrown at packages/jest-circus/src/index.ts:174

      eachError?: Error,
    ): void =>
      _addTest(
        testName,
        mode,
        concurrent,
        fn,
        failing,
        timeout,
        true,
        eachError,
      );
    failing.each = bindEach(failing, false, true);
    return failing;
  };

  test.todo = (testName: Circus.TestNameLike, ...rest: Array<any>): void => {
    if (rest.length > 0 || typeof testName !== 'string') {
      throw new ErrorWithStack(
        'Todo must be called with only a description.',
        test.todo,
      );
    }
    // eslint-disable-next-line @typescript-eslint/no-empty-function
    return _addTest(testName, 'todo', false, () => {}, test.todo);
  };

  const _addTest = (
    testName: Circus.TestNameLike,
    mode: Circus.TestMode,
    concurrent: boolean,
    fn: Circus.TestFn | undefined,
    testFn: (
      testName: Circus.TestNameLike,
      fn: Circus.TestFn,
      timeout?: number,
    ) => void,

View on GitHub (pinned to f49721c78e)

Solutions

1. If you have an implementation, use `test('name', fn)` (or `test.skip` if you want to skip it).
2. If it is genuinely a placeholder, remove the extra arguments: `test.todo('name')` with a single string.
3. Ensure the first argument is a plain string literal or string variable.

Example fix

// before
test.todo('calculates total', () => sum(1,2));

// after
test('calculates total', () => sum(1,2));
// or, as a genuine placeholder:
test.todo('calculates total');

// Wrap test.todo so misuse is caught at author time.
function safeTodo(name: unknown, ...rest: unknown[]): void {
  if (typeof name !== 'string' || rest.length > 0) {
    throw new TypeError('test.todo expects exactly one string argument');
  }
  // test.todo(name)
}

function isValidTodoCall(name: unknown, rest: unknown[]): name is string {
  return typeof name === 'string' && rest.length === 0;
}

When it happens

Trigger: `test.todo('x', () => {})` (passing a function), `test.todo(name1, name2)` (passing multiple args), or `test.todo(myNameVariable)` where the variable is not a string (e.g. a number/symbol).

Common situations: Developers copy a `test(...)` call and only change `test` to `test.todo`, leaving the callback in place; or use test.todo where they actually want a skipped/pending real test.

Related errors

• Returning a Promise from "describe" is not supported. Tests
• A "describe" callback must not return a value.
• Jest: `failing` tests are only supported in `jest-circus`.

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