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

The `todo()` / `it.todo()` API creates a pending test placeholder with ONLY a description string — no callback. Env.todo enforces exactly one argument of type string at Env.ts:601. Any other shape (zero args, multiple args, a non-string, or passing a callback) throws an ErrorWithStack pointing at the todo call site.

Solutions

1. Call todo with exactly one string: `it.todo('description')`.
2. If you need a body, use `it('description', () => {})` or `it.skip(...)` instead.
3. If generating descriptions, coerce to string: `it.todo(String(name))`.

Example fix

// before
it.todo('will do later', () => { /* ... */ });
// after
it.todo('will do later');
// or, if you have a body to skip:
it.skip('will do later', () => { /* ... */ });

function safeTodo(description: string) {
  if (typeof description !== 'string') {
    throw new TypeError(`todo() requires a single string description, got ${typeof description}`);
  }
  return it.todo(description);
}

function isTodoDescription(value: unknown): value is string {
  return typeof value === 'string';
}

When it happens

Trigger: Calling `it.todo('x', () => {})` (callback not allowed), `it.todo()` (no description), `it.todo(123)` (non-string), or `it.todo('a', 'b')` (too many args). The guard at Env.ts:601 checks `arguments.length !== 1 || typeof description !== 'string'`.

Common situations: Confusing todo with a regular test (passing a body); passing a number or symbol as description; a wrapper that forwards extra arguments.

Related errors

• Missing second argument. It must be a callback function…
• Invalid second argument
• describe does not expect any arguments
• Invalid first argument. It must be a callback function.
• Invalid second argument

AI-assisted analysis of jestjs/jest@8e6d128e4a (2026-08-10). Data as JSON: /api/errors/bea3e706b1e1bba5. Report an issue: GitHub.

Appendix: source

Thrown at packages/jest-jasmine2/src/jasmine/Env.ts:602

        if (currentSpec !== null) {
          throw new Error(
            `Tests cannot be nested. Test "${spec.description}" cannot run because it is nested within "${currentSpec.description}".`,
          );
        }
        currentDeclarationSuite.addChild(spec);
        return spec;
      };

      this.xit = function (...args) {
        const spec = this.it.apply(this, args);
        spec.pend('Temporarily disabled with xit');
        return spec;
      };

      this.todo = function () {
        const description = arguments[0];
        if (arguments.length !== 1 || typeof description !== 'string') {
          throw new ErrorWithStack(
            'Todo must be called with only a description.',
            this.todo,
          );
        }

        const spec = specFactory(
          description,
          // eslint-disable-next-line @typescript-eslint/no-empty-function
          () => {},
          currentDeclarationSuite,
        );
        if (currentDeclarationSuite.markedPending) {
          spec.pend();
        } else {
          spec.todo();
        }
        currentDeclarationSuite.addChild(spec);
        return spec;

View on GitHub (pinned to 8e6d128e4a)